Skip to content

CableDyn 0.1.1 - #6

Merged
SMI-Lab-Inha merged 17 commits into
mainfrom
release/0.1.1
Oct 9, 2026
Merged

SMI-Lab-Inha merged 17 commits into
mainfrom
release/0.1.1

Conversation

@SMI-Lab-Inha

Copy link
Copy Markdown
Owner

CableDyn 0.1.1

This PR brings the work collected on dev since v0.1.0 to main and sets the version to 0.1.1.

Contents

  • Torsion of finite-EI lines in the standalone driver:
    • END CONNECTIONS torsion columns;
    • the motionFile roll column;
    • Rigid6 torque;
    • Torq/Twist channels and range columns;
    • Python DeckModel support.
  • Windows stack robustness:
    • large locals are on the heap;
    • GNU Windows executables reserve 64 MiB;
    • the IFX OpenFAST adapter uses heap arrays;
    • new stack tests.
  • Fixes: the taut neutrally buoyant seed; CI and test-suite robustness; the EPUB build; Python typing.
  • Hardening for the release:
    • a static twist above 1000 turns stops by name, in the driver and in the Python deck check;
    • installing torsion invalidates the step snapshot, and every touched field is restored on failure;
    • setting an end connection after an installed torsion, or a mismatched rigid-end director, is refused by name;
    • the coupled shell resets the torsion frame fields at End;
    • torsion channel units are set;
    • END CONNECTIONS messages name the line, the end and the value;
    • channel ids with leading zeros get their units;
    • several doc corrections, and a stack note in the troubleshooting page.
  • Release metadata:
    • version 0.1.1 everywhere;
    • check_release_metadata.py now also rejects any other CableDyn version outside the records of past releases, and tests/test_documentation.py covers it;
    • the Holcombe and Bergdahl comparisons were re-run with 0.1.1, and every result is identical;
    • validation/RELEASE_0_1_1.md is added.
  • Driver end-of-run reporting (from dev):
    • fatal-fault and interrupt reports with the time of the last committed step;
    • per-thread handlers for OpenMP threads;
    • the Exit status: start line and the closing line CableDyn_driver: ended with exit code <n>;
    • Python runners that report a run ended from outside.
  • Review fixes to the end-of-run reporting:
    • the start-up line now states exactly what is guaranteed: "every non-zero exit the driver makes itself ends stderr with ...";
    • the Python runner reports a Fortran runtime abort (for example forrtl: severe (41)) as such, not as an outside end;
    • the static release build now checks the start-up line and the closing line on a refused input;
    • the documented fault-report format and the release driver's exit after Ctrl+Break (forrtl 200, then 1 or 152) match what was observed;
    • a deferred-length allocation no longer reads its hidden length (the -Wmaybe-uninitialized warning of the snan build).
  • Release metadata: the version sweep accepts lines marked past-release, which the driver tests use to stand for a 0.1.0 driver.
  • Known issue noted in the CHANGELOG: an intermittent modal-test access violation on some hosted CI runners with OpenBLAS 0.3.34 (GNU builds only; the release driver uses reference LAPACK).

Checks at the release commit

See validation/RELEASE_0_1_1.md:

  • GNU Release and Debug CTest, including the slow tier;
  • the -fcheck=all + -finit-real=snan sweep;
  • pytest with branch coverage;
  • Sphinx HTML and EPUB with -W -n;
  • release metadata and tree audits;
  • the static IFX build gates;
  • the clean-machine kit, run from a mixed-script path;
  • CableDyn Studio's model tests on the 0.1.1 wheel.

After merging, fast-forward dev to main.

Condensed parallel-transport torsion for the cubic-Hermite cable: torsional END CONNECTIONS columns with explicit GJ, statics with a bordered Newton step and Greenhill stability check, dynamics with turning ends and a motionFile roll column, torque returned to Rigid6 bodies, Torq/Twist channels and range columns, Python deck support, documentation, an example and validation against closed-form solutions and OrcaFlex 11.6d. Decks without torsional restraints run unchanged.
Moves fixed-size locals above 64 KB off the stack in tests and the aggregate initialisation, links GNU Windows executables with a 64 MiB stack reserve, compiles the OpenFAST adapter with heap arrays in the Visual Studio release, removes gfortran 16 false-positive -Wuninitialized warnings, and adds stack regression tests that run large models on a 1 MiB stack.
* Report every abnormal end of the standalone driver

A process that is interrupted or hits a fatal fault now writes one line to
stderr naming the cause and the simulated time of the last committed step,
then lets the event continue to the runtime's own handler, so the exit
status is unchanged. On Windows a console-control handler, a vectored
handler for fatal faults and an unhandled-exception filter (with a stack
guarantee, so a stack overflow is reported) are used; on Linux and macOS
signal handlers on an alternate stack. Only the driver installs them; the
shared library leaves the host process alone.

Every non-zero exit the driver makes itself now ends stderr with the
closing line "CableDyn_driver: ended with exit code <n>". A process ended
from outside (taskkill /F, End task, kill -9) runs none of its own code and
cannot report anything; the missing closing line identifies it, since
taskkill /F leaves exit code 1, the code of a refused input. The Python
runner reports such a run as ended early, with the time its output reached.

Tests: a stack overflow on a 1 MiB stack, a null-pointer write and SIGTERM
each end the process with the report; the march records the time of its
last committed step; the driver's failure checks require the closing line.

* Prepare worker threads and keep the fault context in the abnormal-end report

Every OpenMP parallel region of the library now starts with
CD_Fatal_Thread_Init, which gives the calling thread room to report its
own stack overflow: a stack guarantee on Windows, an alternate signal
stack (freed when the thread ends) on Linux and macOS. It does nothing
until the driver has installed the report, and costs one thread-local
test after a thread's first call. Previously only the installing thread
had that room, so an overflow on a worker thread could still end the
process without a word.

On Linux and macOS the handlers are now three-argument (SA_SIGINFO)
handlers. A hardware fault returns from the handler under the previous
disposition, so the faulting instruction raises the same fault with its
own address and context; a previous three-argument handler is called
with the original siginfo and context. Only asynchronous signals and
faults sent by kill or raise are sent again.

Tests: a stack overflow on an OpenMP worker with a 1 MiB stack is
reported (it ended silently without the per-thread setup); a forked child
with an earlier SA_SIGINFO handler faults at a known address and that
handler receives the kernel's own siginfo, the child ends by the fault's
signal, and the report is written once; and every OpenMP parallel region
in src/ and app/ is checked to begin with the per-thread call.

* Keep ignored signals ignored when the report is installed

The previous disposition of each signal is now classified by one helper
that compares sa_handler with SIG_IGN, SIG_DFL and SIG_ERR whatever the
SA_SIGINFO flag says (sa_handler and sa_sigaction share storage). The
report is not installed on a signal that was ignored, with or without
SA_SIGINFO, or whose disposition cannot be classified, and it chains only
to a real handler function. Previously an inherited SIG_IGN stored with
SA_SIGINFO set was taken for a handler: the report was installed, and the
ignored signal was then passed to the SIG_IGN sentinel as a function.
If restoring the previous disposition fails, the default action is set
so the handler is never entered again.

Test (POSIX, forked children): SIGTERM set to SIG_IGN with SA_SIGINFO,
and to plain SIG_IGN, leaves the child running to a normal exit with no
report; SIG_DFL is reported once and ends the child by SIGTERM; a
one-argument handler is reported once and then runs.

* Re-deliver chained signals through the kernel; make test_modal explain a crash

The report no longer calls a previous signal handler itself. It
re-installs the saved action exactly as it was (handler, flags and mask)
and lets the kernel deliver the signal again: a hardware fault returns so
the instruction re-executes, and an asynchronous signal is raised. The
previous handler therefore runs under its own SA_RESETHAND, sa_mask and
self-blocking, as it would have without the report.

Tests (POSIX, forked children): a previous handler with SA_RESETHAND gets
the first SIGTERM and a second SIGTERM ends the process; a previous
handler with SIGUSR1 in its sa_mask runs with SIGUSR1 and SIGTERM
blocked. The fault-context test still sees the kernel's own siginfo.

test_modal and stack_modal ended once on a hosted Windows runner with
"Exception: SegFault" and no output, and passed on a re-run of the same
commit; the toolchain CI resolves passes here. They now install the
abnormal-end report, so a recurrence names the fault (stack overflow or
access violation), and print the OpenBLAS build and kernel the host
selected before any case runs.

* State the exit contract at start; hoist per-thread setup out of loops

The driver now writes, after its banner, one line stating that every
failure ends stderr with "CableDyn_driver: ended with exit code <n>".
The Python runner infers an outside end (no closing line) only when that
line is present; with a driver that does not write it (0.1.0 and
earlier), a failure is reported with the driver's own text and the time
its output reached, as before.

Every OpenMP region is now a PARALLEL region whose first statement is
CD_Fatal_Thread_Init, followed by the worksharing DO, so a thread is
prepared once per region instead of once per element. The source guard
now refuses combined PARALLEL DO constructs and a per-iteration call.

Hardening: a thread checks the process-wide "installed" flag before its
thread-local one, so a host that never installs the report never touches
it; the POSIX report flag is set with an atomic exchange, so two threads
that fault together report once; alternate signal stacks are at least
64 KiB and at least the system's SIGSTKSZ / _SC_SIGSTKSZ (128 KiB on
macOS; larger on CPUs with big vector state).

Tests: an older driver's refusal is reported with its own text, a new
driver without a closing line as ended from outside; the report followed
by runtime lines (forrtl, a libgfortran backtrace) is read as an abnormal
end; a library deck run leaves the host's signal dispositions and
unhandled-exception filter unchanged; each prepared thread has one
alternate stack of the system size; only app/cabledyn.f90 installs the
handlers; the real driver writes the exact start-up line.

* Tell sent faults apart portably; locate Windows faults; guard-page LAPACK test

A fault signal sent by a process is now recognised by its sender code
(SI_USER, SI_QUEUE, SI_TKILL, SI_TIMER, SI_ASYNCIO, SI_MESGQ where
defined, or any si_code <= 0), not by sign: on macOS SI_USER is positive,
so a SIGSEGV sent with kill() was taken for a hardware fault and the
handler returned instead of sending it again. Test (POSIX, forked
children): SIGSEGV and SIGFPE sent with kill() end the child by that
signal with one report.

On Windows a fault report now names the module and offset of the fault
and, for an access violation, the address read or written, so a fault
inside a library (such as the intermittent one seen in the modal tests
on some hosted runners) identifies itself.

New test lapack_guard_pages: DSYGV and DSBGVX through CableDyn's LAPACK
layer, with every argument array against a no-access page at its end and
at its start (n <= 96, half band widths 0..11, OPENBLAS_CORETYPE=Haswell),
with the argument sizes the modal code uses. It passes with OpenBLAS
0.3.33 and 0.3.34: the modal code's arguments and workspaces are within
bounds.
Moves the unreleased notes under the 0.1.1 heading and extends the release-metadata check with a sweep that rejects any other CableDyn version outside the records of past releases.
DeckFile messages for an END CONNECTIONS row now say which line and
end they concern and quote the offending stiffness, direction or
torsion reference normal. Main-output channel units are recognised
for ids written with leading zeros, as the driver accepts them. More
torsion rows and torsion channel names are checked against the
native driver's verdict.

The docs now say that the motionFile roll column turns the moving end
of the line, that the normal and Pretwist of a Free end are only
checked to be finite, that the Twist channels need a line restrained
at both ends, and how the Windows GNU build sizes its stacks.
The static solve ramps the imposed twist in stages of at most 45 degrees, so a twist given in the wrong units ran for millions of stages, and a still larger one overflowed the integer stage count. The deck check now names the line and the twist in degrees, and the static solver rejects such a twist or twist state with its value.
Installing a torsion description changes the cable's load set. It now invalidates the step snapshot, as a new end connection does, and a description rejected after the acceleration update restores every torsion field it touched, the snapshot included. Ending a cable module also resets its parent-attached torsion frame.
The torsion takes a rigid end's director from its connection and its Theta from the current tangents. Setting the end connections after the torsion now stops by name instead of leaving both stale, and installing a torsion whose director at a rigid end is not the connection direction is refused, as the static solver already does.
The channel-unit lookup gives Torq channels (N.m) and Twist channels (deg), as the range files do, instead of (-). Every END CONNECTIONS row error after the End column now names the line, the end and the offending value.
DeckFile now gives the native driver's verdict on an imposed twist Pretwist(B) - Pretwist(A) above 1000 turns, naming the line and the twist.
…tures

The release-metadata sweep skips lines marked past-release, which the driver tests use to stand for an older driver.
…rrors as such

The start-up line now says that every non-zero exit the driver makes itself ends stderr with the closing line, which is what it guarantees: an interrupt or a fatal fault ends with its own report instead. The Python runner reports a run the Fortran runtime ended with its own error as such, not as an outside end. The static release build checks the start-up line and the closing line on a refused input, the documented fatal-report format matches the report, and a deferred-length allocation no longer reads its hidden length.
The Intel Fortran runtime adds a traceback after its control-break line and can exit with 152 when the traceback meets output in progress; the driver's own report is still the one the Python runner relays.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 9, 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-09T10:46:10.574637Z f27c5e3 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 #35038247 | 📁 Comparing f27c5e3 against latest (c0a88eb)

  🔍 Preview build  

26 files changed · ± 26 modified

± Modified

@SMI-Lab-Inha
SMI-Lab-Inha merged commit f27c5e3 into main Oct 9, 2026
15 checks passed
@SMI-Lab-Inha
SMI-Lab-Inha deleted the release/0.1.1 branch October 12, 2026 07:42
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