Deck format reference (.dat)
This page is for anyone writing or editing a CableDyn input deck. It defines every section,
column, keyword, default, and error rule of the sectioned .dat deck read by the standalone
driver (CableDyn_driver, built as cabledyn), the CableDyn module of OpenFAST
(CompMooring = 5; OpenFAST is maintained by NLR, the National Laboratory of the Rockies,
formerly NREL), the C API, and the Python package.
The deck is a MoorDyn-style deck: it uses MoorDyn v2 section names, columns, point types, and
option keywords, and it reads stock MoorDyn line rows unchanged. CableDyn adds an optional
SECTIONS table, so one line can carry several line types (see
LINES + SECTIONS).
Related pages: Conventions, the OPTIONS reference, Auxiliary file formats, Outputs, and the coupling boundary.
Principles
MoorDyn v2 vocabulary. Where CableDyn adds capability (finite-EI bending, Newton static initial condition), the deck extends MoorDyn and never contradicts it.
Fail closed. Every section, column, and keyword is either supported on a route or rejected at parse with an error that names the feature. Nothing is silently solved as something else.
SI units. Metres, kilograms, newtons and seconds. Angles are in degrees: body attitudes, wave directions,
vesselMotionandTURBINESattitudes, RAO phases and every output angle. Radians appear only where a row says so: angular rates in motion records, wave frequencies, rotational stiffnesses per radian and the MoorDyn-CWaveKin 7direction. There is no unit conversion. Tensions are written in N.Line-oriented, case-insensitive keywords. Blank lines are ignored. Section headers are a name inside a rule of dashes. Table sections skip their column-name and units rows; columns are positional. Comment rules are in Records, comments, and tokens.
Whole-token values. Columns are whitespace-separated. A numeric value is one plain number with a
.decimal point. An unquoted value containing/,,or;, or a repeat count such as2*0.0, is rejected, never read partially (500/2is never500;400,0never shifts the columns). Quote text values that need these characters. TheSYROPE:<path>|alpha|betaEA column and file-path options accept unquoted/and\; paths must not contain spaces,#, or!. Comma lists are accepted only where the grammar names them: FAILURE and CONTROL line lists, SYROPE IC line ids, and OUTPUTS channels. Parse errors name the deck line and quote the row; duplicate and undefined ids are named. Numbers follow the Fortran real syntax, in which the exponent letter may be omitted:1.5-3is read as1.5e-3and3.0+6as3.0e6. MoorDyn’s C reader takes such a token as1.5and3.0, so write exponents withe(1.5e-3) in a deck meant for both codes.
Records, comments, and tokens
These rules apply to every deck record. Auxiliary files (motion history, bathymetry, Syrope tables) use the same comment and record-length rules.
Rule |
Behaviour |
|---|---|
Encoding |
UTF-8. A byte-order mark at the start of the file is ignored. File names inside the deck are UTF-8 (see File names). |
|
start a comment anywhere in a record, including inside a quoted value or a file path. The rest of the record is ignored. |
|
starts a comment only at the start of a record or after whitespace, and only in a record that contains no |
|
a record containing three consecutive dashes is a section header; the non-dash text of the whole record is the section name, so a long title banner such as |
Record length |
at most 512 characters of non-comment text. A longer record fails with |
Blank records |
a record holding only whitespace (after its comment is removed) is skipped anywhere, OPTIONS included. |
Table header rows |
in table sections, a row with no numeric token is a column-name or units row and is skipped. |
Tokens |
separated by ASCII whitespace: space, tab, carriage return, line feed, form feed, or vertical tab. A quoted token may contain spaces. Numeric columns take one plain number (Principle 5). |
Rejected characters |
a NUL character, or a non-ASCII whitespace character such as a no-break space (U+00A0) or an ideographic space (U+3000), outside a comment fails with |
Identifiers |
line-type names, rod-type names, point and body types, |
Error location |
row-level errors read |
Values |
every number in a deck row, an OPTIONS row, or an auxiliary file must be finite and not subnormal: |
Table rows are filtered strictly. In LINE TYPES, BODIES, ROD TYPES, RODS, POINTS, LINES,
SECTIONS, EQUIVALENT BUOYANCY, and END CONNECTIONS, an unquoted token containing /, , or ;,
or of the form n*value, fails as column C value "X" contains .... The one exception is LINE
TYPES column 4 (EA), which is read as text so that SYROPE:<path>|alpha|beta can hold a path.
Only text columns (names, types, Outputs flags, EA/BA, END CONNECTIONS End/Stiffness) may be
quoted; a quoted number or id fails as column C must be an unquoted number. A token that opens a
quote must hold non-empty text inside one pair of matching quotes. LINES attachments (NodeA,
NodeB, AttachA, AttachB) are an unquoted point id or rod end (R<N>A, R<N>B) taken whole:
"1", 1x, or "1 x" fails as malformed LINES row.
FAILURE, CONTROL, and SYROPE IC rows are split on whitespace and parse their comma lists
strictly. OUTPUTS rows are split on whitespace and commas.
Admissible input ranges
Beyond these magnitudes the solver’s force, length, or time scales overflow instead of failing to converge, so a deck outside them is rejected at validation with a message that names the limit.
Quantity |
Admissible range |
|---|---|
Point, body, rod, and turbine coordinates; |
magnitude at most 1e6 m |
|
> 0 and at most 1e3 m/s² |
|
> 0 and at most 1e5 kg/m³ |
|
magnitude at most 1e15 |
LINE TYPES |
at least 1e-3 N and at most 1e15 N |
LINE TYPES |
at least 1e-6 m and at most 1e3 m |
LINE TYPES |
at most 1e15 |
LINE TYPES |
0 to 1e3 |
POINTS |
magnitude at most 1e15 |
POINTS and body |
magnitude at most 1e3 |
Current velocity components (OPTION, WaterKin, |
magnitude at most 1e3 m/s |
Wave height (regular and spectral), WaveKinMod 1 component amplitude |
at most 1e3 m |
Wave period; JONSWAP |
0.1 s to 1e5 s; |
WaveKinMod 1 component frequency |
at most 1e4 rad/s |
|
position ≤ 1e6 m, velocity ≤ 1e4 m/s, acceleration ≤ 1e6 m/s² in magnitude |
|
every value at most 1e6 in magnitude |
Syrope |
1e-6 to 700 |
File names
A file name written in the deck (motionFile, bathymetryFile, WaterKin, a Syrope
settings file, and the files those name) is read as UTF-8, the same as the deck path and
output root given on the command line, so names in any script are allowed. On Windows the
driver opens exactly the named file or refuses it with a reason; it never falls back to a
look-alike name (café is never read as cafe):
the release executables (
CableDyn_driver.exeandopenfast.exe) run with UTF-8 as their Windows code page (Windows 10 version 1903 or later), so every name, and every working folder, is opened as written whatever the system locale;a driver built from source with the GNU toolchain uses the system ANSI code page instead: a name that code page cannot spell is opened through the 8.3 short name of the file or of its folder, and on a volume without 8.3 names it is refused with
the name has characters the Windows ANSI code page cannot represent ..., as is an output root whose own final name has such characters;a path longer than 259 characters is opened through its short or extended-length (
\\?\) spelling, else refused as too long;a reserved device name (
CON,PRN,AUX,NUL,COM1-COM9,LPT1-LPT9, with any extension and in any folder) is refused withthe name is a reserved Windows device, because opening it reads the console or discards the data.
Other systems open the UTF-8 name as given.
Section structure
A section begins at its header and ends at the next header. Sections may appear in any order,
except that SYROPE IC must come after LINES, because its rows name lines that must already
exist. A conventional layout is:
LINE TYPES → BODIES → EXTERNAL LOADS → ROD TYPES → RODS → POINTS → TURBINES → LINES → SYROPE IC → SECTIONS → END CONNECTIONS / EQUIVALENT BUOYANCY / ATTACHMENTS / STIFFENERS / VIV / WAKE OSCILLATOR / VIV AMPLITUDE / VIV DIAMETER / VIV DAMPING / VIV FRAME / VIV STOCHASTIC / FAILURE / CONTROL → OPTIONS → OUTPUTS
Within LINE TYPES, the header row must precede the data rows because it selects their column order.
A line is one object spanning two end points (End A = NodeA, End B = NodeB), built from
an ordered list of sections, each with its own line type and mesh density (the same
line-and-section arrangement OrcaFlex uses): a bare cable and a buoyancy stretch are sections of
one line, and a bend stiffener over its end is a STIFFENERS
row. A single-material line is one section. MoorDyn composites written
as separate lines
joined at a Connect point are also valid.
--------------------- CableDyn Input File ------------------------------------
Composite chain-wire mooring, fairlead to anchor
--------------------- LINE TYPES ---------------------------------------
TypeName Diam MassDenInAir EA BA/-zeta EI Cd_n Cd_t Ca_n Ca_t
(-) (m) (kg/m) (N) (N-s/-) (N-m^2) (-) (-) (-) (-)
chain155 0.252 390.0 1.674e9 -1.0 0.0 1.37 0.64 1.0 0.0
wire 0.20 90.0 7.0e8 -1.0 0.0 1.2 0.05 1.0 0.0
--------------------- POINTS -------------------------------------------
ID Type X Y Z Mass Vol CdA Ca
(-) (-) (m) (m) (m) (kg) (m^3) (m^2) (-)
1 Fixed 400.0 0.0 -50.0 0 0 0 0
2 Coupled 0.0 0.0 0.0 0 0 0 0
--------------------- LINES --------------------------------------------
ID NodeA NodeB Outputs
(-) (-) (-) (-)
1 2 1 -
--------------------- SECTIONS -----------------------------------------
LineID LineType Length NumSegs
(-) (-) (m) (-)
1 chain155 350.0 35
1 wire 60.0 20
--------------------- OPTIONS ------------------------------------------
9.80665 g - Gravitational acceleration (m/s^2)
1025.0 rhoW - Water density (kg/m^3)
50.0 WtrDpth - Water depth (m)
1.0e5 kBot - Seabed penalty stiffness base (Pa/m)
1.0e4 cBot - Seabed normal damping base (Pa-s/m)
--------------------- OUTPUTS ------------------------------------------
"FairTen1"
"AnchTen1"
"FairIncl1"
"AnchIncl1"
"Point2px"
"Point2py"
"Point2pz"
--------------------- need this line -----------------------------------
The example decks in examples/ start with the CableDyn Input File banner shown above, followed
by a free-form title line. Auxiliary data tables referenced by a deck, such as a Syrope working
curve, keep their own headers.
Section headers and aliases
The header name is compared case-insensitively after the dashes are removed and runs of spaces
are collapsed. It must match one of the spellings below; any other name fails with
unknown deck section "<NAME>".
Section |
Accepted header names |
|---|---|
LINE TYPES |
|
BODIES |
|
ROD TYPES |
|
RODS |
|
POINTS |
|
LINES |
|
SECTIONS |
|
SYROPE IC |
|
END CONNECTIONS |
|
EQUIVALENT BUOYANCY |
|
ATTACHMENTS |
|
STIFFENERS |
|
VIV |
|
WAKE OSCILLATOR |
|
VIV AMPLITUDE |
|
VIV DIAMETER |
|
VIV DAMPING |
|
VIV FRAME |
|
VIV STOCHASTIC |
|
FAILURE |
|
CONTROL |
|
TURBINES |
|
EXTERNAL LOADS |
|
OPTIONS |
|
OUTPUTS |
|
Four header forms close the current section without opening a new one; records after them are ignored until the next recognised header:
a bare rule of dashes;
a header named
END;any header whose name contains
NEED(the stockneed this linefooter);any header whose name contains
INPUT FILE(the title banner, such as--- CableDyn Input File ---or--- MoorDyn Input File ---). The title line after it is therefore ignored.
Inside OUTPUTS, a row whose first token is END also closes the channel list.
LINE TYPES
Column |
Meaning |
Notes |
|---|---|---|
|
unique key referenced by LINES / SECTIONS |
duplicate names (case-insensitive) are rejected |
|
hydrodynamic / volume-equivalent diameter [m] |
used for submerged weight, drag, and added mass; at least 1e-6 and at most 1e3 where used |
|
dry mass per unstretched metre [kg/m] |
submerged weight = (m − ρ_w·πd²/4)·g; its magnitude at most 1e6 where used |
|
axial stiffness [N] |
linear (T = EA·ε); at least 1e-3 and at most 1e15 where used; see the viscoelastic and Syrope forms below |
|
axial damping: ≥ 0 is BA [N·s], < 0 is −ζ (damping ratio): by default (MoorDyn’s convention) of each segment, BA = ζ L0 √(EA m) per element, which damps the line’s first axial mode at about ζ π/(2N) on N elements and so depends on the mesh (a run notes the ratio); under |
active in EI = 0 and finite-EI dynamics; ignored in a static-only run |
|
bending stiffness [N·m²]; `EI |
Bb |
|
normal / tangential drag coefficients |
used by EI = 0 dynamic current and Airy-wave runs |
|
normal / tangential added-mass coefficients |
used by EI = 0 dynamic Froude–Krylov and added-mass runs |
Every numeric property must be finite.
Column order from the header row. The stock MoorDyn header names its four hydrodynamic
columns Cd Ca CdAx CaAx (normal drag, normal added mass, axial drag, axial added mass); the
CableDyn order is Cd_n Cd_t Ca_n Ca_t. The data rows cannot distinguish the two, so the header
row decides:
a header containing
CdAxorCaAxselects the stock order;a header containing
CdtorCd_tselects the CableDyn order;with neither, the CableDyn order is used.
A stock-order header applies only to the 10-column row.
Optional finite-EI columns. A 14-column row adds GAs, GJ, Irt, Irn (shear stiffness,
torsional stiffness, transverse and polar (axial) rotary inertia per length):
Name Diam Mass EA BA EI GAs GJ Irt Irn Cd_n Cd_t Ca_n Ca_t. The four extra values must be finite
and either all 0 or all > 0. All zero, or the 10-column row, selects the circular-section
closure GAs = EA/(2(1+0.3)), GJ = EI/(1+0.3), Irt = m d²/16, Irn = m d²/8. The closure
serves the secondary Cosserat library path only: a finite-EI line restrained in torsion
(END CONNECTIONS) takes GJ [N·m²/rad] from the
14-column row of each of its sections and stops by name without it. In the dynamics such a line
carries a twist angle at every node, whose polar rotary inertia is Irn [kg·m²/m]
(m r²/2 for a solid round section; see Nodal twist): give the section’s real
value, as a placeholder Irn gives the line a wrong torsional inertia. GAs and Irt are not
used by the cubic-Hermite route, but the all-or-nothing rule still asks for positive values.
The GJ column may be written GJ|K, with K [N·m] the torque–tension coupling of an armoured
cable or wire rope (T = EA ε + K τ, M = GJ τ + K ε; see
Torque–tension coupling). It needs a finite-EI, linear-elastic type with
K² < EA·GJ. GJ|0 is the plain GJ.
GJ|K|Bt adds the torsional damping Bt [N·m²·s] of the nodal twist (the torque
Bt dτ/dt, stiffness-proportional: a torsional mode of frequency ω has the damping ratio
ω Bt/(2 GJ)); a negative Bt is -ζ, the fraction of an element’s critical torsional damping
l0 √(GJ Irn) on the final mesh, as BA is for the axial damping (an element whose length
active line control changes keeps its ζ). It needs a finite-EI type; GJ|0|Bt is damping
without coupling.
Bending damping. The EI column may be written EI|Bb, with Bb [N·m²·s] the bending
Kelvin–Voigt damping of a finite-EI cable: a damping moment Bb times the rate of the curvature
vector, taken in the frame carried with the cable’s tangent (see Bending damping). It
is stiffness-proportional: a bending mode of frequency ω whose strain energy is all bending has
the damping ratio ω Bb/(2 EI), and a mode that tension also stiffens is damped only in its
bending share, ω Bb/(2 EI) · EI k²/(EI k² + T) for a uniform cable of wavenumber k under
tension T. EI|-zeta|f gives it as the damping ratio 0 < ζ < 1 of a pure bending mode of
frequency f [Hz], Bb = ζ EI/(π f), set once per line type (it does not depend on the mesh).
EI|0 is the plain EI. It needs EI > 0 and acts in the dynamics only (a static solve has no
rates).
Rayleigh damping. EI|-zeta|f1|f2 gives the ratio 0 < ζ < 1 at two frequencies f1 and f2
[Hz]: beside the bending damping Bb = ζ EI/(π (f1 + f2)) it adds a mass-proportional transverse
damping α = 4π ζ f1 f2/(f1 + f2) [1/s], the force α m (m the line’s mass per metre) on the
velocity normal to the cable’s tangent (see Mass-proportional damping). A mode then
has ζ(ω) = α/(2ω) + ω Bb/(2 EI) · EI k²/(EI k² + T): ζ at f1 and f2 for a mode whose
stiffness is all bending, less between them and more outside. In water the α share falls with
the added mass, m/(m + m_a). The velocity is absolute, so the term also damps the rigid
transverse motion and pendulum swing of a span, increasingly below f1 (α/(2ω)): set f1 at
the lowest frequency of interest. It needs EI > 0, is set once per line type and acts in the
dynamics only.
Cross-flow VIV columns (MoorDyn v2). A 10-column row may end with Cl (11 columns) or
Cl dF cF (13 columns), and a 14-column row likewise (15 or 17 columns, so a line restrained in
torsion can carry VIV): the lift coefficient of the vortex-shedding synchronisation model and
the half-range and centre of its band in non-dimensional frequency (MoorDyn’s dF = 0.08 and
cF = 0.18 when only Cl is given). Cl = 0 is no VIV; Cl > 0 needs cF > 0 and
0 <= dF < cF, and the line’s drag in water. It acts in the dynamics on EI = 0 lines and
finite-EI cables (see Cross-flow VIV). The in-line force of a type is a
VIV section row; a WAKE OSCILLATOR row replaces the
lift by a wake oscillator, a VIV AMPLITUDE table makes Cl (and
Cd) depend on the cross-flow amplitude, a VIV DIAMETER row gives
the VIV a diameter of its own, and a VIV DAMPING row splits
the drag into an in-line and a cross-flow part with its own law.
Viscoelastic axial stiffness (MoorDyn ElasticMod). The EA and BA columns accept
bar-separated parts:
EA form |
Model |
Rules |
|---|---|---|
|
linear |
BA is one value |
|
constant dynamic stiffness |
|
|
load-dependent dynamic stiffness |
|
With a two- or three-part EA, BA may be Bs or Bs|Bd, with Bd finite and ≥ 0. BA never has
more parts than EA, and at most two. Viscoelastic types require EI = 0.
Syrope polyester (MoorDyn-F/C working-curve model). Use EA = SYROPE:<settings>|alpha|beta
and BA = BA_s|BA_d:
EA has exactly three parts;
alphaandbetaare finite and > 0.BA has exactly two parts; both are ≥ 0 and their sum is > 0.
The settings file, resolved relative to the deck, holds
OWC,WCType(LINEAR,QUADRATIC, orEXP),k1, andk2rows asvalue name.OWCnames the original-working-curve table, resolved relative to the settings file: astrain tensiontable of at least two numeric rows.BA_denters the slow-state rate; the physical damping contribution isBA_s*d(eps_slow)/dt.A Syrope type requires
EI = 0. A Syrope line is either a single section, taut at initialisation, or a composite line whose other sections are linear-elasticEI = 0sections (a chain–polyester–chain mooring), with every Syrope element in tension at initialisation. It runs on a dynamic deck (dtM/TMax) and takes the seabed,bathymetryFile, Morison loads, current, waves, host fluid fields and VIV of anyEI = 0line, and active line control of a Syrope segment on the OpenFAST route (CONTROL).The static start solves each Syrope element on the rest curve of its load history (the OWC, or the
Tmax0working curve underSYROPE IC). The tension varies along a Syrope section (a sagging section of a composite line, or the weight of a long or inclined taut rope), so every Syrope element takes its own secant EA at its own tension: every element starts on its curve and the dynamics start in the static equilibrium.
The settings-file grammar is in Auxiliary file formats.
EI routing
EI = 0 uses the positions-only cable path on every route. Non-finite or negative EI is
rejected. EI > 0 is routed as follows.
Standalone dynamic run (dtM/TMax set):
Finite-EI lines whose End B is a
Fixed,CoupledorVesselpoint run on the cubic-Hermite route. It covers suspended spans, motion-file, current, and wave cases, and flat or structured seabed contact. Contact uses a C1 normal penalty, compression-only normal damping, and stick-slip seabed friction, each scaled by nodal diameter × tributary length. Slack spans with both endpoints above the bed start from an isometric two-touchdown seed.A line whose End B is a
Coupled/Vesselpoint (a line between two moving points, such as a cable shared by two floaters or aTURBINESshared line) has both ends driven: End B moves with the same motion table as End A (motionFilerows, thevesselMotion/vesselRAOvessel and its rotation,TURBINESrows, themotionFileroll column) and is held where no motion is given. Its static solve is that of aFixedEnd B at its deck position, so aCoupledEnd B the motion leaves at rest is theFixedEnd B, byte for byte.staticsFriction asLaidis refused on such a line (it has no anchored end to lay the line from).A deck whose finite-EI lines are its only lines and whose endpoints are all
Fixed/Coupled/Vesselruns on this route; with EI = 0 lines beside them it is a standalone mixed deck (below). With BODIES, RODS, orConnect/Freepoints it runs on the multibody march.When
motionFilerow 1 differs from the deck fairlead, CableDyn installs that boundary state and the initial fluid field, then recomputes the free-node acceleration from the full structural, contact, and hydrodynamic residual before writingt = 0(also withTMax = 0). The.static.outprofile is written before that, so it holds the static solve.
Standalone mixed deck (separate EI = 0 and EI > 0 lines between Fixed/Coupled/Vessel
points only): the deck is partitioned through the same atomic aggregate used by OpenFAST.
Coupled/Vessel endpoints are held at their deck positions, or follow a motionFile or
vesselMotion as on the cubic-Hermite route: row 1 is installed and the cables’ free-node
accelerations recomputed before t = 0 (also with TMax = 0, whose .out row is then that
state; .static.out holds the static solve), a vessel turns the end connection and torsion
frames of the cables on its points, and the roll column imposes the twist of a line restrained
in torsion. The row-1 transfer also re-derives the interior accelerations of the EI = 0 lines
at that state, which the EI = 0-only route does not, so when row 1 is off the deck pose their
first steps differ from that route’s. A static run (TMax = 0) of a line restrained in torsion
takes False alpha_force_blend, as on the single-line route.
The run writes the common .out and the all-line .static.out tables, plus the range graph of
every line with the r flag.
A mixed deck takes every deck current the single-line routes take: a current OPTION (uniform or
profile), a WaterKin CurrentMod 1 table and MoorDyn-C Currents 1/2/5. The static start of
its EI = 0 lines and finite-EI cables is solved in the current at t = 0, and before every step
the current at the step’s end time is sampled at every node of the step-start state and held
over the step, as on the single-line routes and with the same field evaluation (a Currents 2/5
table that varies in time repeats past its last sample there too). Mixed decks reject, by name,
deck waves (so vesselRAO), WaterKin WaveKinMod 1, MoorDyn-C WaveKin 3/7, and per-line
p/t flags.
Multibody march (bodies, rods, Connect/Free points, EI = 0 lines and finite-EI cables in
one deck). A standalone dynamic deck runs on one march over all of its objects when it has a rod
pinned to a body, a Pinned rod carrying lines, finite-EI lines beside bodies, rods or
Connect/Free points, free or fixed rods beside Rigid6 bodies or Connect/Free points, or
Rigid6 bodies beside Connect/Free points. Under the default bodyScheme monolithic it also
takes every other dynamic deck of free Rigid6 bodies, Point3 buoys, free, fixed or pinned rods
and Connect/Free points on EI = 0 lines, unless the deck has a motionFile, a FAILURE
section or Coupled/Vessel rods.
With bodyScheme monolithic (the default) each step is one implicit generalised-α step: the
end-of-step accelerations of the bodies, rods, Point3 buoys and Connect/Free points are the
unknowns of a Newton iteration, and every iterate steps the attached EI = 0 lines with the
resulting end motion and takes their end reactions and condensed end stiffness
(theory). The step needs no sub-stepping for stability; bodySubstep accuracy
(the default) divides it only to resolve the stiffest body-mooring mode.
With bodyScheme staggered each step is a predictor-corrector:
the free bodies and the free and pinned rods move to their end-of-step positions with their previous accelerations (central difference); a rod pinned to a body turns with its own rotation and keeps End A on the body’s pin point;
the EI = 0 lines are stepped with that end motion, with the
Connect/Freepoints integrated on their summed line-end loads as on the point-system route, and each finite-EI cable is stepped with its End A driven by its attachment and End B held;each body solves its equation of motion together with the rods pinned to it (the body twist and each pinned rod’s rotation as unknowns), each free rod its own, and each
Pinnedrod its rotation about the pin, from the end-of-step line loads; the EI = 0 line end-node inertia and the drag of the objects enter implicitly.
The staggered steps are sub-cycled so the explicit object positions resolve the stiffest
object-mooring mode of the EI = 0 lines. A finite-EI cable end on a body point or a rod end is
pinned unless it has an END CONNECTIONS row: a pinned
end passes its end force to the object at the attachment and no moment. A Rigid or spring end
is fixed in the object: its direction turns with the object, the connection moment is returned to
it, and the monolithic step re-steps the cable at every outer iteration with its end stiffness in
the Newton matrix. A cable between two objects (End B on a body point or a rod end as well) is
driven at both ends and re-stepped at every outer iteration whatever its connections; its
end-to-end stiffness couples the two objects’ coordinates in the one Newton matrix of the step,
and its end loads (and, at a connected or torsional end, the connection moment and torque) return
to each object. The static solve (bodyIC static) balances the cable’s bending end force and
connection moment at every connected end, and at both ends of a cable between two objects
(passes accelerated by Anderson mixing when the deck has such a cable). On this route:
a finite-EI cable’s ends may be
Fixedpoints, Rigid6Body<N>points or rod ends, notFree/Connectpoints orPoint3buoys; aCoupled/Vesselend, which this march has no motion to drive, is rejected by name;a clamped or elastic end, or a torsional one (bending-pinned included), on a body or rod needs
bodyScheme monolithic(the default);staggeredrejects it by name, at either end. The staggered scheme passes cable end forces explicitly and sizes its sub-steps from each end’s spring to its own object, so a stiff cable with both ends on one body (or between two light objects) is resolved there only as far asdtMallows; the monolithic scheme couples it in its Newton matrix;the monolithic step re-steps at every outer iteration every cable with an end, pinned or connected, on a moving object (a Rigid6 body, a free or pinned rod), with its end stiffness in the Newton matrix, so a light object on a stiff cable is as stable as a heavy one; an end on a fixed rod’s end is the
Fixedend there;every
Free/Connectpoint carries at least one EI = 0 line;motionFileandCoupled/Vesselrods are rejected by name.
Static initial condition: the static solve moves the free bodies, the free rods, the pinned rods
(two rotations about the pin, the pin force on the parent body) and the Free/Connect points
together. A finite-EI line enters it with its axial stiffness and weight (its part above the
surface with its dry weight), without its bending stiffness (a note names the line); its own
shape is then solved with the bending stiffness at the equilibrium end positions. A line
connected (clamped, elastic or restrained in torsion) at a body or rod end, a line between two
objects, and a bending-pinned line on a Rigid6 body or a rod end are balanced on their
cubic-Hermite end loads in static passes.
OpenFAST CompMooring = 5 (aggregate route): finite-EI cables run on the cubic-Hermite path:
lazy-wave statics and generalised-α dynamics driven by the coupled fairlead, including platform
rotation at a hang-off that declares an END CONNECTIONS
row. On this route:
deck
wavesandwavetrainOPTIONS are rejected at initialisation on every coupled deck, because the host SeaState supplies the waves; a deckcurrent(or a WaterKinCurrentMod 1table) is rejected on any deck with a finite-EI cable, Rigid6 body or rod, and a deckcurrentrow is kept as a steady current only on a single-turbine, pureEI = 0deck in a SeaState without waves or current; coupled cables take their fluid kinematics from the host SeaState field;a finite-EI cable cannot share a coupled deck with Rigid6 bodies, rods, or
Connect/Freepoints;FAILURE rows are rejected on decks that contain finite-EI cables; CONTROL rows may name finite-EI cables (see CONTROL);
Coupled/Vesselrods are platform-borne and need nomotionFile: each is a node of the OpenFAST mesh at its End A, turns rigidly with the platform orientation (its deck coordinates, like those ofCoupledpoints, are given at the undisplaced platform and moved byPtfmInit), and returns to the platform the force and moment about End A of its attached lines, weight, buoyancy, Morison loads, seabed contact and its own and added-mass inertia (MoorDyn-F’s coupled rod);CoupledPinned/VesselPinnedrods are pinned to the platform: each is a node of the OpenFAST mesh at its End A (moved byPtfmInitwith the rod, like aCoupledrod) that takes the platform position only. The rod turns about the node with its own three rotations, the node orientation and angular rates are ignored, and the node returns a force and no moment: the rod’s lines, weight, buoyancy, Morison loads and seabed contact less its own and added-mass inertia (MoorDyn-F’s coupled pinned rod). The angular acceleration in that inertia is solved for the node’s current acceleration, so the rotation feels the platform acceleration and a CalcOutput at an off-step acceleration returns the rod’s effective inertia about the pin.Pinnedrods turn about their fixed End A. WithbodyIC staticboth start balanced about their pins; a pinned rod that carries no line is not part of the static solve and starts at rest in its deck orientation, turned byPtfmInitfor aCoupledPinnedrod (a dry pendulum given at an angle starts at that angle). An end of aPinnedorCoupledPinnedrod that carries no line needs noRod<ID>A/Rod<ID>BPOINT row on this route; every other rod needs a line or a POINT row at both ends. Outside a coupled host aCoupledPinnedrod is rejected by name (“requires a coupled host”), zero-length ones included;Coupled/Vesselbodies are platform-borne the same way: a mesh node at the body reference point, the body frame turning with the platform, returning the force and moment about the reference point of itsBody<ID>lines, weight, buoyancy and restoring, Morison and Froude-Krylov loads of the SeaState field, seabed contact, external loads and its rigid-body and added-mass inertia (MoorDyn-F’s coupled body). They may share a deck withFreebodies: when the free bodies sub-cycle the coupling step, the host-driven bodies follow the host motion interpolated from the step start;CoupledPinned/VesselPinnedbodies are pinned to the platform asCoupledPinnedrods are: a mesh node at the body reference point (moved and turned byPtfmInitwith the body) that takes the platform position only. The body turns about it with its own three rotations, the node orientation and angular rates are ignored, and the node returns the body’s net load less its inertia, with no moment (MoorDyn-F’s coupled pinned body); the angular acceleration in that inertia is solved for the node’s current acceleration. WithbodyIC staticthe body starts balanced about its node.PtfmInitturns the body with the platform, as it turns the body’s attachment points (M^T R0 for the deck orientation R0 and the platform’s global-to-local DCM M); MoorDyn-F’s driver instead starts a coupled pinned body at its deck orientation, so withbodyIC deckand a rotation inPtfmInitthe two start from different poses. Outside a coupled host such a body is rejected by name (“requires a coupled host”);cables may be suspended or use the same flat/structured seabed contact, normal damping, and stick-slip friction as the standalone Hermite route.
BODIES (3D point buoy + 6D rigid body)
A body is a discrete rigid float or buoy that a line end can attach to. A BODIES row has 15 columns, or 18 with the trailing inertias, or the 14 columns of a MoorDyn v2 row (below).
Column |
Meaning |
|---|---|
|
unique body id ≥ 1 (referenced by |
|
|
|
reference position [m] |
|
reference orientation [deg] ( |
|
body mass [kg]; > 0 (≥ 0 for |
|
displaced volume [m³] (buoyancy ρ_w·g·Vol); ≥ 0 |
|
heave hydrostatic restoring ρ_w·g·A_wp [N/m] |
|
roll/pitch restoring [N·m/rad] ( |
|
drag area and added-mass coefficient (dynamic); ≥ 0 |
|
trailing diagonal rotational inertias [kg·m²]; required and > 0 for |
Every body value must be finite. Both body types require a dynamic deck (dtM/TMax) in the
standalone driver.
The MoorDyn v2 row ID Attachment X0 Y0 Z0 r0 p0 y0 Mass CG* I* Volume CdA* Ca* defines a
Rigid6 body with a centre of gravity: Attachment is Free, Coupled/Vessel for a
host-driven body, or CoupledPinned/VesselPinned for a body pinned to a host node; CG is z
or x|y|z in
the body frame from the reference point (it is also the centre of buoyancy, as in MoorDyn);
I is one value or Ixx|Iyy|Izz about the CG; CdA is one value, CdA|CdA_rot, or 3 or 6
entries, and Ca one value or 3 entries. The body model is isotropic, so direction-dependent
CdA/Ca entries and a non-zero rotational drag area fail closed, as do other attachments.
A line’s End A attaches to a body through a Body<ID> point; the point’s position is the
fairlead offset in the body frame.
A
Point3body supports exactly one attachment point, which becomes a dynamic point with the body’sMass/Vol/CdA/Ca. The static solve does not place it: it starts at its deck position. UnderbodyIC static(the default) a run whose buoy is not balanced there notes the unbalanced force and the distance to its static balance as aFreepoint; give the deck position of that balance, or setbodyIC deckto start it off balance on purpose.A
Rigid6body transfers structural force and moment through rigid attachment kinematics, plus lumped translational current and wave hydrodynamics fromCdA/Ca. Rotational body hydrodynamics are not modelled.A
Rigid6body’s weight acts at its centre of gravity and its buoyancy ρ_w g φVolat its centre of buoyancy, where φ is the submerged fraction. WithbodyWetting sphere(default) φ is that of a sphere of volumeVolcentred at the centre of buoyancy (of projected areaCdAwhenVol= 0), cut by the local free surface: a dry body carries no buoyancy and the force is continuous through the surface.bodyWetting moordynkeeps φ = 1 at any elevation, as in MoorDyn. A body withC33/C44/C55describes a surface-piercing hull: it keeps the full buoyancy ofVol(φ = 1) plus the linear restoring of its reference pose,C33in heave andC44/C55about the body’s own roll and pitch axes (the horizontal projections of its x axis and of the perpendicular), so the restoring does not depend on the heading.The body takes quadratic drag ½ ρ_w φ
CdA|u − v| (u − v) on the relative velocity, in still water too (u = 0), socurrent noneand a zero current give the same body motion; the fluid inertia ρ_w φVol(1 +Ca) u̇ (omitted withbodyHydro moordyn, as in MoorDyn); and the isotropic translational added mass ρ_w φVolCa, as for a MoorDyn Body with a singleCa. There is no rotational added inertia.A
Rigid6body has no contact footprint. Its seabed contact is a one-sided penalty at the reference point over a fixed reference area of 1 m²: stiffnesskBot·1 m² [N/m] and downward-only dampingcBot·1 m² [N·s/m]. Resolve a real footprint with the attached lines or with rods.A standalone dynamic Rigid6 deck with lines and without a
motionFileorFAILUREsection runs on the multibody march under the defaultbodyScheme monolithic(Point3buoys, rods andConnect/Freepoints may join it), and withbodyScheme staggeredwhen it also hasConnect/Freepoints, rods other thanBody<N>rods, or finite-EI lines.
With motionFile, a Rigid6 deck prescribes the full 6-DOF body motion from the body’s
Body<ID> point rows:
If every attachment row implies the same reference-point translation, velocity, and acceleration, the body translates with its deck attitude.
Otherwise the driver recovers the rigid motion behind the rows: rotation by the Davenport q-method on the centred reference→current attachment arms (always a proper rotation, exact for planar sets); angular velocity and acceleration by 3×3 least-squares normal equations on the centred velocity and acceleration rows.
It fails closed when the attachments are collinear (rotation unobservable; at least three non-collinear
Body<ID>points are needed) or when any row deviates from the recovered rigid motion by more than 1e-6 relative to the arm, velocity, or acceleration scale.
EXTERNAL LOADS
EXTERNAL LOADS rows ID Object Fext Blin Bquad CSys, in the MoorDyn-F column order, add a
constant force and translational damping to a Rigid6 body (Object Body<N>): the load
Fext - Blin v - Bquad |v| v acts at the body reference point, per axis of the global frame
(CSys G) or of the body frame (L, velocity and force in body axes). Fext is 0 or
f1|f2|f3 [N]; Blin [N·s/m] and Bquad [N·s²/m²] are one value (all axes) or three,
non-negative. A row whose third token is G, L or - is read in the alternative CableDyn
column order ID Object CSys Fext Blin Bquad. IDs run 1, 2, 3, … in row order. Several rows
on one body add up. The damping
enters the body step implicitly. External loads apply to Rigid6 bodies only: a row on a Point3
body is rejected (“EXTERNAL LOADS apply to Rigid6 bodies only”), and rod and point objects are
rejected by name.
TURBINES (standalone farm decks)
TURBINES rows J X0 Y0 Z0 [PtfmSurge PtfmSway PtfmHeave PtfmRoll PtfmPitch PtfmYaw] let the
standalone driver run a FAST.Farm deck: every Turbine<J> (or T<J>) POINT is a coupled
fairlead whose coordinates are turbine-local; it is placed at the farm-global position
(X0, Y0, Z0) + PtfmInit_J(p) (the MoorDyn-F initial-displacement transform, angles in
degrees). Turbines not in the section are an error naming the point. With a motionFile, the
rows are per-turbine rigid-body records
time J x y z q0 q1 q2 q3 vx vy vz wx wy wz ax ay az alx aly alz (reference position,
unit quaternion, velocity, angular velocity, and their rates); each Turbinex + R(q) p, with the rigid-body velocity and acceleration. A finite-EI line end on a
Turbine<J> point takes its END CONNECTIONS direction Ez and torsion normal Nx in that
turbine’s axes: turned by the PtfmInit rotation at the static start and by R(q), with the
row’s angular velocity and acceleration, in the run (End A and End B alike), as the FAST.Farm
host’s orientations turn them. A TURBINES deck that mixes EI = 0 lines and finite-EI cables (a
power cable shared by two turbines beside their chain legs) runs on the standalone mixed route,
the aggregate of FAST.Farm, with the same placement, records and end frames as the decks of its
cables alone and of its EI = 0 lines alone. In FAST.Farm the host supplies the turbine positions
and the section is not used.
ROD TYPES + RODS (rigid cylindrical rods)
Dynamic decks support free, fixed, pinned, and prescribed rigid cylindrical rods, rods fixed
to a Rigid6 body, rods pinned to a Rigid6 body, and zero-length rods. Lines attach to a rod end
directly with R<N>A/R<N>B (also Rod<N>A/Rod<N>B) in the LINES attachment columns, as in
MoorDyn, or through POINT rows of type Rod<ID>A and Rod<ID>B (at most one of each per rod).
Those POINT coordinates must be finite but are replaced by the rod end coordinates. A line
attached to an end of a rod fixed to a body loads the body at that end. Free, fixed, pinned and
prescribed rods with lines may share a deck with bodies and Connect/Free points (the
multibody march), except that prescribed (Coupled/Vessel) rods need
motionFile, which that march does not take. Rods require a dynamic deck (dtM/TMax) in the
standalone driver.
A deck may consist of bodies and rods alone, without LINE TYPES, POINTS, LINES, or SECTIONS
(for example a floating spar or a pendulum). Its objects are integrated with the explicit
central-difference scheme, or with the monolithic implicit step when the deck names
monolithic bodyScheme; with bodyIC static a floating body starts
at its hydrostatic equilibrium in heave, roll, and pitch (its horizontal position and heading,
which nothing restrains, are kept). Such a deck writes Body<N> and Rod<N> channels only.
ROD TYPES (7 columns, as in MoorDyn, or 9 with the CableDyn axial side coefficients):
Column |
Meaning |
|---|---|
|
rod type key (unique) |
|
cylinder diameter [m]; > 0 |
|
dry mass per unit length [kg/m]; > 0 |
|
transverse drag / added-mass coefficients; ≥ 0 |
|
end drag / end added-mass coefficients (MoorDyn); ≥ 0 |
|
optional columns 8–9: axial side drag / added-mass coefficients (CableDyn extension, default 0 as in MoorDyn); ≥ 0 |
Columns 6–7 are always MoorDyn’s CdEnd CaEnd. A header row naming axial coefficients
(CdAx, CaAx) in columns 6–7, the column order of earlier CableDyn decks, is rejected with a
migration message: move those values to columns 8–9 and set CdEnd CaEnd (0 keeps the earlier
model). A section without a header row uses the MoorDyn meaning.
Rod loads are integrated over the rod’s NumSegs segments. Each cross-section is wet over the
part below the local free surface (a circular segment when the rod is inclined), and buoyancy,
drag, Froude–Krylov, and added mass scale with that wet fraction. Buoyancy acts at the centroid of
the wet part, so a surface-piercing rod carries the exact hydrostatic force and waterplane
restoring of the displaced cylinder (second moment π d⁴/64) at any tilt, continuously as it
submerges or emerges. A wet length element dl carries the translational added mass
ρ_w A dl [Ca (I − a aᵀ) + CaAx a aᵀ] (a = rod axis), as in a MoorDyn Rod, attached at its
offset from the rod centre, which gives the rotational added inertia Ca ρ_w A ∫ s² ds about the
transverse axes (Ca ρ_w A L³/12 for a fully submerged rod) and the matching
translation–rotation coupling. There is no added inertia about the rod axis. Drag and fluid
inertia are evaluated at two Gauss points per wet segment part; with deck waves the free surface
is taken linear between the segment ends, so use more segments for waves shorter than about
10 rod segments.
Each rod end carries MoorDyn’s end effects, scaled by the wet fraction of its end cap: the axial
added mass ρ_w CaEnd V_end a aᵀ with V_end = (2/3) π (d/2)³, the axial drag
½ ρ_w CdEnd A |u_a| u_a (A = π d²/4, u_a the axial relative flow velocity) and the axial fluid
inertia ρ_w CaEnd V_end (u̇·a) a. With deck waves each wet end cap also carries the linear wave
dynamic pressure, which gives the axial Froude–Krylov force (the side then carries only the
CaAx part of the axial fluid inertia). These act along the axis through the rod centre, so they
carry no moment about it. In a coupled run the host (SeaState) fluid is sampled at the NumSegs + 1
segment ends of each rod, End A to End B, and interpolated linearly along the rod; the end caps
carry the sampled wave dynamic pressure, as with deck waves.
Rod seabed contact is distributed along the rod. kBot and cBot are per unit contact area, as
for line nodes. Each of n + 1 stations (End A, End B, and the interior points of n = max(20,
NumSegs) equal segments) carries a spring kBot·d·Δl and a downward-only damper cBot·d·Δl
over its tributary length Δl (L/n inside, L/(2n) at the ends). The resulting forces and moments
about the rod centre support a
rod lying on the bed along its whole length.
RODS (10 columns, or 11 with Outputs):
Column |
Meaning |
|---|---|
|
unique rod id ≥ 1 |
|
a |
|
|
|
rod End A coordinates [m] |
|
rod End B coordinates [m]; distinct from End A (ignored for a zero-length rod) |
|
≥ 1; hydrodynamic segments of the rod (loads integrated per segment); seabed contact uses max(20, |
|
|
POINTS
A POINTS row has 9 columns, ID Type X Y Z Mass Vol CdA Ca, or the short 5-column form
ID Type X Y Z, which sets Mass, Vol, CdA, and Ca to zero. Point ids are unique integers
≥ 1; every value must be finite.
|
Meaning |
Data used |
|---|---|---|
|
anchor held at (X,Y,Z) |
X,Y,Z |
|
fairlead driven by a host or by prescribed motion |
X,Y,Z (held for static; motion file for dynamic) |
|
alias of |
X,Y,Z |
|
line end on body N; (X,Y,Z) is the attachment offset in the body frame |
X,Y,Z offset; the body supplies Mass/Vol/CdA/Ca |
|
line end on rod N End A / End B; coordinates come from the |
X,Y,Z placeholders; zero Mass/Vol/CdA/Ca |
|
free internal point where ≥ 2 lines meet; its static position is solved from force balance (lines, weight/buoyancy, current drag) starting at the deck seed, and the march starts there |
X,Y,Z seed; Mass, Vol, CdA, Ca ≥ 0 |
|
free line end (clump or float terminal); a one-line |
X,Y,Z seed; Mass, Vol, CdA, Ca ≥ 0 |
|
FAST.Farm coupled point on turbine J (turbine-local coordinates) |
X,Y,Z; zero Mass/Vol/CdA/Ca |
For dynamic Connect/Free points, Mass is inertial mass and (rhoW·Vol − Mass)·g is a
constant vertical load. A Mass = 0 junction is accepted; it moves with the end-node mass of its
lines. CdA adds lumped drag and Ca lumped added mass in EI = 0 dynamic runs with uniform or
profile current or deck waves. A Connect/Free point with Mass or Vol (a clump weight or
a buoy) has its own seabed contact, the line contact law with stiffness kBot·A and damping
cBot·A over the footprint A = V^(2/3), where V = Vol, or Mass/7850 (solid steel) when
Vol = 0; a point with neither has none. A Point3 buoy has the same contact over the footprint
of its BODY Mass/Vol (see the theory manual, Seabed contact).
Connect/Free points require dtM/TMax in the
standalone driver. Non-zero Mass/Vol/CdA/Ca on Fixed, Coupled, Vessel, Body<N>,
Rod<N>A/B, or Turbine<J> points is rejected.
A free finite-EI cable end. A Free point that ends exactly one finite-EI line, as its End B
with a Coupled or Vessel End A (a still hang-off is a Coupled point without motion), is that
line’s free end on a standalone deck whose lines are all finite-EI and that has no BODIES,
RODS or other Connect/Free point (a free-hanging cable or riser with a clump or a bare end).
The point’s Mass, Vol, CdA and Ca act on the line’s End B node as an
ATTACHMENTS row at the line’s full arc length (weight
and buoyancy, added mass, and drag against current and waves), with the point’s isotropic drag
½ rhoW CdA ‖w‖ w on the whole relative velocity rather than the attachment’s normal/axial split. The static equilibrium is solved
with the end first held on the chord from End A towards the deck position, at the line’s length
stretched by its hanging weight, then released, so the run starts at the end’s rest position
(the theory manual, Free cable ends); the dynamics leave the end’s position free. Point<P>p…
channels read the line’s End B node, and the End B force (AnchTen, Point<P>F…) is the line load
the point balances, without the point’s own loads (a clump at rest reads its submerged weight). The line must be pinned in bending at both ends (no
non-pinned END CONNECTIONS row), with at most one end restrained in torsion, which is then not
solved (a free end carries no moment or torque; the initialisation note says why), and the point
and the line must be net heavy (the end hangs). A deck in which any Free point is not such an end
(a clamped or buoyant end, a second Free point, a Connect point), and a host-driven deck
(OpenFAST, the C API) or a bathymetryFile deck, is left as it was: the routes that take Free
points run it or refuse a finite-EI cable on a Free point by name. On a flat seabed a seed below
the seabed is placed on it at the same stretched length; an end that comes to rest on the seabed
with a net-heavy point is refused by name (the point has no seabed contact of its own on a
finite-EI line), while a bare end rests on the line’s own contact.
Turbine<J> points (J ≥ 1) need the turbine reference positions from one of two sources: the
OpenFAST/FAST.Farm aggregate route, where the host supplies them, or a
TURBINES section, with which the standalone driver runs the
farm deck. A deck with Turbine<J> points and neither source is rejected, naming the point
type, rather than solving turbine-local coordinates as global ones.
LINES + SECTIONS
A LINES row declares a line and its two end points. The line’s geometry is the ordered list of
its SECTIONS rows, matched by LineID. The unstretched length is the sum of the section
lengths; mesh density is set per section. LINES accepts three row forms:
Columns |
Form |
Meaning |
|---|---|---|
3 |
|
CableDyn line; |
4 |
|
CableDyn line with per-line output flags |
7 |
|
stock MoorDyn v2 row; equal to a 4-column row plus one implicit |
In the 3/4/7-column forms, AttachA/AttachB are POINT ids or rod ends R<N>A/R<N>B
(Rod<N>A/Rod<N>B). A body attachment goes through a Body<N> POINT. A line is defined either by
a 7-column row or by a 3/4-column row plus SECTIONS rows,
never both: a SECTIONS row for a 7-column line is an error naming the line.
LINES columns:
Column |
Meaning |
|---|---|
|
unique line id ≥ 1 |
|
End A / End B POINT ids (distinct). End A is the fairlead (top) end and End B the anchor (lower) end, as in OrcaFlex. |
|
per-line file flags. |
Automatic anchor-first swap. Stock MoorDyn decks list lines anchor first. When a line’s
NodeA is a Fixed point and its NodeB is a Coupled, Vessel, Body<N>, Free, or
Connect point (Turbine<J> points count as coupled), or a finite-EI line’s NodeB is a rod
end (R<N>A/R<N>B), the parser swaps the two ends, reverses that line’s SECTIONS rows, and
swaps its END CONNECTIONS ends, negating their reference directions and pretwists (the
torsion normals swap with their ends). Lines already listed fairlead first, EI = 0 lines to a
rod end, and Free/Connect-to-Coupled lines are left as written.
Endpoint rules.
In a deck without dynamic points (
Connect,Free,Body<N>, orRod<N>A/B), End A must be aCoupled,Vessel, orBody<N>point and End B aFixedpoint. A fairlead below its anchor fails withLINE End A fairlead (NodeA) must not be below End B anchor (NodeB). The exceptions are a FAST.Farm shared line with both ends onTurbine<J>points and a finite-EI line whose End B is also aCoupled/Vesselpoint (a line between two moving points, driven at both ends).A finite-EI line may end on a
Freepoint as its End B on a standalone deck of finite-EI lines (its free end); that point does not count as a dynamic point.In a deck with dynamic points, line ends may be
Fixed,Coupled,Vessel,Connect,Free,Body<N>, orRod<N>A/B.
SECTIONS (4 columns; at least one row per line, listed from End A to End B):
Column |
Meaning |
|---|---|
|
the owning |
|
a LINE TYPES key |
|
section unstretched length [m]; > 0 and at most 1e6, with |
|
section element count, 1 to 1 000 000. A finite-EI line needs far fewer: its static solve is verified up to 20 480 elements on the 80 m reference cable (elements of about 8 mm) and does not converge at 40 960 (about 4 mm). Keep finite-EI elements longer than about |
A single-material line is one SECTIONS row; a bare cable with a buoyancy stretch is three sections
of one line (bare, buoyant, bare). A bend stiffener over a line end is a
STIFFENERS row, not a section.
A standalone deck with a finite-EI section needs
dtM/TMax, unless it is a mixedEI = 0+ finite-EI deck, which may be static-only.On the cubic-Hermite route a finite-EI line starts from the exact EI = 0 catenary of its sections (buoyant lazy-wave sections included) and reaches its bending equilibrium by continuation in EI; the mesh-sequenced route is its fallback (
cable_statics, and the Hermite path in theory).WtrDpth,bathymetryFile,kBot, andcBotadd one-sided normal seabed contact where supported;current/wavesadd translational Morison and Froude–Krylov loads at element midpoints;frictionMuadds stick-slip seabed friction on finite-EI touchdown.Net-buoyant EI = 0 sections are rejected; model them as finite-EI lazy-wave sections.
SYROPE IC (optional, Syrope lines)
SYROPE IC supplies the prior load history of path-dependent polyester lines. It must come
after the LINES section that defines the referenced lines.
--------------------- SYROPE IC ----------------------------------------
Line(s) Tmax0 Tmean0
(-) (N) (N)
1,2 3.53e6 1.18e6
The last two tokens are Tmax0 Tmean0; the tokens before them form the line list. Line ids are
comma-separated (1,2 or 1, 2); ids separated only by spaces are rejected. Values must satisfy
Tmax0 >= Tmean0 >= 0 and Tmax0 > 0, and be finite. Every referenced line must have a
Syrope section, and be named in only one row. On a composite line the history applies to every
Syrope section.
Tmax0 is the rope’s running maximum tension. The static initial condition is solved on its
rest curve, the working curve regenerated at Tmax0 (the OWC beyond that curve’s top strain).
Every element starts with the slow strain whose tension equals its static tension. t = 0 is
therefore the static equilibrium, with no initial transient. An element whose static tension
exceeds Tmax0 sits on the OWC and raises its running maximum to that tension. With fixed
line ends, the geometry and Tmax0 set the mean tension, so Tmean0 is accepted for MoorDyn
compatibility but does not enter the state. If it differs from the static mean tension by more
than 1 %, the driver prints the static value on the console. A line whose initial strain is below
the zero-tension strain of the Tmax0 working curve is slack on that history, and
initialisation stops with an error. Without a SYROPE IC row, a Syrope line starts as a virgin
rope: its static solve uses the OWC, and each element’s running maximum is its static tension.
END CONNECTIONS (optional, finite-EI lines)
END CONNECTIONS sets the bending boundary at either end of a finite-EI line. Omitted ends are
pinned. At most one row may name a given line end. A non-pinned connection requires a finite-EI
line whose End B is a Fixed point or a Coupled/Vessel point, whose connection is held by
that point’s parent and turns with it as End A’s does (the vesselMotion/vesselRAO vessel
standalone, the host orientation of End B’s point when coupled), or a Rigid6 Body<N> point or a
rod end on the multibody march (a line between two objects, whose connection
turns with End B’s object); any other End B fails deck validation. End A may be a Fixed or
Coupled point, a Rigid6 Body<N> point or a rod end.
--------------------- END CONNECTIONS -------------------------------
LineID End Stiffness EzX EzY EzZ
(-) (-) (N-m/rad) (-) (-) (-)
1 A 2.0e4 -0.25 0.0 -0.97
1 B Rigid 1.0 0.0 0.0
Column |
Meaning |
|---|---|
|
existing |
|
|
|
finite bending stiffness ≥ 0 [N·m/rad], |
|
non-zero reference direction, normalised by the parser |
Behaviour:
The direction follows the End A → End B line convention. At a coupled end it is stored in the platform frame and rotates with the OpenFAST orientation input. In the standalone driver
motionFileprescribes translation only, so the direction stays fixed in global axes; withvesselMotionorvesselRAOit is stored in vessel axes (equal to global axes at the reference pose) and turns with the vessel.The connection moment equals the bending moment of the line at its end node, so
BendMom<L>N1(End A) andBendMom<L>N<NumSegs+1>(End B) report it; under a bend stiffener it isBendMomplusStfMomat that node.On a
Body<N>point the direction is given in the body frame, like the point offset, and turns with the body. On a rod end it must be parallel to the rod axis (either sense, in the frame of the rod’s deck coordinates); another direction is rejected by name. The connection moment is part ofBody<N>M*/Rod<N>M*(of both on an end of a rod fixed to a body), and the body or rod carries it in the dynamics and in the static solve.A finite stiffness is an isotropic rotational spring on the tangent direction; the tangent magnitude stays free.
Rigidis an exact two-coordinate direction constraint, not a large penalty; the tangent magnitude remains a solved axial degree of freedom.Pinnedadds no spring and no moment; it is identical to omitting the row.Connection moments are included in the OpenFAST coupled-load mesh.
Rows on an EI = 0 line, duplicate rows, unknown line ids, null directions, negative stiffnesses,
and non-finite values fail deck validation. OpenFAST linearisation with a Rigid end connection
is rejected at initialisation.
Torsion columns
Four or five optional columns restrain the twist of a finite-EI line end (rows of 10 or 11 columns; the 6-column rows keep their meaning):
--------------------- END CONNECTIONS -------------------------------
LineID End Stiffness EzX EzY EzZ TorsStiffness NxX NxY NxZ Pretwist
(-) (-) (N-m/rad) (-) (-) (-) (N-m/rad) (-) (-) (-) (deg)
1 A Rigid 1.0 0.0 0.0 Rigid 0.0 0.0 1.0 0.0
1 B Rigid 1.0 0.0 0.0 Rigid 0.0 0.0 1.0 720.0
Column |
Meaning |
|---|---|
|
|
|
zero-twist reference normal of the end, in the frame of |
|
optional roll of the end frame about |
At a Free end the normal and Pretwist are only checked to be finite numbers; they are not
used.
Behaviour:
Torsion is solved on a line restrained at both ends, and on a line restrained at one end whose other end is free to twist (
TorsStiffnessFreethere, or no row), under the rules below. A free end carries no torque. In statics the line then has none, and its static state is that of the line without the columns; under torque–tension coupling (GJ|K) the stretch twists it byTwist<L> = −Σ (K/GJ)(l − L)over the elements (lstretched,Lunstretched).Twist<L>keeps its sign, the turn of End B relative to End A, right-handed about the End A → End B tangent: a free End B turns by+Twist<L>against End A’s frame carried along the line, a free End A by−Twist<L>against End B’s. In the dynamics the polar inertiaIrncarries torsional waves that reflect at the free end, and the restrained end (and the body or vessel holding it) takes their torque. The free end’sNxandPretwistare not used. The section axes ofCurvX/CurvYstart, with End A restrained, from End A’sNx(not rolled by itsPretwist, as on a line restrained at both ends) and, with End B restrained, from End B’sNxrolled by End B’sPretwist; either way they are carried along the line and turned by its twist.ATTACHMENTS,CONTROL,nModes(the free end’s angle is a mode coordinate, with the clamped–free modes) and OpenFAST linearisation (the free end’s angle is a state) take such a line as they take one restrained at both ends. A line restrained at one end that misses a rule (itsLINE TYPESrows give noGJ, two moving ends, a dynamic or coupled run withFalse alpha_force_blend, a restrained End A on a rod end other than aFixedrod’s or on a non-Rigid6 body) is solved as without the columns, and the standalone driver prints a note with the reason. A solved one’s imposed twist, its restrained end’sPretwist, must lie within 1000 turns, asPretwist(B) − Pretwist(A)must on a line restrained at both ends. A line restrained at End A on a Rigid6 body joins the static balance of the body’s clamped and elastic ends, also at a bending-PinnedEnd A (the body takes its torque).Freecolumns, or no columns, reproduce the 6-column results exactly.The imposed twist is
Phi = Pretwist(B) − Pretwist(A), measured against the line’s own geometric twistTheta, the parallel-transport rotation of the End A normal carried along the centreline to End B (zero for a line that stays in a plane, with both normals perpendicular to that plane). The torque is uniform along the line,M = (Phi − Theta)/C, with the complianceC = Σ L/GJover the sections plus1/kof each torsional end spring. Positive torque is a right-handed twist of End B relative to End A about the End A → End B tangent (OrcaFlex’s sign). A non-planar line hasTheta ≠ 0in its untwisted shape; to start it free of torque, set the End B pretwist to minus the staticTwist<L>of a run with zero pretwist (in degrees); the line then keeps its untwisted shape.The torsion end frame turns with what carries the end: a Rigid6 body, the vessel of
vesselMotion/vesselRAO, or nothing at aFixedor held point or on aFixedrod. ThemotionFileroll column rolls the frame of the line’s moving end (Prescribed motion).On a rod end (an I-tube or J-tube modelled as a rod),
Ezlies along the rod axis andNxis given in the frame of the rod’s deck coordinates, asEzis. AFixedrod holds the frame still, and itsRod<N>M*carries the torque about the line axis. The ends of a rod fixed to a Rigid6 body (RODStypeBody<N>) are points of the body:EzandNxare given in the body frame, the frame rolls with the body, and the torque reaches the body (Body<N>M*) and appears in the rod’sRod<N>M*.A Rigid6 body holding such a line turns by less than 90° per step: a step whose turn would be larger is halved (the twist is read from the body’s orientation, which repeats every turn), and a run that still needs more after six halvings stops by name; reduce
dtM.Torsion may be restrained at a bending-
Pinnedend. The torque then passes through a constant-velocity-joint idealisation: the end frame is carried fromEzto the line tangent by the smallest rotation, so the end transmits the torque semi-tangentially, not as Greenhill’s axial-torque hinge. A straight rod with two such ends buckles atM = 4.9113 EI/Lat zero tension (7.2693 EI/LatT L²/EI = 10), not2π EI/L; clamped ends buckle at8.9868 EI/L(see theory).The torque returns to a Rigid6 body at End A, in the static body equilibrium and in the dynamics; it is part of
Body<N>M*.Statics solve the imposed twist as the last load stage, in steps of at most 45°, test every stage for stability and, above a buckling onset, leave the unstable straight state for the buckled one. Dynamics carry the torsion in every step with a twist angle at every node and the polar inertia
Irnof theLINE TYPESrow (see theory).
Scope. A torsionally restrained line needs a finite-EI line with a Fixed End B or, restrained
at both ends, a Coupled/Vessel or Rigid6 Body<N> End B (both end frames then turn with
their parents, and standalone the motionFile roll column rolls either end: Φ = Pretwist(B) − Pretwist(A) − roll(A) − roll(B), each roll about the tangent pointing into the line from that
end), an explicit GJ on every section, and, at End A, a Fixed, Coupled/Vessel point, a
Rigid6 Body<N> point (the ends of a Body<N> rod included) or an end of a Fixed rod (with a
Fixed End B); in a coupled OpenFAST or FAST.Farm run the End A frame turns with the platform
(see the manual’s OpenFAST page, Line torsion). Each of the following stops with a named error:
torsion on an EI = 0 line, on an end of a Free, Pinned, Body<N>Pinned or CoupledPinned
rod (an axisymmetric rod has no roll angle about its own axis: no load acts about the axis and
its static solve has none, so it cannot hold the torque) or of a Coupled/Vessel rod (no route
carries a finite-EI line on a host-driven rod), at End B on a rod end (a line between two rods:
restrain it through End A, or put a Fixed point at the rod end), on a Point3 body, a dynamic
or coupled run with False alpha_force_blend, any restrained end (one end included) through the
C API’s CableDyn_InitDeck/InitDeckAt, which move the line ends by translation only (a line restrained in torsion needs a host that turns its fairlead frame ...; a C API host passes its
rotations after CableDyn_InitDeckRotating), and a Torq/Twist channel on a line whose
torsion is not solved. OpenFAST linearisation includes the twist angles as states; like any
cable, the line must not have a Rigid bending connection there, nor a second moving end. Seabed
friction does not resist twist (the laid part of a line twists freely).
EQUIVALENT BUOYANCY (optional)
Specifies a cable section by its target submerged weight per metre instead of its dry mass. Rows
are applied after OPTIONS, using the final rhoW and g, and rewrite the named line type’s
Diam and MassDenInAir before validation. The rewritten line type is then used through the
ordinary SECTIONS table; no discrete buoy object is created.
--------------------- EQUIVALENT BUOYANCY -----------------------------
LineType Diam SubmergedWeightNpm
(-) (m) (N/m)
power 0.50 -1483.0
Column |
Meaning |
|---|---|
|
existing |
|
equivalent hydrodynamic / displaced-volume diameter [m] |
|
target net submerged weight [N/m]; positive downward, negative for uplift |
A row fails if the line type is unknown or duplicated, a value is non-finite, or the result would need a negative dry mass. Net-buoyant EI = 0 sections are still rejected (see LINES + SECTIONS).
ATTACHMENTS (optional, finite-EI lines)
Discrete buoyancy modules and clump weights on a finite-EI line, the alternative to a smeared EQUIVALENT BUOYANCY section. Each attachment is a point load at a node of the cable, not a separate object: there is no Connect point, and its loads enter the cable’s own static and dynamic equations.
--------------------- ATTACHMENTS ----------------------------------
LineID ArcLength Mass Volume CdA Ca CdAx
(-) (m) (kg) (m^3) (m^2) (-) (m^2)
1 42.5:5.0:87.5 114.15 0.2297 0.78 1.0 0.204
1 120.0 800.0 0.0 0.3 0.0
Column |
Meaning |
|---|---|
|
existing |
|
unstretched arc length from End A [m], or a series |
|
dry mass [kg] |
|
displaced volume [m³] (buoyancy |
|
drag area normal to the line [m²] |
|
added-mass coefficient on |
|
optional drag area along the line [m²]; default 0 |
The drag acts on the fluid velocity relative to the node, w = u − v, split into its parts
normal (w_n) and along (w_t) the line tangent at the node:
½ rhoW (CdA ‖w_n‖ w_n + CdAx ‖w_t‖ w_t). This is the line’s own Morison law per metre with
CdA = Cd_n d and CdAx = π Cd_t d, so a module that adds the diameter d_m − d over a
pitch p carries CdA = Cd_n (d_m − d) p and CdAx = π Cd_t (d_m − d) p and matches the
smeared section in a current.
Behaviour:
An attachment acts at the node nearest its arc length; the initialisation note reports the largest distance between an attachment and its node. Mesh the line so that nodes fall at the attachments, with several elements between neighbouring attachments to resolve the curvature between them.
Loads: the net weight
(Mass − rhoW Volume) gdownward; with the dry mass, the added massCa rhoW Volume(a constant nodal mass); the fluid-inertia forcerhoW Volume (1 + Ca) du/dtand the drag against the current and wave velocity at the node. A deck current (acurrentrow, uniform or profile, or a MoorDyn-CCurrentsfield att = 0, sampled at the attachment node) loads the attachments in the static initial condition with the same drag law at rest, so a run in a current starts in equilibrium. An attachment above the free surface carries its weight only, in the static initial condition too. Attachments have no seabed contact of their own; the node’s contact acts on the line.The static equilibrium is solved first with each attachment’s net weight, and in a current across the vertical plane of the line its drag areas, spread over the two elements at its node, then carried to the discrete loads by continuation. The current drag depends on the node’s position and line direction, and the weight on the side of the surface an attachment is on, so the final solve is repeated until the node positions change by less than 1e-9 m and no attachment changes side. A residual floor above the tight static tolerance is accepted at the coupled static tolerance 1e-6, as on a line without attachments, and noted with the residual reached. On a line restrained in torsion the torsion stage (the imposed twist) follows on the discrete equilibrium, with the attachments’ net weights and drag as nodal loads (the drag again to a fixed point), so a run starts in the twisted equilibrium. An attachment adds no polar inertia to the line’s twist.
A row fails if the line is not finite-EI, the arc lies beyond the line, every one of
Mass,Volume,CdAandCdAxis zero, a value is negative or non-finite, or a series has a non-positive pitch orfirst > last. A stock-order line (anchor asNodeA) measures the arc from that anchor. Attachments run on the cubic-Hermite cable route, standalone (End ACoupled/VesselorFixed, End BFixed,CoupledorVessel) and coupled (OpenFASTCompMooring = 5, the C API and Python), where the SeaState kinematics the host samples at every cable node reach the attachments at theirs; a checkpoint restart is bit-identical.
STIFFENERS (optional, finite-EI lines)
A bend stiffener: a tapered polyurethane sleeve over a line end, usually at a hang-off, that spreads the bending of the cable over its length. The sleeve is not a separate object; it adds its bending stiffness, mass, buoyancy and drag to the elements it covers. Each row is one conical segment, and the rows of one line end follow each other outward from the stiffener root, each starting where the previous one ends. A cylindrical root, a cone and a tip are three rows.
--------------------- STIFFENERS ------------------------------------
LineID End Length RootOD TipOD InnerD E Density
(-) (-) (m) (m) (m) (m) (Pa) (kg/m^3)
1 A 0.4 0.45 0.45 0.17 5.0e7 1150
1 A 3.6 0.45 0.18 0.17 5.0e7 1150
Column |
Meaning |
|---|---|
|
existing |
|
the end the stiffener sleeves: |
|
length of the segment along the line [m] |
|
outer diameter at the segment’s root side [m] |
|
outer diameter at the segment’s tip side [m]; the diameter varies linearly in between |
|
inner (bore) diameter [m], smaller than both outer diameters |
|
Young’s modulus of the sleeve material [Pa] |
|
density of the sleeve material [kg/m³] |
Behaviour:
Over the stiffener the section bends as cable and sleeve together:
EI(s) = EI_cable + E π/64 (OD(s)⁴ − InnerD⁴). The sleeve carries no axial load and no torque, soEAandGJare the cable’s. Each element takes the compliance average ofEI(s)over its length,L / ∫ ds/EI(s), the cable mass plus the mean sleeve mass, a diameter of the displaced area of cable plus solid sleeve,√(d² + OD² − InnerD²), for its buoyancy, added mass and drag alike, as a line type has one diameter (the sleeve’s outer diameter whenInnerDis the cable diameter; see theory, Bend stiffeners). Elements the stiffener does not reach keep their line type’s values exactly.The element properties are piecewise constant, one value per deck element, so the deck mesh must resolve the taper: an initialisation note names a stiffener that spans fewer than 10 elements and the element length that resolves it. Split the section at the stiffener tip and mesh the part under it finely (about 0.1–0.2 m elements for a typical 3–8 m stiffener). The node outputs and the element peaks of
.elements.outdo not take these element values: they readEI(s)at their own arc, and at a real step of the section (the tip, rows that do not match, two line types) the softer side’s.The stiffener root takes the moment only where the end is held in rotation: declare the end
Rigid, or a rotational spring, in END CONNECTIONS. A stiffener at a pinned end prints a note.Outputs:
Curv<L>N<J>is the curvature cable and sleeve share;BendMom<L>N<J>the cable’s own moment (the line type’sEI× curvature, the value to check against the cable’s limits);StfMom<L>N<J>the sleeve’s share, so that the two add up to the section moment the root connection carries.FairDefl<L>/AnchDefl<L>give the angle between the end force and the held direction, which withFairTen/AnchTenis the stiffener’s load case. Keep the fine mesh a couple of metres past the stiffener tip, where the cable’s curvature can peak.The material is linear elastic. A row fails if the line is not finite-EI, a value is non-finite, above 1e15 or out of range (
Length,RootOD,TipODandEmust be positive,InnerDandDensitynon-negative,InnerDbelow both outer diameters), or the stiffeners of End A and End B together are longer than the line. On a stock-order line (anchor asNodeA) theEndcolumn follows the written row, so the stiffener stays on the same physical end. Stiffeners run wherever the cubic-Hermite cable does, standalone and coupled.
VIV (optional)
In-line vortex-induced vibration of a line type: a second vortex-shedding force along the
relative flow, the direction of the drag, at twice the cross-flow frequency (Ulveseter et al.
2018; see In-line VIV). One row per line type, which must carry the cross-flow lift
(Cl > 0 in LINE TYPES), since the in-line phase runs at twice the cross-flow one.
--------------------- VIV ----------------------------------------------
TypeName ClX alpha Chh
(-) (-) (-) (-)
cable 0.85 0.15 0.5
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive), at most one row each |
|
in-line shedding coefficient |
|
optional frequency band of the in-line phase about twice the cross-flow one, |
|
optional higher-harmonic coefficient |
Behaviour:
Per unit length the force is
1/2 rho D ClX cos(phi_x) U v_n, withv_nthe relative normal flow andUits speed; its phase followsdphi_x/dt = 2 (dphi/dt) [1 + alpha sin(phi_xd - phi_x)],phithe cross-flow phase andphi_xdthe phase of the in-line motion. Ulveseter et al. takeClX = 0.85andalpha = 0.15withCl = 0.65.Chhadds the higher-harmonic force of Ulveseter et al. (2019), the lift’s form1/2 rho D Chh cos(phi + phi_x) U (t x v_n)at the sum of the two phases: across the flow at three times the cross-flow frequency (and once and five times, through the in-line motion), along it at twice and four times. It needs no state of its own. Ulveseter et al. useChhfrom 0 to 1.5.The Outputs flag
Vfile carries the in-line force with the lift, and the phase is part of the step-recovery, snapshot and checkpoint state. A row withClX = 0leaves the run exactly as without it.It acts wherever the cross-flow lift does: on
EI = 0lines (a node force over the node’s half elements, as the lift) and on finite-EI cables (integrated with the lift), standalone and coupled. A row fails if it is notTypeName ClX [alpha [Chh]], names an undefined or already named type, or holds a value out of range;ClX > 0fails on a type without the cross-flow lift, andChh > 0withClX = 0.See
examples/viv_taut_cable_inline.dat.
Published coefficient sets. The synchronisation band of the LINE TYPES columns is the
f0 +/- df of the papers (cF = f0, dF = df), and their Morison inertia coefficient
C_M is 1 + Ca. Two published sets, as LINE TYPES and VIV columns:
Source |
|
|
|
|
|
|
|
|
|---|---|---|---|---|---|---|---|---|
Ulveseter et al. (2018), Table 3: a 10 m riser model in current and in current and waves |
1.2 |
1.0 |
0.65 |
0.08 |
0.18 |
0.85 |
0.15 |
0 |
Ulveseter et al. (2019), Table 1 and Section 4: the NDP high-mode riser in uniform current |
1.2 |
1.0 |
0.85 |
0.064 |
0.144 |
0.75 |
0.15 |
1.5 |
Each was fitted to its experiments by the authors and is a starting point, not a universal set;
MoorDyn’s band defaults (dF 0.08, cF 0.18) are those of the first.
WAKE OSCILLATOR (optional)
Wake-oscillator vortex-induced vibration of a line type, the model of Facchinetti et al. (2004):
a van der Pol oscillator per node stands for the near wake and drives the cross-flow lift, coupled
to the cable’s cross-flow acceleration (see Wake oscillator). It replaces the
synchronisation model of the LINE TYPES Cl column for that type, so the type keeps Cl = 0, and
it acts on finite-EI cables and EI = 0 lines alike.
--------------------- WAKE OSCILLATOR ----------------------------------
TypeName CL0 St eps A
(-) (-) (-) (-) (-)
cable 0.3 0.2 0.3 12
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive), at most one row each |
|
reference lift coefficient |
|
optional Strouhal number > 0 of the wake frequency |
|
optional van der Pol parameter > 0 (default 0.3) |
|
optional acceleration coupling >= 0 (default 12; |
Behaviour:
Per unit length the lift is
1/4 rho D CL0 q U^2across the relative flow, the direction of theCllift (Uthe relative normal flow speed), withq'' + eps om (q^2 - 1) q' + om^2 q = (A/D) y''at each node,om = 2 pi St U_a/DwithU_athe ambient flow speed normal to the line andy''the node’s cross-flow acceleration. The defaults are the values Facchinetti et al. fix from forced-wake data. The cross-flow damping of the fluid is the Morison drag of the type’sCd, which the paper’sgamma = Cd/(4 pi St)linearises.qstarts on its limit cycle at the node’s VIV phase seed,q = 2 cos(phi_0)(VIVphaseSeed), and is part of the step-recovery, snapshot and checkpoint state. The Outputs flagVfile andVIVPowcarry the wake lift. A row withCL0 = 0leaves the run exactly as without it.A row fails if it is not
TypeName CL0 [St [eps [A]]], names an undefined or already named type, or holds a value out of range;CL0 > 0fails on a type withCl > 0. A line whose types mix the two models fails.
VIV AMPLITUDE (optional)
Amplitude-dependent coefficients of the synchronisation model of a line type (Thorsen et al.
2016): a table over the cross-flow amplitude ratio A/D of the coefficient Cv that replaces the
type’s LINE TYPES Cl, and of a factor CdAmp of its normal drag coefficient Cd (see
Amplitude-dependent coefficients). The rows of one type follow each other in
increasing A/D.
--------------------- VIV AMPLITUDE ------------------------------------
TypeName AD Cv CdAmp
(-) (-) (-) (-)
riser 0.0 0.8 1.0
riser 0.3 0.9 1.5
riser 0.6 0.0 2.0
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive) whose |
|
amplitude ratio A/D >= 0 of the row, strictly increasing over the type’s rows |
|
cross-flow coefficient >= 0 at that amplitude, in place of |
|
optional factor > 0 of the type’s normal drag coefficient at that amplitude (default 1) |
Behaviour:
Each node estimates its cross-flow amplitude as Thorsen et al. do (their Eq. 8 and 9): half the travel of the node across the ambient flow between two zero crossings of its cross-flow velocity, smoothed by a tenth of the difference at every time step (with a VIV FRAME row, the flow and the velocity relative to the cable’s filtered motion). An element takes the mean of its free nodes over its diameter as A/D (the one free node next to a fixed end or anchor), and from its table
Cv(for the lift) andCdAmp(timesCd, for the normal Morison drag), linear between rows and held beyond the first and last. The coefficients of a step use the estimate of the committed state. The estimate starts at 0, and the static equilibrium takes the type’s ownCd, so a table whoseCdAmpat A/D 0 is not 1 starts the run off that equilibrium.VIVAmp<L>N<J>(OUTPUTS) is the smoothed amplitude of node J [m].A table whose
Cvfalls to zero above some A/D limits the response there (Thorsen et al. fit such a curve to riser tests, their Fig. 7).CdAmpgives the drag amplification of a vibrating cylinder, for example Chaplin et al. (2005, Eq. 4),Cd/Cd0 = 1 + 2.3 s + 1.7 s^2with the r.m.s. cross-flow displacements = (A/D)/sqrt(2)of a harmonic response.The estimate assumes a narrow-band response, as theirs does. With the in-line VIV of a
VIVsection row,ClXandChhstay constant. The estimate is part of the step-recovery, snapshot and checkpoint state. A table withCv = ClandCdAmp = 1throughout runs as the type without it.It acts on
EI = 0lines and finite-EI cables, standalone and coupled. A row fails if it is notTypeName AD Cv [CdAmp], names an undefined type or one without the synchronisation lift (Cl = 0, as a wake-oscillator type), holds a value out of range, does not increase inAD, or has other columns than the type’s earlier rows; a type takes 2 to 32 rows.
VIV DIAMETER (optional)
The diameter of the VIV model of a line type, apart from the hydrodynamic diameter Diam that
its drag, added mass and buoyancy keep (see VIV diameter).
--------------------- VIV DIAMETER -------------------------------------
TypeName Dviv
(-) (m)
zone 0.9
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive) with VIV ( |
|
diameter > 0 of its VIV model [m], at most 1e15 |
Behaviour:
The VIV of the type takes
Dvivwherever it takes the diameter: the shedding frequencycF U/Dvivand its band (or the wake frequency2 pi St U/Dvivand the couplingA/Dviv), the lift, in-line and higher-harmonic forces1/2 rho Dviv C U^2, and the amplitude ratio of a VIV AMPLITUDE table. The drag, added mass, buoyancy and seabed contact keepDiam; so do the stiffener and attachment loads.A buoyancy-module zone of a cable whose modules are ATTACHMENTS rows can be given its own VIV: split the line into SECTIONS at the zone, give the zone a copy of the cable’s line type with
Dvivthe module diameter and its ownCl,dFandcF(orCl 0for no VIV there), and keep the modules’ mass, volume and drag in ATTACHMENTS. CableDyn models no shedding interaction between modules and bare cable; the coefficients of such a zone are the user’s choice.A row with
Dvivequal toDiamruns as the type without it. It acts onEI = 0lines and finite-EI cables, standalone and coupled. A row fails if it is notTypeName Dviv, names an undefined or already named type or one without VIV, or holds a value out of range.
VIV FRAME (optional)
The flow frame of the VIV model of a line type: the frame the model takes the cable’s motion and
the free stream in, the earth and the ambient flow by default. A cable moved through the water by
a tow or by its floater sees no ambient flow, so its wake oscillator never shed, and its
synchronisation phase saw no cross-flow velocity and its amplitude estimate stayed at zero; with a
filter time Tf the frame moves with the cable’s own slow motion (see
Wake oscillator and Flow frame of the synchronisation model).
--------------------- VIV FRAME ----------------------------------------
TypeName Tf
(-) (s)
cable 10
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive) with LINE TYPES |
|
filter time >= 0 [s], at most 1e15; |
Behaviour:
The node’s velocity is low-pass filtered over
Tf(first order, started at the node’s initial velocity). The slow motion then counts as flow; the cable’s own VIV velocity, much faster thanTf, does not.On a wake-oscillator type the wake frequency
2 pi St U_a/DtakesU_a= the speed normal to the line of the ambient flow less the filtered velocity.On a synchronisation type (LINE TYPES
Cl > 0) the cross-flow and in-line phases take the node’s velocity less the filtered velocity, along the axes of the relative flow, so the shedding speed stays the relative normal speed; with a VIV AMPLITUDE table the amplitude estimate takes that velocity across the ambient flow less the filtered velocity, and with it the table’sCvandCdAmp; on a finite-EI cable with VIV DAMPING the split takes its in-line and cross-flow axes, and its blend to Morison’s drag, from that flow. The lift and drag act on the relative velocity, unchanged.Take
Tfseveral VIV periods long and short against the motion: the filter scales the VIV velocity atomegabyomega Tf/sqrt(1 + (omega Tf)^2)(0.9985 at 0.29 Hz withTf10 s) and lags a motion atomega_mbyatan(omega_m Tf). A taut cable towed at 0.15 m/s through still water (VIV at 0.28 Hz) withTf10 s locks in as the same cable held in a 0.15 m/s current: with the wake oscillator A/D within 0.6 % and frequency within 0.001 Hz, where the ambient flow gave it no lock-in; with the synchronisation model A/D within 0.02 % of the held cable with the same row (within 0.25 % without the row), with or without a VIV AMPLITUDE table and VIV DAMPING. On a held cable in a currentTfchanges A/D by 0.03 % (wake oscillator) and at most 0.24 % (synchronisation model).The two conditions hold together only for a motion much slower than the VIV. Keeping about 95 % of the VIV velocity (
omega Tf >= 3) while leaving at most 10 % of the motion’s velocity in the relative velocity (omega_m Tf <= 0.1) needs a motion period at least 30 VIV periods long. For a motion only a few VIV periods long (a floater heave close to the VIV frequency) noTfseparates the two, and the response depends onTf: report its sensitivity toTf.The filtered velocity is part of the step-recovery, snapshot and checkpoint state. A row with
Tf = 0leaves the run exactly as without it. It acts onEI = 0lines and finite-EI cables, standalone and coupled. A row fails if it is notTypeName Tf, names an undefined or already named type or one without VIV (neither LINE TYPESCl > 0nor a WAKE OSCILLATOR row), or holds a value out of range.
VIV STOCHASTIC (optional)
The stochastic synchronisation of Ulveseter et al. (2017): the centre cF of a line type’s
synchronisation band becomes a slowly varying random process, so the response can wander between
modes as in long risers in shear (see Stochastic band centre).
--------------------- VIV STOCHASTIC -----------------------------------
TypeName sigma c Nf seed
riser 0.016 0.07 100 1
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive) with |
|
standard deviation of the band centre, 0 to 1e3 (0: the constant |
|
top of the centre’s flat spectrum as a fraction of |
|
number of frequency components, an integer from 1 to 1000 (optional, default 100) |
|
seed of the components’ start phases, an integer from 0 to 2147483646 (optional, default 0) |
Behaviour:
At a lifting node the centre is
cF + sum_i a sin(p_i + 2 pi f_i theta),thetathe integral ofU/Dover time (Uthe shedding speed of the phase rate), withNfcomponents at the mid-pointsf_i = (i - 1/2) c cF/Nfof a flat spectrum over(0, c cF]and amplitudea = sigma sqrt(2/Nf), so its standard deviation issigma. Each component advances at its non-dimensional frequency timesU/D, as the shedding phase does, so the centre is slow against the VIV forcwell below 1 (Ulveseter et al. takec0.07). The band half-widthdFstays constant.The start phases are uniform in
[0, 2 pi), drawn for each node from the seed, the node and the line, so the nodes are independent (no spanwise correlation, as in the article), a run repeats its realisation and two lines of one type differ. A different seed is another realisation; report statistics over several.thetais part of the step-recovery, snapshot and checkpoint state (one value per node). A row withsigma = 0leaves the run exactly as without it. It acts onEI = 0lines and finite-EI cables, standalone and coupled, with or without in-line VIV.A row fails if it is not
TypeName sigma c [Nf [seed]], names an undefined or already named type, one withoutCl > 0or one with a WAKE OSCILLATOR row, or holds a value out of range.
VIV DAMPING (optional, finite-EI lines)
Splits the normal Morison drag of a line type into an in-line and a cross-flow part in the frame of the ambient flow, and gives the cross-flow part its own law: the quadratic damping of Thorsen et al. (2016) and, optionally, a Morison-form term (see Cross-flow damping).
--------------------- VIV DAMPING --------------------------------------
TypeName a b c
(-) (-) (-) (-)
riser 0 0 1
Column |
Meaning |
|---|---|
|
an existing LINE TYPES name (case-insensitive) with a VIV AMPLITUDE table, at most one row each |
|
the cross-flow damping coefficient |
|
optional factor >= 0 of a Morison-form cross-flow term |
Behaviour:
At each point of the line, with
e_xalong the ambient flow normal to the line ande_yacross it, the relative normal velocitywsplits intow_xandw_y. The normal drag per unit length becomes1/2 rho D [Cdn CdAmp |w| w_x e_x + (C_dy |w_y| + c Cdn |w|) w_y e_y]: Morison’s in-line part, with the drag factorCdAmpof the type’s amplitude table, and the cross-flow law of the row. Where the ambient normal flow falls below 0.01 m/s the axes are undefined and the drag blends smoothly back to Morison’s. With a VIV FRAME row the axes and the blend take the ambient flow relative to the cable’s filtered motion.0 0 1amplifies the in-line drag alone. With an amplitude table’sCdAmp(for example Chaplin et al. 2005, Eq. 4), the mean in-line drag of a vibrating cable rises while its cross-flow drag stays Morison’s. The factor multiplies the whole in-line drag term, so the in-line damping rises with it. ACdAmpwithout this row multiplies the whole normal drag, the cross-flow damping included.0.31 0.89is the published cross-flow-only model of Thorsen et al. (2016), fitted to still-water decay tests fory0/Dup to about 0.6. It removes the linear part of Morison’s cross-flow damping (1/2 rho D Cdn U y'), so use it without in-line VIV: with aVIVsection row the in-line force turns with the relative flow and can drive a low-frequency cross-flow motion that nothing damps.0 0 1withCdAmp1 is Morison’s drag (to round-off). The split acts in the dynamics; the static solve keeps Morison’s drag, which is the same at rest.DragPowreports the split drag.Finite-EI cables only, standalone and coupled; an
EI = 0line with the row is refused by name. A row fails if it is notTypeName a b [c], names an undefined or already named type or one without an amplitude table, or holds a value out of range.
FAILURE (optional, EI = 0 decks)
A FAILURE row detaches line ends from a point during a dynamic run, with MoorDyn’s trigger rules.
--------------------- FAILURE ------------------------------------------
FailID Point Line(s) FailTime FailTen
(-) (-) (-) (s) (N)
1 P3 1,2 0 2.5e6
Column |
Meaning |
|---|---|
|
integer; rows are numbered 1, 2, 3, … in order |
|
the point the lines detach from: |
|
one line id or a comma list without spaces ( |
|
trigger time [s]; |
|
trigger tension [N] at the attached line end; |
At least one of FailTime > 0 or FailTen > 0 is required; both must be finite. At each
committed step an unfailed row fires when t >= FailTime (if positive) or when the attached-end
tension of any listed line reaches FailTen (if positive). Firing moves the listed line ends onto
a new free point with id = largest deck point id + row number, and prints
CableDyn: FAILURE <id> triggered at t = .... A row whose lines were already detached by an
earlier row has no effect.
FAILURE rows are used by three routes: the standalone EI = 0 dynamic point-system run, the
standalone Rigid6 body run, and the OpenFAST aggregate for pure EI = 0, non-FAST.Farm, frictionless
decks without Rigid6 bodies. In the standalone driver a FAILURE deck needs dtM and TMax;
finite-EI lines, rods, motionFile, and frictionMu are each rejected by name. A FAILURE deck with
free Rigid6 bodies runs on the staggered body scheme (bodyScheme is overridden, with a note) and
may not also hold Connect/Free points or Point3 bodies; a detached line end is integrated as
a free point while the bodies carry on with the remaining lines. This models a line break at a
fairlead in an accidental limit state (ALS) analysis; see
examples/als_volturnus_line_break_time.dat.
CONTROL (optional, OpenFAST line control)
A CONTROL row assigns lines to an active cable-control channel driven by the OpenFAST ServoDyn
CableDeltaL / CableDeltaLdot inputs.
--------------------- CONTROL ------------------------------------------
ChannelID Line(s)
(-) (-)
1 1,2
2 3
Column |
Meaning |
|---|---|
|
positive integer control channel |
|
one line id or a comma list without spaces ( |
Each line belongs to at most one channel. Before every advance, the channel’s DeltaL sets the
unstretched length of each assigned line’s fairlead-side segment to its initial length plus
DeltaL; DeltaLdot supplies the matching rate. The fairlead-side segment is the one at the
line’s end on a host-driven point: Coupled, Vessel, Turbine<J>, Body<N>, or an end of a
Coupled or Vessel rod. When both ends or neither end are on such points, it is the segment at
the NodeB written in the deck. A line written in the stock MoorDyn order, with its host-driven
end at NodeB, is therefore controlled where MoorDyn-F controls it, at its last segment N at
AttachB; so is a line with both or no host-driven ends. A line written fairlead first, with its
only host-driven end at NodeA, is controlled at that end. The length is held over the advance.
On a linear-elastic segment the axial damping acts on the strain rate, as in MoorDyn-F
(BA (lstrd − lstr ld/l)/l), so a segment paid out at constant strain carries no damping
tension; the viscoelastic and Syrope laws take the plain chord rate lstrd, as MoorDyn-F and
MoorDyn-C do (see the bullets below).
A command outside MoorDyn-F’s bounds stops the run with a message that names the channel, the
line, the command and the bound, as MoorDyn-F stops there. With UnstrLen the line’s unstretched
length and N its number of segments, both summed over its SECTIONS rows, MoorDyn-F refuses
DeltaL > UnstrLen/N and DeltaL < −0.5 UnstrLen/N; CableDyn makes the same comparisons, so
a command MoorDyn-F accepts is accepted. On a line of one section UnstrLen/N is the controlled
segment’s initial length S, and the bounds read −S/2 ≤ DeltaL ≤ S. On a line of several
sections the controlled segment can be shorter or longer than UnstrLen/N; a command within the
bounds that would make it zero or negative (possible when it is shorter than half of
UnstrLen/N) also stops the run, with a message that names the line.
On an
EI = 0line the segment is the end element on that side, of initial length S. The step evaluates the committed side of its generalised-α blend at the lengths of the previous advance (with the force blend, the default, the step-start force; underFalse alpha_force_blend, lengths blended with the configuration), so a length ramp is followed without lag at anyrhoInf.A Syrope polyester segment (a Syrope line, or a composite line whose fairlead-side section is Syrope) carries its slow stretch over the length change, as MoorDyn-F and MoorDyn-C carry it: they keep the stretch
dl_1of the segment as its state and read its slow strain asdl_1over the new length. The running maximum tension is kept, and the slow-strain rate takes the chord rate without the paid-out term, as MoorDyn’s Syrope rate does. A slow pay-out therefore unloads the segment along the working curve of its load history, and a haul-in beyond the running maximum follows the OWC and raises it.A viscoelastic segment (
Es|EdorEs|alphaMBL|vbeta) keeps its slow-branch stretchdl_1as it is over the length change and reads it at the new length, as MoorDyn-F and MoorDyn-C do: the tensionEA_1 dl_1/L0 + BA ld_1/L0, the rateld_1withdl= stretched length −L0, and the load-dependentEA_Dall take the newL0, and the rate takes the chord rate without the paid-out term. A slow pay-out or haul-in therefore follows the static lawEstimes the strain; a fast change first meets the dynamic stiffness and relaxes to it.On a finite-EI cable, which runs from a
Fixedanchor to a host-driven fairlead, the segment is the fairlead segment of the deck mesh (the length of theSECTIONSrow at the fairlead over itsNumSegs). Where the static initialisation refined the mesh, it is the cable elements that make up that segment. Each of them scales by (S +DeltaL)/S, S being the segment’s initial length, with rateDeltaLdotl/S for an element of initial length l, so the segment becomes S +DeltaLlong. The structural and attachment mass, the seabed contact coefficients and the tributary lengths follow the new lengths;BAkeeps its initial resolution. The step blends the force of the committed state, taken at the lengths of the previous advance, with the force at the new lengths, so a length ramp is followed without lag at anyrhoInf. This needs the force-blended generalised-α, the default: a deck that controls a finite-EI cable underFalse alpha_force_blendfails at initialisation with a message that names the line. Within the bounds above, a cable of one section scales each element within [0.5, 2] of its initial length; on a cable of several sections the scaling can leave that range, beyond the resolution its static mesh was built for, so keep large commands on a fairlead section whose segments are at leastUnstrLen/N long.On a cable restrained in torsion at both ends the torsion follows the lengths too: the line’s torsional compliance, the elements’ torsional stiffness
GJ/l and dampingBt/l, the torque–tension coupling and the polar inertiaIrnl/2 at the nodes take the new lengths, a torsional damping written as-ζkeeps itsζ(Bt= ζ l √(GJIrn) at the new length; a positiveBtstays), and the damping acts on the rate of the twist per unit length, so a segment paid out at constant twist per length carries no damping torque. A haul-in raises the torque of a fixed end-to-end twist asGJTwist/L does.
The host input arrays are sized to the highest channel id.
CONTROL is supported only on the OpenFAST CompMooring = 5 route, for non-FAST.Farm decks,
without OpenFAST linearisation. The standalone driver rejects a CONTROL section.
OPTIONS (value keyword order, case-insensitive keyword)
The OPTIONS reference is the complete table of every keyword and alias with its
type, unit, default, valid range, and route. examples/cabledyn_options_reference.dat shows every
syntax form. The most frequently edited keywords are:
Keyword |
Meaning |
Default |
|---|---|---|
|
gravity [m/s²] |
9.80665 |
|
water density [kg/m³] |
1025.0 |
|
water depth [m]; seabed plane z = −WtrDpth. Omit for a suspended or taut line with no bottom contact |
none |
|
structured bathymetry file (rows |
none |
|
seabed penalty stiffness base [Pa/m = N/m³], scaled per line node and rod contact station by diameter × tributary length, at a Free/Connect point with Mass or Vol and a Point3 buoy by its footprint |
1.0e5 |
|
seabed normal damping base [Pa·s/m = N·s/m³], scaled like |
1.0e4 |
|
|
|
|
isotropic seabed friction coefficient: stick-slip springs on line nodes (held by the static solve too in a deck current, from the still-water laid shape, or toward the as-laid position with |
0 |
|
anisotropic line friction: the coefficients along and across the local line axis (OrcaFlex axial/normal); an omitted one takes |
|
|
statics seabed friction policy (OrcaFlex): |
|
|
lay azimuth (deg, from +x toward +y) of every line, or of line |
chord direction, from the lower end |
|
as-laid effective tension (N, ≥ 0) of every line, or of line |
0 |
|
dynamic time step [s] |
— |
|
dynamic end time [s]; an integer multiple of |
— |
|
generalised-α spectral radius |
0.4 |
|
plausibility bound on |
0.5 |
|
first output time [s] in the range graphs of the |
0 |
|
|
|
|
coupled finite-EI cable reaction switch. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
non-negative strain band for the dynamic tensile audit |
|
|
integer from 4 to 65536; maximum step subdivision for dynamic-step recovery on tension-only and bending lines. Internal prescribed states lie on one C2 quintic trajectory and land on the nominal coupling endpoint. The standalone summary reports recovered intervals and the largest subdivision used |
|
|
|
|
|
real in (0, 90], deg; largest taut-segment turn per step before |
|
|
integer from 2 to 1024; most sub-steps |
|
|
Gauss order 1–6 for the finite-EI axial energy; a value different from the bending order gives selective integration |
|
|
Gauss order 1–6 for the finite-EI curvature energy |
|
|
dynamic Newton controls; keyword-first syntax, unlike scalar rows. |
|
|
|
none |
|
|
none |
|
one train of a multi-train sea, rows add up (at most 16): |
none |
|
cos-2s spreading exponent of a spectral |
0 |
|
direction bins of a spread train |
9 |
|
frequency components per train and direction (at least 2) |
200 |
|
Fourier terms of a |
0 |
|
modal analysis: the N lowest natural frequencies and mode shapes of every line about its static equilibrium, written to |
0 |
|
integer from 1 to 2147483646; seed of the random spectral sea (the same seed gives the same sea on every platform; train i uses seed + 7919 (i − 1)) |
1 |
|
half-cosine start-up ramp of the wave amplitudes [s]; the current is not ramped. |
0 |
|
path to a prescribed-motion time series for |
— |
|
path to a 6-DOF vessel record; every |
— |
|
path to a displacement RAO table; the vessel moves as the RAO response to the deck waves; an alternative to |
— |
|
|
|
The example decks write each record as value keyword - Description (unit) {choices} (the
OpenFAST style). The parser reads only the value keyword pair. The unit follows the description
and is omitted for dimensionless records; braces list the accepted values of a discrete option.
The positional current and waves records place the keyword after their parameters and accept
the same trailing description; the numeric fields before the keyword are validated strictly.
9.80665 g - Gravitational acceleration (m/s^2)
1.0e5 kBot - Seabed penalty stiffness base (Pa/m)
airy 2.0 8.0 0.0 waves - Wave model, height, period, and direction (m, s, deg)
staggered bodyScheme - Multibody step scheme {monolithic; staggered}
Option rows are last-row-wins. Unknown keywords are rejected. Static-solver tolerances are built
in, so keys such as staticRelTol or staticMaxIter are rejected like any other unknown option;
set the dynamic Newton controls with dynamic_solver. The stock MoorDyn keywords dtIC,
TmaxIC, CdScaleIC, threshIC, TScheme, WriteLog, and dtOut are accepted and ignored,
because CableDyn uses a Newton static initial condition, an implicit integrator, and
caller-controlled output cadence. MoorDyn-F’s inertialF is accepted as 1 only (CableDyn
always returns the inertia of coupled bodies and rods; 0 and 2 are rejected by name), and
inertialF_rampT is accepted and ignored.
MoorDyn-C WaveKin and Currents modes
A MoorDyn-C deck selects its water kinematics with the numeric WaveKin and Currents options
and fixed-name files in the deck folder. CableDyn reduces each wave file to wave components and
evaluates them exactly at every node, with Wheeler stretching; MoorDyn-C tabulates them on
water_grid.txt and interpolates, so that file is not read. The current files are evaluated at
every node’s position and time as MoorDyn-C interpolates them. Standalone decks only.
Option |
File |
Meaning |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
a depth profile in time: lines 1-4 and 6 are free text, line 5 lists the depths |
|
|
a grid in x, y, z and time: line 1 is |
Currents 2 and 5 follow MoorDyn-C v2.7.1 (constructDynamicCurrentGrid,
construct4DCurrentGrid and CurrentGrid::getCurrentKin):
the table is resampled in time at its smallest time interval
dt, fromt = 0tofloor(t_last/dt) dt(a last time that is not a multiple ofdtis not reached), linearly between rows and held at the first and last rows;between samples the current is linear in time; past the last sample the grid repeats with period
nt dt(ntsamples), holding itst = 0value over the last interval of each period, as MoorDyn-C’s index wrap does. A run longer than the last sample prints a note;in x, y and z the current is linear between grid coordinates and held beyond the end ones; the node elevation is not stretched;
the current has no fluid acceleration (MoorDyn-C sets it to zero), so its time variation adds no Froude-Krylov or added-mass load;
the static start takes the current at
t = 0, as MoorDyn-C’s default stationary initial condition does (its legacy dynamic relaxation,ICgenDynamic 1, samples the current over the relaxation time instead);a grid holds at most 2e6 resampled points in space and time (every static solve holds a copy, 48 MB at the limit);
the C API and the OpenFAST point-system shells have no simulation clock: they apply a current constant in time as a steady field, as
Currents 1, sampled at the nodes of the static state and, through the C API, at the step-start nodes before every step, and refuse one that varies in time;current_profile_4d.txtis read as MoorDyn-C documents it, which MoorDyn-C v2.7.1 does not quite do: it reads its rows from line 7, so a row on line 6 leaves that grid point at zero, and it matches a row to the grid by the text of its coordinates, so a row writing-0for0or1.0for1lands on the first grid point. CableDyn reads line 6 as a row unless it is text and matches by value, and it rejects a missing, repeated or off-grid point. A file with a text line 6 and its coordinates written as on lines 2-5 reads the same in both codes.
With WaveKin 3, MoorDyn-C (its default UnifyCurrentGrid 1) adds a current to the wave grid,
where it is sampled on water_grid.txt; CableDyn adds the current at the nodes, as MoorDyn-C’s
UnifyCurrentGrid 0.
Rejected by name: WaveKin 1 (kinematics set node by node through the MoorDyn-C API; a deck has
no source for them), WaveKin 2 (the FFT grid: wave_frequencies.txt resampled to an even
spectrum; WaveKin 7 evaluates the same file’s components exactly), WaveKin 4-6 and
Currents 3-4 (no kinematics source in MoorDyn-C v2.7.1). A deck that also declares a waves
option, a WaterKin file, or a second current source is rejected as double counting. On shared
inputs the wavekin_modes test holds WaveKin 7 and Currents 1 identical to MoorDyn-C v2.7.1 (5e-12 relative) and WaveKin 3
within 3e-7 m in elevation and 1e-4 in velocity and acceleration at MoorDyn-C’s grid points,
the remainder being MoorDyn-C’s grid interpolation and its approximate wave number. The
mdc_currents test holds Currents 2 and 5 identical to MoorDyn-C v2.7.1 at 739 points and
times (including past the last sample), and mdc_currents_runs matches the tension change of a
time-varying and of a sheared current to MoorDyn-C’s within 0.9 % on a 70 m rope.
wave_frequencies.txt is the file MoorDyn-C v2.7.1 reads, a beta per row included: its
SUM_COMPONENTS mode gives each row its own direction too. WaveRefX and WaveRefY
(options) are an extension of CableDyn and no part of MoorDyn-C or MoorDyn-F: a
deck with them is not a plain MoorDyn deck, and a MoorDyn solver would not place the phases there.
A mean level, a non-zero omega = 0 row or the mean of wave_elevation.txt, is added to the
elevation alone, as MoorDyn-C does: every wave number stays that of WtrDpth, and the Wheeler
stretching maps the water column under the total elevation, the level included. The
wavekin_modes test holds both files with a 0.8 m level, under six WaveKin 7 components in
six directions, to MoorDyn-C v2.7.2: WaveKin 7 to 1e-8 of its scale and WaveKin 3 to the
tolerances above. The mean of a WaterKin WaveKinMod 1 record raises the still-water level
instead (below).
MoorDyn-F WaterKin file modes
A MoorDyn-F deck may select a WaterKin file (grammar in Auxiliary file formats).
WaveKinMod and CurrentMod are independent switches. SEASTATE is recognised only as the
WaveKinMod value token, never in a trailing comment.
Mode |
Meaning |
|---|---|
|
no waves |
|
elevation history resampled at |
|
waves from the coupled host SeaState field |
|
no current |
|
N-level WaterKin depth table, interpolated at structural nodes |
|
current from the coupled host SeaState field |
The mean of a WaveKinMod 1 record raises the still-water level: its wave numbers are those of
WtrDpth plus the mean, and the stretching maps the water column under the raised level.
MoorDyn-F instead drops the record’s mean, and its Nyquist bin, so a record whose mean is not zero
puts the surface of the two codes apart by that mean.
WaveKinMod 1 is standalone-only. It needs a WaveKinFile of at least four finite
time elevation rows starting at t = 0 with strictly increasing times, a positive dtWave, a
positive TMax, and the ordinary waves requirements (dtM/TMax and WtrDpth). It cannot be
combined with a waves option or with CurrentMod = 2, and it is rejected on the coupled
aggregate route and in a mixed EI = 0 + finite-EI standalone deck.
Host modes (WaveKinMod 2/SEASTATE, CurrentMod 2) require aggregate/OpenFAST
initialisation with a SeaState field; the standalone driver rejects them with
WaterKin WaveKinMod 2/SEASTATE is coupled-only.
Host waves may be combined with a file
CurrentMod 1profile.Current-only host mode removes host wave velocity and acceleration and uses still-water wetting.
SeaState embeds its standard steady current in
WaveVel. The module reconstructs that current on the same four vertical grid nodes and interpolation weights before removing or keeping it. If SeaState uses its user-defined current (SeaStateCurrMod = 2), the field cannot be decomposed and is rejected whenever separate wave/current selection is required.An explicit WaterKin file overrides SeaState:
WaveKinMod 0/CurrentMod 0disables both host components, andWaveKinMod 0/CurrentMod 1uses only the file profile. The full host field is used only when the deck gives no WaterKin selection.A deck that declares both a
currentoption and a WaterKinCurrentMod 1table is rejected as double counting.
Prescribed motion (motionFile)
0 or none (any case) disables prescribed motion, so one deck can serve static and dynamic
cases. With an active path:
On the finite-EI (
EI > 0) route each prescribed endpoint is a moving support: its velocity, acceleration, and support inertia enter the dynamic residual, not only its position. Row 1 is committed as the initial boundary state before thet = 0fluid sample and output; this does not advance time.Coupled/Vesselrods are prescribed from their two end rows while the attached lines advance;Freerods in the same deck are integrated dynamically.Rigid6 decks prescribe the full 6-DOF body motion from
Body<N>rows (see BODIES).A mixed
EI = 0+ finite-EI deck of lines betweenFixed/Coupled/Vesselpoints moves the points of both line kinds from their rows, and a finite-EI line on them as on the finite-EI route (row 1 installed beforet = 0, the roll column below).Connect/Freepoint-system decks and FAILURE decks rejectmotionFile.
Every non-comment record of the motion file is one row time point_id x y z vx vy vz ax ay az of
plain numbers; tokens after the eleventh are ignored, except that a deck with a line solved in
torsion reads a twelfth, roll [deg]: at the point, the roll of the frame of the line’s moving
end restrained in torsion (End A, or End B in a deck that lists the Fixed anchor as End A; both
ends of a line between two moving points), right-handed about the line tangent pointing into the
line from that end. It imposes Phi(t) = Pretwist(B) − Pretwist(A) − roll(A)(t) − roll(B)(t),
the roll of a Fixed end, or of an end free in torsion, being 0: the roll has the sense of
Pretwist(A) at End A (where the inward tangent is Ez) and the opposite sense to Pretwist(B)
at End B (where it is −Ez), so equal rolls of the two ends of a line between two moving points
twist it by twice the roll, and a rigid roll of the line about its axis (opposite rolls) does not
twist it. The roll is 0 at
t = 0 and is given on every row of the point or on none. Header lines must be comments. time must
lie on the 0, dtM, 2·dtM, … grid (rows after TMax are read and not used) and point_id must be
a prescribed point. Each
(point, time) pair appears once, every prescribed point needs a row at every grid time, and rows
may appear in any order. See also Auxiliary file formats.
Vessel motion (vesselMotion, vesselRAO)
A vessel is a rigid body that carries every Coupled/Vessel point of the deck. Its
reference point vesselRef (default 0|0|0) is the rotation centre and the RAO origin. The deck
positions of the points are their positions at the reference pose, where the vessel axes are the
global axes. With the vessel reference point at r(t) and rotation R(t), a point with deck
position P moves as
x = r + R p, v = dr/dt + w × (R p), a = d²r/dt² + al × (R p) + w × (w × (R p)), p = P − vesselRef
where w and al are the angular velocity and acceleration in global axes. The resulting point
rows replace a motionFile, so vessel motion runs wherever a motionFile runs; decks with
prescribed rods, Rigid6 bodies or TURBINES reject it. motionFile, vesselMotion and
vesselRAO are alternatives: a deck may activate only one. A finite or Rigid END CONNECTION
at a vessel point keeps its direction in vessel axes, so it turns with the vessel and its
moment follows the vessel rotation.
Rotations use the OrcaFlex vessel convention: R = Rz(yaw)·Ry(pitch)·Rx(roll), right-handed
about the vessel x (roll), y (pitch) and z (yaw) axes, applied yaw, then pitch, then roll.
vesselMotion record. One row per dtM grid time from 0 to TMax, in any order (rows on
the grid after TMax are read and not used), in one of two forms for the whole file:
time x y z roll pitch yaw vx vy vz wx wy wz ax ay az alx aly alz (19 values)
time x y z q0 q1 q2 q3 vx vy vz wx wy wz ax ay az alx aly alz (20 values)
x y z is the reference-point position [m]; roll pitch yaw are the Euler angles [deg], or
q0 q1 q2 q3 a unit quaternion (scalar first, norm within 1e-6 of 1); vx vy vz and
ax ay az are the reference-point velocity [m/s] and acceleration [m/s²]; wx wy wz and
alx aly alz are the angular velocity [rad/s] and angular acceleration [rad/s²] in global axes.
The driver uses the velocities and accelerations as given; they must be the time derivatives of
the positions and rotations for the motion to be consistent.
vesselRAO table. Displacement RAOs in blocks, one per relative wave heading:
HEADING 0
# period surgeA surgeP swayA swayP heaveA heaveP rollA rollP pitchA pitchP yawA yawP
6.0 0.10 95.0 0.0 0.0 0.35 5.0 0.0 0.0 0.9 100.0 0.0 0.0
10.0 0.60 92.0 0.0 0.0 0.95 2.0 0.0 0.0 1.2 95.0 0.0 0.0
HEADING 45
...
Periods in s; translation amplitudes in m/m, rotation amplitudes in deg/m; phases in deg.
Phase convention: a lag relative to the wave crest at the vessel reference point. A wave component whose elevation at
vesselRefisa cos(ωt − ε)moves DOF j asA_j a cos(ωt − ε − P_j): a positive phaseP_jmeans the motion peaksP_j/ωafter the crest passes the reference point. This is OrcaFlex’s default RAO convention (phases as lags, relative to the wave crest at the RAO origin, rotations in deg/m).The relative heading of a wave component is its own direction of travel (the vessel axes are the global axes), so the components of a spread sea or of several wave trains each take the RAO at their own heading. Every block must list the same periods; periods and headings may appear in either order.
The complex RAO
A e^(−iP)is interpolated linearly in period and in heading. A component period outside the table takes the RAO of the nearest tabulated period (the run notes how many components do); a heading outside the tabulated range is an error, and a one-block table applies to its own heading only.The waves are the deck linear sea:
airy, the spectralwavesrows (withWaveSpreading),wavetrainrows, or a WaterKinWaveKinMod 1file, with the same component frequencies, directions and phases that drive the line kinematics, so the vessel and the line see one sea. A nonlinearstream/deanwave has no linear components and is rejected withvesselRAO. The response is multiplied by therampTimeramp; velocities and accelerations are the exact time derivatives (including those of the ramp), and rotation rates become the global angular velocity and acceleration through the Euler-angle kinematics.
OUTPUTS (one channel per line)
The example decks list one double-quoted channel per row; the quotes are removed on read. Rows
with several channels separated by whitespace or commas (FairTen1 AnchTen1,
FairTen1, AnchTen1) are also accepted, quoted as a whole ("FairTen1, AnchTen1") or not. A bare
END row closes the list. Channel names are
case-insensitive and at most 64 characters.
The example decks request FairTen, AnchTen, FairIncl, and AnchIncl for every line;
point-system examples add point X/Y/Z position and finite-EI examples add selected curvature and
bending moment. None of these channels is mandatory.
Channel |
Meaning |
Unit |
|---|---|---|
|
line L fairlead (End A) line-end tension: the magnitude of the force the line actually exerts on its End-A point (end element force with axial damping, including the bending shear of a finite-EI line, plus the end node’s share of the submerged weight, seabed contact and drag at the actual velocity; without the end node’s inertia), the static end reaction at rest. Route differences (seabed friction) are in Outputs |
N |
|
line L anchor (End B) line-end tension, as |
N |
|
line L vertical component of the |
N |
|
line L horizontal magnitude of the |
N |
|
line L fairlead (End A) signed inclination below horizontal (0 = horizontal; positive = downward) |
deg |
|
line L anchor (End B) signed inclination below horizontal (0 = horizontal; positive = downward) |
deg |
|
line L fairlead (End A) declination from +GZ (0 = up, 90 = horizontal, 180 = down) |
deg |
|
line L anchor (End B) declination from +GZ (0 = up, 90 = horizontal, 180 = down) |
deg |
|
aliases of |
deg |
|
line L deflection of the End-A / End-B end force from the direction a |
deg |
|
point P position component |
m |
|
alias of |
m |
|
Rigid6 body and rod channels in the MoorDyn-F names: position, attitude, velocity and acceleration ( |
see Outputs |
|
resultant of the line-end and cable end forces on point P (each the |
N |
|
line L effective tension at node J. EI = 0 lines: the mean of the two adjacent segment tensions. Finite-EI lines: the axial component of the section force recovered from nodal equilibrium ( |
N |
|
line L curvature at node J. |
1/m |
|
line L bend moment = EI × curvature / (1 + ε), the moment that balances the forces on the section, relative to the stress-free reference shape (≈ 0 at the reference; the finite-EI reference is straight). Finite-EI lines: recovered from nodal equilibrium, the moment the neighbouring elements carry ( |
N·m |
|
line L share of the section moment a bend stiffener carries at node J (the section moment less |
N·m |
|
line L node J position component |
m |
|
line L node J velocity component (0 in static-only runs) |
m/s |
|
line L node J acceleration component (0 in static-only runs) |
m/s² |
|
line L declination of the axial tangent at node J (from +GZ; 0 = up, 90 = horizontal, 180 = down) |
deg |
|
line L azimuth of the axial tangent at node J (from +GX toward +GY, in [0, 360)) |
deg |
|
line L touchdown point (TDP): arc length from End A, between the last grounded node and the next, where the parabola through the last grounded node and the next two nodes crosses the contact-onset height (1e-6 m above the seabed); continuous as nodes ground and lift off (Outputs) |
m |
|
line L TDP position |
m |
|
line L layback: horizontal distance from the TDP to the suspended end |
m |
|
line L TDP excursion: horizontal TDP displacement from its initial position, along the initial direction toward the suspended end |
m |
|
line L grounded length: deformed chord length along the nodes from the grounded end to the TDP; continuous with the TDP, 0 only when nothing touches (the grounded end has lifted off) |
m |
|
line L torque at node J (uniform along the line in statics); positive for a right-handed twist of End B relative to End A about the End A → End B tangent. Only on a line solved in torsion (restrained at both ends, or at one end with the other free) |
N·m |
|
line L material twist accumulated from End A to node J, |
deg |
|
line L total twist |
deg |
|
line L power of the VIV loads (cross-flow lift, and the in-line force of a |
W |
|
line L power of the Morison drag (and, on a finite-EI line, its ATTACHMENTS’ drag) |
W |
|
line L power of the structural damping ( |
Bb |
|
the same per unit unstretched length about node J (node J’s share: half of each of its elements’ power and its own node loads’, over half their unstretched length) |
W/m |
|
line L smoothed cross-flow amplitude estimate at node J (Thorsen et al. 2016, Eq. 9), which a VIV AMPLITUDE table reads; only on a line with such a table; 0 at a node without VIV |
m |
<L>/<P>are deck LINE/POINT ids, not array positions. A channel that matches no supported form, names an unknown id, or carries trailing text (for examplePoint2px_raw) is a parse error. The.outheader lists each channel token verbatim.Curvature, bend moment, declination, azimuth, and end angles are computed from node positions, so they are available on every route: static, independent EI = 0 dynamic, point-system EI = 0 dynamic, independent finite-EI dynamic, rod dynamic, Rigid6 dynamic, multibody and mixed.
BendMomis non-zero only on finite-EI lines. The axial tangent points End A → End B (OrcaFlex’s node Ez axis).Per-line
pandtfiles are available on the same routes except the mixedEI = 0+ finite-EI route, therrange graph on every standalone route; other flags are rejected.TDP<L>channels need a seabed (WtrDpthorbathymetryFile) and a line that rests on the seabed at exactly one end in its initial state; otherwise the run stops with exit code 1 naming the line. They are available on every route, OpenFAST included.The anchor uplift check of a drag-embedment anchor (no vertical load at the anchor in the intact condition) reads
TDP<L>Grd(greater than a small tolerance such as 0.01 m throughout);AnchFz<L>is the vertical anchor load. On anEI = 0line it includes the anchor node’s lumped weight, so its sign change lags the anchor segment’s lift-off; see Outputs (Anchor uplift).In an OpenFAST
CompMooring = 5run, channel headers in the OpenFAST output and in<OpenFASTRoot>.CD.outuse OpenFAST’s 20-character width (ChanLen). A longer channel name stops coupled initialisation with an error naming the channel; keep coupled channel names within 20 characters.
File layouts and column definitions for every output are in Outputs.
Static-configuration file <out_root>.static.out
The along-arc static profile (a range graph of the static state) is written in the
OpenFAST/MoorDyn tabular layout that pyDatView reads, one row per node of every line. Its
columns are LineID Node ArcLength X Y Z Tension Curvature BendMoment Declination Inclination Azimuth (Outputs defines each one). These standalone routes write it:
a static-only
EI = 0deck (nodtM/TMax);the cubic-Hermite finite-EI route, on both static (
TMax = 0) and dynamic runs, together with the element-extrema file<out_root>.elements.out;a mixed
EI = 0+ finite-EI deck.
The independent EI = 0 dynamic, point-system, rod, and Rigid6 routes do not write it. The file
is additive; <out_root>.out is
unchanged.
An OpenFAST CompMooring = 5 run always writes <OpenFASTRoot>.CD.static.out after coupled
initialisation. It also writes <OpenFASTRoot>.CD.out at the committed dtM cadence when the
deck requests time-history channels; this file is independent of OpenFAST DT_Out.
Driver workflow
CableDyn_driver <deck.dat> <out_root>
A source build names the same program cabledyn; see the command-line reference.
Parse the deck into line types, points, lines, options, and outputs; fail closed on any unsupported feature.
Build each line’s mesh and analytic catenary seed.
Static initial condition: per-line load-continuation Newton solve on the flat or structured penalty seabed; point systems add the shared-point force balance.
Dynamic run (when
dtM/TMaxare set): generalised-α integration from the static state, with BA damping, added mass, seabed spring, normal damping and stick-slip seabed friction, optional uniform/profile-current Morison drag, and optional wave drag, Froude–Krylov, and buoyancy wetting.Finite-EI decks run on the cubic-Hermite route with held or prescribed translational end motion, structural loads, translational current/wave loads, and flat or structured seabed contact, damping, and friction on the same residual. Finite-EI rotational hydrodynamics are not modelled. Decks that add bodies, rods or
Connect/Freepoints run on the multibody march.Without
motionFile,Fixed/Coupledends are held at their deck positions. With it, the file gives a row on thedtMgrid for everyCoupled/Vesselpoint, prescribed rod end, and prescribed Rigid6Body<N>point at every time.A mixed
EI = 0+ finite-EI deck runs on the failure-atomic aggregate used by OpenFAST, with every coupled end held. Prescribed motion, deck wave/current, and per-linep/trequests are rejected; useOUTPUTSchannels for mixed-deck histories. A static-only mixed deck may omit bothdtMandTMax; a positiveTMaxneeds an explicit positivedtM.
Output
<out_root>.out: column 1 isTime(s), followed by the requested channels. The time column has 17 significant digits (ES25.16E3), so time stamps round-trip exactly on long records and fine steps; channel columns useES15.7E3(ES15.7on the mixed route). A static-only run writes one row at t = 0. On single-type routes, LINESOutputsflagspandtalso write per-line files (static: node/segment tables; dynamic: time series).
Exit codes, the stdout/stderr split, and the completion line are in Exit status and automation; error messages and fixes are in Troubleshooting.
Design decisions
SI units in the deck; tensions output in N.
The static initial condition is always a load-continuation Newton equilibrium computed from geometry alone; there is no initial-condition option, and an
ICmoderow is rejected. MoorDyn’s drag-scaled dynamic relaxation is not used; its tuning keywords are accepted and ignored.A line is one object (End A → End B) built from ordered
SECTIONS, each with its own line type and mesh. The stock one-type-per-line MoorDyn row is the single-section case.