Skip to content

feat(capi): host-coupling calls for CFD hosts (ABI 1.2) - #18

Merged
SMI-Lab-Inha merged 3 commits into
devfrom
feat/capi-host-coupling
Oct 16, 2026
Merged

SMI-Lab-Inha merged 3 commits into
devfrom
feat/capi-host-coupling

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

Summary

C ABI 1, minor extension 2: calls for hosts that drive the Coupled points of a deck, CFD solvers in particular. Every existing function is unchanged.

A CFD coupling written against MoorDyn's C API ran into three gaps:

  • Initial position. MoorDyn_Init(X, XD) moves the coupled points to the host's positions before the initial condition. CableDyn_InitDeck solved the statics at the deck coordinates. A body that starts elsewhere therefore started the lines with a transient. For foamMooring's EsfLOWC box, whose fairleads start 15 mm below the deck, line 4's fairlead load moved by up to 0.38 N of its 0.52 N static value and was still 0.04 N off after 1 s.
  • Outer correctors. There was no way to rewind the model between the outer correctors of a host time step (MoorDyn_Serialize/Deserialize).
  • Coupled-vector layout. The layout differs from MoorDyn's (on the point route it includes the Fixed anchors) and could only be derived from the deck.

New calls

void CableDyn_InitDeckAt(void *h, const char *deck_path, int deck_path_len,
                         const double *q0, int n_q0, int *err_stat);
void CableDyn_SaveState(void *h, int *err_stat);
void CableDyn_RestoreState(void *h, int *err_stat);
void CableDyn_GetCoupledLayout(void *h, int *point_id, int *point_type, int n_block, int *err_stat);
  • InitDeckAt solves the statics with every line-bound Coupled/Vessel point at its entry of q0, on both the point and the aggregate route.
    • q0 is either the host blocks alone (MoorDyn's X for a deck whose Coupled points are all line-bound) or the full coupled vector.
    • A post-check confirms every host block starts at q0; a point shared by two lines must be given one position.
    • For the box, held fairleads then keep their load to 2e-16 N, and line 4's load (0.3026, −0.0761, −0.4114) N is bit-identical to the deck moved to the host positions. MoorDyn gives (0.3034, −0.0763, −0.4136) N.
  • SaveState / RestoreState keep one in-memory deep copy of the whole model (and the aggregate's committed time).
    • Restore then step is bit-identical to stepping from the saved state, on both routes, across any number of steps (the dtM sub-steps of a host step included).
    • Covered states: viscoelastic, Syrope, seabed friction, point fluid fields, bodies and rods.
    • Slot lifetime:
      • a successful Init* discards the save;
      • a failed InitDeck/InitDeckAt keeps it with the model;
      • a failed InitLine/InitLines discards it unless an aggregate model stays live.
  • GetCoupledLayout returns the deck point id and type of every block of the coupled vector.

Python: init_deck_at (flat or (3, n) with n ≠ 3), save_state, restore_state (restores time), coupled_layout, host_dofs.

Docs: doc/capi.rst gains "Coupling a host (CFD) solver". It compares the call sequence with MoorDyn's C API step by step:

  • initialisation;
  • vector layout (with the box as worked example);
  • end-of-step motion (MoorDyn's Step takes the start of the step);
  • outer correctors keyed on the start-of-step time;
  • load summation (the two foamMooring restraint conventions);
  • the fixed step of the aggregate route;
  • units.

Tests

  • c_api_host_coupling (C, shared library):
    • the box at host positions (no transient, InitDeck transient magnitude), save/restore bit-identity on both routes;
    • saves across failed inits;
    • a raw InitLine handle;
    • viscoelastic + friction, Syrope and Free-point decks with UpdatePointFluidFields between save and restore;
    • InitDeckAt rejections (shared fairlead given two positions, End A below its anchor);
    • the full form on a Free-point deck;
    • test files removed on every exit.
  • test_c_api: save, 3 trial steps, restore on rod and body decks, bit-for-bit with a directly driven aggregate.
  • test_c_api_stack: InitDeckAt, save and restore on a 1 MiB stack.
  • Python: python/tests/test_host_coupling.py, including a POINTS table with Coupled rows before Fixed ones.
  • Full suite, Windows, gfortran, Release, slow tier included: 260/260. Python passes. pre-commit run --all-files and the Sphinx build with -W 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 — no validation result changes
  • 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

A host that drives the Coupled points of a deck, such as a CFD solver
with a rigid-body solver, had three gaps compared with MoorDyn's C API:

- CableDyn_InitDeck solved the statics at the deck coordinates, while
  MoorDyn_Init(X, XD) moves the coupled points to the host's positions
  first. A body that starts elsewhere gave the lines a start-up
  transient. For foamMooring's EsfLOWC box, whose fairleads start 15 mm
  below the deck, the fairlead load of line 4 moved by up to 0.38 N of
  its 0.52 N static value and was still 0.04 N off after 1 s.
- There was no way to rewind the model between the outer correctors of
  a host time step (MoorDyn_Serialize/Deserialize).
- The layout of the coupled vector differs from MoorDyn's (on the point
  route it includes the Fixed anchors) and could only be derived from
  the deck.

New entry points, C ABI 1 minor extension 2; no existing function
changes:

- CableDyn_InitDeckAt solves the statics with every line-bound
  Coupled/Vessel point at its entry of q0, on the point route (new
  optional coupled_positions of CD_Init_Deck_System) and the aggregate
  route (CD_AGG_Init_From_Deck). q0 is either the host blocks alone,
  MoorDyn's X layout, or the full coupled vector. A post-check confirms
  that every host block starts at q0. For the box the held fairleads
  then keep their load to 2e-16 N, and line 4's load (0.3026, -0.0761,
  -0.4114) N is bit-identical to the deck moved to the host positions.
- CableDyn_SaveState and CableDyn_RestoreState keep one in-memory deep
  copy of the whole model (and the aggregate's committed time). It is
  independent of the step's own rollback buffers, so any number of
  steps, including the dtM sub-steps of a host step, may lie between
  save and restore. Restore then step is bit-identical to stepping from
  the saved state on both routes.
- CableDyn_GetCoupledLayout returns the deck point id and type of every
  block of the coupled vector.

Python gains init_deck_at, save_state, restore_state, coupled_layout
and host_dofs. The C API manual has a new section, Coupling a host
(CFD) solver, that compares the call sequence with MoorDyn's step by
step: initialisation, vector layout, end-of-step motion, outer
correctors, load summation, the fixed step of the aggregate route and
units. Tests: c_api_host_coupling (the box deck, a chain-and-cable
aggregate deck), save/restore in test_c_api and the 1 MiB stack gate,
and python/tests/test_host_coupling.py.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
- CableDyn_SaveState marks the slot invalid while it overwrites it, so
  an allocation failure inside the copy cannot leave a half-written
  slot marked valid.
- InitLine and InitLines build the point system in place, so a failed
  call loses the previous model; it now discards the saved state as
  well, and the manual limits the atomic re-initialisation guarantee to
  InitDeck and InitDeckAt.
- Python init_deck_at rejects a (3, 3) q0 as ambiguous (column- or
  row-per-point) and asks for the flat form.
- A test with the Coupled rows listed before the Fixed ones checks that
  the coupled blocks, the host DOFs and the loads follow the POINTS
  table order.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
- The save follows the live model: a successful Init* discards it, a
  failed InitDeck/InitDeckAt keeps it with the model, and a failed
  InitLine/InitLines discards it unless an aggregate model stays live;
  the handle comment, header, manual, coupling boundary note and Python
  docs now say the same.
- The host call sequence keys the save on the start-of-step time
  (t_prev - t_saved >= 1e-3 dt), so a pass retried with a smaller dt
  restores instead of saving an already advanced model, as foamMooring's
  sixDoFMooringRestraints does.
- MoorDyn comparisons: 6 values per coupled body or cantilevered rod and
  3 per pinned rod or point; the Coupled-only q0 equals MoorDyn's X when
  every Coupled point is attached to a line; the moment conventions of
  the two foamMooring restraints are named. Only the aggregate slot
  allocation returns CD_C_ALLOC_FAIL; an out-of-memory copy aborts.
- Tests: the save across failed inits on both routes, save/restore on a
  raw InitLine handle, bit-identity with viscoelastic + friction, Syrope
  and a Free point with UpdatePointFluidFields between save and
  restore, InitDeckAt rejections (a shared fairlead given two positions,
  End A below its anchor) and the full form on a Free-point deck,
  InitDeckAt on the 1 MiB stack, and test decks removed on every exit.

Signed-off-by: Jae Hoon Seo <jaehoon.seo@inha.ac.kr>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 16, 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-16T08:22:38.040620Z 5e177cc PR opened
ℹ️ 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 #35186986 | 📁 Comparing 5e177cc against latest (f27c5e3)

  🔍 Preview build  

21 files changed · ± 21 modified

± Modified

@SMI-Lab-Inha
SMI-Lab-Inha merged commit f2caf1f into dev Oct 16, 2026
15 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the feat/capi-host-coupling branch October 17, 2026 09:04
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