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, pointProps=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, pointProps=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.
bathymetry (filename, optional) – Filename for MoorDyn-style bathymetry input file.

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. If dynamic stiffnesses are already activated, it does nothing. 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.]), DOFs=[0, 1, 2, 3, 4, 5])

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:

Body

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:

Line

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:

Point

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

disconnectLineEnd(lineID, endB): Disconnects the specified end of a Line object from whatever point it’s attached to, and instead attaches it to a new free point.

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)

getCost(): Fill in and return a cost dictionary for the System.

getCoupledDynamicMatrices(lines_only=False): Write something here later

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)

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

Parameters:

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, normal=True)

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)
normal (bool) – Whether to also return the normal vector (default True).

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.

getSystemDynamicMatrices(DOFtype='free', lines_only=False): Write something here later

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 plot_box: If false, hides the axes and box so just the plotted lines are visible. :type plot_box: 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 plot_linelabels: Adds line numbers to plot in text. Default is False. :type plot_linelabels: bool, optional :param plot_pointlabels: Adds point numbers to plot in text. Default is False. :type plot_pointlabels: bool, optional :param plot_endpoints: Adds visible end points to lines. Default is False. :type plot_endpoints: 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)

saveMaxTensions(T): Store max tensions at each line computed elsewhere for later use in MoorPy (e.g., for computing anchor costs).

setBathymetry(x, y, depth)

Provide a System with existing bathymetry data, rather than having it read in its own data and store it locally. This allows reuse of bathymetry grid data that may be stored elsewhere. It saves a ref.

Parameters:

x (list or array) – X coordinates of rectangular bathymetry grid [m].
y (list or array) – Y coordinates of rectangular bathymetry grid [m].
depth (2D array) – Matrix of depths at x and y locations [m]. Positive depths. Shape should be [len(x), len(y)]

setLineType(dnommm=None, material=None, source=None, name='0', mass=None, d_vol=None, w=None, EA=None, lineType=None, overwrite=True, **kwargs)

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

Parameters:

dnommm (float, optional) – nominal diameter [mm]. Default is None
material (string, optional) – string identifier of the material type be used. Default is None
source (dict or filename (optional)) – YAML file name or dictionary containing line property scaling coefficients. If not provided but dnommm and material have been provided, whatever has already been loaded into the MoorPy system will be used.
name (string (optional)) – Identifier for the line type. Default is “0”
mass (float, optonal) – mass/m [kg/m] of mooring line material. Default is None. Not needed if dnommm and material or lineType provided unless mass does not follow scaling
d_vol (float, optional) – volumetric diameter [m]. Default is None. Not needed if dnommm and material or lineType provided unless d_vol does not follow scaling
w (float, optional) – weight/m [N/m] of mooring line material. Default is None. Not needed if dnommm and material or lineType provided unless w does not follow scaling
EA (float, optional) – stiffness [N] of mooring line material. Default is None. Not needed if dnommm and material or lineType provided unless EA does not follow scaling
lineType (dict, optional) – Dictionary containing line type properties such as m, material, EA, d_nom If lineType provided, none of the previous inputs are required.
overwrite (bool, optional) – Controls whether or not to overwrite a lineType that has the same string identifier as the input name. Default is True.

Return type:

lineType

setPointType(design, source=None, name='', **kwargs)

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

Parameters:

design (string or dict) – design keyword from DesignProps or dictionary with num_a_<anchor key>, num_b_<buoy key>, num_c_<connect key> entries
source (dict or filename (optional)) – YAML file name or dictionary containing point property scaling coefficients and design properties. If not provided, whatever has already been loaded into the MoorPy system will be used.
name (string (optional)) – Identifier for the point type (otherwise wll be generated automatically).

Returns:

pointType – A pointType structure agnostic of point size

Return type:

dict

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=[], Lm=[0], T_half=42, phi=None, dynamicStiffness=False, cleanLineTypeName=False, MDoptionsDict={})

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
Lm (list of floats) – Mean load on mooring line as FRACTION of MBL, used for dynamic stiffness calculation. Only used if line type has a nonzero EAd. Can either be a list with a single Lm to be assumed for all line types, or a list of Lm values with length equal to the number of lines with a nonzero EAd
T_half (float, optional) – For tuning response of viscoelastic model, the period when EA is half way between the static and dynamic values [s]. Default is 42.
phi (list of floats, optional) – platform’s rotations variables [deg]. Defaults to None and platforms are not unrotated.
dynamicStiffness (float) – if true, automatically activateDynamicStiffness to calculate dynamic EA
MDoptionsDict (dictionary, optional) – MoorDyn Options. If not given, default options are considered.
cleanLineTypeName (bool, optional) – If true, line type names will be renamed to “type_{counter}” to avoid long names that may cause issues in MoorDyn.

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.

updateSystemDynamicMatrices(omegas=array([0.]), S_zeta=array([0.]), seabed_tol=0.0001)

Updates the dynamic matrices of all the lines in the system. Works only with lumped mass approach (MoorDyn input file) This function can only properly update/compute the inertia, added mass, and stiffness matrices of each line in the system.

This function also updates the damping matrix, but this is done considering unitary amplitude motions of the nodes, which is not correct. If omegas and S_zeta are provided, the damping matrix will account for wave kinematics as well, but that would still be wrong

To properly compute the damping matrix, you should call line.updateLumpedMass externally providing the motion RAOs of the line ends.