Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions doc/capabilities.rst
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ Line and constitutive capability
the platform, ``PtfmInit``, checkpoints, linearisation with the twist angles as states;
see :doc:`openfast`) and through the C API with the host's rotations
(``CableDyn_InitDeckRotating``, :doc:`capi`), active line control (``CONTROL``) of the
fairlead segment on the coupled route; ``Torq``/``Twist`` channels and standalone range
fairlead segment on the coupled route; ``Torq``/``Twist`` channels and range
graphs. Stopped by name: ``CableDyn_InitDeck``/``InitDeckAt`` (which move the line ends by
translation only), ends of free and pinned rods (axisymmetric, no roll angle) and of
``Coupled``/``Vessel`` rods, bodies other than Rigid6 and ``False alpha_force_blend``.
Expand Down Expand Up @@ -193,9 +193,10 @@ Loads and environment
- a 6-DOF vessel record, or the RAO response to the deck waves, moves every
``Coupled``/``Vessel`` point of a line deck; see :doc:`options`
* - Range graphs (``r`` line output flag, ``RangeStart``)
- Standalone only
- minimum, maximum, and mean along each line over the run; a coupled OpenFAST deck rejects
the flag
- Standalone and OpenFAST
- minimum, maximum, and mean along each line over the run, from the committed steps; a run
restarted from a checkpoint keeps them. A FAST.Farm shared mooring and the C API reject
the flag by name
* - WaterKin CurrentMod-1 file table
- Supported
- bit-identical to the equivalent inline depth profile
Expand Down
2 changes: 2 additions & 0 deletions doc/capi.rst
Original file line number Diff line number Diff line change
Expand Up @@ -937,6 +937,8 @@ The deck is validated under the standalone-deck rules:
- the standalone driver (prescribe motion through ``CableDyn_Step`` instead)
* - a ``FAILURE`` section (line failures)
- the standalone driver; the OpenFAST module
* - the ``LINES`` ``Outputs`` flag ``r`` (range graph)
- the standalone driver; the OpenFAST module in a single-turbine run
* - a ``CONTROL`` section (active line control)
- the OpenFAST module
* - ``WaveKinMod 2`` / ``SEASTATE`` wave kinematics
Expand Down
4 changes: 2 additions & 2 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -740,7 +740,7 @@ never both: a `SECTIONS` row for a 7-column line is an error naming the line.
|--------|---------|
| `ID` | unique line id ≥ 1 |
| `NodeA`, `NodeB` | End A / End B POINT ids (distinct). **End A is the fairlead (top) end and End B the anchor (lower) end**, as in OrcaFlex. |
| `Outputs` | per-line file flags. `-` = none. `p` (node positions) and `t` (segment tensions) write `<out_root>.Line<ID>.p.out` / `.t.out`, End A first. Static EI = 0 decks write node/segment tables; independent EI = 0, point-system EI = 0, independent finite-EI, rod, and Rigid6 dynamic decks write time series (one row per output time). `r` writes the range graph `<out_root>.Line<ID>.range.out`: the minimum, maximum and mean over the run (from `RangeStart`) of the node tension, curvature, bend moment, declination and seabed clearance (and torque and twist on a line with torsion), on every standalone route; a coupled OpenFAST deck rejects it. Line-node channels in the main `.out` file are requested in `OUTPUTS`. |
| `Outputs` | per-line file flags. `-` = none. `p` (node positions) and `t` (segment tensions) write `<out_root>.Line<ID>.p.out` / `.t.out`, End A first. Static EI = 0 decks write node/segment tables; independent EI = 0, point-system EI = 0, independent finite-EI, rod, and Rigid6 dynamic decks write time series (one row per output time). `r` writes the range graph `<out_root>.Line<ID>.range.out`: the minimum, maximum and mean over the run (from `RangeStart`) of the node tension, curvature, bend moment, declination and seabed clearance (and torque and twist on a line with torsion), on every standalone route and in a single-turbine OpenFAST run (`<RootName>.CD.Line<ID>.range.out`); a FAST.Farm shared mooring and the C API reject it. Line-node channels in the main `.out` file are requested in `OUTPUTS`. |

**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
Expand Down Expand Up @@ -1264,7 +1264,7 @@ syntax form. The most frequently edited keywords are:
| `TMax` | dynamic end time [s]; an integer multiple of `dtM` | — |
| `rhoInf` | generalised-α spectral radius | 0.4 |
| `maxStrain` | plausibility bound on `EI = 0` element strain, checked after every committed dynamic step; a non-finite state or a larger strain stops the run with exit code 2. `0` disables it | 0.5 |
| `RangeStart` / `range_start` | first output time [s] in the range graphs of the `LINES` `Outputs` flag `r`; earlier rows (a start-up transient) are left out. ≥ 0 and ≤ `TMax`; needs `TMax` and a line with the `r` flag | 0 |
| `RangeStart` / `range_start` | first output time [s] in the range graphs of the `LINES` `Outputs` flag `r`; earlier rows (a start-up transient) are left out. ≥ 0 and ≤ `TMax` (the host's in OpenFAST); needs a line with the `r` flag and, standalone, `TMax` | 0 |
| `modified_newton` | `True`/`False`: reuse the tangent within a step on every dynamic solver the deck builds (the EI = 0 system and each coupled finite-EI cable): one effective-tangent factorization per step, contraction-checked with a refresh when the direction goes stale. Committed states meet the same Newton tolerance either way | `False` |
| `cable_load_feedback` | coupled finite-EI cable reaction switch. `True` returns cable force and moment to the host. `False` marches the cable with the same moving boundary and host fluid field and keeps its output channels, but returns zero force and moment; use it for a one-way comparison, not as a physical model | `True` |
| `adaptive_mesh` | `True`/`False`; allow finite-EI mesh refinement when the static resolution check is fragile | `False` |
Expand Down
2 changes: 1 addition & 1 deletion doc/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ What CableDyn does
- yes
* - Modal analysis (``nModes``), range graphs, discrete ``ATTACHMENTS``
- yes
- ``ATTACHMENTS`` only
- range graphs and ``ATTACHMENTS``
* - Checkpoint/restart, linearisation, FAST.Farm, active tensioning
- —
- yes (:doc:`openfast`)
Expand Down
16 changes: 14 additions & 2 deletions doc/openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,12 @@ the seabed (``Z_Depth = WtrDpth + MSL2SWL``): they are in the seabed, where the
grid bottom are the right ones. FAST.Farm runs, which use still water, and SeaState fields
without waves or current are not checked.

SeaState's cosine depth grid is coarsest at the bottom: its deepest interval is
``Z_Depth*sin(pi/(2*(NZ - 1)))``, about 22 m at 200 m depth with ``NZ = 15``, and the field falls
linearly across it to the seabed, so near the seabed it differs from a deck depth table; when that
interval exceeds 5 % of the depth (``NZ`` below 33) and a line lies in it, an initialisation note
states the interval and the ``NZ`` that would bring it under 5 %.

Run and confirm
---------------

Expand Down Expand Up @@ -268,7 +274,11 @@ channels ``AnchFz<L>``, ``AnchFH<L>`` and ``TDP<L>Grd``) and units are in :doc:`
* - ``<RootName>.CD.static.out``
- CableDyn-owned, always written: the static-equilibrium profile of every line, one row per
node (arc length, coordinates, effective tension, curvature, bend moment, declination,
inclination, azimuth) — the coupled range graph, at the state of the printed line summary
inclination, azimuth), at the state of the printed line summary
* - ``<RootName>.CD.Line<L>.range.out``
- CableDyn-owned, for a line with the ``LINES`` ``Outputs`` flag ``r``: the range graph, the
minimum, maximum and mean at every node over the committed steps from ``RangeStart``,
written when the run reaches ``TMax`` (:doc:`outputs`)
* - ``<RootName>.CD.rst.dat``
- temporary CableDyn-owned copy of the deck, written in the ``MooringFile`` folder only
when a run restarts from a checkpoint (see *Lifecycle features*), and removed after use
Expand Down Expand Up @@ -380,7 +390,9 @@ without an auxiliary process:
* **Checkpoint/restart** serialises the committed line, constitutive, connection, body, and rod
state needed to continue the trajectory, with the SeaState fields the committed step holds and,
with ``dtM`` larger than ``DT``, the loads of the solve before it (the load predictor), so a
restart continues the run bit for bit at any ``dtM``. A checkpoint is accepted only on a committed CableDyn
restart continues the run bit for bit at any ``dtM``. The accumulated range graphs (``LINES``
flag ``r``) are part of it, so a restarted run writes the range files of an uninterrupted one. A
checkpoint is accepted only on a committed CableDyn
step, so choose ``ChkptTime`` as a whole multiple of ``dtM``; a checkpoint written between two
commits stops the restart with a message that says so. On restart the module writes a
temporary deck copy, ``<RootName>.CD.rst.dat``, beside the ``MooringFile``, rebuilds the model
Expand Down
6 changes: 4 additions & 2 deletions doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -282,8 +282,10 @@ Clock and initial condition
- finite, ≥ 0 and ≤ ``TMax`` (any value at ``TMax = 0``, where the graphs hold the
``t = 0`` row). First output time accumulated into the range graphs
(``<out_root>.Line<L>.range.out``, ``LINES`` ``Outputs`` flag ``r``), so a start-up
transient is left out. Needs ``TMax`` and at least one line with the ``r`` flag
- standalone only
transient is left out. Needs at least one line with the ``r`` flag and, standalone,
``TMax``
- both; OpenFAST holds it against the host ``TMax``. A FAST.Farm shared mooring rejects the
``r`` flag
- ``100.0 RangeStart``

Nonlinear solver
Expand Down
15 changes: 13 additions & 2 deletions doc/outputs.rst
Original file line number Diff line number Diff line change
Expand Up @@ -384,6 +384,16 @@ every node: the minimum and maximum equal those of the channel time
histories exactly, and the mean is their arithmetic mean. The file is written when the run
completes; a run that stops early leaves none.

A single-turbine OpenFAST run writes the same file as ``<RootName>.CD.Line<L>.range.out``. Its
samples are the rows of ``<RootName>.CD.out``: the state at ``t = 0`` and every committed ``dtM``
step, once each whatever ``DT``, ``DT_Out`` and the correction iterations are; a step OpenFAST
corrects counts once, with its corrected state. The accumulators are double precision on every
OpenFAST build and travel in the checkpoint, so a restart continues them. The file is written at
the end of a run that reaches ``TMax``; the run removes one left by an earlier run when it starts,
and one that stops before ``TMax`` says so and leaves none. An OpenFAST run stopped early on
purpose (``CalcSteady`` once steady) counts as stopping early. A FAST.Farm shared mooring and the
C API write no range file and reject the flag by name.

Layout: title line, header row, **units row**, then one row per node, End A first. The title reads
``CableDyn range graph (line <L>; <n> samples from t = <t0> s to t = <t1> s; public node order
End A -> End B)``.
Expand Down Expand Up @@ -1018,8 +1028,9 @@ a run and intact after a crash.

Select CableDyn channels in the ``OUTPUTS`` section of the CableDyn ``MooringFile``; they are not
members of the top-level ``.fst`` ``OutList``. The ``TDP<L>`` channels are evaluated from the
coupled state against the touchdown reference of the converged initialisation; the range files of
the ``LINES`` flag ``r`` are a standalone output, and a coupled deck with that flag is rejected. For
coupled state against the touchdown reference of the converged initialisation. The ``LINES`` flag
``r`` adds ``<RootName>.CD.Line<L>.range.out`` (see above) to a single-turbine run; a FAST.Farm
shared-mooring deck with that flag is rejected. For
a single-turbine run the module also prints
every selected channel's static value to the screen after initialisation. A deck with no
``OUTPUTS`` section is valid but publishes no channels.
Expand Down
2 changes: 1 addition & 1 deletion doc/tutorial_openfast.rst
Original file line number Diff line number Diff line change
Expand Up @@ -232,7 +232,7 @@ Check, in order:
CableDyn step (every ``dtM``), with a units row
* - ``IEA-15-UMaine_CompMooring5_CableDyn.CD.static.out``
- the initial nodal equilibrium of every line (arc length, coordinates, tension, curvature,
bend moment, declination, inclination, azimuth) — the coupled range graph
bend moment, declination, inclination, azimuth)
* - ``*.ED.sum``, ``*.HD.sum``
- the usual OpenFAST module summaries

Expand Down
31 changes: 18 additions & 13 deletions python/cabledyn/deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -1623,8 +1623,11 @@ class DeckFile:
current is kept as a steady field when SeaState carries no waves or current and is
rejected otherwise. The native C API (:class:`cabledyn.CableDyn`) reads decks with the
standalone rules, so it rejects the ``CoupledPinned``/``VesselPinned`` bodies and rods
that ``caller_driven=True`` accepts; FAST.Farm, in turn, refuses bodies and rods when it
initialises the module. A coupled deck carries bodies or rods, not both (a rod fixed to a
that ``caller_driven=True`` accepts; a FAST.Farm shared mooring, in turn, refuses bodies and
rods and the ``LINES`` range-graph flag ``r`` when it initialises the module, and the C API
refuses the flag. ``RangeStart`` is held
against the host's ``TMax`` when OpenFAST initialises the module, not against a deck
``TMax``. A coupled deck carries bodies or rods, not both (a rod fixed to a
body counts as a rod): ``caller_driven=True`` rejects a deck with both, as the coupled
route and the C API do, while the standalone driver's multibody march takes them.
"""
Expand Down Expand Up @@ -4125,17 +4128,19 @@ def is_body_kind(kind: str, pinned: bool) -> bool:
f"{self._label}: OPTION RangeStart needs a line with the LINES Outputs "
"flag r (range graph)"
)
if not has_tmax:
raise DeckFormatError(
f"{self._label}: OPTION RangeStart needs a dynamic deck (TMax)"
)
tmax_value = _native_float(option_by_key["tmax"].values[0])
# at TMax = 0 (a dynamic deck's static start) the range graphs hold the t = 0 row
if _native_float(range_start.values[0]) > tmax_value and tmax_value > 0.0:
raise DeckFormatError(
f"{self._label}: OPTION RangeStart exceeds TMax: the range window would hold "
"no output time"
)
# a coupled host owns the run time: the native init holds the window against it
if not self.caller_driven:
if not has_tmax:
raise DeckFormatError(
f"{self._label}: OPTION RangeStart needs a dynamic deck (TMax)"
)
tmax_value = _native_float(option_by_key["tmax"].values[0])
# at TMax = 0 (a dynamic deck's static start) the range graphs hold the t = 0 row
if _native_float(range_start.values[0]) > tmax_value and tmax_value > 0.0:
raise DeckFormatError(
f"{self._label}: OPTION RangeStart exceeds TMax: the range window would "
"hold no output time"
)

# Native check_channel: ids are digit strings compared by value, so leading zeros
# are accepted (FairTen01 is FairTen1).
Expand Down
23 changes: 23 additions & 0 deletions python/tests/test_deck_file.py
Original file line number Diff line number Diff line change
Expand Up @@ -2547,6 +2547,29 @@ def test_range_flag_and_range_start_follow_native_rules():
assert DeckFile.from_text(_edit(_STATIC, ("1 2 1 -\n", "1 2 1 r\n"))).lines[0].tokens[3] == "r"


def test_coupled_range_flag_and_range_start_take_the_host_clock():
# the host owns the run time: no deck TMax is needed, and one is not a bound on RangeStart
no_tmax = _edit(
_STATIC,
("1 2 1 -\n", "1 2 1 r\n"),
("50.0 WtrDpth\n", "50.0 WtrDpth\n100.0 RangeStart\n"),
)
deck = DeckFile.from_text(no_tmax, caller_driven=True)
assert deck.option("RangeStart").values == ("100.0",)
assert deck.lines[0].tokens[3] == "r"
deck_tmax = _edit(
_DYNAMIC, ("1 2 1 -\n", "1 2 1 r\n"), ("10.0 TMax\n", "10.0 TMax\n12.0 RangeStart\n")
)
with pytest.raises(DeckFormatError, match="exceeds TMax"):
DeckFile.from_text(deck_tmax)
assert DeckFile.from_text(deck_tmax, caller_driven=True).option("RangeStart").values == (
"12.0",
)
# the flag is still what RangeStart needs
with pytest.raises(DeckFormatError, match="needs a line with the LINES Outputs flag r"):
DeckFile.from_text(_edit(no_tmax, ("1 2 1 r\n", "1 2 1 -\n")), caller_driven=True)


def test_fixtures_are_valid_decks():
static = DeckFile.from_text(_STATIC)
dynamic = DeckFile.from_text(_DYNAMIC)
Expand Down
Loading
Loading