API

This will provide a list of all callable functions, classes, and methods.

Conventions

As discussed in Model Structure, Point and Body objects can be either fixed, coupled, or free. The object’s “type” attribute describes this, with 1=fixed, 0=free, -1=coupled. These properties can be changed after a mooring system has been created (for example, to simulate a disconnection).

The System Class

class moorpy.system.System(file='', dirname='', rootname='', depth=0, rho=1025, g=9.81, qs=1, Fortran=True)

A class for the whole mooring system

__init__(file='', dirname='', rootname='', depth=0, rho=1025, g=9.81, qs=1, Fortran=True)

Creates an empty MoorPy mooring system data structure and will read an input file if provided.

Parameters

file (string, optional) – An input file, usually a MoorDyn input file, that can be read into a MoorPy system. The default is “”.
depth (float, optional) – Water depth of the system. The default is 0.
rho (float, optional) – Water density of the system. The default is 1025.
g (float, optional) – Gravity of the system. The default is 9.81.

Returns

Return type

None.

addBody(mytype, r6, m=0, v=0, rCG=array([0.0, 0.0, 0.0]), AWP=0, rM=array([0.0, 0.0, 0.0]), f6Ext=array([0.0, 0.0, 0.0, 0.0, 0.0, 0.0]))

Convenience function to add a Body to a mooring system

Parameters

type (int) – the body type: 0 free to move, 1 fixed, -1 coupled externally
r6 (array) – 6DOF position and orientation vector [m, rad].
m (float, optional) – mass, centered at CG [kg]. The default is 0.
v (float, optional) – volume, centered at reference point [m^3]. The default is 0.
rCG (array, optional) – center of gravity position in body reference frame [m]. The default is np.zeros(3).
AWP (float, optional) – waterplane area - used for hydrostatic heave stiffness if nonzero [m^2]. The default is 0.
rM (float or array, optional) – coordinates or height of metacenter relative to body reference frame [m]. The default is np.zeros(3).
f6Ext (array, optional) – applied external forces and moments vector in global orientation (not including weight/buoyancy) [N]. The default is np.zeros(6).

Returns

Return type

None.

addLine(lUnstr, type_string, nSegs=40, pointA=0, pointB=0, cb=0)

Convenience function to add a Line to a mooring system

Parameters

lUnstr (float) – unstretched line length [m].
type_string (string) – string identifier of LineType object that this Line is to be.
nSegs (int, optional) – number of segments to split the line into. The default is 20.
int (pointB) – Point number to attach end A of the line to.
optional – Point number to attach end A of the line to.
int – Point number to attach end B of the line to.
optional – Point number to attach end B of the line to.

Returns

Return type

None.

addLineType(type_string, d, massden, EA)

Convenience function to add a LineType to a mooring system

Parameters

type_string (string) – string identifier of the LineType object that is to be added.
d (float) – volume-equivalent diameter [m].
massden (float) – mass of line per length, or mass density [kg/m], used to calculate weight density (w) [N/m]
EA (float) – extensional stiffness [N].

Returns

Return type

None.

addPoint(mytype, r, m=0, v=0, fExt=array([0.0, 0.0, 0.0]), DOFs=[0, 1, 2])

Convenience function to add a Point to a mooring system

Parameters

type (int) – the point type: 0 free to move, 1 fixed, -1 coupled externally
r (array) – x,y,z coordate position vector [m].
m (float, optional) – mass [kg]. The default is 0.
v (float, optional) – volume [m^3]. The default is 0.
fExt (array, optional) – applied external force vector in global orientation (not including weight/buoyancy) [N]. The default is np.zeros(3).
DOFs (list, optional) – list of which coordinate directions are DOFs for this point (default 0,1,2=x,y,z). E.g. set [2] for vertical motion only.. The default is [0,1,2].

Returns

Return type

None.

animate(ts): Redraws mooring system positions at step ts. Currently set up in a hack-ish way to work for animations involving movement of either free DOFs or coupled DOFs (but not both)

animateSolution(DOFtype='free')

Creates an animation of the system

Returns
Return type: None.

animatelines(interval=200, repeat=True, delay=0, runtime=- 1, **kwargs)

Parameters

dirname (string) – The name of the directory folder you are in.
rootname (string) – The name of the front portion of the main file name, like spar_WT1, or DTU_10MW_NAUTILUS_GoM.
interval (int, optional) – The time between animation frames in milliseconds. The default is 200.
repeat (bool, optional) – Whether or not to repeat the animation. The default is True.
delay (int, optional) – The time between consecutive animation runs in milliseconds. The default is 0.

Returns

line_ani – an animation of the mooring lines based off of MoorDyn data. Needs to be stored, returned, and referenced in a variable

Return type

animation

getCoupledStiffness(dx=0.1, dth=0.1, solveOption=1, lines_only=False, tensions=False, nTries=3, plots=0)

Calculates the stiffness matrix for coupled degrees of freedom of a mooring system with free uncoupled degrees of freedom equilibrated.

Parameters

dx (float, optional) – The change in displacement to be used for calculating the change in force. The default is 0.1.
dth (float, optional) – The change in rotation to be used for calculating the change in force. The default is 0.1.
solveOption (boolean, optional) – Indicator of which solve option to use. The default is 1.
plots (boolean, optional) – Determines whether the stiffness calculation process is plotted and/or animated or not. The default is 0.
lines_only (boolean) – Whether to consider only line forces and ignore body/point properties.
tensions (boolean) – Whether to also compute and return mooring line tension jacobians

Raises

ValueError – If the solveOption is not a 1 or 0

Returns

K – nCpldDOF x nCpldDOF stiffness matrix of the system

Return type

matrix

getDOFs()

returns updated nDOFs and nCpldDOFs if the body and point types ever change

Returns

nDOF (int) – number of free degrees of freedom based on body and point types.
nCpldDOF (int) – number of coupled degrees of freedom based on body ad point types.

getForces(DOFtype='free', lines_only=False)

Returns a vector with the net forces/moments along DOFs in the System. DOFs can be of ‘free’ objects, ‘coupled’ objects, or ‘both’.

Parameters

DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.
lines_only (boolean, optional) – An option for calculating forces from just the mooring lines or not. The default is False, meaning forces will include weight, buoyancy, and any external loads assigned to bodies or points.

Returns

f – The force values.

Return type

array

getPositions(DOFtype='free', dXvals=[])

Returns a vector with the DOF values of objects in the System. DOFs can be of ‘free’ objects, ‘coupled’ objects, or ‘both’.

Parameters

DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.
dXvals (list or array, optional) – If provided, a second vector filled with a value coresponding to each DOF type returned. If dXvals is size 2, it contains the values for translational and rotational DOFs, respectively. If dXvals is size 3, it expects the values for point DOFs, body translational DOFs, and body rotational DOFs, respectively.

Returns

X (array) – The DOF values - bodies, then points.
dX (array, if dXvals is provided) – A vector with the corresponding dXvals value for each returned DOF value.

getSystemStiffness(DOFtype='free', dx=0.1, dth=0.1, solveOption=1, lines_only=False, plots=0)

Calculates the stiffness matrix for all selected degrees of freedom of a mooring system whether free, coupled, or both (other DOFs are considered fixed).

Parameters

DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.
dx (float, optional) – The change in displacement to be used for calculating the change in force. The default is 0.1.
dth (float, optional) – The change in rotation to be used for calculating the change in force. The default is 0.1.
solveOption (boolean, optional) – Indicator of which solve option to use. The default is 1.
plots (boolean, optional) – Determines whether the stiffness calculation process is plotted and/or animated or not. The default is 0.

Raises

ValueError – If the solveOption is not a 1 or 0

Returns

K – nDOF x nDOF stiffness matrix of the system

Return type

matrix

getSystemStiffnessA(DOFtype='free', lines_only=False, rho=1025, g=9.81)

A method to calculate the system’s stiffness matrix based entirely on analytic gradients from catenary

Parameters

DOFtype (string, optional) – specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is “free”.
hydro (bool, optional <<<<< replaced this with lines_only for now for consistency with others. Could reconsider (for all functions)) – specifies whether to include hydrostatic stiffness components of bodies. The default is 0 (to not include).
rho (float, optional) – DESCRIPTION. The default is 1025.
g (float, optional) – DESCRIPTION. The default is 9.81.

Raises

ValueError – Raised if an invalid DOFtype is used.

Returns

K – complete analytic stiffness matrix of the system for the specified DOFs.

Return type

matrix

getTensions()

Returns a vector with the line end tensions for all lines in the system.

Returns: T – The tension values for all line ends A then all line ends B [N].
Return type: array

initialize(plots=0)

Initializes the mooring system objects to their initial positions

Parameters: plots (bool, optional) – toggle to plot the system at initialization or not. The default is 0.
Returns
Return type: None.

load(filename)

Loads a MoorPy System from a MoorDyn-style input file

Parameters: filename (string) – the file name of a MoorDyn-style input file.
Raises: ValueError – DESCRIPTION.
Returns
Return type: None.

mooringEq(X, DOFtype='free', lines_only=False, tol=0.001, profiles=0)

Error function used in solving static equilibrium by calculating the forces on free objects

Parameters

X (array) – A list or array containing the values of all relevant DOFs – for bodies first, then for points. If type is ‘both’, X provides the free DOFs followed by the coupled DOFs.
DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.
tol (float, optional) – Tolerance to use in catenary calculations [m].

Returns

f – The forces (and moments) on all applicable DOFs in the system. f is the same size as X.

Return type

array

parseYAML(data)

Creates a MoorPy System from a YAML dictionary >>> work in progress <<<

Parameters: data (dictionary) – YAML dictionary to be parsed through.
Raises: ValueError – DESCRIPTION.
Returns
Return type: None.

plot(ax=None, bounds='default', rbound=0, color=None, **kwargs)

Plots the mooring system objects in their current positions :param bounds: signifier for the type of bounds desired in the plot. The default is “default”. :type bounds: string, optional :param ax: Plot on an existing set of axes :type ax: axes, optional :param color: Some way to control the color of the plot … TBD <<< :type color: string, optional :param hidebox: If true, hides the axes and box so just the plotted lines are visible. :type hidebox: bool, optional :param rbound: A bound to be placed on each axis of the plot. If 0, the bounds will be the max values on each axis. The default is 0. :type rbound: float, optional :param title: A title of the plot. The default is “”. :type title: string, optional :param linelabels: Adds line numbers to plot in text. Default is False. :type linelabels: bool, optional :param pointlabels: Adds point numbers to plot in text. Default is False. :type pointlabels: bool, optional :param endpoints: Adds visible end points to lines. Default is False. :type endpoints: bool, optional :param bathymetry: Creates a bathymetry map of the seabed based on an input file. Default is False. :type bathymetry: bool, optional

Returns

fig (figure object) – To hold the axes of the plot
ax (axis object) – To hold the points and drawing of the plot

plot2d(Xuvec=[1, 0, 0], Yuvec=[0, 0, 1], ax=None, color=None, **kwargs)

Makes a 2D plot of the mooring system objects in their current positions

Parameters

Xuvec (list, optional) – plane at which the x-axis is desired. The default is [1,0,0].
Yuvec (lsit, optional) – plane at which the y-axis is desired. The default is [0,0,1].
ax (axes, optional) – Plot on an existing set of axes
color (string, optional) – Some way to control the color of the plot … TBD <<<
title (string, optional) – A title of the plot. The default is “”.

Returns

fig (figure object) – To hold the axes of the plot
ax (axis object) – To hold the points and drawing of the plot

plotEQsolve(iter=- 1): Plots trajectories of solving equilibrium from solveEquilibrium.

setPositions(X, DOFtype='free')

Sets the DOF values of some objects in the System - ‘free’ objects, ‘coupled’ objects, or ‘both’.

Parameters

X (array) – A list or array containing the values of all relevant DOFs – for bodies first, then for points. If type is ‘both’, X provides the free DOFs followed by the coupled DOFs.
DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.

solveEquilibrium(DOFtype='free', plots=0, tol=0.05, rmsTol=0.0, maxIter=500, display=0, no_fail=False, finite_difference=False)

Solves for the static equilibrium of the system using the dsolve function approach in MoorSolve

Parameters

DOFtype (string, optional) – Specifies whether to consider ‘free’ DOFs, ‘coupled’ DOFs, or ‘both’. The default is ‘free’.
plots (int, optional) – Determines whether to plot the equilibrium process or not. The default is 0.
tol (float, optional) – The absolute tolerance on positions when calculating equilibriumk [m]
maxIter (int, optional) – The maximum number of interations to try to solve for equilibrium. The default is 200.
no_fail (bool) – False raises an error if convergence fails. True doesn’t.
finite_difference (bool) – False uses the analytical methods for system stiffness, true uses original finite difference methods.

Raises

SolveError – If the system fails to solve for equilibrium in the given tolerance and iteration number

Returns

success – True/False whether converged to within tolerance.

Return type

bool

transform(trans=[0, 0], rot=0, scale=[1, 1, 1])

Applies scaling (can flip if negative), rotation, and translations (in that order) to the mooring system positions

Parameters

trans (array, optional) – how far to shift the whole mooring system in x and y directions [m]. The default is [0,0].
rot (float, optional) – how much to rotate the entire mooring system in the yaw direction [degrees]. The default is 0.
scale (array, optional) – how much to scale the mooring system x and y dimensions by (relative) (NOT IMPLEMENTED). The default is [1,1] (unity).

unload(fileName, MDversion=2, **kwargs)

Unloads a MoorPy system into a MoorDyn-style input file

Parameters

fileName (string) – file name of output file to hold MoorPy System.
**kwargs (TYPE) – DESCRIPTION.

Returns

Return type

None.

unload_farm(fileName, depth=600): Unloads a MoorPy system into a MoorDyn FAST.Farm input file