Skip to content

Python API Reference

Stencil

mannrs.Stencil.Stencil pydantic-model

Bases: BaseModel

Main entry point for defining a turbulence stencil, constraints, and turbulence field generation specs.

Fields:

from_toml classmethod

from_toml(filepath: str | Path) -> Stencil

Load stencil parameters (and optional constraints) from a TOML file.

constrain

constrain(constraints: list[Constraint], spectral_compression_target: float = 0.8, corr_thres: float = 0.0001) -> Stencil

Apply constraints to the stencil. Returns a ConstrainedStencil object.

build

build(parallel: bool = True) -> StencilInstance

Materialize the Mann turbulence stencil in memory.

mannrs.Stencil.StencilInstance

Built stencil, ready to generate turbulence fields.

Methods:

Name Description
turbulence

Generate a constrained 3D Mann turbulence field realization.

get_axes

Get the spatial grid axes corresponding to the generated field.

turbulence

turbulence(ae: float, seed: int, parallel: bool = True) -> Windfield

Generate a constrained 3D Mann turbulence field realization.

Parameters:

Name Type Description Default
ae float

Turbulence intensity scaling factor (α·ε^{2/3}).

required
seed int

Random seed for reproducibility.

required
parallel bool

Whether to use parallel computation during synthesis (default: True).

True

Returns:

Type Description
Windfield

Resultant turbulent velocity field.

get_axes

get_axes() -> tuple[ndarray, ndarray, ndarray]

Get the spatial grid axes corresponding to the generated field.

Returns:

Type Description
tuple of np.ndarray

(x, y, z) coordinate arrays of lengths Nx, Ny, Nz respectively.

Constraint

mannrs.Stencil.Constraint pydantic-model

Bases: BaseModel

A velocity constraint at a specific point in space.

Fields:

  • x (float)
  • y (float)
  • z (float)
  • u (float)

u pydantic-field

u: float

Desired streamwise (x-direction) velocity at the constraint point (m/s).

x pydantic-field

x: float

X-coordinate of the constraint point (m).

y pydantic-field

y: float

Y-coordinate of the constraint point (m).

z pydantic-field

z: float

Z-coordinate of the constraint point (m).

Windfield

mannrs.Windfield.Windfield dataclass

A container for generated wind field data.

Examples:

Save to file:

>>> wf.write("turbulence_field.nc", format="netCDF")

Access individual components:

>>> u_velocity = wf.U  # Streamwise component
>>> v_velocity = wf.V  # Lateral component
>>> w_velocity = wf.W  # Vertical component
>>> x_coords = wf.x    # X-coordinates

Methods:

Name Description
write

Write the turbulence field to disk in one of several supported formats.

write

write(filename: Path, format: Literal['npz', 'netCDF', 'HAWC2'] = 'npz', u_offset: float = 0.0, y_offset: float = 0.0, z_offset: float = 0.0) -> None

Write the turbulence field to disk in one of several supported formats.

Parameters:

Name Type Description Default
filename Path

Target file path. For HAWC2 output, this stem will be used to generate three files (*_u, *_v, *_w).

required
format (npz, netCDF, HAWC2)

Output format:

  • "npz" : NumPy archive.

  • "netCDF" : NetCDF format.

  • "HAWC2" : Three component files suitable for HAWC2.

"npz"
u_offset float

Constant offset to add to the u-component of the velocity field.

0.0
y_offset float

Spatial offset applied to the y-axis.

0.0
z_offset float

Spatial offset applied to the z-axis.

0.0
Notes
  • In "HAWC2" mode, three separate files are created for the velocity components (u, v, w) with suffixes appended to the given filename stem.