API reference

The public API is intentionally small and is importable directly from the top-level pyiecwind package. The stability guarantees for these names are described in API contract.

Parameters

class pyiecwind.IECParameters(si_unit, t1, wtc, catg, slope_deg, iec_edition, hh, dia, vin, vrated, vout, conditions=())[source]

Validated, immutable input parameters stored internally in SI units.

Construction is the single validation gate: every public path (the parser, the wizard, direct API use) goes through __post_init__, which enforces the IEC turbine class/category/edition, finite and positive geometry, and a physically ordered cut-in < rated < cut-out speed range. A frozen dataclass with a tuple of conditions makes an invalid object impossible to create and impossible to mutate into one afterwards.

Length and speed fields are stored in SI (m, m/s); si_unit only controls how values are rendered in output files and how condition-code speeds are interpreted.

Parameters:

si_unit (bool) – Render output in SI (m, m/s) when True, English (ft, ft/s) when False.
t1 (float) – Transient start time [s].
wtc (int) – IEC turbine class: 1, 2, or 3.
catg (str) – Turbulence category: "A", "B", or "C" (normalised to upper case).
slope_deg (float) – Inflow inclination angle [deg].
iec_edition (int) – IEC 61400-1 edition for the power-law shear exponent: 1 or 3.
hh (float) – Hub height [m].
dia (float) – Rotor diameter [m]; must be positive and less than twice the hub height.
vin (float) – Cut-in, rated, and cut-out wind speeds [m/s]; must satisfy 0 < vin < vrated < vout.
vrated (float) – Cut-in, rated, and cut-out wind speeds [m/s]; must satisfy 0 < vin < vrated < vout.
vout (float) – Cut-in, rated, and cut-out wind speeds [m/s]; must satisfy 0 < vin < vrated < vout.
conditions (tuple of str, optional) – Condition codes to generate (e.g. ("ECD+R", "EWM50")). Stored as a tuple.

Raises:

ValueError – If any field is non-finite or out of its allowed range.

Generation

pyiecwind.generate_all(params, output_dir=None, *, strict=True, atomic=False)[source]

Generate every condition listed in params.

Fails closed by default: the first invalid condition raises, so a caller never silently receives partial output. Repeated condition codes describe the same <code>.wnd file and are generated once (first-seen order preserved).

Parameters:

params (IECParameters) – Validated turbine definition and the list of condition codes to generate.
output_dir (str or pathlib.Path or None, optional) – Directory to write the <code>.wnd files into; created if it does not exist. When None (the default) files are written to the current working directory.
strict (bool, default True) – If True, raise ValueError on the first condition that cannot be generated. If False, collect failures into the result and continue.
atomic (bool, default False) – If True, stage all files in a temporary directory and only move them into output_dir once the whole batch has been generated. Combined with strict=True this is all-or-nothing: an invalid condition raises and the output directory is left untouched, never partially populated.

Returns:

The paths written and any per-condition errors (errors are only populated when strict=False).

Return type:

GenerationResult

Raises:

ValueError – If strict is True and a condition code is unknown or invalid.

Examples

>>> 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=("EWM50", "NWP10.0"),
... )
>>> result = generate_all(params, output_dir="out", atomic=True)
>>> result.count
2

pyiecwind.generate_from_input_file(input_file, *, output_dir=None, strict=True, atomic=False)[source]

Parse input_file and generate all of its conditions.

A convenience wrapper combining parse_input_file() and generate_all().

Parameters:

input_file (str or pathlib.Path) – Path to an input file in any supported layout.
output_dir (str or pathlib.Path or None, optional) – Directory for the generated .wnd files (see generate_all()).
strict (bool, default True) – Passed through to generate_all(); fails closed by default.
atomic (bool, default False) – Passed through to generate_all(); when combined with strict, a single invalid condition leaves no files behind.

Returns:

The parsed parameters and the generation outcome.

Return type:

tuple of (IECParameters, GenerationResult)

Raises:

FileNotFoundError – If input_file does not exist.
ValueError – For malformed input, or (when strict=True) an invalid condition.

class pyiecwind.GenerationResult(generated=(), errors=())[source]

Outcome of a batch generation run.

generated holds the paths written successfully and errors holds the conditions that were skipped (only populated when strict=False).

Parameters:

generated (tuple[Path, ...])
errors (tuple[GenerationError, ...])

property count: int: Number of files written.

property ok: bool: True when every requested condition was generated.

class pyiecwind.GenerationError(code, message)[source]

A single condition that could not be generated.

Parameters:

code (str)
message (str)

Condition generators

Each generator writes one .wnd file and returns its path. They are available from the pyiecwind.core compatibility facade.

pyiecwind.core.gen_ecd(code, params, output_dir=None)[source]

Generate an Extreme Coherent Gust with Direction Change (ECD) .wnd file.

Parameters:

code (str) – Condition code of the form ECD[+/-]R[+/-modifier] (e.g. "ECD+R", "ECD-R+1.5"). The sign sets the direction-change sense; the optional modifier (magnitude <= 2 m/s in user units) offsets the rated hub speed.
params (IECParameters) – Turbine definition supplying rated speed, slope, and shear exponent.
output_dir (str or pathlib.Path or None, optional) – Output directory; created if missing. None writes to the current working directory.

Returns:

Path to the written .wnd file.

Return type:

pathlib.Path

Raises:

ValueError – If code is malformed, the modifier exceeds +/-2 m/s, or the resulting hub speed exceeds the reference wind speed.

Input and templates

pyiecwind.parse_input_file(filepath='pyiecwind.ipt', *, legacy=False)[source]

Read an input file and return validated IECParameters.

The OpenFAST-style table, keyed (key = value), and legacy positional layouts are auto-detected. A file may instead pin its layout explicitly with a ! format: <id> comment directive (openfast-table-v1, keyed-v1, or legacy-v1); when present it overrides auto-detection. See docs/data_sources.rst for the full Input Format v1 specification.

Parameters:

filepath (str or pathlib.Path, optional) – Path to the input file. Defaults to pyiecwind.ipt in the current working directory.
legacy (bool, default False) – If True, unsupported IEC editions are coerced to edition 3 (emitting an IECWindWarning) instead of raising. Provided for backward compatibility with older inputs.

Returns:

The validated, immutable parameter object.

Return type:

IECParameters

Raises:

FileNotFoundError – If filepath does not exist.
ValueError – For malformed input, an unknown key, a duplicate scalar field, an unrecognised si_unit token or format directive, an out-of-range value, or (unless legacy=True) an unsupported edition.

Examples

>>> from pyiecwind import parse_input_file
>>> params = parse_input_file("examples/sample_case.ipt")
>>> params.wtc
2

pyiecwind.write_template(dest='pyiecwind_template.ipt')[source]

Write a commented example input file to dest.

Parameters:: dest (str or pathlib.Path, optional) – Destination path. Defaults to pyiecwind_template.ipt.
Returns:: The path that was written.
Return type:: pathlib.Path

pyiecwind.format_openfast_input(params)[source]

Render parameters as an OpenFAST-style input file.

The output round-trips: feeding it back through parse_input_file() reproduces the same conditions and scalars.

Parameters:: params (IECParameters) – The parameters to render. Length and speed fields are shown in the parameters’ own unit system (si_unit).
Returns:: The formatted input-file text, including the grouped Cases section.
Return type:: str

Diagnostics

exception pyiecwind.IECWindWarning[source]

Advisory warning for non-fatal IEC validation concerns.

Emitted for inputs that are accepted but fall outside IEC guidance (for example an inclination angle beyond 8 deg). Callers who want strict behaviour can escalate these to errors:

import warnings
warnings.simplefilter("error", IECWindWarning)