[andrew-platt]

Ready to merge after CI testing

Feature or improvement description

This PR fixes the three problems reported in #3516. It also fixes a module-indexing error in the glue code's tight-coupling sub-step check, found while working on item 1.

1. A numeric DTBeam was not seen by the BeamDyn driver

BD_Init used its Interval argument only as the default for DTBeam and never returned the time step it used. The driver kept stepping inputs and output times with its own dt while the integrator advanced by DTBeam. With dt = 0.002 and DTBeam = 0.001, bd_5MW_dynamic gave N1Fxl = -3.8e5 at t = 0.004 s instead of about 7.0e3, with no message.

• BD_Init now returns p%dt through Interval, as the Interval documentation says it should.
• beamdyn_driver now sub-steps BeamDyn. If DTBeam is an integer divisor of the driver dt, it takes dt/DTBeam BeamDyn steps per driver step and still writes output and VTK every dt. It stops with an error if DTBeam is larger than dt or does not divide it. Static analysis is not sub-stepped (from Copilot review): it does not use DTBeam, since each driver step is a load step.
• OpenFAST, loose coupling (ModCoupling = 1): the glue code already sub-steps modules at the time step returned from their Init (MV_AddModule / FAST_UpdateStates). Before, it always got DT back from BeamDyn, used a single sub-step, and BeamDyn integrated by DTBeam: the same silent mismatch as in the driver. Now BeamDyn is sub-stepped correctly. A DTBeam larger than DT, or one that does not divide it, is rejected by MV_AddModule.
• BD_UpdateStates now gives BD_UpdateGlobalRef the inputs interpolated to t + p%dt when BeamDyn is being sub-stepped (from Copilot review). Before, it passed u(1), which during glue-code sub-stepping is the root motion at the end of the full glue-code step, so intermediate sub-steps updated the reference frame and root node from future root motion. When u(1) is already at t + p%dt (no sub-stepping, and the driver), u(1) is used as before. In the test below this made no measurable difference to the results.
• OpenFAST, tight coupling (ModCoupling = 2, 3): the glue code integrates the BeamDyn states at DT and does not call BD_UpdateStates, so DTBeam is not used. The solver now prints its existing "Sub-stepping disabled" info message for BeamDyn (see item 4).
• A zero or negative DTBeam is now rejected (from Copilot review). BD_ValidateInputData requires DTBeam > 0 for dynamic solves. Static solves skip the check, since they don't use DTBeam and the driver dt may be 0 there. The driver also rejects a nonpositive BeamDyn step before computing sub-steps. Before, zero divided by zero, and a negative value gave a nonpositive sub-step count, so the beam states never updated while output time advanced.
• The DTBeam entry in the BeamDyn input-file docs now states these rules.

2. Registry unpack reads had no error return

None of the generated read(RF%Unit) statements in ModReg.f90 had iostat. A truncated checkpoint stopped the program with a Fortran runtime error instead of setting RF%ErrStat, which kills the calling process when OpenFAST is used as a library (C/Python). #3486 checks the file size before unpacking, but that does not cover other read errors. Despite what the issue says, the write(RF%Unit) statements had no iostat either.

ModRegGen.py now generates iostat checks on the data-number and data reads and writes, setting RF%ErrStat/RF%ErrMsg on failure. ModReg.f90 is regenerated from it. Before the change, the generator reproduced the committed file exactly, so the only differences in ModReg.f90 come from the generator change.

RegUnpackPointer also used the unpacked index to look up RF%Pointers without checking for a read error (from Copilot review). With the new iostat checks, or an existing data-number mismatch, the index is undefined at that point. A corrupt index was also never range-checked, so a bad checkpoint could still crash the calling process. RegUnpackPointer now initializes its outputs, returns if the read failed, and sets an error if the index is outside RF%Pointers.

3. BD_End closed the summary file without resetting the unit

BD_End now sets m%Un_Sum = -1 after closing the file. A caller that reuses the same misc variables can then no longer close a stale unit a second time.

4. Tight-coupling sub-step check used the wrong module index (FAST_Solver.f90)

The loop that prints "Sub-stepping disabled for this module" for tightly coupled modules indexed GlueModData(i) instead of GlueModData(p%iModTC(i)). So it checked and named the first size(p%iModTC) modules in GlueModData rather than the tightly coupled ones. All the other category loops above it already use p%iModTC(i). Only the info message is affected.

Related issue, if one exists

Closes #3516
Related: #3486 (BeamDyn C bindings). Item 2 only shows up through the C/Python interface added there.

Impacted areas of the software

• BeamDyn: BD_Init, BD_End, BD_ValidateInputData (DTBeam > 0), BD_UpdateStates (reference frame update when sub-stepped)
• BeamDyn driver: time stepping when DTBeam is numeric
• OpenFAST glue code: BeamDyn sub-stepping with loose coupling (through the returned DTBeam); tight-coupling sub-step info message
• NWTC Library: ModRegGen.py / ModReg.f90 (checkpoint pack/unpack used by every module's registry routines)
• Docs: BeamDyn DTBeam description
• Regression tests: new bd_5MW_dynamic_substep case (reg_tests/CTestList.cmake, r-test)

Additional supporting information

• The first four commits are one per item, in the order above. A fifth commit removes an OpenFAST DTBeam == DT check that the first commit had added. It turned out not to be needed for either coupling mode. The last four commits address the Copilot review: rejecting a nonpositive DTBeam (item 1), the error and range checks in RegUnpackPointer (item 2), no sub-stepping for static analysis in the driver (item 1), and the interpolated inputs for BD_UpdateGlobalRef (item 1).
• All 20 BeamDyn primary input files in r-test use DTBeam = "DEFAULT". In that case Interval comes back unchanged, and the driver and glue code take a single BeamDyn step per step. Regression results should not change.
• OpenFAST cases with a numeric DTBeam different from DT now sub-step BeamDyn (loose coupling) or print an info message that DTBeam is not used (tight coupling). Before, they ran with an inconsistent time step and no message.
• Known limitation, not fixed here: in OpenFAST with InterpOrder = 2, a sub-stepped BeamDyn gets a wrong root motion during the first glue-code step, which gives a large start-up transient in the root loads (see test results). The glue code fills the input history before the start time with copies of the initial input, so quadratic interpolation to the intermediate sub-step times is biased. InterpOrder = 1 is not affected, and neither is the BeamDyn driver. This is a glue-code problem that is not specific to BeamDyn; see Sub-stepped modules get a wrong input on the first glue-code step when InterpOrder = 2 #3521.
• No new tests are added.

Generative AI usage

Claude Code (claude-opus-5-5) was used to read the issue, make the changes, run the checks below, and draft this description. The changes were reviewed by the author.

Assisted-by: Claude Code:claude-opus-5-5 [Bash] [Read] [Edit]

Development testing

Built beamdyn_driver and openfast (gfortran, Release, double precision). Ran bd_5MW_dynamic from r-test, shortened to t_final = 0.02 s:

Driver dt	DTBeam	N1Fxl at 0.004 s	N2Fxl at 0.004 s	N1Fxl at 0.02 s
0.002	DEFAULT	6.676e+03	2.593e+03	1.618e+04
0.001	DEFAULT	6.995e+03	2.743e+03	1.524e+04
0.002	0.001 (2 sub-steps)	6.995e+03	2.743e+03	1.524e+04

• The sub-stepped run matches the dt = 0.001 run exactly at every output time compared. The baseline row matches the values given in BeamDyn: numeric DTBeam not seen by the driver; registry unpack without error return; BD_End summary unit #3516.
• With DTBeam = 0.0015 and dt = 0.002, the driver stops with "must be an integer divisor of the driver time step".
• With DTBeam = 0 or DTBeam = -0.001, the driver stops with "DTBeam must be greater than 0." The sub-stepped case gives the same results as before this change.
• bd_static_cantilever_beam with DTBeam = 0.001 (driver dt = 0.002) gives output identical to DTBeam = DEFAULT, which matches the r-test baseline.

OpenFAST loose-coupling sub-stepping: Damped_Beam_Rotating from r-test with ModCoupling = 1, RotSpeed = 60 rpm, Linearize = False, TMax = 0.3 s. Reference: DT = 0.00075, DTBeam = DEFAULT. Sub-stepped: DT = 0.0015, DTBeam = 0.00075.

Time (s)	Channel	Reference	Sub-stepped, InterpOrder = 1	Sub-stepped, InterpOrder = 2
0.0015	B1RootFyr (N)	1.106e+06	1.106e+06	6.542e+10
0.0015	B1RootMxr (N·m)	-3.001e+06	-3.001e+06	-1.891e+11
0.3	B1RootFyr (N)	1.149e+06	1.149e+06	9.521e+05
0.3	B1TipTDyr (m)	2.181e-03	2.181e-03	3.107e-03

• With InterpOrder = 1, the sub-stepped run agrees with the reference to about 5e-7 (relative) on the root load and tip deflection channels over the whole run. It does so with and without the BD_UpdateGlobalRef change.
• With InterpOrder = 2, the sub-stepped run has the start-up transient described under "Additional supporting information".
• Not exercised: the tight-coupling info message for a numeric DTBeam, and the new checkpoint iostat and RegUnpackPointer error paths.
• The full regression suite was not run.

Regression testing

• r-test branch merging required (b/BD_driver_dt, adds modules/beamdyn/bd_5MW_dynamic_substep)
  • check when r-test is updated

[Copilot]

🟡 Changes recommended

Unchecked pointer-index read failures can still crash the host, while nonpositive BeamDyn time steps can cause division by zero or silently skip state updates.

2 open issues

• Reject nonpositive beam time steps before calculating substeps · New
• Check RegUnpack errors before accessing the pointer index · New

What changed in this PR

This PR addresses #3516 by aligning BeamDyn time stepping with its callers, improving registry checkpoint error handling, and preventing stale summary-file unit reuse.

Changes:

• Return BeamDyn’s actual time step, add standalone-driver sub-stepping, and reject mismatched time steps in OpenFAST.
• Add checkpoint read/write error reporting in the registry generator and generated routines.
• Reset the closed summary-file unit and correct module indexing in tight-coupling diagnostics.

File	Description
modules/​openfast-library/​src/​FAST_Subs.f90	Reject BeamDyn time steps that differ from OpenFAST’s step.
modules/​openfast-library/​src/​FAST_Solver.f90	Correct module indexing in sub-stepping diagnostics.
modules/​nwtc-library/​src/​ModReg.f90	Add generated checkpoint read/write error checks.
modules/​nwtc-library/​ModRegGen.py	Generate registry I/O status checks and error messages.
modules/​beamdyn/​src/​Driver_Beam.f90	Sub-step BeamDyn while preserving the driver’s output cadence.
modules/​beamdyn/​src/​BeamDyn.f90	Return the actual time step and reset the closed summary unit.
docs/​source/​user/​beamdyn/​input_files.rst	Document DTBeam requirements for OpenFAST and standalone use.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Sub-stepping uses future root motion during intermediate updates, introducing artificial deformation, and makes static analyses perform redundant nonlinear solves.

1 open issue

• Interpolate moving-root input at each sub-step · New

1 previously missed issue

In code that hasn't changed since last review

Static analyses incorrectly use dynamic timestep ratio

modules/​beamdyn/​src/​Driver_Beam.f90:275

Static analyses also reach this branch, even though BD_UpdateStates dispatches to BD_Static, which solves equilibrium rather than advancing by p%dt. For a stationary static case with driver dt = 0.1 and numeric DTBeam = 0.0001, the new loop performs 1,000 equivalent nonlinear solves per output step instead of one. Keep n_substeps = 1 and use dt_global for the driver's time markers in static analyses; only dynamic analyses need the timestep ratio.

2 resolved since last review

• Check RegUnpack errors before accessing the pointer index
• Reject nonpositive beam time steps before calculating substeps

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Existing regressions exercise only one sub-step, leaving multi-sub-step equivalence, preserved driver output cadence, and the static load-step exception without automated coverage.

1 open issue

• Add regression coverage for BeamDyn sub-stepping and load-step exception · New

1 resolved since last review

• Interpolate moving-root input at each sub-step

_{Review effort: Balanced}