pyCatenary

class pycatenary.cable.MooringLine(fairlead: Sequence[float], anchor: Sequence[float], L: float | Sequence[float], w: float | Sequence[float], EA: float | Sequence[float] | None = None, floor: bool = True)

Bases: object

Class to create a mooring line.

Mooring lines can be elastic or rigid, and multisegmented or not. If the line is multisegmented, the properties must be given in a list going from the anchor to the fairlead.

Parameters:

fairlead (sequence of floats) – Fairlead coordinates [x, y, z] (3D) or [x, y] (2D).
anchor (sequence of floats) – Anchor coordinates [x, y, z] (3D) or [x, y] (2D).
L (float, or sequence of floats) – Unstretched line length [m]. If a list is provided, it is assumed to be a multisegmented cable.
w (float, or sequence of floats) – Submerged weight [N/m]. If a list is provided, it must match the length of the L list.
EA (float, or sequence of floats) – Axial stiffness [N]. Must be provided if the cable is elastic. If EA is None, the cable is assumed to be rigid. If a list is provided, it must match the length of the L list.
floor (bool) – If True, the floor is assumed to be at the anchor level. If fairlead is below anchor, the floor will be at fairlead level.

update_axial_stiffness(EA: float | Sequence[float]) → None

Updates the axial stiffness of the cable.

Parameters:: EA (float, or sequence of floats) – Axial stiffness [N]. Must be of the same length as the original EA list.

compute_solution() → None

Computes solution of the catenary.

It is computed according to current anchor and fairlead positions.

get_position(s: float, from_fairlead: bool = False) → ndarray

Returns position at a given distance along line from 0 to L.

Parameters:

s (float) – Distance along line [m].
from_fairlead (bool, optional) – False (by default): distance is measured from the anchor, True: distance is measured from the fairlead.

Returns:

position – Position [x, y, z] (3D) or [x, y] (2D).

Return type:

np.ndarray

get_tension(s: float, from_fairlead: bool = False) → ndarray

Returns tension at a given distance along line from 0 to L.

Parameters:

s (float) – Distance along line [m].
from_fairlead (bool, optional) – False (by default): distance is measured from the anchor, True: distance is measured from the fairlead.

Returns:

tension – Tension vector [N].

Return type:

np.ndarray

get_fairlead_force() → ndarray

Returns force at fairlead.

Returns:: force – Tension vector [N].
Return type:: np.ndarray

get_anchor_force() → ndarray

Returns force at anchor.

Returns:: force – Tension vector [N].
Return type:: np.ndarray

plot(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

Plots line from anchor to fairlead.

Parameters:

npoints (int, optional) – Number of points along the line, by default 100.
show_tension (bool, optional) – If True, color the line by tension magnitude, by default True.
colormap (str, optional) – Matplotlib colormap name, by default “viridis”.

plot_2d(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

Plots line from anchor to fairlead in 2D.

Parameters:

npoints (int, optional) – Number of points along the line, by default 100.
show_tension (bool, optional) – If True, color the line by tension magnitude, by default True.
colormap (str, optional) – Matplotlib colormap name, by default “viridis”.

Raises:

ImportError – If matplotlib is not installed.

plot_3d(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

Plots line from anchor to fairlead in 3D.

Parameters:

npoints (int, optional) – Number of points along the line, by default 100.
show_tension (bool, optional) – If True, color the line by tension magnitude, by default True.
colormap (str, optional) – Matplotlib colormap name, by default “viridis”.

Raises:

ImportError – If matplotlib is not installed.

set_anchor_position(position: Sequence[float]) → None

Sets coordinates of anchor.

Parameters:: position (sequence of floats) – Anchor position [x, y, z] (3D) or [x, y] (2D).

get_anchor_position() → ndarray

Returns coordinates of anchor.

Returns:: position – Anchor position [x, y, z] (3D) or [x, y] (2D).
Return type:: np.ndarray

set_fairlead_position(position: Sequence[float]) → None

Sets coordinates of fairlead.

Parameters:: coords (sequence of floats) – Fairlead position [x, y, z] (3D) or [x, y] (2D).

get_fairlead_position() → ndarray

Returns coordinates of fairlead.

Returns:: position – Fairlead position [x, y, z] (3D) or [x, y] (2D).
Return type:: np.ndarray

computeSolution() → None

getTension(s: float) → ndarray

setAnchorCoords(coords: Sequence[float]) → None

setFairleadCoords(coords: Sequence[float]) → None

plot2D(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

plot3D(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

s2xyz(s: float) → ndarray

pycatenary.catenary.get_array(x: float | Sequence[float]) → ndarray

Converts input to numpy array.

Parameters:: x (Union[float, Sequence[float]]) – Input to convert to numpy array.
Returns:: x – Numpy array of the input.
Return type:: np.ndarray

class pycatenary.catenary.CatenaryBase(L: float | Sequence[float], w: float | Sequence[float], floor: bool = True)

Bases: ABC

Base class for catenaries.

Parameters:

L (Union[float, Sequence[float]]) – Unstretched line length [m]. If a list is provided, it is assumed to be a multisegmented cable.
w (Union[float, Sequence[float]]) – Submerged weight [N/m]. If a list is provided, it must match the length of the L list.
floor (bool) – If True, the floor is assumed to be at the anchor level.

get_tension(s: float) → ndarray

Returns tension at a given distance along the line from the anchor.

Parameters:: s (float) – Distance along line [m].
Returns:: tension – Tension vector [N].
Return type:: np.ndarray

s2xy(s: float) → ndarray

Returns [x,y] coords at a given distance along line.

Parameters:: s (float) – Distance along line [m].
Returns:: xy – [x,y] coordinates.
Return type:: np.ndarray

plot(npoints: int = 100, show_tension: bool = True, colormap: str = 'viridis') → None

Plots catenary in 2D from (0, 0) to (d, h).

Parameters:

npoints (int, optional) – Number of points along the line, by default 100.
show_tension (bool, optional) – If True, color the line by tension magnitude, by default True.
colormap (str, optional) – Matplotlib colormap name, by default “viridis”.

Raises:

ImportError – If matplotlib is not installed.

abstract compute_solution(d: float, h: float) → None

Abstract method to calculate the catenary solution.

This method must be implemented by subclasses to define the specific catenary calculation algorithm (rigid or elastic).

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].

get_force_beginning_of_line()

get_force_end_of_line()

getTension(s: float) → ndarray

getState(d: float, h: float) → None

class pycatenary.catenary.CatenaryRigid(L: float | Sequence[float], w: float | Sequence[float], floor: bool = True)

Bases: CatenaryBase

A class for rigid catenary.

Parameters:

L (Union[float, Sequence[float]]) – Unstretched line length [m]. If a list is provided, it is assumed to be a multisegmented cable.
w (Union[float, Sequence[float]]) – Submerged weight [N/m]. If a list is provided, it must match the length of the L list.
floor (bool) – If True, the floor is assumed to be at the anchor level.

compute_solution(d: float, h: float) → None

Calculates the solution for rigid catenary.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].

class pycatenary.catenary.CatenaryElastic(L: float | Sequence[float], w: float | Sequence[float], EA: float | Sequence[float] | None = None, floor: bool = True)

Bases: CatenaryBase

A class for elastic catenary

Parameters:

L (Union[float, Sequence[float]]) – Unstretched line length [m]. If a list is provided, it is assumed to be a multisegmented cable.
w (Union[float, Sequence[float]]) – Submerged weight [N/m]. If a list is provided, it must match the length of the L list.
EA (Union[float, Sequence[float]]) – Axial stiffness [N]. If a list is provided, it must match the length of the L list.
floor (bool) – If True, the floor is assumed to be at the anchor level.

compute_solution(d: float, h: float) → None

Calculates the solution for elastic catenary.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].

pycatenary.root_finding.get_root_a(L: float, d: float, h: float, a0: float = 1.0, tol: float = 1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0) → float

Returns the initial guess for the catenary a parameter.

Parameters:

L (float) – Unstretched line length [m].
d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
a0 (float) – Initial guess for the catenary a parameter.
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.

Returns:

a – Initial guess for the catenary a parameter.

Return type:

float

pycatenary.root_finding.newton_raphson(f: Callable[[float], float], df: Callable[[float], float], x0: float, tol: float = 1e-06, maxit: int = 1000, must_converge: bool = True) → float

Newton-Raphson root finding algorithm (for transcendental equations).

Parameters:

f (function) – Function to find the root of.
df (function) – Derivative of the function f (df/dx).
x0 (float) – Initial guess of x.
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

x – Root of the function.

Return type:

float

pycatenary.root_finding.bisection(f: Callable[[float], float], int1: float, int2: float, tol: float = 1e-06, maxit: int = 1000, must_converge: bool = True) → float

Bisection root finding algorithm (for transcendental equations).

Parameters:

f (function) – Function to find the root of.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.

Returns:

x – Root of the function.

Return type:

float

pycatenary.root_finding.integrate_tension(s1: float, s2: float, w: float, Ha: float, Va: float) → float

Helper function to integrate tension along a cable segment.

Parameters:

s1 (float) – Start of the cable segment [m].
s2 (float) – End of the cable segment [m].
w (float) – Submerged weight [N/m].
Ha (float) – Horizontal tension at s1 [N].
Va (float) – Vertical tension at s1 [N].

Returns:

Ts – Integrated tension.

Return type:

float

pycatenary.root_finding.nofloor_rigid(d: float, h: float, L: Sequence[float], tol: float = 1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → float

Returns catenary shape for rigid cable with no floor.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a – Catenary shape parameter.

Return type:

float

pycatenary.root_finding.nofloor_elastic(d: float, h: float, L: Sequence[float], w: Sequence[float], EA: Sequence[float], tol=1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → tuple[float, ndarray]

Returns catenary solution for elastic cable with no floor.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
w (Sequence[float]) – Submerged weight [N/m].
EA (Sequence[float]) – Axial stiffness [N].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a (float) – Catenary shape parameter.
e (np.ndarray) – Elongation of the cable segments [m].

pycatenary.root_finding.fully_lifted_elastic(d: float, h: float, L: Sequence[float], w: Sequence[float], EA: Sequence[float], tol: float = 1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → tuple[float, ndarray]

Returns catenary solution for fully lifted elastic cable.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
w (Sequence[float]) – Submerged weight [N/m].
EA (Sequence[float]) – Axial stiffness [N].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a (float) – Catenary shape parameter.
e (np.ndarray) – Elongation of the cable segments [m].

pycatenary.root_finding.fully_lifted_rigid(d: float, h: float, L: Sequence[float], tol=1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → float

Returns catenary solution for fully lifted rigid cable.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a – Catenary shape parameter.

Return type:

float

pycatenary.root_finding.partly_lifted_elastic(d: float, h: float, L: Sequence[float], w: Sequence[float], EA: Sequence[float], tol: float = 1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → tuple[float, ndarray, ndarray]

Returns catenary solution for partly lifted elastic cable.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
w (Sequence[float]) – Submerged weight [N/m].
EA (Sequence[float]) – Axial stiffness [N].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a (float) – Catenary shape parameter.
e (np.ndarray) – Elongation of the cable segments [m].
Lsu (np.ndarray) – Lifted line lengths of the cable segments [m].

pycatenary.root_finding.partly_lifted_rigid(d: float, h: float, L: Sequence[float], tol: float = 1e-06, maxit: int = 1000, int1: float = 0.01, int2: float = 10000000000.0, must_converge: bool = True) → tuple[float, ndarray]

Returns catenary solution for partly lifted rigid cable.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
int1 (float) – Lower bound for the bisection algorithm.
int2 (float) – Upper bound for the bisection algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

a (float) – Catenary shape parameter.
Lsu (np.ndarray) – Lifted line lengths of the cable segments [m].

pycatenary.root_finding.straight_elastic(d: float, h: float, L: Sequence[float], w: Sequence[float], EA: Sequence[float], H_low: float = 0, H_high: float = 10000000000.0, tol: float = 1e-06, maxit: int = 1000, must_converge: bool = True) → tuple[float, ndarray]

Returns horizontal tension and elongation for straight elastic cable.

Parameters:

d (float) – Horizontal distance between anchor and fairlead [m].
h (float) – Vertical distance between anchor and fairlead [m].
L (Sequence[float]) – Unstretched line length [m].
w (Sequence[float]) – Submerged weight [N/m].
EA (Sequence[float]) – Axial stiffness [N].
H_low (float) – Lower bound for the horizontal tension at anchor [N].
H_high (float) – Upper bound for the horizontal tension at anchor [N].
tol (float) – Tolerance for the root finding algorithm.
maxit (int) – Maximum number of iterations for the root finding algorithm.
must_converge (bool) – If True, an error will be raised if the algorithm does not converge. If False, a warning will be issued if the algorithm does not converge.

Returns:

H (float) – Horizontal tension at anchor [N].
e (np.ndarray) – Elongation of the cable segments [m].