Skip to content

feat(dynamics): sub-step EI = 0 steps that turn or snap taut - #25

Merged
SMI-Lab-Inha merged 5 commits into
devfrom
feat/ei0-adaptive-substeps
Oct 19, 2026
Merged

SMI-Lab-Inha merged 5 commits into
devfrom
feat/ei0-adaptive-substeps

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

At typical coarse steps, the snap peaks of tension-only (EI = 0) lines were set by the time step rather than by the physics, under any scheme. Segments rotating several degrees per step left all-chain snap peaks 10–20 % low, and semitaut peaks came out high. This PR re-solves such steps in sub-steps, by default.

  • Trigger. After a line step converges, it is re-solved from the same committed state in sub-steps along the existing quintic end-motion boundary when either:

    • a taut segment turned more than ei0_substep_angle (default 1°; n = max(4, ⌈turn/angle⌉), capped by ei0_substep_max, default 16); or
    • a segment snapped from slack to taut above 0.25 of the largest start tension, at an axial Courant number above 1.

    The result is re-measured once. If a sub-step fails, the plain step is kept. Stall-recovery rungs are taken as given.

  • Options. ei0_substeps auto|off; off reproduces the previous results bit for bit. False alpha_force_blend (paper mode) turns it off unless the deck sets it.

  • Routes. Covered: standalone, line systems, the staggered multibody march, OpenFAST, FAST.Farm and the C API. Lines with an active junction DOF in the monolithic body scheme are not sub-stepped (they need the plain step's end tangent). The monolithic scheme is the default for decks with Rigid6 bodies, rods or Free/Connect points; their junction lines are not sub-stepped, and the run says so.

  • Reporting. The run audit measures per solver step. OpenFAST prints the sub-step counts at the end of the run.

  • Start-slack dashpot share bounded. A segment slack at the step start that carries a step-start dashpot force now has its kept share bounded too. It may return at most its own one-step dissipation T_d,n·|l̇_n|·Δt, plus the end share's credit. The bound is continuous at the reversal and has a consistent tangent. Before, a turning or reversing step returned up to 45.6 times that bound. 50 of 52 examples are byte-identical; the two line-break decks move by at most 0.04 % in their tension statistics.

  • Snap-load documentation corrected. The undamped EI = 0 light-cable reproducer from the force-blend change has no converged snap peak: the peak rises as dtM falls, as single segments rattle, and an explicit lumped-mass solver agrees. Converged finite-EI runs give 0.093 MN at the fairlead and 0.057 MN at the anchor. The CHANGELOG, theory and modelling guide say so, and recommend physical axial damping or finite EI for converged peaks.

Results

Lozon moorings at dtM = 0.1 s, mean of 7 runs, against 0.5 / 0.25 ms references:

Case Before Now
80 m all-chain heave 5 m / 7 s, fairlead / anchor −14.7 / −17.2 % −3.8 / −7.7 %
200 m semitaut surge 10 m / 14 s, anchor +15.9 % about +4 %
200 m semitaut surge 5 m / 7 s, anchor +25.5 % about −2 %
  • Semitaut chain–polyester reproducer: 5.74 MN → 4.65 MN (converged 4.6 MN).
  • Unchanged:
    • Bergdahl, the snap-load study, the one-hour VolturnUS-S and L2/L3 parity;
    • 54 of the 56 example runs. The two line-break decks differ after the failure by less than 0.0005 %.
  • Cost: about 1.67× on the severe mooring envelope; small elsewhere.

Tests

  • Model tests: the turn trigger, a snap-only trigger in partly taut and fully slack lines, no re-solve when the axial wave is resolved, the re-measure path, the sub-step-failure fallback (equal to off bit for bit), the cap, and restore of viscoelastic, Syrope and friction state.
  • Determinism and parity: restart bit identity; Python and Fortran option parity.
  • Full suite (Windows, gfortran, Release, slow tier included): 266/266. Python: 2028 passed. pre-commit run --all-files and the Sphinx build with -W pass. OpenFAST builds, and its smoke and restart runs pass.

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

At dtM 0.1 s a taut segment of the Lozon 80 m all-chain mooring turns by
up to 6 deg per step in 5 m / 7 s heave, and both generalised-alpha blends
gave snap-load peaks 10 to 20 % low. The release cap was not the cause: it
acts in 0.3 % of the element steps, never near a peak, and the cycle maxima
with and without it agree to within 1 %. The peaks followed the algorithmic
damping, so a coarse step under-resolves them whatever the blend.

CD_Step_Model now measures each converged step against its committed start.
When a segment that ends the step taut turned by more than
ei0_substep_angle (default 1 deg), or a segment slack at the start ends
above a quarter of the largest step-start tension, the interval is solved
again from the same committed state in max(4, ceil(turn/angle)) equal
sub-steps, at most ei0_substep_max (default 16). The end motion follows the
quintic of the recovering step and the last sub-step lands on the given end
state. The sub-stepped interval is measured once more and re-solved when
its turn needs more sub-steps; a sub-step that fails returns the plain step.
The decision depends only on the committed state and the step inputs, so a
restart repeats it. Every route that steps EI = 0 lines goes through it
(standalone lines and line systems, OpenFAST, FAST.Farm, the C API) except
the monolithic junction coupling, which needs the nominal step's end
reaction and tangent. The recovering step keeps taking its rungs as given.

New OPTIONS ei0_substeps auto|off (default auto; off with False
alpha_force_blend unless the deck sets it, so paper mode is unchanged),
ei0_substep_angle and ei0_substep_max, mirrored in the Python deck reader.
off gives the previous results bit for bit. The run audit measures turns
and axial-wave crossings per solver step, reports the sub-stepped steps,
and its turn note states the peak underestimate.

Over seven runs with amplitudes 3e-4 apart, against 0.5 / 0.25 ms runs, the
80 m heave fairlead and anchor maxima move from 15 / 17 % low to 4 / 8 %
low, and the 200 m semitaut anchor maxima in 10 m / 14 s and 5 m / 7 s
surge from +16 / +26 % to -1.4 / -2.6 %. 19 of 21 EI = 0 dynamic examples
are unchanged; the line-break decks' pre-failure snap moves by 5-11 %.
Bergdahl RMSE 1.58 -> 1.59 N (record files and provenance updated); the
other validation records move within their recorded ranges or not at all.
The 20-run mooring envelope takes 1.65 times as long.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The halves of a line-system step that CD_Step_System halved after a
failure now take their steps as given (CD_Step_Model as_given), as the
rungs of the recovering step do, and the system rollback restores the
run audit's largest solver step with the line state.

A step whose sub-step fails now keeps the plain step's own converged
result instead of solving it a third time. The turn trigger counts a
segment that ends the step above 1e-3 of the largest step-start tension,
the audit's floor. Counting only segments taut at both ends, as the
review suggested, left the Lozon semitaut anchor peaks 5 % high on
average and up to 25 % high in single runs, so the trigger keeps
segments that were slack at the step start. The strains use the step's
own unstretched lengths, and a comment marks where a length that changes
within the step would need its step-start value.

The counts are visible on every route: OpenFAST and FAST.Farm print them
at the end of the run, CD_AGG_Get_Substep_Counts and
CD_Get_System_Substep_Counts return them, and the standalone driver
notes once per run that the monolithic body/point step is not
sub-stepped.

Tests cover the snap-only trigger, the re-measure path, the failing
sub-step fallback (equal to off bit for bit), the ei0_substep_max cap,
and the complete restore of the viscoelastic, Syrope and seabed friction
states, through test-only hooks. The slack-dynamics bounds are widened
around the measured peaks.

Figures with the final build: the 80 m heave maxima are 3.8 / 7.7 % low,
the 200 m semitaut anchor maxima 1.4 / 2.6 % low and the 80 m surge
maxima 1.8 % low / 1.4 % high, over seven runs. The Bergdahl records,
the L2-2 parity and the shipped examples match the previous commit. The
20-run mooring envelope takes 1.63 times as long (1.6 to 2.5 times on
the 5 m / 7 s and 10 m / 14 s motions, 4 to 7 sub-steps). The docs,
CHANGELOG, VALIDATION and ARCHITECTURE now give these figures.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
A convergence study of the light-cable and stiff-seabed reproducers of
the force-blend fix shows that the undamped EI = 0 deck has no converged
snap peak: the peak rises as dtM falls (0.32 to 0.46 MN at microsecond
steps, also with an explicit lumped-mass solver), as single segments
rattle, and falls with mesh refinement at a fixed step. Its 20 ms
averages converge to 0.083 / 0.047 MN, and converged finite-EI runs give
0.093 MN at the fairlead and 0.057 MN at the anchor. On the stiff seabed
the EI = 0 peak does not converge either.

The CHANGELOG, theory and options pages no longer call the light-cable
or stiff-seabed figures references; they give the finite-EI values
instead of "0.1 to 0.18 MN at rhoInf = 0 and with a finite-EI model".
The sub-stepping entry states that on this undamped cable the sub-steps
resolve more of the segment rattle and can raise isolated spikes (anchor
0.16 to 0.52 MN at dtM 0.5 ms), and that with physical axial damping
they change nothing.

The modelling guide and the snap-note entry of the troubleshooting page
now advise physical axial damping (BA in N s, not the per-segment
damping-ratio form, which changes with the mesh) or finite EI to obtain
converged snap peaks. The slack-dynamics test header says the same of
its bounds, which catch a spike or a lost snap rather than a reference.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
…t only committed steps

The depth-floor rerun of a stalled line-system step now steps every line as
the nominal step does, sub-steps included, so its result is again that of the
step without the fallback; only the halves of a recovery take their steps as
given. The monolithic junction arms the end query only on lines with an active
junction DOF, so a line whose ends are all fixed or anchored is sub-stepped
there too. The docs and changelog state that the monolithic scheme is the
default of standalone decks with bodies, rods or free points, that the lines
attached to them are not sub-stepped (7 of the 21 shipped EI = 0 dynamic
examples), and what a triggering step costs at most.

The trigger takes the segment tensions the run audit takes (the viscoelastic
and Syrope law tensions included), floors the step-start tension scale at
0.1 % of the line's initial tension, and treats a slack-to-taut snap as one
only when the step does not resolve the axial wave over the segment. The
Bergdahl matrix at 0.3125 ms therefore takes no sub-step and is back to its
previous record bit for bit; its 0.1 m mesh and 0.625 ms runs keep theirs. The
light cable at 0.5 ms takes no sub-step either. Flooring at the full initial
tension was tried and left the Lozon semitaut anchor peaks up to 29 % high, so
the floor is 0.1 %.

The sub-step diagnostics are 64-bit, roll back with the line states (line
system rollback, the fallback frame, the system snapshot and the stall
recovery) and are reported as steps examined. The ei0 settings are checked
when the model is initialised, and the deck parser applies the Python
reader's rule to ei0_substep_max. The sub-step slots and the recovery snapshot
share one copy routine of the committed state. The OpenMP line loop is
scheduled dynamically; results do not depend on the thread count.

Tests: a partly taut snap case on each side of the quarter threshold, a case
whose step resolves the axial wave, init-time rejection of invalid settings,
deck rejection of bad ei0 options, the viscoelastic anchor bound checked
against the uncapped figure with every step taken as given, and a sway turn
bound relative to the unresolved turn. Figures in the docs, the changelog,
VALIDATION.md and the Bergdahl record are updated from reruns.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
The release cap of the force-blended EI = 0 step skipped every segment
slack at the step start. A damped segment whose ends separate there still
keeps alpha_f T_d,n of its step-start dashpot force along its old chord,
and returns alpha_f T_d,n p to the motion when the step turns or reverses
its ends, with no strain energy behind it.

The kept share of such a segment now has the dashpot's own one-step
dissipation as its budget, W_d = T_d,n |ldot_n| dt, ldot_n the dashpot's
elongation rate at t_n (the axial rate, less l_n l0_dot/l0 while the line
pays out, so W_d > 0 whenever T_d,n /= 0). When p > 0 the kept force
alpha_f T_d,n is replaced by (W_d + N_d)/p when that is smaller, with the
end share's credit N_d = max((1 - alpha_f) T_d,n+1 p_n+1, 0); a
compressive T_d,n is capped alike for p < 0. The kept dashpot share of an
element slack at the step start then returns at most its own one-step
dissipation plus the end share's credit. The capped force grows without
bound as p -> 0, so it is continuous there, and alpha_f |p| <= |ldot_n| dt
is a sufficient test of an inactive cap. The tangent takes dp/dd = -t_n
and, while the credit is positive, the dependence of T_d,n+1 and p_n+1 on
q_n+1 (through v_n+1) on the banded, dense and probe paths. Taut-start
and undamped segments are unchanged.

In the test chain (a segment slack at t_n moving at 0.05 to 2 m/s, either
sense, turning by 0 to 180 degrees) the kept share returned up to 45.6
times W_d + N_d (44.6 W_d above the bound) before; with the cap it stays
within the bound to 8e-14 W_d on the 29 of 448 rows where it acts, a
segment with no step-start dashpot force keeps the plain blend bit for
bit, and the tangent of capped rows matches the finite difference to
1.2e-10 on both paths.

Of the 52 shipped examples 50 are byte-identical. The two Volturnus line
break decks (chain with zeta damping in a JONSWAP sea) diverge from
t = 246 s pointwise, as slack segments do, while their tension peaks
change by at most 0.01 %, means by at most 0.02 % and standard deviations
by at most 0.04 %. The light-cable, viscoelastic and Syrope reproducer
bounds still hold.

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-19T20:58:06.971789Z ee045a0 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 #35253368 | 📁 Comparing ee045a0 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. You're on a roll.

Reviewed commit: ee045a0dc6

ℹ️ 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 d2387ee into dev Oct 19, 2026
15 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/ei0-adaptive-substeps branch October 19, 2026 22:26
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