Skip to content

feat(control): active tension of finite-EI cables; committed lengths under the force blend - #26

Merged
SMI-Lab-Inha merged 9 commits into
devfrom
feat/finite-ei-active-tension
Oct 20, 2026
Merged

SMI-Lab-Inha merged 9 commits into
devfrom
feat/finite-ei-active-tension

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

Active line tensioning (CONTROL, driven by a ServoDyn cable-control channel) now works for finite-EI cables in OpenFAST, and its EI = 0 path follows MoorDyn-F through ramps.

  • Finite-EI cables. A CONTROL row may name a finite-EI cable in an OpenFAST run (CompMooring = 5).
    • Its fairlead-side segment changes length and rate as MoorDyn-F's does.
    • Its committed force is kept across the length update.
    • Checkpoint restarts and correction steps reproduce the run bit for bit.
  • Committed lengths (EI = 0). A length update re-derived the committed acceleration at the new length, and the next step blended only the new length. So every change entered the committed side of the generalised-α blend, and ramps lagged:
    • fairlead tensions ran up to 4.1 % above MoorDyn-F on the pay-out and 6.3 % below on the haul-in.
    • The line now keeps the lengths and rates its committed state was reached with. Under the force-blended step, every step-start quantity (start force, release cap, law stiffness, dashpot) uses them; end-of-step quantities use the new ones; inertia uses blended lengths.
    • With ei0_substeps auto, a pending change is spread linearly over the sub-steps.
    • An external-load update refreshes the distributed-load remainder before the recompute.
  • Bounds. A command outside MoorDyn-F's bounds (length within UnstrLen/N of zero, and so on) now stops the run by name, as MoorDyn-F does.
  • Unchanged. Runs without CONTROL, and zero commands, are bit-identical.

Validation

Coupled A/B against stock MoorDyn: a ServoDyn cable-control DLL drives the same pay-out/haul-in DeltaL schedule into CompMooring = 5 and = 3 in one binary.

Line Ramp difference, fairlead / anchor Hold responses
EI = 0 0.13 % / 0.39 % (was 4.1 % / 6.3 % at the fairlead) within 0.6 % / 0.7 %
Finite-EI cable (EI = 1e5 N·m², 50 elements) 0.21 % / 0.86 % —

A restart mid-ramp and in the hold, and NumCrctn = 1, are bit-identical.

Tests

  • Pay-out closed form: a taut weightless line paid out against EA(H/L′ − 1) − BA·H·L̇′/L′² matches to 1.8e-3 N (4.2 N before).
  • Sub-stepped pay-out against ei0_substeps off at dt/4: 3.3e-8 N.
  • Length-change step: closed forms and finite-difference tangents, including the release cap, law bound, dashpot and slack-start terms under a pending change.
  • Model twin tests: start load, start force and recomputed acceleration bit for bit against an uncommanded twin.
  • Finite-EI cable control: closed forms, caches, snapshot/restore and restart.
  • Full suite (Windows, gfortran, Release, slow tier included): all pass. Python passes. pre-commit run --all-files and the Sphinx build with -W pass. OpenFAST builds.

Checklist

  • pre-commit run --all-files passes
  • ctest --test-dir build --output-on-failure passes
  • python -m pytest tests python/tests passes (if Python or validation records changed)
  • VALIDATION.md updated if a validation result changed
  • CHANGELOG.md updated under [Unreleased] (heading added if missing) for user-visible changes
  • Documentation in doc/ updated for changed inputs, options, or outputs
  • Conventional Commit title (feat:, fix:, docs:, ...)
  • Commits are signed off (git commit -s) under the
    Developer Certificate of Origin

ServoDyn's cable control (CONTROL rows, CableDeltaL and CableDeltaLdot)
drove EI = 0 lines only; a deck with a finite-EI cable and CONTROL was
refused. The cubic-Hermite cable treated every length-derived quantity
as fixed after initialisation.

A CONTROL row may now name a finite-EI cable. Before each mooring step
the aggregate scales every cable element of the line's fairlead-side
deck segment S by (S + DeltaL)/S, with the matching rate, so the
segment is S + DeltaL long, as MoorDyn sets its segment N. The cable
rebuilds what depends on the lengths in its initialisation order (the
constant mass with the attachment masses, the tributary lengths, the
seabed contact and friction coefficients), so a restart is
bit-identical; snapshots carry the lengths and rates. The axial damping
acts on the rate of the strain the elastic force uses, so a segment
paid out at constant strain carries no damping force. As on the EI = 0
path the length is held at its end-of-step value across the step and
the mass-rate term is left out. A command outside half to twice the
segment's initial length stops the run by name, lines restrained in
torsion and FAST.Farm decks refuse CONTROL with a cable, and a zero
command leaves the run bit-identical to an uncontrolled one.

The control table now maps each CONTROL line by its rank among lines of
its kind; it mapped deck lines to EI = 0 system lines by position, which
would have been wrong in a mixed deck.

Tests: the damping Jacobian with a length rate against finite
differences; caches equal to a fresh build at the new lengths, and
exact snapshot/restore; closed forms on vertical cables (hanging top
reaction w(L + DeltaL) to 2e-7, taut top tension EA(H - L')/L' + wL'/2
to 6e-13, pay-out damping lag to 8.5e-4 N of 100 N); a slow ramp ending
at the static solve of the edited lengths; and, on the aggregate, a zero
command, the bounds, a rewind, a mixed deck, a refined mesh and
checkpoint restarts in a hold, in a ramp and on a grounded cable.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
Two corrections found in the coupled OpenFAST check of cable control.

Which segment. MoorDyn-F sets segment N, the one at the written
AttachB (MoorDyn.f90, l(N) = UnstrLen/N + DeltaL), which in its
anchor-first decks is the fairlead side. CableDyn always changed the
segment at its End A, which is the fairlead only on lines the
anchor-first swap reverses or that are written fairlead first. A stock
Connect-to-Vessel clump leg was tensioned at the clump. CONTROL now
changes the segment at the line's fairlead-side end, the end on a
host-driven point, and at the written NodeB when both or neither ends
are host-driven. Lines from a Fixed anchor to a Coupled, Vessel or Body
point, in either order, and fairlead-first lines are unchanged; the
changelog lists the lines that change. A finite-EI cable keeps its End
A span.

When. With the length held at its end-of-step value, the
force-blended step re-evaluated its committed force at the new lengths,
an error of about alpha_f EA dL/l per step: a finite-EI pay-out ramp at
rhoInf 0.4 ran 80 kN above stock MoorDyn's on the IEA-15 UMaine model
(haul-in 125 kN below). The cable now keeps the lengths its committed
state was reached with and evaluates the committed force there, and a
step after a length change starts from the Newmark predictor (without
it the 5e-3 step tolerance let the tension ring at 8-12 kN). The ramp
now follows MoorDyn's to 5 kN. A checkpoint rebuild re-applies the
command before it reloads the mirror, so the committed lengths come back
with it.

Tests: a constant pay-out on a taut line against the closed form at
alpha_f = 2/7 and 0 (8.5e-4 N; the old timing gives 1.42 N), and stock-
order clump legs and rod-end lines tensioned at the host-driven end.
In OpenFAST, restarts mid-ramp and in a hold are bit-identical, and
NumCrctn = 1 is bit-identical to 0.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The coupled A/B of ServoDyn cable control against stock MoorDyn scored
the hold windows only. During the ramps the controlled fairlead
tensions of EI = 0 lines ran up to 97 kN (4.1 %) above MoorDyn on the
pay-out and 148 kN (6.3 %) below it on the haul-in, at rhoInf 0.4, and
still 58 kN and 89 kN at rhoInf 0.

A length update re-derived the committed acceleration under the new
length, and the next generalised-alpha step evaluated its blended
configuration with the new length only, so each length change entered
the committed side of the blend. The line model now keeps the lengths
and rates its committed state was reached with, copied and rolled back
with that state; an update keeps the committed acceleration (a load
that is not finite at the new length now fails before anything is
written); and a step after a change blends the old and new lengths of
the changed elements as it blends the configuration. A checkpoint
restart re-applies the restored command as the committed state's
(`restored`), so the restarted run carries the uninterrupted one's
committed lengths.

The ramps now follow MoorDyn to 3 kN (0.13 %), also at 100 segments;
the holds move by less than 0.01 %. A unit test pays out a taut,
weightless line at constant rate against EA(H/L' - 1) - BA H L'_dot /
L'^2 (4.2 N error before, 1.8e-3 N after, at rhoInf 0.4 and 0), and an
aggregate test restarts mid-ramp and in the hold bit-identically. The
A/B scorer now gates the ramps (1 % of the baseline). Runs without
CONTROL, and a zero command, are bit-identical.

With finite-EI cable control in the same branch, one apply routine
serves both line kinds: `restored` also marks a cable's lengths as
committed, and the shell re-applies the command once, before the
line interiors and cable mirrors reload.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
MoorDyn-F stops a run when a cable-control command lengthens a segment
by more than its length or shortens it by more than half
(MoorDyn.f90, ErrID_Fatal), and CableDyn's finite-EI control already
refused the same span change. CableDyn's EI = 0 control printed a
one-time warning and applied the command.

An EI = 0 command is now refused by name (channel, line, command and
segment length) when it leaves -S/2 <= DeltaL <= S, with S the
controlled segment's length, checked for every row before any line
changes. The finite-EI rule (S + DeltaL)/S in [0.5, 2] is the same
bound. The published A/B schedule (-1 m to +2 m on 17 m segments) is
well inside it.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
- The soft-stall fallback of an EI = 0 step restores the committed
  segment length and rate with the rest of its frame, so a failed
  fallback reruns the blended step, not an unblended one.
- Recomputing a cable's acceleration (torsion or end-connection setup,
  a refreshed held fluid) keeps the committed lengths and solves the
  acceleration at them, instead of committing the new length early.
- The bound of an active-tension command is MoorDyn-F's, on both line
  kinds: DeltaL may not exceed UnstrLen/N nor fall below -0.5
  UnstrLen/N, with UnstrLen and N summed over the line's sections; a
  command within the bound that would still shorten a controlled
  segment to zero is refused by name.
- A command that fails part way through a multi-row apply takes back
  the lines already changed, so a refused command leaves every length
  as it was.
- CONTROL on a cable needs the force-blended step: with
  alpha_force_blend off it is refused at initialisation (and the blend
  cannot be switched off on a controlled cable). Syrope segments are
  refused as controlled segments.
- A -0 rate is normalised to +0, so a zero command stays bit-identical.
- Cables take the host-driven-end rule of EI = 0 lines and fail closed
  by name when the controlled end is not host-driven.

Tests: the fallback restore, fault injection on both row orders, -0
rates, ramps at rhoInf 0 and 0.4 against the closed form with the
committed force recomputed every step. The OpenFAST active-tension A/B
reference is unchanged and restarts are bit-identical.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
CD_Recompute_Model_Acceleration (reached through CD_FAST_UpdateStates,
the external-load update, the friction init and the standalone
drivers) committed the present segment lengths, so a recompute between
an active-tension command and the next step dropped the blend of old
and new lengths. It now solves the acceleration at the committed
lengths and rates and restores the present ones bit for bit, as the
cable route does. Test: after a length change a recompute equals a
never-commanded twin and the next step equals the blended step, also
through the system update. OpenFAST active-tension outputs and restarts
are unchanged.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The EI = 0 step now blends forces, (1 - alpha_f) r(q_{n+1}, v_{n+1})
+ alpha_f r(q_n, v_n), with r_n evaluated afresh at the committed state,
and caps the releases of tension-only elements on the projected chord
shortening, with the law secant bounded by the law stiffness and the
kept axial-damping share covered. The committed-length treatment of
active line control was written for the configuration blend: after a
length change it gave every alpha-level term the blended lengths
(1 - alpha_f) l0 + alpha_f l0_c. Under the force blend that left the
step-start force at blended lengths and its dynamic loads at the new
ones, which no time level owns; on the taut pay-out test the tension
then followed the closed form only to 7.4e-3 N per 1 N step, with a
rhoInf dependence of 8.6e-4 N.

Each share of the residual now takes the lengths of its own time level.
With the force blend the step-start force is the committed state's: the
internal force uses l0_c (new optional start_l0 of
CD_Cable_Gen_Alpha_Step), and the step-start load (damping at
l0_dot_c, viscoelastic and Syrope start tensions and stiffnesses,
seabed contact, damping and friction, drag, Froude-Krylov, buoyancy) is
evaluated with l0_c, l0_dot_c and the distributed load and recomputed
seabed coefficients rebuilt at l0_c with the helpers the length update
uses. So is every step-start quantity of the release cap: e_n, T_n,
W_n, the secant T_n/e_n, the law stiffness k_n (EA_D/l0_c, K1/l0_c) and
the dashpot tension T_d,n (with the committed rates, new optional
start_l0_rate). The end-of-step force and the cap's end-state
quantities take the new lengths and rates: e_{n+1}, the estimate
T^_{n+1} = min(T_n/e_n, k_n) e_{n+1} and T_d,n+1, while the
projections p and p_{n+1} are geometric (l_n = l0_c + e_n). The dashpot
weight measures the end stretch against the new length, its band
running from l0 to l0 + c e_n. A haul-in can make p_{n+1} more negative,
so the capped force is bounded below by zero and the cap's quick
inactivity test uses N >= W_n - (1 - alpha_f) T_n (l_n - l0)^2/(4 e_n),
which is W_n/2 without a change. The constant external load of the
step is (1 - alpha_f) f_ext(l0) + alpha_f f_ext(l0_c). The inertia,
which the force blend keeps at the alpha level, takes the blended
lengths: the structural mass (new optional mass_l0) and the added mass
at q_alpha. An acceleration re-derived between a command and the next
step is solved as the step evaluates its committed side, so with the
force blend at the committed external load and seabed coefficients too.
Under False alpha_force_blend the previous blended-length treatment is
kept unchanged. Runs without a length change take the plain path.

The pay-out of a taut weightless line now follows
EA (H/L' - 1) - BA H L'_dot/L'^2 to 1.79e-3 N at rhoInf 0.4 and
1.80e-3 N at 0 (the start-up transient; 6.8e-6 N between them), and
1.81e-3 N under False alpha_force_blend; the test tolerances are
tightened to catch the mixed treatment and now cover both blends. New
tests: the force-blended step with a length change against the closed
form of its residual (force, projected cap including turning releases
and a haul-in whose end share alone exceeds W_n, inertia) and a central
difference of its tangent on the banded and dense paths; the dashpot
share and the law bound of the cap under a length and rate change
against their closed forms, with finite-difference tangents; and a
weighted, damped, grounded line whose step-start load, internal force,
release-cap data (dashpot tension included) and re-derived
acceleration after a command equal, bit for bit, those of its
uncommanded twin, with the inertia at the blended lengths.

Example decks without CONTROL give byte-identical outputs to dev. In
the coupled OpenFAST comparison with stock MoorDyn the ramp differences
stay at 0.13 % (controlled fairleads) and 0.39 % (anchors) for the
EI = 0 lines and 0.21 % / 0.86 % for the finite-EI cable; the hold
responses of the reference table move by 0.011 percentage points at
most. Restarts mid-ramp and in the hold and NumCrctn = 1 remain
bit-identical.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
… recompute

CD_Update_Model_External_Loads wrote the new external load, re-derived
the acceleration and only then stored the distributed-load remainder
f_ext - assemble(dist, l0). Under the force blend with a length change
pending, the recompute rebuilds the committed external load from that
remainder at the committed lengths, so the committed acceleration was
solved without the load the caller had just applied (also through
CD_Update_System_Line_External_Loads). The remainder is now assembled
and stored before the recompute and restored with the external load
and the acceleration if the recompute fails; a failing assembly writes
nothing. Results are otherwise unchanged.

A test applies a command and then an external-load update and compares
the re-derived acceleration with that of an uncommanded twin given the
same load. The comments on the committed lengths in the model type and
in CD_Update_Model_SegmentLength now describe the force-blend treatment
(step-start force at the committed lengths, end-of-step force at the
new ones, only the inertia at blended lengths) and the blended lengths
of every alpha-level term under False alpha_force_blend.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
A step that ei0_substeps auto solves again from the committed state now
treats a pending length change of active line control as the plain step
does. The lengths and rates the committed state was reached with (l0_c,
l0_dot_c) are part of the state commit_state_copy saves, so every pass of
the sub-stepping, the recovery snapshot and the plain step's kept result
start from the right committed lengths. Sub-step k of n ends at the
lengths and rates interpolated linearly in time between the committed and
the new ones at k/n, with the external load and seabed coefficients
rebuilt at them as CD_Update_Model_SegmentLength builds them; the last
sub-step ends at the new lengths, rates, external load and seabed
coefficients bit for bit, and a failed sub-step puts them back before the
plain step's result is returned. The trigger takes the step-start
tensions and the slack classification of a snap at the committed lengths.

Before this, every sub-step took the new lengths, so the whole change
entered the first sub-step. On a line turning by 2.3 deg per step and paid out at 0.05 m/s, every
step solved in four sub-steps, the march now equals one taken as given at
a quarter of the step to 3e-8 N (test_model: payout-substeps); it had
departed from it by 22 N, 2.2 times the tension change per step. Runs
without CONTROL and with a zero command take the unchanged path.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@SMI-Lab-Inha

Copy link
Copy Markdown
Owner Author

@codex review

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 19, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-19T22:38:51.898198Z b22a611 Manual request
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 CableDyn | 🛠️ Build #35255649 | 📁 Comparing b22a611 against latest (f27c5e3)

  🔍 Preview build  

29 files changed · ± 29 modified

± Modified

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Bravo.

Reviewed commit: b22a611d4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@SMI-Lab-Inha
SMI-Lab-Inha merged commit 065df73 into dev Oct 20, 2026
15 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/finite-ei-active-tension branch October 20, 2026 00:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant