Repository navigation
feat(capi): host-coupling calls for CFD hosts (ABI 1.2) - #18
Merged
Merged
Conversation
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>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
C ABI 1, minor extension 2: calls for hosts that drive the
Coupledpoints 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:
MoorDyn_Init(X, XD)moves the coupled points to the host's positions before the initial condition.CableDyn_InitDecksolved 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.Fixedanchors) and could only be derived from the deck.New calls
InitDeckAtsolves the statics with every line-boundCoupled/Vesselpoint at its entry ofq0, on both the point and the aggregate route.q0is either the host blocks alone (MoorDyn'sXfor a deck whose Coupled points are all line-bound) or the full coupled vector.q0; a point shared by two lines must be given one position.SaveState/RestoreStatekeep one in-memory deep copy of the whole model (and the aggregate's committed time).dtMsub-steps of a host step included).Init*discards the save;InitDeck/InitDeckAtkeeps it with the model;InitLine/InitLinesdiscards it unless an aggregate model stays live.GetCoupledLayoutreturns 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(restorestime),coupled_layout,host_dofs.Docs:
doc/capi.rstgains "Coupling a host (CFD) solver". It compares the call sequence with MoorDyn's C API step by step:Steptakes the start of the step);Tests
c_api_host_coupling(C, shared library):InitLinehandle;UpdatePointFluidFieldsbetween save and restore;InitDeckAtrejections (shared fairlead given two positions, End A below its anchor);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/tests/test_host_coupling.py, including a POINTS table with Coupled rows before Fixed ones.pre-commit run --all-filesand the Sphinx build with-Wpass.Checklist
pre-commit run --all-filespassesctest --test-dir build --output-on-failurepassespython -m pytest tests python/testspasses (if Python or validation records changed)[Unreleased](heading added if missing) for user-visible changesdoc/updated for changed inputs, options, or outputsfeat:,fix:,docs:, ...)git commit -s) under theDeveloper Certificate of Origin