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, lineProps=None, **kwargs)

A class for the whole mooring system

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

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.

Return type:

None.

activateDynamicStiffness(display=0): Switch mooring system model to dynamic line stiffness values and adjust the unstretched line lengths to maintain the same tensions. This only has an effect when dynamic line properties are used.

addBody(mytype, r6, m=0, v=0, rCG=array([0., 0., 0.]), AWP=0, rM=array([0., 0., 0.]), f6Ext=array([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).

Return type:

None.

addLine(lUnstr, lineType, 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].
lineType (string or dict) – string identifier of lineType for this line already added to the system, or dict specifying custom line type.
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.

Return type:

None.

addLineType(type_string, d, mass, EA, name='')

Convenience function to add a LineType to a mooring system or adjust the values of an existing line type if it has the same name/key.

Parameters:

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

Return type:

None.

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

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].
body (int, optional) – ID of body that point is attached to, in which case r is the relative position on the body.

Return type:

None.

addRod(rodType, rA, rB, nSegs=1, bodyID=0): draft method to add a quasi-Rod to the system. Rods are not yet fully figured out for MoorPy

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)

animateLines(figure=None, axis=None, color=None, 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.
runtime (int, optional) – The desired time that the animation should run to in seconds. The default is -1, which means to run the full simulation

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

animateSolution(DOFtype='free')

Creates an animation of the system

Return type:: None.

checkTensions(N=None): Checks the line tensions and MBLs of a MoorPy system in its current state with the quasi-static model. Returns: list of tension/MBL for each line. :param N: Number of timesteps to skip for transients :type N: int, only required if qs == 0

getAnchorLoads(sfx, sfy, sfz, N)

Calculates anchor loads :param sfx: Safety factor for forces in X direction :type sfx: float :param sfy: Safety factor for forces in Y direction :type sfy: float :param sfz: Safety factor for forces in Z direction :type sfz: float :param N: Number of timesteps to skip for transients :type N: int

Return type:: Array of maximum anchor loads in order of fixed points (tons)

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

getCoupledStiffnessA(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 - analytical appraoch.

Parameters:

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

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.

getDepthFromBathymetry(x, y)

interpolates local seabed depth and normal vector

Parameters:

x (float) – x and y coordinates to find depth and slope at [m]
y (float) – x and y coordinates to find depth and slope at [m]

Returns:

depth (float) – local seabed depth (positive down) [m]
nvec (array of size 3) – local seabed surface normal vector (positive out)

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.
Return type:: None.

load(filename, clear=True)

Loads a MoorPy System from a MoorDyn-style input file

Parameters:

filename (string) – the file name of a MoorDyn-style input file.
clear (boolean) – Starts from a clean slate when true. When false, will build on existing mooring system objects.

Raises:

ValueError – DESCRIPTION.

Return type:

None.

loadData(dirname, rootname, sep='.MD.'): Loads time series data from main MoorDyn output file (for example driver.MD.out) :param dirname: Directory name :type dirname: str :param rootname: MoorDyn output file rootname :type rootname: str :param sep: MoorDyn file name seperator :type sep: str

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.
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.

revertToStaticStiffness(): Revert mooring system model back to the static stiffness values and the original unstretched lenths.

ropeContact(lineNums, N)

Determines whether Node 1 is off the ground for lines in lineNums :param lineNums: Line number to calculate rope contact for corresponds to MoorDyn file ***STARTS AT 1 :type lineNums: list of integers :param N: Number of timesteps to skip for transients :type N: int

Returns:: min_node1_z – Minimum height of node 1 above seabed for lines in lineNums (m)
Return type:: list of floats

sagDistance(lineNums, N)

Calculates sag distance for center node for each line in lineNums :param lineNums: Line number to calculate sag distance for corresponds to MoorDyn file ***STARTS AT 1 :type lineNums: list of integers :param N: Number of timesteps to skip for transients :type N: int

Returns:

minsagz (list of floats) – Minimum distance below waterline for center node in order of lines in lineNums(m)
maxsagz (list of floats) – Maximum distance below waterline for center node in order of lines in lineNums (m)

setLineType(dnommm, material, source=None, name='', **kwargs)

Add or update a System lineType using the new dictionary-based method.

Parameters:

dnommm (float) – nominal diameter [mm].
material (string) – string identifier of the material type be used.
source (dict or filename (optional)) – YAML file name or dictionary containing line property scaling coefficients. If not provided, whatever has already been loaded into the MoorPy system will be used.
name (string (optional)) – Identifier for the line type (otherwise will be generated automatically).

Return type:

None.

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’.

setRodType(d, name='', **kwargs): hasty replication of setLineType for rods

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, line_dL=0, rod_dL=0, flag='p', outputList=[])

Unloads a MoorPy system into a MoorDyn-style input file

Parameters:

fileName (string) – file name of output file to hold MoorPy System.
line_dL (float, optional) – Optional specified for target segment length when discretizing Lines
rod_dL (float, optional) – Optional specified for target segment length when discretizing Rods
outputList (list of strings, optional) – Optional list of additional requested output channels

Return type:

None.

unload_md_driver(outFileName, outroot='driver', MDinputfile='test.dat', depth=600)

Function to output moordyn driver input file :param outFileName: :type outFileName: moordyn driver input file name :param outroot: :type outroot: root name for output files (ex if outroot = ‘driver’, the MD output file will be driver.MD.out) :param MDinputfile: :type MDinputfile: name of the moordyn input file :param depth: :type depth: water depth

Return type:: None.

updateCoords(tStep, colortension, cmap_tension, label, dt): Update animation function. This gets called by animateLines every iteration of the animation and redraws the lines and rods in their next positions.