SMI-Lab-Inha · Nov 7, 2026 · Nov 7, 2026 · Nov 7, 2026 · Nov 7, 2026 · Nov 7, 2026
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -1166,7 +1166,7 @@ set_tests_properties(cable_statics_modes PROPERTIES LABELS "fortran;driver;hermi
 # clamped hang-off moment under vessel pitch.
 add_executable(test_vessel_motion tests/test_vessel_motion.f90)
 target_link_libraries(test_vessel_motion PRIVATE cabledyn_core)
-file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/vessel_motion)
+file(MAKE_DIRECTORY ${CMAKE_BINARY_DIR}/vessel_motion/vm_wk7)
 add_test(NAME vessel_motion COMMAND test_vessel_motion WORKING_DIRECTORY ${CMAKE_BINARY_DIR}/vessel_motion)
 set_tests_properties(vessel_motion PROPERTIES LABELS "fortran;unit;dynamic;validation")
 

diff --git a/doc/driver_format.md b/doc/driver_format.md
@@ -1329,7 +1329,7 @@ every node's position and time as MoorDyn-C interpolates them. Standalone decks
 | 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 `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` |
+| `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)` with the row's own `beta` (0 when the column is left out); the `omega = 0` row is a mean-level offset and its `beta` has no effect. Rows of different directions describe a short-crested sea, summed in ascending frequency |
 | `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 |
 | `Currents 2` | `current_profile_dynamic.txt` | a depth profile in time: lines 1-4 and 6 are free text, line 5 lists the depths `z1 ... zn` (strictly increasing, read in single precision as MoorDyn-C does), and each later row is `t ux1 ... uxn [uy1 ... uyn [uz1 ... uzn]]` (missing components zero), at least two rows with strictly increasing `t` |
 | `Currents 5` | `current_profile_4d.txt` | a grid in x, y, z and time: line 1 is `nx ny nz nt`, lines 2-5 the x, y, z and t coordinates (each strictly increasing, at least two times), then one `x y z t ux uy uz` row per grid point, in any order, matched to the grid by value; a text line 6 is a header |
@@ -1368,16 +1368,25 @@ where it is sampled on `water_grid.txt`; CableDyn adds the current at the nodes,
 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), and a `wave_frequencies.txt` whose
-rows have different directions. 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`
+`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](options.rst)) 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 non-zero `omega = 0` row raises the still-water level. CableDyn then takes every wave number at
+the depth `WtrDpth` plus that level, as it does for the mean of an elevation record, where
+MoorDyn-C keeps `WtrDpth` and adds the level to the elevation alone. The two differ by the order
+of the level over the depth in the long components.
+
 (waterkin-file-modes)=
 ### MoorDyn-F `WaterKin` file modes
 

diff --git a/doc/file_formats.rst b/doc/file_formats.rst
@@ -549,7 +549,8 @@ two columns:
    * - 2
      - ``elevation``
      - m
-     - Free-surface elevation η at the reference location.
+     - Free-surface elevation η at the reference location: the origin, or the point of the
+       ``WaveRefX`` and ``WaveRefY`` options, an extension of CableDyn.
 
 * Blank lines are skipped. Lines before the first data row whose first token is not
   a number, such as a ``time elevation`` header, are skipped. Once data has

diff --git a/doc/options.rst b/doc/options.rst
@@ -761,6 +761,16 @@ Ambient fluid and prescribed motion
        component at or below the cut-off is refused
      - standalone
      - ``6.2832 WvHiCOff``
+   * - ``WaveRefX``, ``WaveRefY``
+     - number [m], at most 10\ :sup:`6` in magnitude
+     - ``0``
+     - the horizontal point that the phases of an elevation record or a component file
+       (WaterKin ``WaveKinMod 1``, ``WaveKin 3`` and ``7``) refer to: the record was measured
+       there, and each phase uses the position relative to it (:ref:`theory-waves`). An
+       extension of CableDyn, which neither MoorDyn-C nor MoorDyn-F reads. A deck with any other
+       sea, or none, is refused by name
+     - standalone
+     - ``250.0 WaveRefX``
    * - ``Currents``
      - ``0``, ``1``, ``2`` or ``5``
      - ``0``

diff --git a/doc/theory.rst b/doc/theory.rst
@@ -1112,6 +1112,19 @@ 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.
 
+The phase of a component of an elevation history or a ``WaveKin 7`` table is
+
+.. math::
+
+   \theta_i = k_i\big[(x - x_r)\cos\beta_i + (y - y_r)\sin\beta_i\big] - \omega_i t + \phi_i,
+
+with :math:`(x_r, y_r)` the ``WaveRefX``, ``WaveRefY`` point where the record was measured, the
+origin by default. The sea of a record referred to a point is therefore the same sea with the
+deck translated, and a vessel RAO takes the vessel's position relative to that point. A history
+has one direction :math:`\beta_i = \beta`. The rows of a ``WaveKin 7`` table may each have
+their own: a short-crested sea, whose elevation and kinematics are the sums of those of its
+directions, stretched by the one total elevation.
+
 Every point sums every component of the elevation. The sums run in interleaved partial sums
 added up in a fixed order, so a result does not depend on the vector width or the thread
 count, and each point is a function of its position and time alone: nothing carries from one

diff --git a/examples/cabledyn_options_reference.dat b/examples/cabledyn_options_reference.dat
@@ -99,6 +99,8 @@ none      waves             - Wave model and parameters (m, s, deg) {none; airy;
 -- 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]
+-- 0.0     WaveRefX         - x of the point an elevation record or component file refers to (m) [default: 0]
+-- 0.0     WaveRefY         - y of the point an elevation record or component file refers to (m) [default: 0]
 -- 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