Code from other projects

GUST copies some ERF files rather than linking ERF, uses AMReX and GoogleTest as libraries, and re-implements methods from FastWindTerrain. This page lists what comes from where and how copies are kept honest.

The extraction manifest

Every file copied from ERF lives under extern_erf/ and has one row in extern_erf/EXTRACTED.md: the local file, its ERF source path, the ERF commit it was copied from, its status, and notes.

  • Status unchanged: the local file is byte-identical to the ERF source at that commit.

  • Status modified: the local changes are recorded in extern_erf/patches/<file>.patch, a unified diff from the ERF file to the local file.

Copied: the mesh and terrain-metric code (ERF_GridUtils.H, ERF_TerrainMetrics.{H,cpp}, ERF_ChopGrids.cpp and the small headers they include), ERF’s Python plotfile reader for the check scripts, and the Askervein terrain file. ERF_TerrainMetrics.{H,cpp} are modified: the coordinate builders take the smoothing choice and \(\gamma_m\) as arguments instead of reading ERF’s inputs, return the number of STF levels capped, and lose the refined-level (AMR) paths, which GUST does not use. BTF no longer rewrites the ground layer: ERF writes \(h\,z_\mathrm{top}/z_\mathrm{top}\) there (within 1 ulp of \(h\)) while other GPU threads read the same nodes, so the result depended on thread order. Its ghost columns outside non-periodic sides take the clamped domain node’s height there instead (ERF’s builder first sets every node outside the domain to bogus_large_value; skipping the whole ground layer, as the first version of this change did, left those nodes at 1e150 and the extrapolation below the ground at 2e150, which a Dirichlet-ground solve read).

erf_plotfile.py is modified (follow-up of #43): it takes a FAB’s size and byte order from the byte-order descriptor, one entry per byte, and refuses any descriptor other than a plain little- or big-endian float or double. The upstream reader takes the floating-point format’s field count as the size, which is 8 for float data too, so it read single-precision plotfiles as byte-swapped doubles.

Copied unchanged for the Poisson solve: ERF’s terrain Poisson operator (ERF_TerrainPoisson.{H,cpp}, ERF_TerrainPoisson_3D_K.H) and ERF_SolverUtils.H, whose get_fft_bc maps the domain boundary names to the FFT preconditioner’s boundaries (Outflow/Open: odd, periodic: periodic, any other name: even). The copy includes the zero total flux through Neumann faces, terrain cross term included (ERF#4272, merged as ERF#4279). ERF_SolveWithGMRES.cpp is an ERF member function and is not copied; Source/Poisson.cpp drives GMRES the same way (Solution algorithm). Two shim headers in Source/erf_shims/ stand in for ERF headers the copies include.

Copied unchanged for the surface layer: ERF_MOSTUtils.H, whose similarity_funs give the surface layer’s stability functions (Boundary conditions). ERF’s MOST kernels (ERF_MOSTStress.H, ERF_MOSTAverage.cpp) are not copied: they are tied to ERF’s state layout and plane averaging, and Source/SurfaceLayer.cpp follows their formulas per column. The reference-height lookup fix ERF#3982 is already in the pinned ERF.

Copied unchanged for the forest canopy: ERF_ForestUtils.H, whose validate_laimax checks canopy.laimax and the laimax of type 2 lines in canopy.file (Forest canopy). ERF’s ERF_ForestDrag.cpp is not copied: it reads NetCDF and samples the profile at the cell centre, while Source/Canopy.cpp reads point files and takes the profile’s mean over each cell (Forest canopy).

The drift check

tools/check_extern_erf.py --erf <ERF clone> fails when:

  • an unchanged file differs from its ERF source;

  • a modified file has no patch, or its patch no longer matches the local changes;

  • a file under extern_erf/ (other than EXTRACTED.md, LICENSE.md and patches/) has no row, or a row names a missing file;

  • the manifest table lacks its header row.

With --report-upstream <ref> it also lists the ERF commits that touched each copied file after its pinned commit. That list is a report: upstream fixes (for example ERF#4272 and ERF#4279) are reviewed and copied over deliberately, not automatically. CI runs the check on every pull request.

Licences and attribution

Project

How GUST uses it

Licence and what it requires

ERF

Copied files in extern_erf/; Tests/Unit_Tests/Gold/erf_hill2d_* are ERF outputs at the pinned commit.

BSD-style licence with the LBNL “Enhancements” clause (ERF LICENSE.md). Redistributed source must keep ERF’s copyright notice, conditions and disclaimer: ERF’s LICENSE.md is copied into extern_erf/ with the first copied file, and copied files keep their headers.

AMReX

Git submodule, built as a library.

BSD-style licence (external/amrex/LICENSE), kept with the submodule.

GoogleTest

Git submodule, used by the tests only.

BSD 3-Clause (external/googletest/LICENSE), kept with the submodule.

FastWindTerrain

Method knowledge only (mass-consistent solve, anisotropy, inflow profiles, O’Brien correction), re-implemented. No code is copied.

—

Kynema-SGF (formerly AMR-Wind)

Cross-check of the Axell–Liungman closure in unit tests. No code is copied.

—

GUST itself is distributed under the BSD 2-Clause licence (LICENSE).