Merge pull request #4 from SMI-Lab-Inha/academic-polish

Academic polish: docs encoding, provenance, validation framing, supply-chain hardening

Author: SMI-Lab-Inha

.github/dependabot.yml

@@ -0,0 +1,15 @@
+version: 2
+updates:
+  # Python dependencies declared in pyproject.toml (runtime + extras).
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  # GitHub Actions used by the workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

.github/workflows/ci.yml

@@ -68,6 +68,30 @@ jobs:
       - name: Run tests with coverage gate
         run: pytest --cov=pyiecwind --cov-report=term-missing
 
+  audit:
+    name: Dependency audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install package and pip-audit
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e . pip-audit
+
+      - name: Audit dependencies for known vulnerabilities
+        # Skip the local (editable) pyiecwind package, which is not on PyPI and
+        # cannot be audited. --strict is intentionally omitted so the skipped
+        # local package is not itself treated as a failure; pip-audit still exits
+        # non-zero when a real vulnerability is found in a dependency.
+        run: pip-audit --skip-editable
+
   docs:
     name: Build documentation
     needs: lint

.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed, with build provenance
+# attestation. Requires a one-time setup on PyPI: configure a Trusted Publisher
+# for this project pointing at this repository and the "release.yml" workflow
+# (https://docs.pypi.org/trusted-publishers/). No API token is stored.
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    name: Build, attest, and publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write       # OIDC: trusted publishing + attestation signing
+      attestations: write   # build provenance attestation
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          twine check dist/*
+
+      - name: Attest build provenance
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-path: "dist/*"
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1

CITATION.cff

@@ -0,0 +1,29 @@
+cff-version: 1.2.0
+message: "If you use this software, please cite it as below."
+title: "pyIECWind: IEC 61400-1 wind-condition file generation for OpenFAST InflowWind"
+abstract: >-
+  pyIECWind generates IEC 61400-1 wind-condition (.wnd) files for the OpenFAST
+  InflowWind module, implementing the wind-condition models historically provided
+  by NREL IECWind behind a typed, validated, and regression-locked Python API and
+  command-line interface.
+type: software
+authors:
+  - family-names: Seo
+    given-names: Jae Hoon
+    affiliation: "SMI Lab, Inha University"
+    # orcid: "https://orcid.org/0000-0000-0000-0000"  # add when available
+version: "0.1.0"
+date-released: "2026-05-22"
+license: MIT
+repository-code: "https://github.com/SMI-Lab-Inha/pyIECWind"
+url: "https://github.com/SMI-Lab-Inha/pyIECWind"
+keywords:
+  - wind energy
+  - wind turbine
+  - IEC 61400-1
+  - IECWind
+  - OpenFAST
+  - InflowWind
+# identifiers:
+#   - type: doi
+#     value: "10.5281/zenodo.XXXXXXX"  # add a Zenodo DOI after archiving a release

README.md

@@ -7,76 +7,97 @@
 ![OpenFAST](https://img.shields.io/badge/OpenFAST-InflowWind-0A7E8C)
 
 `pyIECWind` generates IEC 61400-1 wind-condition `.wnd` files for the OpenFAST
-*InflowWind* module. It reproduces the wind-condition models of the legacy NREL
-*IECWind* tool behind a typed, validated Python API, a reproducible command-line
-interface, and a regression-locked test suite.
-
-The six classical condition families — `ECD`, `EWS`, `EOG`, `EDC`, `NWP`, and
-`EWM` — are supported across SI and English unit systems and IEC 61400-1
-Editions 1 and 3. See [Scope and limitations](docs/limitations.rst) for the
-precise boundary of what is implemented.
-
-## Highlights
-
-- **Validated inputs.** `IECParameters` is frozen and validated on construction;
-  invalid turbine definitions fail immediately rather than producing misleading
-  files.
-- **Fail-closed generation.** The batch API raises on the first invalid condition
-  by default; partial output is opt-in.
-- **Verified output.** A committed golden `.wnd` corpus and an independent oracle
-  derived from the IEC equations lock numeric results
-  ([Validation](docs/validation.rst)).
-- **Three input formats.** An OpenFAST-style table (recommended), a keyed format,
-  and the legacy positional layout ([Input files](docs/data_sources.rst)).
-- **Typed and documented.** `mypy --strict`, NumPy-style docstrings, and a Sphinx
-  documentation set.
+*InflowWind* module. It implements the IEC 61400-1 wind-condition models
+historically provided by NREL's *IECWind* tool, behind a typed, validated, and
+regression-locked Python API and command-line interface.
+
+It targets compatibility with selected legacy *IECWind*-style workflows. It has
+**not** been validated byte-for-byte against NREL *IECWind* output; see
+[Validation](#validation) for the exact strength of the current evidence.
 
 ## Installation
 
 ```bash
 python -m pip install pyiecwind
 ```
 
-For a conda environment or a source/development install, see
-[Installation](docs/installation.rst).
+Conda and source/development installs are described in
+[docs/installation.rst](docs/installation.rst).
 
 ## Usage
 
-Generate wind files from an input file:
+Command line:
 
 ```bash
-pyiecwind run examples/sample_case.ipt -o outputs
+pyiecwind run examples/sample_case.ipt -o outputs   # generate from an input file
+pyiecwind template my_case.ipt                       # write a starter template
+pyiecwind wizard -o outputs                          # guided, interactive build
 ```
 
-Write a starter template, or use the guided wizard:
+Python API:
 
-```bash
-pyiecwind template my_case.ipt
-pyiecwind wizard -o outputs
+```python
+from pyiecwind import IECParameters, generate_all
+
+params = IECParameters(
+    si_unit=True, t1=40.0, wtc=2, catg="B", slope_deg=0.0, iec_edition=3,
+    hh=80.0, dia=80.0, vin=4.0, vrated=10.0, vout=24.0,
+    conditions=("ECD+R", "EWSV+12.0", "EWM50"),
+)
+result = generate_all(params, output_dir="outputs")
+print(result.count)
 ```
 
-From Python:
+`IECParameters` validates on construction and is immutable; `generate_all` fails
+closed (raises on the first invalid condition) unless `strict=False`.
 
-```python
-from pyiecwind import generate_from_input_file
+## Supported scope
 
-params, result = generate_from_input_file("examples/sample_case.ipt", output_dir="outputs")
-print(f"generated {result.count} files")
-```
+| Aspect | Supported |
+| --- | --- |
+| IEC 61400-1 edition | Editions 1 and 3 (power-law shear exponent alpha = 0.2 / 0.14) |
+| Turbine class | I, II, III (Vref = 50 / 42.5 / 37.5 m/s) |
+| Turbulence category | A, B, C (Iref = 0.16 / 0.14 / 0.12) |
+| Condition families | ECD, EWS, EOG, EDC, NWP, EWM |
+| Unit systems | SI (m, m/s) and English (ft, ft/s) |
+| Inflow inclination | up to 8 deg (larger values warn) |
 
-See [Quickstart](docs/quickstart.rst) for more.
+### Limitations and non-goals
 
-## Documentation
+- IEC 61400-1 Edition 2 and other editions are rejected (opt-in legacy coercion only).
+- Turbine class S and site-specific/measured turbulence are not modelled.
+- Speed modifiers are valid only on the rated (`R`) reference.
+- This package generates inflow files; it does not run OpenFAST.
+
+Full detail: [docs/limitations.rst](docs/limitations.rst).
+
+## Validation
+
+Output is protected by three layers of differing strength, documented with a
+per-scenario reproducibility matrix in [docs/validation.rst](docs/validation.rst):
 
-The full documentation is hosted at
-[pyiecwind.readthedocs.io](https://pyiecwind.readthedocs.io/en/latest/). The
-source is in [`docs/`](docs/) and builds with Sphinx
-(`sphinx-build -W -b html docs docs/_build/html`). Key references:
+1. **Golden regression corpus** - committed reference `.wnd` files regenerated and
+   compared on every run. These are generated by this package, so they detect
+   *regressions*, not original-formulation errors.
+2. **Independent analytical oracle** - each family's headline quantity is
+   recomputed directly from the IEC 61400-1 equations (reference values
+   transcribed independently) and compared to the output.
+3. **Property/invariant tests** - durations, row counts, unit scaling, grammar,
+   and direction-ramp monotonicity (Hypothesis).
 
-- [Theory](docs/theory.rst) — the IEC equations behind each case family
-- [Input files](docs/data_sources.rst) and [Units](docs/units.rst)
-- [API reference](docs/api.rst) and [API contract](docs/api_contract.rst)
-- [Validation](docs/validation.rst) and [Scope and limitations](docs/limitations.rst)
+**Tolerance policy:** header/comment lines are compared exactly (version stamp
+masked); numeric data rows are compared column-by-column within +/- 5e-4, half of
+the rendered three-decimal precision. **No external byte-for-byte comparison
+against NREL IECWind binaries has been performed**; such an external reference
+layer is future work.
+
+## Documentation
+
+Hosted at [pyiecwind.readthedocs.io](https://pyiecwind.readthedocs.io/en/latest/)
+(source in [`docs/`](docs/), built with Sphinx). Highlights:
+[Theory](docs/theory.rst) (IEC equations), [API reference](docs/api.rst),
+[API contract](docs/api_contract.rst), [Input files](docs/data_sources.rst),
+[Units](docs/units.rst).
 
 ## Development
 
@@ -87,8 +108,22 @@ mypy
 pytest --cov=pyiecwind
 ```
 
-Contribution guidelines and the full quality-gate list are in
-[Contributing](docs/contributing.rst).
+Quality gates and contribution guidelines: [docs/contributing.rst](docs/contributing.rst).
+
+## Citation
+
+If you use `pyIECWind` in academic work, please cite it. Citation metadata is in
+[`CITATION.cff`](CITATION.cff); GitHub renders a ready-to-use citation from that
+file under *Cite this repository*.
+
+## References
+
+- IEC 61400-1, *Wind turbines - Part 1: Design requirements* (Editions 1 and 3).
+- B. J. Jonkman and M. L. Buhl, *IECWind*, National Renewable Energy Laboratory.
+- OpenFAST *InflowWind* module documentation, National Renewable Energy Laboratory.
+
+See [docs/theory.rst](docs/theory.rst) for the equations and their mapping to the
+implementation.
 
 ## License
 

benchmarks/bench_generation.py

@@ -6,11 +6,20 @@
 
 Usage::
 
-    python benchmarks/bench_generation.py [repeats]
+    python benchmarks/bench_generation.py [repeats]      # human-readable
+    python benchmarks/bench_generation.py [repeats] --json  # machine-readable
+
+The ``--json`` output is suitable for recording a baseline and comparing against
+later runs. See the threshold policy in ``docs/contributing.rst`` -- CI runs this
+as a smoke test (must complete without error); wall-clock comparison is done
+offline against a recorded baseline rather than gated in CI, because shared
+runners are too noisy for a stable threshold.
 """
 
 from __future__ import annotations
 
+import argparse
+import json
 import sys
 import tempfile
 import time
@@ -35,22 +44,42 @@ def run_once() -> int:
     return total
 
 
-def main(argv: list[str]) -> int:
-    repeats = int(argv[1]) if len(argv) > 1 else 5
+def measure(repeats: int) -> dict[str, float | int]:
+    """Run the workload ``repeats`` times (after a warm-up) and summarise timings."""
 
     files = run_once()  # warm up imports and the filesystem
-    samples = []
-    for _ in range(repeats):
-        start = time.perf_counter()
-        run_once()
-        samples.append(time.perf_counter() - start)
-
+    samples = [(_timed_run()) for _ in range(repeats)]
     best = min(samples)
-    mean = sum(samples) / len(samples)
-    print(f"scenarios={len(SCENARIOS)}  files/run={files}  repeats={repeats}")
-    print(f"best={best * 1e3:.1f} ms   mean={mean * 1e3:.1f} ms   per-file={best / files * 1e6:.0f} us")
+    return {
+        "scenarios": len(SCENARIOS),
+        "files_per_run": files,
+        "repeats": repeats,
+        "best_ms": round(best * 1e3, 3),
+        "mean_ms": round(sum(samples) / len(samples) * 1e3, 3),
+        "per_file_us": round(best / files * 1e6, 1),
+    }
+
+
+def _timed_run() -> float:
+    start = time.perf_counter()
+    run_once()
+    return time.perf_counter() - start
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Benchmark wind-file generation.")
+    parser.add_argument("repeats", nargs="?", type=int, default=5)
+    parser.add_argument("--json", action="store_true", help="Emit machine-readable JSON.")
+    args = parser.parse_args(argv)
+
+    result = measure(args.repeats)
+    if args.json:
+        print(json.dumps(result))
+    else:
+        print(f"scenarios={result['scenarios']}  files/run={result['files_per_run']}  repeats={result['repeats']}")
+        print(f"best={result['best_ms']} ms   mean={result['mean_ms']} ms   per-file={result['per_file_us']} us")
     return 0
 
 
 if __name__ == "__main__":
-    raise SystemExit(main(sys.argv))
+    raise SystemExit(main())

docs/api_contract.rst

@@ -26,7 +26,7 @@ Two modules are supported import facades:
     ``gen_ewm``) and the shared constants.
 
 Every module declares an explicit ``__all__``. **Any name not listed in a
-module's ``__all__`` — in particular underscore-prefixed helpers — is internal
+module's ``__all__`` - in particular underscore-prefixed helpers - is internal
 and may change or disappear without notice.** Importing internals from their
 defining modules is unsupported.
 
@@ -46,8 +46,8 @@ Validated, immutable parameters
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :class:`~pyiecwind.IECParameters` is a frozen dataclass that validates on
-construction. Every public path — the parser, the wizard, and direct
-construction — goes through the same validation, so an object that violates the
+construction. Every public path - the parser, the wizard, and direct
+construction - goes through the same validation, so an object that violates the
 IEC class/category/edition, geometry, or speed-ordering rules cannot exist. The
 ``conditions`` field is stored as a tuple; instances cannot be mutated into an
 invalid state afterwards.
@@ -112,5 +112,5 @@ Concurrency and thread-safety
   Generating different conditions, or the same conditions into different output
   directories, is safe to run concurrently.
 * The one shared resource is the filesystem. Writing the **same** output path
-  from multiple workers at once is **not** safe — give each worker a distinct
+  from multiple workers at once is **not** safe - give each worker a distinct
   ``output_dir``. The batch helpers already write one file per condition code.