SeaState: On-demand block partitioning of wave kinematics to reduce memory (WvKinBlockMod)

[mayankchetan]

SeaState: on-demand wave-kinematics block partitioning (WvKinBlockMod)

This PR is ready to be merged.

Feature or improvement description

Adds an optional on-demand block partitioning mode for the SeaState
wave-kinematics volume arrays (velocity, acceleration, dynamic pressure, and —
when enabled — the MCF acceleration). Today SeaState precomputes these arrays
over the entire wave grid at initialization and holds them resident for the
whole simulation. For grids that are large relative to the region a structure
actually visits, most of that memory is never touched.

With WvKinBlockMod = 1, the grid is divided into cube blocks partitioned in
X, Y, and Z. Each block is computed the first time wave kinematics are
requested at a point inside it, and (optionally) freed after a configurable idle time.
Evicted blocks are transparently and deterministically recomputed on next
access.

Physical behavior is unchanged by default: WvKinBlockMod = 0 (full-domain
precompute) is byte-identical to the previous code. Note that the three new
input lines are required additions to the SeaState input file
(WvKinBlockMod has no parser default; the other two accept DEFAULT) — the
companion r-test submodule bump adds them to every SeaState deck.

seastate_blocks_2x2.mp4

New inputs (SeaState SPATIAL DISCRETIZATION section)

Input	Type	Default	Meaning
WvKinBlockMod	int	— (required)	0 = precompute full domain (current behavior); 1 = on-demand blocks
WvKinBlockSize	real (m)	100	Target edge length of a cube block, applied to all three of X, Y, and Z (snapped to whole cells, min 8 cells/side; the non-uniform cosine-distributed Z grid snaps via the mean Z spacing, so coarse-Z grids may remain a single Z block); used only when WvKinBlockMod = 1
WvKinBlockFreeT	real (s)	600	Free a block after this much sim time without an access; ≤ 0 disables freeing; used only when WvKinBlockMod = 1

Guards: WaveMod = 0 and WrWvKinMod = 2 force mode 0; WaveMod = 6
(externally-supplied full kinematics) with mode 1 is a fatal input error.

Block VTK visualization

Adds an optional <root>.SeaSt.WaveBlocks.<frame>.vtk output series so the
on-demand block partition can be watched evolve during a run:

• Triggers, no new glue inputs. In the glue code it rides the existing
  WrVTK = 2 animation output — no new .fst/SeaState input is added. The
  standalone SeaState driver gets one new optional trailing input,
  WrBlockVTK (write interval in steps; 0/absent = off, preserving
  compatibility with every existing driver input file).
• Encoding. One VTK cell per block; the BlockLife cell scalar is -1
  for a block never populated, 0 for an evicted block, and (0, 1] for a
  resident block (normalized time remaining before eviction, pinned at 1
  when WvKinBlockFreeT <= 0).
• Restart-safe. The per-block EverPopulated flag is packed/unpacked via
  the registry, and the non-owning BlockStore alias on the WaveField is
  re-established on restart, so a restarted run resumes with the correct
  never/evicted/active block states.

Related issue, if one exists

None.

Impacted areas of the software

• SeaState (modules/seastate/src/): SeaSt_WaveField.f90/.txt,
  SeaState.f90/.txt, SeaState_Input.f90, SeaState_DriverCode.f90,
  Waves.f90, Waves2.f90/.txt, UserWaves.f90, registry-generated
  *_Types.f90.
• OpenFAST glue (modules/openfast-library/src/FAST_Subs.f90): the guarded
  block-VTK call in WrVTK_Surfaces.
• openfast_io (openfast_io/openfast_io/FAST_reader.py, FAST_writer.py):
  read/write the three new inputs.
• Documentation: docs/source/user/seastate/input_files.rst, appendix.rst.
• r-test: submodule bump adding the three inputs to all SeaState decks
  (branch f/seastate-block-partition on the r-test fork).

Additional supporting information

Design

• Shared seed-driven kernels. The first- and second-order wave-kinematics
  column computations were extracted into WaveKinKernel_ComputeColumns
  (Waves.f90) and WaveKinKernel_AddSecondOrderColumns (Waves2.f90). Mode 0
  (full-grid loop) and mode 1 (per-block fill) call the same kernels, so the
  two modes agree to solver precision and evicted blocks regenerate
  bit-identically. Kernels depend only on captured seeds and immutable grid
  data — no run-time mutable state, no date/random. The kernels take
  iPtZ0/nPtZ Z sub-range arguments; mode 0 always passes the full Z
  range, so its loop structure (and output) is unchanged by the Z
  partitioning.
• Block store. Owned by the SeaState MiscVar (m%WaveBlockStore); the
  WaveField carries a non-owning pointer. Blocks partition grid cells in
  all three axes and store a halo of three extra grid planes per axis (one
  below, two above the block's cells) to satisfy the 4-point cubic
  interpolation stencil.
• Eviction. WaveField_SweepBlocks frees idle blocks under an
  !$OMP CRITICAL(SeaSt_BlockPop) guard; the just-accessed block is timestamped
  before any sweep so it can never evict itself.
• Init memory report. SeaState prints a one-time report of full-domain vs
  block resident memory at the end of initialization.

Measured guidance (added to the user docs)

Block-size × free-time sweeps on 5MW OC4-Semi and MHK_RM1_Floating:

• On-demand partitioning helps most when the grid is much larger than the
  queried footprint. For station-keeping platforms (static footprint), savings
  come from block size, not eviction.
• The halo makes small blocks counterproductive: WvKinBlockSize
  = 50 m split the MHK footprint across 3 blocks and used ~17% more peak
  memory than the full-domain default. 100–200 m used a single block at
  parity-to-modest savings (OC4-Semi: −5% at the 100 m default).
• WvKinBlockFreeT has no effect for station-keeping platforms (footprint
  never idles); it matters only for a query that migrates across the grid.

Generative AI usage

Substantial portions of this feature were developed with Anthropic Claude
(Claude Code); all design decisions were made and approved by the human
author. A multi-agent workflow was used: Claude Fable 5 orchestrated (design
interview, implementation planning, adjudication of review findings), with
implementation and per-task independent code reviews delegated to smaller
Claude models, and two independent whole-branch reviews performed by Claude
Opus. Every task was gated by an independent review pass (spec compliance +
code quality) before proceeding, and all changes are backed by the test
evidence below. Development relied heavily on the OpenFAST Agent Kit (OAK) —
OpenFAST-specific sub-agents and MCP tooling for reading/editing/running
cases, searching the docs/code corpus, and navigating the Fortran source.

Co-authored-by: Anthropic Claude claude@anthropic.com

Test results, if applicable

Mode-0 byte-identity (the primary gate). All 11 SeaState module regression
cases produce byte-identical .SeaSt.out data vs the post-kernel-refactor
baseline. This gate was re-run and re-passed 11/11 after each later structural
change (the Z/cube-block partitioning and the block VTK export). The one-time
kernel extraction introduces a floating-point reassociation drift of ≤ 1 ULP of
the printed output precision (max relative ≈ 8×10⁻⁷, well under the r-test
tolerance of ~2×10⁻⁵) vs the pre-refactor snapshot — documented for
transparency.

Mode 0 ≡ Mode 1. Re-verified on the final code (after the Z/cube-block
change): nine twin pairs across five cases — seastate_1 (3×3×2 forced cube
layout), seastate_wavemod5 (3×3×2), seastate_WaveMod7_WaveStMod2,
hd_MCF_WaveStMod2 (1×1×4 pure-Z stack, MacCamy-Fuchs array per block), and
5MW_OC3Mnpl_DLL_WTurb_WavesIrr (second-order QTFs filled over true Z
sub-ranges, 1×1×2) plus 5MW_OC4Semi_WSt_WavesWN under the full glue stack —
all bit-identical to the mode-0 twin (binary channel data max abs diff
0.0; text outputs differ only in run-timestamp header lines). Wave kinematics
were also compared directly: a 9-probe twin (NWaveKin = 9, probes placed
to sample every XY block column and both Z layers of a 3×3×2 partition) shows
all 63 kinematics output channels (FVelJ*, FAccJ*, FDynPJ) exactly equal
between the two modes at every output step. Deterministic
regeneration after eviction: a 1000 s drifting-platform run with 166
evictions/repopulations is payload-byte-identical to its eviction-disabled
twin. Earlier smoke coverage (py_seastate_1 binding, 5MW_OC3Mnpl restart,
eviction-on/off) also passed byte-identical.

Block VTK verified end-to-end. A drifting-platform run on 5MW OC4-Semi
(CompMooring = 0, HydroDyn WaveDisp = 1 so the kinematics footprint follows
the drift, TMax = 300, WvKinBlockFreeT = 30) produced a 301-frame series
showing all three states (never / evicted / active); a pinned run
(WvKinBlockFreeT = -1) showed only never/active with every resident block
exactly at 1.0; the standalone-driver trigger was exercised on
seastate_wr_kin1 (needs NWaveKin > 0) with well-formed frames every 5
steps. Three additional 1000 s OC4-Semi drifting-platform visualization runs
(mode 0 / eviction-off / WvKinBlockFreeT = 60) confirmed the full block life
cycle in the exported series: block counts growing with the drift, the eviction
countdown, and 15 blocks evicted by the end of the eviction-enabled run.

Full regression suite. ctest -j 8 (196 tests). 7 failures, all triaged as
unrelated to this feature:

Test	Cause
MHK_RM1_Floating_MR_Linear	pre-existing known failure (linearization)
Damped_Beam_Rotated, 5MW_Land_BD_Linear, IEA22MW_ModalDamping	BeamDyn/linearization — this diff touches no BeamDyn code
openfast_io_library	environment: pytest not installed
py_wavetank_test1	environment: nptdms not installed
5MW_OC4Jckt_DLL_WTurb_WavesIrr_MGrowth	HD load channels differ ~0.6% rel; zero wave-channel diff; mode-0 SeaState output byte-identical — attributable to inherited upstream HydroDyn (NLFKHst) changes / turbulent-DLL chaotic divergence vs the gold, not to this feature

Independent whole-branch code review (Claude Opus): no Critical or Important
findings. All six binding invariants (mode-0 byte-identity, mode 0 ≡ mode 1,
deterministic regeneration, halo correctness, guards, eviction/ownership
safety) verified by source trace. Three Minor, non-blocking observations
recorded.

• r-test branch merging required
  (f/seastate-block-partition on the r-test fork — adds the three new input
  lines to all SeaState decks)

• please squash commits before merge

[jjonkman]

Super cool that AI made this PR come together very quickly!

See a couple comments below.

In the conversation, what does "mode 1" mean in the following?:

Guards: WaveMod = 0 and WrWvKinMod = 2 force mode 0; WaveMod = 6
(externally-supplied full kinematics) with mode 1 is a fatal input error.

[jjonkman]

Why is WvKinBlockMod made a switch? Are you expecting additional options in the future? If not, this could be a TRUE/FALSE flag.

[mayankchetan]

mode 1 is referring to WvKinBlockMod=1, but you are right, I should just change that to a TRUE/FALSE flag

[RBergua]

This looks very cool, @mayankchetan!

Just a couple of questions based on the visualization:

1. There seems to be a random block active. I'm not sure if this is related to the visualization or if the block is active in reality for some reason.

2. Looking at the initial video frame, it seems that the wave kinematics for the mooring lines are active (SeaState-MoorDyn coupling).

But when the simulation advances, the blocks for the mooring lines seem to not be active anymore. Again, I'm not sure if this is related to the visualization or the actual behavior.

[mayankchetan]

This looks very cool, @mayankchetan!

Just a couple of questions based on the visualization:

1. There seems to be a random block active. I'm not sure if this is related to the visualization or if the block is active in reality for some reason.

2. Looking at the initial video frame, it seems that the wave kinematics for the mooring lines are active (SeaState-MoorDyn coupling). But when the simulation advances, the blocks for the mooring lines seem to not be active anymore. Again, I'm not sure if this is reated to the visualization or the actual behavior.

So,

1. That's the anchor location, so the block is active to provide values to MoorDyn. The SeaBed is at 200m and the SeaState domain is until 25m depth.
2. yes! for the example we used SEASTATE WaterKin in MD. I spoke to @luwang00 about this, the mooring lines go below the seabed (because the stiffness is finite) and will not query SeaState for data:

openfast/modules/seastate/src/SeaSt_WaveField.f90

Line 171 in f5a0166

! Check if point is below the seabed

3. Another cool observation, in the eviction case, you can see a few blocks active even after the turbine has moved away. Its because we have outputs in SeaState at those coordinates, so the block is considered "always" active.

[RBergua]

Thanks for the feedback, @mayankchetan. One small follow-up question based on my understanding of the settings used:
Assuming that the Moordyn-SeaState coupling is enabled, SeaState 3D grid is defined up to 25 m deep, and the water depth is 200 m, is SeaState providing information for the line if it's outside the 3D grid defined? This would help me understand if the anchor location can indeed receive data from SeaState or not.

[Copilot]

Pull request overview

This PR adds an optional on-demand block-partitioning mode for SeaState wave-kinematics volume data to reduce initialization memory by lazily populating (and optionally evicting) kinematics blocks, while preserving the existing full-domain precompute mode.

Changes:

• Introduces WvKinBlockMod/WvKinBlockSize/WvKinBlockFreeT inputs and wiring for on-demand wave-kinematics blocks in SeaState (including restart packing/unpacking support).
• Refactors shared wave-kinematics generation into per-column kernels reused by both full-domain precompute (mode 0) and block population (mode 1), including second-order additions.
• Adds optional wave-block VTK visualization output (SeaState driver and OpenFAST glue hook) and documents the new inputs/behavior.

Reviewed changes

Copilot reviewed 19 out of 20 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
openfast_io/openfast_io/FAST_writer.py	Writes the three new SeaState spatial-discretization inputs.
openfast_io/openfast_io/FAST_reader.py	Reads the three new SeaState spatial-discretization inputs.
modules/seastate/src/Waves2.txt	Updates registry text to reflect removal of full-size init-time temporaries.
modules/seastate/src/Waves2_Types.f90	Removes the Waves2_InitOutputType and associated pack/copy/destroy routines.
modules/seastate/src/Waves.f90	Adds shared first-order column kernel and refactors init to capture seeds + call kernel for mode 0.
modules/seastate/src/UserWaves.f90	Avoids allocating full-domain volume arrays when block mode is active.
modules/seastate/src/SeaState.txt	Adds new input fields and misc-var block-store pointer to the registry definitions.
modules/seastate/src/SeaState.f90	Wires block store ownership, guards, seed capture, second-order integration, and memory reporting.
modules/seastate/src/SeaState_Types.f90	Adds new input fields and registry pack/unpack/copy support for the block store pointer.
modules/seastate/src/SeaState_Input.f90	Parses/validates the new inputs and stores them into p%WaveField.
modules/seastate/src/SeaState_DriverCode.f90	Adds optional driver-only WrBlockVTK trailing input and writes block VTK frames.
modules/seastate/src/SeaSt_WaveField.txt	Adds block/block-store type definitions and new WaveField fields for block mode.
modules/seastate/src/SeaSt_WaveField.f90	Implements block layout, population/eviction, VTK export, and unified interpolation access.
modules/seastate/src/SeaSt_WaveField_Types.f90	Adds registry-generated types and pack/unpack/copy/destroy support for blocks/store.
modules/openfast-library/src/FAST_Subs.f90	Hooks block VTK writing into existing WrVTK=2 surface output path.
LICENSE	Updates the Apache-2.0 appendix boilerplate copyright placeholder line.
docs/source/user/seastate/input_files.rst	Documents new inputs, sizing guidance, and VTK visualization behavior.
docs/source/user/seastate/appendix.rst	Updates the SeaState input-file structure example to include new inputs.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.