foxes.utils.gaussian_pwakes_utils¶

Attributes¶

Functions¶

Module Contents¶

foxes.utils.gaussian_pwakes_utils.build_lookup_dataset(r_over_sigma: numpy.ndarray, sigma_over_d: numpy.ndarray, n_rho: int = 512, *, version_tag: str = LOOKUP_VERSION, sigma_spacing: 'linear' | 'log' | None = None, asymptote_rel_tol: float = _ASYMPTOTE_REL_TOL) → xarray.Dataset[source]¶

Build an in-memory lookup dataset for Gaussian partial-wake geometry.

Parameters:¶

r_over_sigma

1D axis of normalized wake-centre offsets R / sigma.

sigma_over_d

1D axis of normalized Gaussian widths sigma / D.

n_rho

Radial quadrature resolution for weight generation.

version_tag

Version tag of the lookup artifact schema.

sigma_spacing

Optional spacing descriptor used for sigma_over_d.

asymptote_rel_tol

Maximum relative error permitted for the large-sigma asymptote.

Returns:¶

ds

Dataset with coordinates r_over_sigma and sigma_over_d and data variable weight.

foxes.utils.gaussian_pwakes_utils.create_lookup_axes(r_over_sigma_max: float = 28.0, n_r: int = 201, sigma_over_d_min: float = 0.02, sigma_resolution: float = 0.05, sigma_spacing: 'linear' | 'log' = 'log', min_weight: float = _ASYMPTOTE_MIN_WEIGHT, n_rho: int = 512, asymptote_rel_tol: float = _ASYMPTOTE_REL_TOL) → tuple[numpy.ndarray, numpy.ndarray][source]¶

Create normalized lookup axes for Gaussian rotor-disc weights.

The returned axes are dimensionless and use:

• r_over_sigma = R / sigma for wake-centre offset over Gaussian width,

• sigma_over_d = sigma / D for Gaussian width over rotor diameter.

Parameters:¶

r_over_sigma_max

Upper bound of the radial-offset axis. Lower bound is always 0.

n_r

Number of points along the r_over_sigma axis.

sigma_over_d_min

Lower bound of the sigma_over_d axis.

sigma_resolution

Approximate spacing between points along the sigma_over_d axis.

sigma_spacing

Spacing strategy for sigma_over_d. Use "log" to resolve narrow wakes with higher density near the lower bound.

min_weight

Lowest material weight used when assessing asymptote accuracy.

n_rho

Radial quadrature resolution used when assessing asymptote accuracy.

asymptote_rel_tol

Maximum relative error permitted for the large-sigma asymptote.

Returns:¶

r_over_sigma

Monotonic non-negative axis values.

sigma_over_d

Monotonic positive axis values.

foxes.utils.gaussian_pwakes_utils.evaluate_lookup_dataset(ds: xarray.Dataset, r_over_sigma: numpy.ndarray, sigma_over_d: numpy.ndarray, *, bounds_policy: 'clip' | 'nan' | 'raise' = 'clip', fill_value: float | None = np.nan) → numpy.ndarray[source]¶

Interpolate lookup weights at query points.

Parameters:¶

ds

Lookup dataset produced by build_lookup_dataset().

r_over_sigma

Query values for normalized wake-centre offsets R / sigma.

sigma_over_d

Query values for normalized Gaussian widths sigma / D.

bounds_policy

Out-of-bounds policy for radial R / sigma lookup queries:

• "clip": clip radial queries to axis limits before interpolation,

• "nan": return fill_value for out-of-bounds radial queries,

• "raise": raise ValueError for an out-of-bounds radial query.

Queries below the sigma / D range use its lower bound and queries above it use the large-sigma asymptote regardless of this policy.

fill_value

Forwarded to RegularGridInterpolator.

Returns:¶

weights

Interpolated weights with broadcasted query shape.

foxes.utils.gaussian_pwakes_utils.evaluate_lookup_geometry(ds: xarray.Dataset, r: numpy.ndarray, d: numpy.ndarray, sigma: numpy.ndarray, *, is_waked: numpy.ndarray | None = None, bounds_policy: 'clip' | 'nan' | 'raise' = 'clip', fill_value: float | None = np.nan, masked_value: float = 0.0, min_weight: float = 0.0, clip_check_min_weight: float | None = None) → numpy.ndarray[source]¶

Evaluate lookup weights from geometric inputs with numeric guards.

Parameters:¶

ds

Lookup dataset produced by build_lookup_dataset().

r

Wake-centre radial offsets R in meters.

d

Rotor diameters D in meters.

sigma

Gaussian widths sigma in meters.

is_waked

Optional boolean mask. False entries are masked to masked_value and are not validated as active waked points.

bounds_policy

Radial bounds behavior used by evaluate_lookup_dataset().

fill_value

Fill value used by interpolation for bounds_policy='nan'.

masked_value

Output value for masked (non-waked) entries.

min_weight

Weights strictly below this threshold are set to masked_value.

clip_check_min_weight

Optional threshold for bounds_policy='clip': if any out-of-bounds query yields a clipped lookup weight greater than this threshold, ValueError is raised.

Returns:¶

weights

Interpolated rotor weights with broadcasted input shape.

foxes.utils.gaussian_pwakes_utils.gaussian_disc_weight(r_over_sigma: numpy.ndarray, sigma_over_d: numpy.ndarray, n_rho: int = 512) → numpy.ndarray[source]¶

Compute rotor-disc averaged Gaussian weights on normalized axes.

The wake profile is modeled as:

\[g(\mathbf{u}) = \exp\left(-\frac{\|\mathbf{u} - \mathbf{u}_c\|^2}{2\sigma^2}\right)\]

where normalized coordinates are used in units of rotor diameter.

Parameters:¶

r_over_sigma

1D axis of normalized wake-centre offsets R / sigma.

sigma_over_d

1D axis of normalized Gaussian widths sigma / D.

n_rho

Number of midpoint samples for radial quadrature in the closed-form angularly integrated expression.

Returns:¶

weights

2D array of shape (len(r_over_sigma), len(sigma_over_d)) containing disc-averaged Gaussian factors.

foxes.utils.gaussian_pwakes_utils.gaussian_disc_weight_analytical(r: numpy.ndarray, d: numpy.ndarray, sigma: numpy.ndarray, *, is_waked: numpy.ndarray | None = None, masked_value: float = 0.0, min_weight: float = 0.0) → numpy.ndarray[source]¶

Calculate Gaussian rotor-disc weights from the noncentral chi-squared CDF.

Parameters:¶

r

Wake-centre radial offsets R in meters.

d

Rotor diameters D in meters.

sigma

Gaussian widths sigma in meters.

is_waked

Optional boolean mask. False entries are set to masked_value.

masked_value

Output value for masked points and weights below min_weight.

min_weight

Weights strictly below this threshold are set to masked_value.

Returns:¶

weights

Rotor-disc averaged Gaussian weights.

foxes.utils.gaussian_pwakes_utils.generate_lookup_dataset(min_weight: float = 1e-08, r_over_sigma_max: float | None = None, sigma_over_d_min: float = 0.02, radial_resolution: float = 0.1, sigma_resolution: float = 0.05, sigma_spacing: 'linear' | 'log' = 'log', n_rho: int = 512, version_tag: str = LOOKUP_VERSION, radial_expand_factor: float = 1.2, asymptote_rel_tol: float = _ASYMPTOTE_REL_TOL) → xarray.Dataset[source]¶

Deterministically generate a Gaussian lookup dataset from axis settings.

Parameters:¶

min_weight

Lower weight threshold for the lookup table. It determines the lower retained weights and the radial extent where lookup contributions become negligible when r_over_sigma_max is omitted.

r_over_sigma_max

Upper bound of the r_over_sigma axis. If omitted, a conservative bound is derived from min_weight and sigma_over_d_min.

sigma_over_d_min

Lower bound of the sigma_over_d axis.

radial_resolution

Approximate spacing between interpolation points along the r_over_sigma axis.

sigma_resolution

Approximate spacing between interpolation points along the sigma_over_d axis.

sigma_spacing

Spacing strategy for sigma_over_d.

n_rho

Radial quadrature resolution for weight generation.

version_tag

Version tag of the lookup artifact schema.

radial_expand_factor

Multiplicative growth factor for r_over_sigma_max during auto-expansion.

asymptote_rel_tol

Maximum relative error permitted for the large-sigma asymptote.

Returns:¶

ds

Lookup dataset with generation metadata.

foxes.utils.gaussian_pwakes_utils.load_lookup_dataset(fpath: str | pathlib.Path) → xarray.Dataset[source]¶

Load a Gaussian lookup dataset from NetCDF and validate schema.

Parameters:¶

fpath

Input path to a lookup NetCDF artifact.

Returns:¶

ds

Validated in-memory lookup dataset.

foxes.utils.gaussian_pwakes_utils.save_lookup_dataset(ds: xarray.Dataset, fpath: str | pathlib.Path, *, complevel: int = 5, nc_engine: str | None = None) → None[source]¶

Persist a Gaussian lookup dataset to NetCDF.

Parameters:¶

ds

Lookup dataset.

fpath

Output path for the NetCDF artifact.

complevel

Compression level passed to NetCDF encoding.

nc_engine

NetCDF backend engine.

foxes.utils.gaussian_pwakes_utils.validate_lookup_dataset(ds: xarray.Dataset) → None[source]¶

Validate that a dataset matches the Gaussian lookup schema.

Parameters:¶

ds

Candidate lookup dataset.

foxes.utils.gaussian_pwakes_utils.AXIS_R_OVER_SIGMA = 'r_over_sigma'¶

foxes.utils.gaussian_pwakes_utils.AXIS_SIGMA_OVER_D = 'sigma_over_d'¶

foxes.utils.gaussian_pwakes_utils.DATA_WEIGHT = 'weight'¶

foxes.utils.gaussian_pwakes_utils.LOOKUP_VERSION = 'v1'¶