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
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,25 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Changed

- `TMax = 0` checks the static start of any dynamic deck as it stands: a `motionFile` or
`vesselMotion` record may run past `TMax` (its later rows are checked on the `dtM` grid and
not used, so a long record also serves a shorter run), and `RangeStart` is accepted at
`TMax = 0`, where the range graphs hold the `t = 0` row. A standalone deck without `TMax` that
asks for the march now says so: its error ends "to check a dynamic deck's static start only,
give dtM with TMax = 0".
- Deck waves from a WaterKin elevation history (`WaveKinMod 1`) run two to four times faster.
Below the surface, the velocity and acceleration sums stop once the components still to come,
too short to reach that depth, cannot change them beyond round-off. On a 1024-element lazy-wave
cable over 300 s, a record at `dtWave` 0.25 s (600 components) runs in 103 s instead of 226 s,
and one at 0.1 s in 189 s instead of about 660 s, with output identical to the printed digits.
A `jonswap` sea changes at round-off.
- An elevation record (WaterKin `WaveKinMod 1`) keeps only its Fourier components up to the new
`WvHiCOff` option, in rad/s as in SeaState, by default 0.5 Hz (MoorDyn-C's fixed cut for
`WaveKin 3`, which now follows the option too); `none WvHiCOff` keeps them up to the Nyquist
frequency of `dtWave`, as MoorDyn-F and earlier CableDyn did. A one-hour record at `dtWave`
0.1 s drops from 18,000 components to 1,800. On the 300 s lazy-wave case both records then run
in 72 s, and every output channel's standard deviation moves by at most 0.002 %. A record with
no component at or below the cut-off is refused by name.
- Under a bend stiffener, `BendMom<L>N<J>` (and the `BendMoment` columns of the static profile,
range graphs and element file) report the cable's own moment, the line type's EI times the
curvature; lines without stiffeners are unchanged.
Expand All @@ -68,6 +87,12 @@ All notable changes to CableDyn are recorded in this file. The format follows

### Fixed

- A deck with a WaterKin elevation history (`WaveKinMod 1`) at `TMax = 0`, a check of the static
start, reduces the record over its own length instead of failing for want of a positive
`TMax`.
- Reading a WaterKin `WaveKinFile` no longer slows with the square of its length: the rows grow
by doubling instead of copying the whole record per row. A 10 s run on a 168,000-row record
took 107 s and now takes 3.5 s.
- A weightless or near-neutral taut finite-EI line (a neutrally buoyant cable, a tendon) failed
its static solve, even straight along its chord: the convergence test scaled the residual by
the line's weight alone, far below the round-off of its axial forces. A taut line's scale now
Expand Down
12 changes: 12 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -1613,6 +1613,18 @@ if(Python3_Interpreter_FOUND)
message(STATUS "range_graph_tdp: skipped (numpy not importable in ${Python3_EXECUTABLE})")
endif()

# TMax = 0 checks the static start of a dynamic deck: vesselMotion and motionFile records
# that outlast TMax, RangeStart at TMax = 0, and the hint of a deck without dtM and TMax.
add_test(NAME static_check
COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/tests/test_static_check.py
--exe $<TARGET_FILE:cabledyn>
--examples ${CMAKE_CURRENT_SOURCE_DIR}/examples
--output ${CMAKE_BINARY_DIR}/static_check)
set_tests_properties(static_check PROPERTIES
LABELS "python;driver;integration;static;dynamic"
TIMEOUT 600
ENVIRONMENT "${_cabledyn_python_test_environment}")

# Anchor uplift channels (AnchFz/AnchFH, TDP<L>Grd): the analytic laid and suspended elastic
# catenaries, the Point<P>F identity on every standalone route, and a surge that lifts the
# anchor of a catenary (needs numpy).
Expand Down
11 changes: 6 additions & 5 deletions doc/driver_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -1182,7 +1182,7 @@ them on `water_grid.txt` and interpolates, so that file is not read. Standalone

| Option | File | Meaning |
|---|---|---|
| `WaveKin 3` | `wave_elevation.txt` | `time elevation` rows from `t = 0` (no header rows), resampled linearly at `dtWave` to `floor(t_last/dtWave) + 1` samples (the last dropped when the count is odd) and reduced to its Fourier components; components above 0.5 Hz are dropped and the mean is a mean-level offset, as MoorDyn-C does. Waves travel along +x |
| `WaveKin 3` | `wave_elevation.txt` | `time elevation` rows from `t = 0` (no header rows), resampled linearly at `dtWave` to `floor(t_last/dtWave) + 1` samples (the last dropped when the count is odd) and reduced to its Fourier components; components above `WvHiCOff` (default 0.5 Hz, MoorDyn-C's fixed cut) are dropped and the mean is a mean-level offset, as MoorDyn-C does. Waves travel along +x |
| `WaveKin 7` | `wave_frequencies.txt` | `omega Re Im [beta]` rows [rad/s, m, m, rad], the first at `omega = 0`: each row is the component `\|c\| sin(omega t - k d + arg c)`, `d = x cos(beta) + y sin(beta)`; the `omega = 0` row is a mean-level offset. All rows must share one `beta` |
| `Currents 1` | `current_profile.txt` | `z ux uy uz` rows after its header rows, strictly increasing `z`; linear in `z` and held beyond the end rows |

Expand All @@ -1208,7 +1208,7 @@ A MoorDyn-F deck may select a WaterKin file (grammar in [Auxiliary file formats]
| Mode | Meaning |
|---|---|
| `WaveKinMod = 0` | no waves |
| `WaveKinMod = 1` | elevation history resampled at `dtWave` over deck `TMax` (host `TMax` for caller-driven decks), truncated or zero-padded, and Fourier-reduced once on one padded DFT time base |
| `WaveKinMod = 1` | elevation history resampled at `dtWave` over deck `TMax` (host `TMax` for caller-driven decks), truncated or zero-padded, and Fourier-reduced once on one padded DFT time base, keeping the components up to `WvHiCOff` (default 0.5 Hz; `none` keeps all, as MoorDyn-F) |
| `WaveKinMod = 2` / `SEASTATE` | waves from the coupled host SeaState field |
| `CurrentMod = 0` | no current |
| `CurrentMod = 1` | N-level WaterKin depth table, interpolated at structural nodes |
Expand Down Expand Up @@ -1261,7 +1261,8 @@ about the line tangent pointing into the line from that end. Either way it impos
(where the inward tangent is `Ez`) and the opposite sense to `Pretwist(B)` at End B (where it is
`−Ez`). 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, …, TMax` grid and `point_id` must be a prescribed point. Each
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](file_formats.rst).

Expand All @@ -1287,8 +1288,8 @@ 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, in one
of two forms for the whole file:
**`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:

```text
time x y z roll pitch yaw vx vy vz wx wy wz ax ay az alx aly alz (19 values)
Expand Down
18 changes: 14 additions & 4 deletions doc/file_formats.rst
Original file line number Diff line number Diff line change
Expand Up @@ -211,10 +211,11 @@ The model grid is ``t_k = k·dtM`` for ``k = 0 … TMax/dtM``, and ``TMax`` must
whole multiple of ``dtM``. The file is checked against this grid:

* Each ``time`` must match a grid time to within ``100·ε·max(1, TMax)``, where ε is
double-precision machine epsilon. Times off the grid, before ``0``, or after
``TMax`` are rejected (``time is outside the dtM/TMax grid``). Write times with
enough digits to hit the grid exactly. A file that runs past ``TMax`` must be cut
to length.
double-precision machine epsilon. Times off the grid or before ``0`` are rejected
(``time is outside the dtM/TMax grid``). Write times with enough digits to hit the
grid exactly. A file may run past ``TMax``: its rows after ``TMax`` are checked
(on the ``dtM`` grid, to within ``100·ε·max(1, time)``) and not used, so a long
record serves a shorter run and ``TMax = 0`` checks the static start.
* Every eligible point needs exactly one row at every grid time. A repeated
point/time pair is rejected (``duplicate row for point <id> at this time``). A
missing pair is rejected once the whole file has been read (``motionFile must
Expand Down Expand Up @@ -563,6 +564,15 @@ two columns:
* ``TMax / dtWave`` may be at most 10\ :sup:`6` samples; a longer record is rejected
(``WaterKin TMax/dtWave needs more than 1000000 wave samples``) because the one-time
reduction grows with the square of the sample count.
* The components above the ``WvHiCOff`` option (default :math:`\pi` rad/s, 0.5 Hz) are
dropped, as SeaState drops those of an elevation series; ``none WvHiCOff`` keeps them up to
the Nyquist frequency of ``dtWave``, as MoorDyn-F does. A record with no component at or
below the cut-off, for example a run shorter than 2 s, is refused by name.
* The record keeps about ``TMax WvHiCOff / (2 pi)`` components (150 for a 300 s run), or
``TMax / (2 dtWave)`` with ``none`` (600 at ``dtWave`` 0.25 s), against the 200 of a
``jonswap`` sea. Every node sums all of them for its surface elevation. Below the surface,
the components too short to reach the node's depth are dropped once they cannot change its
velocity and acceleration beyond round-off (:ref:`theory-waves`).

Example
~~~~~~~
Expand Down
4 changes: 3 additions & 1 deletion doc/migrating.rst
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,9 @@ Keyword map
* - ``kBot``, ``cBot``, seabed friction coefficient
- ``kBot``, ``cBot``, ``frictionMu`` (alias ``mu``)
* - ``WaterKin`` file (``CurrentMod 1``, ``WaveKinMod 1``)
- same file; ``WaveKinMod 2`` and ``SEASTATE`` only when coupled to OpenFAST
- same file; ``WaveKinMod 2`` and ``SEASTATE`` only when coupled to OpenFAST. An
elevation record keeps its components up to ``WvHiCOff`` (default 0.5 Hz); give
``none WvHiCOff`` to keep all of them, as MoorDyn-F does
* - ``FAILURE``, ``CONTROL`` sections
- ``FAILURE`` on ``EI = 0`` decks, standalone and in OpenFAST (a deck with a finite-EI
cable rejects it); ``CONTROL`` on ``EI = 0`` lines and finite-EI cables in OpenFAST, not
Expand Down
3 changes: 2 additions & 1 deletion doc/modeling.rst
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,8 @@ resolves the wave a snap does not trigger them, and at 0.5 ms the cable takes no

Begin with the smallest model that should equilibrate:

#. omit ``dtM``/``TMax`` for an ``EI = 0`` static-only checkout;
#. omit ``dtM``/``TMax`` for an ``EI = 0`` static-only checkout, or set ``TMax = 0`` to check
the static start of a dynamic deck with all its other options;
#. verify endpoint order, length, submerged weight, and seabed elevation;
#. request endpoint tensions and the static along-arc profile;
#. inspect contact, touchdown, curvature, and symmetry; then
Expand Down
17 changes: 15 additions & 2 deletions doc/options.rst
Original file line number Diff line number Diff line change
Expand Up @@ -269,14 +269,17 @@ Clock and initial condition
- real, s
- absent (static-only)
- finite, ≥ 0 and an integer multiple of ``dtM``. ``TMax = 0`` runs the dynamic
initialisation and writes the ``t = 0`` row
initialisation and writes the ``t = 0`` row: the static start of a dynamic deck, checked
with every other option kept (motion records longer than ``TMax`` and a later
``RangeStart`` included)
- standalone only; OpenFAST uses the host ``TMax``. Do not copy the host duration into a
coupled deck
- ``600.0 TMax``
* - ``RangeStart`` / ``range_start``
- real, s
- ``0``
- finite, ≥ 0 and ≤ ``TMax``. First output time accumulated into the range graphs
- 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
Expand Down Expand Up @@ -743,6 +746,16 @@ Ambient fluid and prescribed motion
- the step at which ``WaveKin 3`` resamples ``wave_elevation.txt`` (MoorDyn-C)
- standalone
- ``0.1 dtWave``
* - ``WvHiCOff``
- positive number [rad/s] or ``none``
- ``3.14159`` (0.5 Hz)
- the high cut-off frequency of an elevation record (WaterKin ``WaveKinMod 1``,
``WaveKin 3``): its Fourier components above it are dropped, as SeaState's ``WvHiCOff``
zeroes the spectrum of an elevation series. ``none`` keeps them up to the Nyquist
frequency of ``dtWave``, as MoorDyn-F's ``WaveKinMod 1`` does. A record with no
component at or below the cut-off is refused
- standalone
- ``6.2832 WvHiCOff``
* - ``Currents``
- ``0`` or ``1``
- ``0``
Expand Down
14 changes: 14 additions & 0 deletions doc/theory.rst
Original file line number Diff line number Diff line change
Expand Up @@ -828,6 +828,8 @@ configuration derivative in the tangent. The Hermite path evaluates the consiste
holds it over the step. The spatial gradient of the wave field is omitted from the tangent on
both paths; the residual is exact, so the converged state is unaffected.

.. _theory-waves:

Waves
~~~~~

Expand Down Expand Up @@ -892,6 +894,18 @@ commensurate, the record does not repeat (an equally spaced comb would repeat af
its component table (amplitude, frequency, phase), for example a WaterKin ``WaveKinMod`` 1
elevation history, which is reduced once to its Fourier components on the run time base.

Every point sums every component of the elevation. The velocity, acceleration and dynamic
pressure sums run in order of increasing :math:`k_i`. For :math:`-h \le z' \le 0` both depth
ratios :math:`\cosh k(z' + h)/\sinh kh` and :math:`\sinh k(z' + h)/\sinh kh` fall as
:math:`k` grows, so the cosh ratio of the last summed component times the remaining
:math:`\sum_{j \ge i} a_j\omega_j`, :math:`\sum a_j\omega_j^2` and :math:`\sum a_j\omega_j^2/k_j`
bounds the rest of each sum. The sums stop once those bounds are below half an ulp of the
magnitudes already summed. A deep point therefore skips the short components that have
decayed to nothing there, and the result changes at round-off only. This matters for an
elevation history, which keeps its components up to the ``WvHiCOff`` cut-off (0.5 Hz by
default) or, with ``none``, all :math:`T_{max}/(2\,\Delta t_{wave})` of them up to the Nyquist
frequency of ``dtWave``.

**Regular nonlinear waves.** A ``stream`` wave is Dean's stream-function wave
(:ref:`Dean, 1965 <ref-dean1965>`) solved numerically by the Fourier method of
:ref:`Rienecker & Fenton (1981) <ref-rienecker1981>`. In the frame moving with the celerity
Expand Down
9 changes: 7 additions & 2 deletions doc/troubleshooting.rst
Original file line number Diff line number Diff line change
Expand Up @@ -199,8 +199,13 @@ Clock, motion, and environment
- a deck that mixes ``EI = 0`` and finite-EI lines writes no modal files. Run the modal
analysis on a deck whose lines are all ``EI = 0`` or all finite-EI.
* - motionFile ``time is outside the dtM/TMax grid``
- every row time must be ``k·dtM`` for ``0 ≤ k ≤ TMax/dtM``. Resample the history onto the
``dtM`` grid.
- every row time must be ``k·dtM`` with ``k ≥ 0`` (rows after ``TMax`` are not used).
Resample the history onto the ``dtM`` grid.
* - ``... requires dtM and TMax; to check a dynamic deck's static start only, give dtM with
TMax = 0``
- the deck asks for the march (motion, current, waves, bodies, rods, finite-EI sections,
``RangeStart`` ...) without ``TMax``. Keep the deck and set ``TMax = 0``: the run solves
the static start and writes the ``t = 0`` row.
* - ``motionFile must provide every Coupled/Vessel point at every dtM time`` (or ``every
eligible prescribed point``)
- the file is missing at least one (point, time) pair. Every prescribed point needs a row at
Expand Down
1 change: 1 addition & 0 deletions examples/cabledyn_options_reference.dat
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,7 @@ none waves - Wave model and parameters (m, s, deg) {none; airy;
-- 0.1 dtOut - MoorDyn output-cadence compatibility only; accepted and ignored
-- 0 Currents - MoorDyn-C current mode {0=none; 1=current_profile.txt} [default: 0]
-- 0.25 dtWave - MoorDyn-C WaveKin 3 resampling step (s) [default: 0.25]
-- 3.14159 WvHiCOff - High cut-off of an elevation record, WaveKinMod 1 or WaveKin 3 (rad/s) {value; none} [default: 3.14159]
-- Keyword aliases (equivalent spellings, case-insensitive):
-- g = gravity; rhoW = WtrDnsty = water_density; WtrDpth = water_depth; kBot = kb; cBot = cb
-- bathymetryFile = bathymetry_file = seafloorFile = seafloor_file; frictionMu = mu = frictionCoefficient
Expand Down
Loading
Loading