wakemarch 0.1.0__tar.gz

wakemarch-0.1.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.1.0 — 2026-11-02
+
+First public release.
+
+- Single-turbine steady wake model with curled wake shape: the recommended
+  configuration of the authors' research solver (thrust exponent 2, vortex
+  diffusivity factor 0.5, momentum fraction 0.95, near-wake display ramp).
+- `WakeModel`, `Numerics` and `WakeResult`: immutable inputs, explicit deficit
+  and velocity sampling, read-only histories, live progress display.
+- `Turbine`: power/CT and CP/CT tables, three reference presets pinned from
+  FLORIS 4.6.2 (NREL 5 MW, IEA 10 MW, IEA 15 MW), rotor-equivalent operating
+  point. The tabulated speed range is the operating range; table CT ≥ 1 is capped
+  at 0.97 for the wake with a warning. `Turbine.fixed` for constant coefficients.
+- Input limits: H ≥ D/2 and |yaw| ≤ 50° (validated to 40°).
+- Runtime dependencies NumPy ≥ 1.24 and SciPy ≥ 1.10; Python ≥ 3.11.
+- Four example notebooks (API, resolution/cost, turbines, optional public PIV
+  comparison).

wakemarch-0.1.0/CITATION.cff

@@ -0,0 +1,24 @@
+cff-version: 1.2.0
+message: >-
+  If you use WakeMarch, please cite it using these metadata. The paper
+  describing the model will be added here once it has a DOI.
+title: WakeMarch
+abstract: >-
+  Steady cross-plane marching wake model for a single yawed wind turbine with
+  curled wake shape.
+type: software
+authors:
+  - family-names: Bui
+    given-names: Hoang Hai
+    orcid: "https://orcid.org/0000-0003-4485-0325"
+    affiliation: University of Bergen
+version: 0.1.0
+date-released: "2026-11-02"
+license: BSD-3-Clause
+repository-code: "https://github.com/haibuihoang/wakemarch"
+keywords:
+  - wind energy
+  - wake model
+  - yaw
+  - wake steering
+  - curled wake

wakemarch-0.1.0/CITATION.md

@@ -0,0 +1,8 @@
+# Citation
+
+Citation metadata are in [CITATION.cff](CITATION.cff) (GitHub shows a "Cite this
+repository" button for it). The paper describing the model and a software DOI
+will be added there when available.
+
+For reproducibility, also record `wakemarch.__version__`, the Python, NumPy and
+SciPy versions, all physical and numerical inputs, and your sampling definitions.

wakemarch-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, University of Bergen
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

wakemarch-0.1.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include README.md PROVENANCE.md pyproject.toml
+include CITATION.md CITATION.cff CHANGELOG.md LICENSE
+recursive-include docs *.md *.json *.png
+recursive-include tools *.py
+recursive-include examples *.py
+recursive-include examples *.ipynb
+recursive-include tests *.py
+prune examples/.ipynb_checkpoints
+global-exclude .DS_Store
+
+recursive-include src/wakemarch/data *.json *.txt

wakemarch-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.4
+Name: wakemarch
+Version: 0.1.0
+Summary: Cross-plane marching wake model for yawed wind turbines with curled wakes
+Author: Hoang Hai Bui
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/haibuihoang/wakemarch
+Project-URL: Issues, https://github.com/haibuihoang/wakemarch/issues
+Project-URL: Changelog, https://github.com/haibuihoang/wakemarch/blob/main/CHANGELOG.md
+Keywords: wind energy,wake model,yaw,wake steering,curled wake
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: src/wakemarch/data/FLORIS_LICENSE.txt
+Requires-Dist: numpy<3,>=1.24
+Requires-Dist: scipy<2,>=1.10
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.8; extra == "plot"
+Provides-Extra: notebooks
+Requires-Dist: matplotlib>=3.8; extra == "notebooks"
+Requires-Dist: jupyterlab>=4; extra == "notebooks"
+Requires-Dist: ipykernel>=6; extra == "notebooks"
+Requires-Dist: nbclient>=0.10; extra == "notebooks"
+Requires-Dist: nbconvert>=7; extra == "notebooks"
+Provides-Extra: validation
+Requires-Dist: h5py>=3.10; extra == "validation"
+Requires-Dist: netCDF4>=1.6; extra == "validation"
+Dynamic: license-file
+
+# WakeMarch
+
+WakeMarch is a steady, cross-plane marching wake model for a single yawed wind
+turbine. It resolves the curled (kidney-shaped) wake produced by the
+counter-rotating streamwise vortex pair of a yawed rotor, in uniform or
+power-law-sheared inflow, and returns the wake deficit, streamwise vorticity and
+velocity anywhere downstream.
+
+The core depends only on NumPy (≥ 1.24) and SciPy (≥ 1.10) and needs
+Python 3.11 or later. The upper bounds `<3`/`<2` are compatibility boundaries,
+not evidence of tests on every release.
+
+![WakeMarch hub-height and cross-plane wake](https://raw.githubusercontent.com/haibuihoang/wakemarch/main/docs/images/wake.png)
+
+Start with the [user guide](https://github.com/haibuihoang/wakemarch/blob/main/docs/USER_GUIDE.md), then the
+[API notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_api_test.ipynb) and
+[resolution/cost notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_performance.ipynb).
+[Turbine curves and presets](https://github.com/haibuihoang/wakemarch/blob/main/docs/TURBINES.md) and an
+[interactive turbine notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_turbines.ipynb) accept user CP/CT
+or power/CT tables, including rotor-wide velocity samples.
+An optional [PIV comparison](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_piv_validation.ipynb) uses a
+separately downloaded public dataset and discloses inherited calibration.
+Read [scientific scope](https://github.com/haibuihoang/wakemarch/blob/main/docs/SCIENCE.md) and [citation](https://github.com/haibuihoang/wakemarch/blob/main/CITATION.md) before
+using results in research. The figure is generated by `examples/plot_wake.py`.
+
+## Install and run
+
+```sh
+python -m pip install wakemarch
+```
+
+Or, from a source checkout (the directory containing `pyproject.toml`):
+
+```sh
+python -m pip install .
+python -I examples/first_wake.py
+python -I tests/test_api.py
+```
+
+### Jupyter notebooks
+
+The interactive entry point is `examples/wakemarch_api_test.ipynb`. It contains
+editable inputs, live progress, hub-height/cross-plane plots, yaw comparisons,
+and executable API checks. Run every cell with a fresh kernel.
+
+```sh
+python -m pip install 'wakemarch[notebooks]'      # or '.[notebooks]' from source
+python -m jupyterlab examples/wakemarch_api_test.ipynb
+```
+
+No measurement data, FLORIS, plotting or Jupyter are needed for the core example
+or tests. For verifying built artifacts, see [release checks](https://github.com/haibuihoang/wakemarch/blob/main/docs/RELEASING.md).
+
+```python
+from wakemarch import Numerics, WakeModel
+
+model = WakeModel(
+    D=126, H=90, U=8, CT=0.8, yaw_deg=25, TI=0.06,
+    numerics=Numerics(h_D=1 / 20),
+)
+result = model.solve(max_dist_D=10)
+deficit = result.sample_deficit(x=5 * 126, y=0, z=90)
+velocity = result.sample_streamwise_velocity(x=5 * 126, y=0, z=90)
+print(deficit, velocity)  # m/s
+```
+
+Progress is enabled by default. Jupyter uses a native HTML progress bar (no widget
+extension needed); terminals use a text bar. `model.solve(progress=False)` is
+silent. A callable such as `progress=lambda completed_D, total_D: ...` receives
+an initial zero and updates after each marching step. Total distance includes
+the reconstruction buffer. The display closes on success, errors and interrupts;
+callback exceptions propagate. Progress observes the solve without changing its
+numerical operations. It measures downstream advancement, not a guaranteed time
+remaining estimate.
+
+## Define turbine performance once
+
+```python
+from wakemarch import Turbine, Numerics
+
+turbine = Turbine.preset("nrel_5MW")
+point = turbine.operating_point([6.0, 10.0], yaw_deg=20)
+print(point.power_W, point.CT)
+model = turbine.wake_model([6.0, 10.0], yaw_deg=20, TI=0.1,
+                           numerics=Numerics(h_D=0.1))
+```
+
+Use `Turbine.from_cp_ct(...)` or `Turbine.from_power_ct(...)` for your own curves,
+or `Turbine.fixed(...)` for constant coefficients. See
+[units, efficiency, averaging and table limits](https://github.com/haibuihoang/wakemarch/blob/main/docs/TURBINES.md). The scalar-CT
+`WakeModel` API does not require a power curve.
+
+## Conventions and API
+
+- Physical inputs: `D`, `H` in metres (H ≥ D/2); `U` in m/s; `CT` is the
+  **unyawed** thrust coefficient; `TI` is a fraction, e.g. 0.06, not 6; yaw is in
+  degrees, |yaw| ≤ 50 (validated to 40).
+- Positive yaw deflects towards negative `y`. `x` is downstream from the turbine,
+  `y` is lateral from its centre, and sampled `z` is height above ground.
+- `Numerics` groups grid and stepping choices. Defaults are grid D/30, lateral
+  width 8D, top 3.5D **above hub**, dx=0.1D, requested storage interval=0.25D.
+  There is no automatic coarsening. Ground and open boundaries are enabled.
+- `WakeModel` uses the recommended thrust exponent 2, vortex diffusivity factor
+  0.5, momentum fraction 0.95, and near-wake display ramp (0.5, 1D). Historical
+  empirical additions are not exposed in the public API.
+- `solve()` returns an independent `WakeResult`; solving again never changes a
+  previous result. Inputs/settings are immutable dataclasses.
+- Sampling accepts scalars or broadcastable arrays. `sample_deficit` includes
+  reconstruction and the display ramp; `sample_streamwise_velocity` subtracts
+  this from the same power-law background used by the model.
+- Upstream of the tilted rotor (`x + y*tan(yaw) < 0`), deficit is zero. Outside
+  downstream stored support the default is an error. `bounds="zero"` explicitly
+  requests a zero-deficit extension (background streamwise velocity).
+  Nonfinite coordinates and negative heights raise errors.
+- `result.x` is the stored **marching** coordinate x_s, not global x on a yawed
+  cross-plane. `result.z` is absolute height; `z_relative` is relative to hub.
+  `marching_deficit`, `streamwise_vorticity`, and
+  `streamwise_velocity_derivative` have axes `(x_s, z_relative, y)` and units m/s,
+  1/s and 1/s. They are read-only views; the histories do not include the display
+  ramp. Use the sampling methods for physical-space visualizations.
+
+The kernel marches an extra yaw-dependent distance for reconstruction. With
+dx=0.1D, requested storage 0.25D stores at 0.3D spacing (storage happens on
+marching steps). Sampling uses actual stored support, not the nominal requested
+distance.
+
+## Scientific scope
+
+This is a steady engineering model of one turbine in uniform or power-law-sheared
+inflow, not an active downstream-turbine or farm solver. Input bounds are numerical
+guards, not claims of validation over their entire range. It does not resolve
+ground-boundary-layer dynamics or wake pressure gradients. It has known near-wake,
+high-TI and high-yaw/far-wake limitations.
+
+The vorticity advection construction is approximately conservative; the full
+variable-coefficient diffusion equation does not establish exact circulation
+conservation. Force-based initialization does not imply exact agreement of the
+discrete vortex integral with its target. Better empirical predictions are not
+proof of exact force or conservation consistency. Validation evidence is in the
+accompanying paper; installing the package does not add new observational
+validation.
+
+Optional dependency groups: `[plot]`, `[notebooks]`, `[validation]`. They are
+conveniences for documentation and data workflows, not required by the core.
+Measurement and simulation datasets are not distributed with the package; each
+keeps its own licence and access terms.
+
+## Development and provenance
+
+See [provenance](https://github.com/haibuihoang/wakemarch/blob/main/PROVENANCE.md). `wakemarch._kernel` is private; its many
+historical research switches are not a supported public interface. The package
+reproduces eight frozen reference cases of the authors' research solver to
+rtol=1e-7, atol=1e-8 (`tools/check_release.py` runs the portable checks).
+
+## Licence
+
+BSD 3-Clause; see [LICENSE](https://github.com/haibuihoang/wakemarch/blob/main/LICENSE). The bundled reference turbine tables come
+from FLORIS 4.6.2 and keep their own BSD 3-Clause licence
+(`src/wakemarch/data/FLORIS_LICENSE.txt`).

wakemarch-0.1.0/PROVENANCE.md

@@ -0,0 +1,40 @@
+# Provenance
+
+WakeMarch packages the recommended configuration
+(`YawedWakeSolver.recommended(...)`) of the authors' research solver
+`src/curl_pns.py`, SHA-256
+`f3dce8e95c77942caf59c8a0745d9ff6d2f9ed4ab642062cec46e752856a33fc`
+(research repository commit `3027932`). The solver is project research code,
+not the official implementation of any comparison model.
+
+## Kernel
+
+`src/wakemarch/_kernel.py` is a copy of that solver with:
+
+- explanatory comments and an optional progress observer;
+- caching of fixed advection and multipole geometry;
+- reuse of the exact variable-coefficient diffusion factorization as the next
+  preconditioner after a stalled refinement.
+
+The discrete operators, residual threshold (1e-9), precision, grid, physics and
+fitted constants are unchanged. Iteration paths can differ, so equality is
+checked numerically, not textually: the installed package reproduces eight
+frozen reference cases of the research solver (zero, positive, negative and
+40° yaw; shear; low/high turbulence; coarse and fine grids) at rtol=1e-7,
+atol=1e-8. This holds from NumPy 1.24.4/SciPy 1.10.1 to NumPy 2.4/SciPy 1.17.
+The reference arrays are kept with the authors' development records and are not
+shipped.
+
+## Added code
+
+- The public API (`WakeModel`, `Numerics`, `WakeResult`), input checks,
+  explicitly named sampling methods and tests. No change to model equations or
+  fitted constants.
+- `Turbine` (power/CT and CP/CT tables, presets, rotor-equivalent operating
+  point) and `Turbine.fixed` (constant coefficients). Three reference tables are
+  pinned from FLORIS 4.6.2 with their source hashes and licence
+  (`src/wakemarch/data/`).
+
+An independently developed set of additional wake corrections was evaluated and
+not adopted; it is not part of the package. Packaging does not establish new
+scientific claims; see [scientific scope](docs/SCIENCE.md).

wakemarch-0.1.0/README.md

@@ -0,0 +1,159 @@
+# WakeMarch
+
+WakeMarch is a steady, cross-plane marching wake model for a single yawed wind
+turbine. It resolves the curled (kidney-shaped) wake produced by the
+counter-rotating streamwise vortex pair of a yawed rotor, in uniform or
+power-law-sheared inflow, and returns the wake deficit, streamwise vorticity and
+velocity anywhere downstream.
+
+The core depends only on NumPy (≥ 1.24) and SciPy (≥ 1.10) and needs
+Python 3.11 or later. The upper bounds `<3`/`<2` are compatibility boundaries,
+not evidence of tests on every release.
+
+![WakeMarch hub-height and cross-plane wake](https://raw.githubusercontent.com/haibuihoang/wakemarch/main/docs/images/wake.png)
+
+Start with the [user guide](https://github.com/haibuihoang/wakemarch/blob/main/docs/USER_GUIDE.md), then the
+[API notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_api_test.ipynb) and
+[resolution/cost notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_performance.ipynb).
+[Turbine curves and presets](https://github.com/haibuihoang/wakemarch/blob/main/docs/TURBINES.md) and an
+[interactive turbine notebook](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_turbines.ipynb) accept user CP/CT
+or power/CT tables, including rotor-wide velocity samples.
+An optional [PIV comparison](https://github.com/haibuihoang/wakemarch/blob/main/examples/wakemarch_piv_validation.ipynb) uses a
+separately downloaded public dataset and discloses inherited calibration.
+Read [scientific scope](https://github.com/haibuihoang/wakemarch/blob/main/docs/SCIENCE.md) and [citation](https://github.com/haibuihoang/wakemarch/blob/main/CITATION.md) before
+using results in research. The figure is generated by `examples/plot_wake.py`.
+
+## Install and run
+
+```sh
+python -m pip install wakemarch
+```
+
+Or, from a source checkout (the directory containing `pyproject.toml`):
+
+```sh
+python -m pip install .
+python -I examples/first_wake.py
+python -I tests/test_api.py
+```
+
+### Jupyter notebooks
+
+The interactive entry point is `examples/wakemarch_api_test.ipynb`. It contains
+editable inputs, live progress, hub-height/cross-plane plots, yaw comparisons,
+and executable API checks. Run every cell with a fresh kernel.
+
+```sh
+python -m pip install 'wakemarch[notebooks]'      # or '.[notebooks]' from source
+python -m jupyterlab examples/wakemarch_api_test.ipynb
+```
+
+No measurement data, FLORIS, plotting or Jupyter are needed for the core example
+or tests. For verifying built artifacts, see [release checks](https://github.com/haibuihoang/wakemarch/blob/main/docs/RELEASING.md).
+
+```python
+from wakemarch import Numerics, WakeModel
+
+model = WakeModel(
+    D=126, H=90, U=8, CT=0.8, yaw_deg=25, TI=0.06,
+    numerics=Numerics(h_D=1 / 20),
+)
+result = model.solve(max_dist_D=10)
+deficit = result.sample_deficit(x=5 * 126, y=0, z=90)
+velocity = result.sample_streamwise_velocity(x=5 * 126, y=0, z=90)
+print(deficit, velocity)  # m/s
+```
+
+Progress is enabled by default. Jupyter uses a native HTML progress bar (no widget
+extension needed); terminals use a text bar. `model.solve(progress=False)` is
+silent. A callable such as `progress=lambda completed_D, total_D: ...` receives
+an initial zero and updates after each marching step. Total distance includes
+the reconstruction buffer. The display closes on success, errors and interrupts;
+callback exceptions propagate. Progress observes the solve without changing its
+numerical operations. It measures downstream advancement, not a guaranteed time
+remaining estimate.
+
+## Define turbine performance once
+
+```python
+from wakemarch import Turbine, Numerics
+
+turbine = Turbine.preset("nrel_5MW")
+point = turbine.operating_point([6.0, 10.0], yaw_deg=20)
+print(point.power_W, point.CT)
+model = turbine.wake_model([6.0, 10.0], yaw_deg=20, TI=0.1,
+                           numerics=Numerics(h_D=0.1))
+```
+
+Use `Turbine.from_cp_ct(...)` or `Turbine.from_power_ct(...)` for your own curves,
+or `Turbine.fixed(...)` for constant coefficients. See
+[units, efficiency, averaging and table limits](https://github.com/haibuihoang/wakemarch/blob/main/docs/TURBINES.md). The scalar-CT
+`WakeModel` API does not require a power curve.
+
+## Conventions and API
+
+- Physical inputs: `D`, `H` in metres (H ≥ D/2); `U` in m/s; `CT` is the
+  **unyawed** thrust coefficient; `TI` is a fraction, e.g. 0.06, not 6; yaw is in
+  degrees, |yaw| ≤ 50 (validated to 40).
+- Positive yaw deflects towards negative `y`. `x` is downstream from the turbine,
+  `y` is lateral from its centre, and sampled `z` is height above ground.
+- `Numerics` groups grid and stepping choices. Defaults are grid D/30, lateral
+  width 8D, top 3.5D **above hub**, dx=0.1D, requested storage interval=0.25D.
+  There is no automatic coarsening. Ground and open boundaries are enabled.
+- `WakeModel` uses the recommended thrust exponent 2, vortex diffusivity factor
+  0.5, momentum fraction 0.95, and near-wake display ramp (0.5, 1D). Historical
+  empirical additions are not exposed in the public API.
+- `solve()` returns an independent `WakeResult`; solving again never changes a
+  previous result. Inputs/settings are immutable dataclasses.
+- Sampling accepts scalars or broadcastable arrays. `sample_deficit` includes
+  reconstruction and the display ramp; `sample_streamwise_velocity` subtracts
+  this from the same power-law background used by the model.
+- Upstream of the tilted rotor (`x + y*tan(yaw) < 0`), deficit is zero. Outside
+  downstream stored support the default is an error. `bounds="zero"` explicitly
+  requests a zero-deficit extension (background streamwise velocity).
+  Nonfinite coordinates and negative heights raise errors.
+- `result.x` is the stored **marching** coordinate x_s, not global x on a yawed
+  cross-plane. `result.z` is absolute height; `z_relative` is relative to hub.
+  `marching_deficit`, `streamwise_vorticity`, and
+  `streamwise_velocity_derivative` have axes `(x_s, z_relative, y)` and units m/s,
+  1/s and 1/s. They are read-only views; the histories do not include the display
+  ramp. Use the sampling methods for physical-space visualizations.
+
+The kernel marches an extra yaw-dependent distance for reconstruction. With
+dx=0.1D, requested storage 0.25D stores at 0.3D spacing (storage happens on
+marching steps). Sampling uses actual stored support, not the nominal requested
+distance.
+
+## Scientific scope
+
+This is a steady engineering model of one turbine in uniform or power-law-sheared
+inflow, not an active downstream-turbine or farm solver. Input bounds are numerical
+guards, not claims of validation over their entire range. It does not resolve
+ground-boundary-layer dynamics or wake pressure gradients. It has known near-wake,
+high-TI and high-yaw/far-wake limitations.
+
+The vorticity advection construction is approximately conservative; the full
+variable-coefficient diffusion equation does not establish exact circulation
+conservation. Force-based initialization does not imply exact agreement of the
+discrete vortex integral with its target. Better empirical predictions are not
+proof of exact force or conservation consistency. Validation evidence is in the
+accompanying paper; installing the package does not add new observational
+validation.
+
+Optional dependency groups: `[plot]`, `[notebooks]`, `[validation]`. They are
+conveniences for documentation and data workflows, not required by the core.
+Measurement and simulation datasets are not distributed with the package; each
+keeps its own licence and access terms.
+
+## Development and provenance
+
+See [provenance](https://github.com/haibuihoang/wakemarch/blob/main/PROVENANCE.md). `wakemarch._kernel` is private; its many
+historical research switches are not a supported public interface. The package
+reproduces eight frozen reference cases of the authors' research solver to
+rtol=1e-7, atol=1e-8 (`tools/check_release.py` runs the portable checks).
+
+## Licence
+
+BSD 3-Clause; see [LICENSE](https://github.com/haibuihoang/wakemarch/blob/main/LICENSE). The bundled reference turbine tables come
+from FLORIS 4.6.2 and keep their own BSD 3-Clause licence
+(`src/wakemarch/data/FLORIS_LICENSE.txt`).

wakemarch-0.1.0/docs/RELEASING.md

@@ -0,0 +1,77 @@
+# Development and release verification
+
+## Portable checks
+
+From the package root, in an environment with Python 3.11+ and setuptools/wheel:
+
+```sh
+python -m pip install 'setuptools>=77' wheel
+python -I -B tools/check_release.py --output /tmp/wakemarch-check --notebooks
+```
+
+Use any new writable output directory on Windows instead of `/tmp/...`. The
+driver builds a wheel and sdist, creates fresh isolated environments, resolves
+dependencies, checks import origins, runs `pip check`, tests, the example and
+executable documentation. It checks the built source contains the guide and
+notebooks. `--notebooks` adds figure generation and fresh-kernel execution from
+the extracted source using the installed wheel. Outputs and logs stay outside
+the source tree. `--minimum` pins the declared floors, NumPy 1.24.4 and
+SciPy 1.10.1.
+
+For an offline local check only:
+
+```sh
+python -I -B tools/check_release.py --offline --notebooks --output /tmp/wakemarch-offline
+```
+
+This mode inherits local numerical/notebook/build dependencies; it is **not**
+fresh dependency resolution. Its result records `isolated_dependencies=false`.
+The authors additionally compare every release with eight frozen reference
+cases of the research solver at rtol=1e-7, atol=1e-8; those reference arrays are
+not shipped.
+
+## Continuous integration
+
+`.github/workflows/package.yml` runs wheel/sdist checks on Linux, macOS and
+Windows with Python 3.11–3.14, plus a Linux Python 3.11 minimum-dependency job.
+The Linux Python 3.11 job also executes the data-free notebooks. Dependency
+upper bounds are not evidence of compatibility with every future version.
+The workflow has read-only repository access.
+
+## Publishing
+
+`.github/workflows/publish.yml` builds the distributions and uploads them with
+PyPI trusted publishing (no API tokens): manually to TestPyPI
+(`workflow_dispatch`, target `testpypi`) or to PyPI when a GitHub release is
+published. The trusted publisher must be configured on (Test)PyPI for this
+repository, workflow `publish.yml` and environments `testpypi`/`pypi`.
+The workflow refuses to run while any release file still contains the marker
+`PENDING-D2` (author/copyright metadata not yet supplied) or the classifier
+`Private :: Do Not Upload`.
+
+Release steps: update `version`, `CHANGELOG.md` and `CITATION.cff`; run the
+portable checks (normal, `--minimum`, `--notebooks`); confirm CI is green;
+rehearse on TestPyPI; then publish a GitHub release.
+
+This follows the [GitHub Python CI guide](https://docs.github.com/en/actions/tutorials/build-and-test-code/python),
+the [PyPA packaging guide](https://packaging.python.org/en/latest/tutorials/packaging-projects/)
+and [PyPA trusted publishing](https://docs.pypi.org/trusted-publishers/).
+
+## Paper reproducibility
+
+The paper's figures were produced with the authors' research solver. Record the
+package version used for any figure only after reproducing it with that version.
+`docs/release-metadata.json` records licence, repository and DOI metadata.
+
+## Notebooks
+
+To run all four notebooks with a registered local kernel and an existing
+download of the PIV data (no automatic data access):
+
+```sh
+python -I -B tools/run_notebooks.py --output /tmp/wakemarch-notebooks --piv-data /path/to/Bastankhah_jfm_2016.h5
+```
+
+The CI notebook job executes only the three data-free examples. The PIV notebook
+is checked locally against the checksum-pinned public file; this does not create
+a redistributable data fixture or a blind-validation claim.

wakemarch-0.1.0/docs/SCIENCE.md

@@ -0,0 +1,74 @@
+# Scientific scope and evidence
+
+WakeMarch implements the accepted recommended single-turbine model: thrust
+exponent 2, vortex diffusivity factor 0.5, momentum fraction 0.95, and display
+ramp (0.5, 1D). The package does not expose historical optional empirical
+corrections as supported public settings. The combined independent-correction
+experiment remains archived and is not the production model.
+
+The intended first audience is researchers. The model has known near-wake,
+high-turbulence and high-yaw/far-wake limitations. It does not resolve wake
+pressure gradients or ground-boundary-layer dynamics. Input guards are not an
+experimental validation envelope. Engineering and operational use requires
+application-specific assessment; no farm solver or active downstream-turbine
+model is provided.
+
+Advection is approximately conservative; variable-coefficient diffusion does not
+establish exact circulation conservation. Force-based initialization does not
+guarantee exact equality of the discrete vortex integral and its target. Better
+empirical predictions are not proof of exact conservation or force consistency.
+
+## What the software checks establish
+
+- API tests: input conventions, sampling, progress, independent results and
+  diffusion residual checks.
+- Frozen-array comparisons: implementation agreement with eight accepted
+  research cases at rtol=1e-7, atol=1e-8. These are not observational error bars.
+- Grid notebook: differences between numerical resolutions for a specified case.
+  Its finest grid is a reference, not a converged solution or observation.
+- Historical numerical tests: manufactured operators, symmetry and approximate
+  invariants, subject to their stated tolerances.
+- Historical measurement comparisons: scientific evidence with calibration and
+  preprocessing choices described in the research reports, not recreated by a
+  successful package installation.
+
+## Data and validation boundary
+
+The accompanying paper compares the model with PALM LES, hub-height PIV,
+Oldenburg lidar and NTNU/ForWind LDA data. The LES data used in the paper are not
+distributed with this package. Other datasets have their own access and license
+terms; a code license cannot grant redistribution rights to them. No measurement
+files are included in the wheel or source distribution.
+
+The optional [PIV measurement notebook](../examples/wakemarch_piv_validation.ipynb)
+uses [Bastankhah and Porté-Agel's Zenodo v1 dataset](https://zenodo.org/records/3607598),
+DOI 10.5281/zenodo.3607598. Obtain the HDF5 file separately and inspect its terms;
+the notebook checks the record's MD5 and records SHA-256. No data are bundled.
+It inherits the historical unyawed CT=0.9 and k=0.024 calibration, converts k to
+equivalent TI and performs no new fit. These cases were previously examined
+during model development: this is not a new blind test. Its same-point RMS
+comparison differs from historical scoreboard preprocessing and metrics.
+Do not label the introductory or grid notebooks as measurement validation.
+Record geometry, inflow/CT values, yaw sign and coordinate mapping, uncertainty
+and calibration exposure. Evaluate model and data on the same measurement support.
+For tower/floor-contaminated laboratory planes, document the rotor-band mask.
+
+Do not silently substitute synthetic data when measurements are missing. Farm
+validation additionally requires turbine interaction, local inflow and thrust
+definitions; the single-wake downstream rotor u³ proxy is insufficient.
+
+## Paper linkage
+
+`release-metadata.json` records publication metadata. The paper's figures were
+produced with the authors' research solver, which this package reproduces to
+rtol=1e-7 on eight reference cases; the paper-specific software version is
+recorded once figure reproduction with the package has been verified. Until the
+paper reference is available, see [citation](../CITATION.md).
+
+## Reference turbine performance inputs
+
+The package now includes reference power/CT tables and a rotor-equivalent
+operating model; see [TURBINES.md](TURBINES.md). This adds no farm validation or
+new wake physics. CP converted from the power tables is electrical-equivalent.
+User CP inputs require an explicit efficiency convention. Effective-speed yaw
+power mapping is an approximation, not a controller simulation.