FAST.Farm slice output (terrain following, and arbitrary slice)

[andrew-platt]

Not ready to merge. See merge order below

Co-authored-by: Regis Thedin registhedin@gmail.com - conceptual development and multi-round plan iteration

Feature or improvement description

Adds two new FAST.Farm VISUALIZATION output features requested by the "Large Wind Farm Task" (§2.8 and §2.9) and issue #2383. Both are gated by dedicated block headers so existing FAST.Farm input files remain unchanged.

1. NumPlaneSlices — axis-aligned, extent-controlled planar sampling (Snippet 6 grammar from the plan). Each slice is defined by an origin(m), an axis-aligned normal, and two in-plane extent(m) values. The sample grid is fixed to the low-res spacing (dX_Low/dY_Low/dZ_Low), so no npoints column is required. Off-axis normals are a fatal input error whose message forward-references the future point-cloud extension.
2. NumTerrainSlices — terrain-following point-cloud sampling from an STL surface or a plain-text point cloud, each swept along one or more Offsets(m) in an OffsetNormal direction (facet-normal by default for STL). Every sample point is trilinearly interpolated in the low-res disturbed wind field at each output step.

Both features write self-describing XML VTK output (.vts StructuredGrid for planar slices, .vtp PolyData for point clouds) plus a matching .series JSON sidecar for ParaView's built-in time-series loader. Out-of-domain sample nodes are masked with IEEE quiet NaN so ParaView clips them automatically.

Each feature has its own sampling period (WrPlaneDT, WrTerrainDT) that falls back to WrDisDT via DEFAULT, so users can sample the two feature streams at rates independent of the classic disturbed-wind output.

Feature 1 — three axis-aligned planes (conceptual and real output)

The LESinflow_ArbSlice reg-test deck plants three slices: a horizontal hubXY plane (red, normal (0,0,1)), a cross-stream crossYZ plane through the turbine (green, normal (1,0,0)), and a stream-wise crossXZ plane (blue, normal (0,1,0)). All three intersect at the WT1 turbine.

Above: horizontal hubXY plane at $t = 24$ s parsed directly from FAST.Farm.Plane.hubXY.008.vts. The plane is discretised at $121 \times 61$ nodes on the low-res spacing (dX_Low = dY_Low = 10 m); the wake deficit downstream of WT1 shows up as the dark low-velocity patch centred at $(1000, 1000)$.

Input file syntax (from the reg-test deck):

--- AXIS-ALIGNED PLANE SLICES (extent-controlled) --- [Feature 1, Snippet 6 grammar]
3                  NumPlaneSlices     - Number of axis-aligned extent-controlled planar slices (-) [0 to 99]
DEFAULT            WrPlaneDT          - Feature 1 sampling period (s); DEFAULT falls back to WrDisDT
SliceName  origin(m)      normal   extent1(m)  extent2(m)
(-)        (m,m,m)        (-)      (m)         (m)
"hubXY"    (700 700 95)   (0 0 1)  1200        600           ! 1200x600 XY plane at hub height
"crossYZ"  (1000 700 5)   (1 0 0)  600         300           ! 600x300 YZ plane through the turbine at x=1000
"crossXZ"  (700 1000 5)   (0 1 0)  1200        300           ! 1200x300 XZ plane through the turbine at y=1000

Feature 2 — STL mountain + hub cloud (conceptual and real output)

The LESinflow_TerrainSlice reg-test deck plants two slices:

• "terr" — a 4-facet pyramid mountain read from mountain.stl (12 vertices, one per STL facet corner), swept along the per-facet normal to three offset sheets at 50/100/150 m. Total sample count: $3 \times 12 = 36$ points.
• "hub" — a 9-point hand-authored point cloud read from hub_points.txt, one sheet at offset 0 with an explicit vertical OffsetNormal (0 0 1). Exercises the CSV-with-header parser path in ReadPointCloudFile.

Above: sampled velocity magnitude at $t = 24$ s parsed from FAST.Farm.TerrSlice.terr.008.vtp (green circles, 36 pts across three offset sheets) and FAST.Farm.TerrSlice.hub.008.vtp (blue squares, 9 pts at hub height). The underlying pyramid is drawn faint for scale.

Input file syntax (from the reg-test deck):

--- TERRAIN-FOLLOWING SAMPLING --- [Feature 2, PDF §2.8 grammar with SourceType flag]
2                  NumTerrainSlices   - Number of terrain-following point-cloud slices (-) [0 to 99]
DEFAULT            WrTerrainDT        - Feature 2 sampling period (s); DEFAULT falls back to WrDisDT
SliceName   Offsets(m)     OffsetNormal   SourceType   FileName
(-)         (m,list)       (-,-,-|dflt)   (STL|Point)  (quoted)
"terr"      50 100 150     default        STL          "mountain.stl"       ! sample above the mountain surface on 3 offset sheets
"hub"       0.0            (0 0 1)        Point        "hub_points.txt"     ! single sheet at hub height (offset 0)

Related issue, if one exists

Closes / addresses #2383 (parts pt. 1 = axis-aligned planar sampling, pt. 2 = terrain-following point cloud). The full design plan lives in FF_output_features_plan.md on the branch and cross-references the same issue.

Impacted areas of the software

Area	File(s)	Change
AWAE core	modules/awae/src/AWAE.f90	New: ExtractSliceSub (bounded variant of ExtractSlice), ValidatePlaneSlices, EmitPlaneSlices, ReadSTLFile, ReadPointCloudFile, ValidateTerrainSlices, EmitTerrainSlices. Init calls both Validate* after existing slice validation; End closes both feature's .series sidecars.
AWAE I/O helpers	modules/awae/src/AWAE_IO.f90	New: WriteVTK_PolyData (.vtp), WriteVTK_StructuredGrid_2D (.vts), streaming VTK_Series_Open / _Append / _Close for .series JSON sidecars.
AWAE registry	modules/awae/src/AWAE_Registry.txt	Flat-array fields on InputFileType / ParameterType / MiscVarType for both features (flat rather than array-of-derived-type — see design notes below).
AWAE types (generated)	modules/awae/src/AWAE_Types.f90	Regenerated.
FAST.Farm glue	glue-codes/fast-farm/src/FAST_Farm_IO.f90	New: ReadPlaneSlicesBlock and ReadTerrainSlicesBlock (both use backspace-and-return for missing headers, so pre-existing decks continue to parse unchanged).
Reg-tests	reg_tests/CTestList.cmake	Two new ff_regression entries — LESinflow_ArbSlice and LESinflow_TerrainSlice.
Reg-test decks	reg_tests/r-test submodule bump to 64feb0011	New decks with baselines (see r-test PR below).
Docs	docs/source/user/fast.farm/InputFiles.rst, OutputFiles.rst, ModelGuidance.rst, FutureWork.rst, api_change.rst	New sub-sections describing input syntax, output naming (.Plane.<name>.<t>.vts, .TerrSlice.<name>.<t>.vtp, matching .series sidecars), NaN masking, and the independent sampling-rate story. FutureWork links back to #2383 for the arbitrary-orientation extension.

Additional supporting information

Commit layout on this branch (4 logical commits on top of b/FF_wake_start_noise):

Commit	Subject
12af71a69	FAST.Farm: foundation for terrain-following and axis-aligned planar output
eff99bcdd	FAST.Farm: Feature - axis-aligned planar sampling (NumPlaneSlices)
e7ace15fd	FAST.Farm: Feature - terrain-following point-cloud sampling (NumTerrainSlices)
cdfb61065	FAST.Farm docs: document the new NumPlaneSlices / NumTerrainSlices blocks

Design notes worth calling out at review:

• Flat arrays instead of AWAE_PlaneSliceType/AWAE_TerrainSliceType. An earlier draft used derived types for the per-slice state, but the generated per-element pack/unpack in FAST_Farm_Types.f90 blew past the 7.7 GiB container's memory ceiling during f951 code-gen. The switched design uses PlaneSliceOrigin(3,:) / PlaneSliceExtent1(:) / etc. plus a prefix-sum TerrainSliceOffsetIdx(:) into a packed TerrainSliceOffsetsPacked(:) — the ragged offsets stay ragged without paying the derived-type registry cost.
• Duplicate-emit guard for t = 0. Farm_InitialCO calls AWAE_CalcOutput twice at $t=0$ (once for validation and once for the actual initial output). Both features carry a scalar m%LastPlaneSliceN / m%LastTerrainSliceN initialised to -1; the Emit* routines early-return when m%Last*N == n so the identical .vts/.vtp file isn't rewritten and the .series sidecar doesn't get a duplicate t=0 entry.
• NaN masking for out-of-domain nodes. EmitPlaneSlices pre-fills the write buffer with ieee_value(0.0_SiKi, ieee_quiet_nan), then calls the bounded ExtractSliceSub for only the in-domain window [iLoE, iHiE] × [jLoE, jHiE]. EmitTerrainSlices NaN-fills any point whose $(x, y, z)$ falls outside [oXYZ, oXYZ + (nXYZ-1)·dXYZ]. ParaView masks these automatically.
• Off-axis normals in Feature 1 are a fatal error (per plan §3.7): the message names the offending slice and forward-references the future arbitrary-orientation point-cloud extension (docs/source/user/fast.farm/FutureWork.rst).

Conceptual overlap with the existing AWAE_vtk .vtk.series writer. During the rebase onto b/FF_wake_start_noise (see "Test results" below) it became clear that this branch's AWAE_IO.f90::VTK_Series_Open/_Append/_Close helpers and the base branch's AWAE_vtk.f90::Write_DisWind_Series/Write_WakePlane_Series/Write_WireFrame_Series both emit ParaView .series JSON sidecars, but with materially different flow patterns:

	AWAE_vtk (base branch)	AWAE_IO (this PR)
Trigger	Called once from AWAE_End after the run	Streamed: Open at Init, Append each CalcOutput, Close at End
File extension	.vtk.series (legacy VTK)	.vts.series / .vtp.series (XML VTK)
Requires known step count?	Yes — iterates 0..NumDT/WrDisSkp1	No — accretes as steps happen
Behaviour on abnormal termination	Nothing written	Whatever steps completed are still valid ParaView-loadable

No literal duplicate code and both routines coexist without collision on the merged branch, but a future cleanup PR could consolidate them into a single AWAE_vtk interface (streaming API for both) — kept out of this PR to hold the rebase minimal.

Generative AI usage

Substantial portions of this PR — implementation across all 4 phases, rebase conflict resolution onto b/FF_wake_start_noise, and reg-test deck authoring — were generated with AI assistance. Co-author trailers are on every commit.

Co-authored-by: Anthropic Claude Opus 4.7 claude@anthropic.com
Co-authored-by: Google Gemini 3.5 Flash gemini@google.com
Co-authored-by: GitHub Copilot copilot@github.com

Test results, if applicable

• r-test branch merging required — bumps reg_tests/r-test submodule pointer from 14c0e913e (b/FF_wake_start_noise) to 64feb0011 (r-test f/FF_sliceOutput, 2 commits: 7be23c16e LESinflow_ArbSlice deck + 64feb0011 LESinflow_TerrainSlice deck). See companion r-test PR.

Full FAST.Farm regression suite in build-docker-double (double-precision, AMREX_READER=ON, RelWithDebInfo):

100% tests passed, 0 tests failed out of 9
Total Test time (real) = 126.99 sec

    Start 84: AMReX .................. Passed
    Start 85: TSinflow ............... Passed
    Start 86: LESinflow .............. Passed
    Start 87: LESinflow_ArbSlice ..... Passed   ← Feature 1 deck (new)
    Start 88: LESinflow_TerrainSlice . Passed   ← Feature 2 deck (new)
    Start 89: TSinflow_curl .......... Passed   ← b/'s updated wake-decay baseline still matches
    Start 90: ModAmb_3 ............... Passed
    Start 91: TSinflowADskSED ........ Passed
    Start 92: MD_Shared .............. Passed

Output verification. For each new deck, the per-step .vts/.vtp files were spot-checked by parsing the XML and confirming (a) node coordinates match the input origin + i·d_axis / Pts + Offset·OffsetNormal arithmetic to machine precision, (b) .series sidecars have exactly one entry per CalcOutput invocation with monotonically increasing time, and (c) no duplicate t = 0 entry from the double-call inside Farm_InitialCO.

Merge order

• final release of 5.0.1
• cross merge of 5.0.1 to dev
• perform a check of code redundancy after merging dev to this branch
• merge

[andrew-platt]

Note: as posted there are a lot of merge conflicts. This was developed off of branch b/FF_wake_start_noise which has not been merged to rc-5.0.1 release at the time of posting.

[Copilot]

Pull request overview

This pull request extends FAST.Farm’s visualization/output capabilities by adding new slice-output options (extent-controlled axis-aligned planar sampling and terrain-following point-cloud sampling) with ParaView-friendly XML VTK outputs and streamed .series time-index sidecars, while also updating wake/VTK infrastructure and regression coverage to support and validate the new outputs.

Changes:

• Adds new FAST.Farm VISUALIZATION blocks for NumPlaneSlices and NumTerrainSlices, including parsing, runtime state, and XML VTK output (.vts / .vtp) with streamed .series sidecars.
• Introduces/updates AWAE VTK writer infrastructure (new AWAE_vtk.f90, new XML writers and .series helpers in AWAE_IO.f90, updated generated types/registry).
• Updates FAST.Farm regression test registration and documentation for the new input/output features.

Reviewed changes

Copilot reviewed 20 out of 24 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
vs-build/modules/AWAE.vfproj	Adds AWAE_vtk.f90 to the Visual Fortran project sources.
reg_tests/CTestList.cmake	Registers two new FAST.Farm regression tests for the new slice-output features.
modules/wakedynamics/src/WakeDynamics.f90	Updates wake-plane lifecycle/merging/removal logic and initializes additional state fields.
modules/wakedynamics/src/WakeDynamics_Types.f90	Adds LowResBounds to init/parameter types and updates pack/unpack/copy routines.
modules/wakedynamics/src/WakeDynamics_Registry.txt	Declares LowResBounds in the WakeDynamics registry for code generation.
modules/awae/tests/test_AMReX_reader.f90	Adjusts test scalar kinds/constants for time and grid calculations.
modules/awae/src/AWAE_vtk.f90	Adds AWAE VTK output module (wake plane files + .vtk.series generation).
modules/awae/src/AWAE_Types.f90	Regenerated AWAE types/pack/unpack to include new slice feature fields and updated VTK root naming.
modules/awae/src/AWAE_Registry.txt	Extends AWAE registry with new slice inputs/runtime state and clarifies misc/param field semantics.
modules/awae/src/AWAE_IO.f90	Adds XML VTK writers (.vtp, .vts) and streamed .series helpers; updates disturbed-wind output root naming.
modules/awae/CMakeLists.txt	Adds AWAE_vtk.f90 to the AWAE static library build.
glue-codes/fast-farm/src/FAST_Farm_Subs.f90	Adjusts MaxNumPlanes logic and passes low-res domain bounds into WakeDynamics init input.
glue-codes/fast-farm/src/FAST_Farm_IO.f90	Adds optional parsing blocks for plane slices and terrain slices (backspace-and-return behavior for legacy decks).
docs/source/user/fast.farm/OutputFiles.rst	Documents new .vts/.vtp outputs and .series sidecars for the added slice features.
docs/source/user/fast.farm/ModelGuidance.rst	Adds guidance on choosing between classic slices, extent-controlled planes, and terrain-following point clouds.
docs/source/user/fast.farm/InputFiles.rst	Documents the new VISUALIZATION sub-block grammars and point-cloud file format.
docs/source/user/fast.farm/FutureWork.rst	Notes future extension toward arbitrary-orientation planar sampling.
docs/source/user/api_change.rst	Records the new optional FAST.Farm input blocks as an API/input change.
.gitignore	Ignores common devcontainer/VSCodedocker workspace files.

---

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

[andrew-platt]

Todo (@andrew-platt)

• manually check diffs commit-by-commit for sanity using my knowledge.

[jjonkman]

Thanks for adding these new visualization features! Just a few comments:

• I would think WrPlaneDT and WrTerrainDT should DEFAULT back to DT_Low or DT_Low-VTK, just like WrDisDT does. Basing the DEFAULTs of the new visualization time step outputs on the old WrDisDT is confusing, especially given that I assume you'd want to use one or the other visualization features, not both at the same time.
• For the new plane slices, the normal must be X, Y or Z; would it be better simply to specify that directly, rather than as a normal vector? Or perhaps this is a placeholder for a future generic plane slice? If the normal is kept, must it be normalized to unity or will the normalization be calculated internally?
• For the new plane slices, are you linearly interpolating the data between planes if the selected plane is not aligned with the low-resolution grid? (This is how the existing plane slice visualization works.)
• For the new terrain slices, I'm not sure I understand how the STL option is useful. I would think it would be more useful if the STL file is specified as Z-elevations across an XY plane of points, that is Z = Function(X,Y), and then Z-offsets would be user specified such that the outputs would be located at the set of points defined by Function(X,Y) + Offset. This would make the most sense if you wanted to output a terrain-following flow field rather than an XY slice at a fixed Z elevation. This option wouldn't work if the STL file has mulitple Z-elevations at the same X,Y point, but I doubt we'll consider terrain that complex.