<!-- canonical: https://jmrplens.github.io/phonometry/reference/api/environment/wind-turbine/ -->
Source: https://jmrplens.github.io/phonometry/reference/api/environment/wind-turbine/

Wind-turbine acoustic noise (IEC 61400-11:2012+A1:2018).

Two closed-form quantities of the standard:

* [`apparent_sound_power_level`](/phonometry/reference/api/environment/wind-turbine/#apparent_sound_power_level) -- the A-weighted apparent sound power
  level `L_WA` referred to the equivalent point source at the rotor centre,
  from the ground-board sound pressure level and the slant distance
  ([`slant_distance`](/phonometry/reference/api/environment/wind-turbine/#slant_distance)),
  $L_{W\mathrm{A}} = L_p - 6 + 10 \cdot \log_{10}(4\pi R_1^2/S_0)$ (Formula 26).
* [`wind_turbine_tonality`](/phonometry/reference/api/environment/wind-turbine/#wind_turbine_tonality) -- the tonal-audibility chain (Formulae 30-34):
  the critical bandwidth ([`critical_bandwidth`](/phonometry/reference/api/environment/measurement/#critical_bandwidth)), the masking-noise level,
  the tonality and the audibility criterion, giving the tonal audibility
  `ΔL_a` that decides whether a tone is audible.

The tonal-audibility formula itself is the ISO 1996-2 Annex C one already in
[`measurement`](/phonometry/reference/api/environment/measurement/); what is specific to IEC 61400-11 is
how the tone and masking-noise levels and the (Zwicker) critical band are
determined from the narrowband spectrum. The rating adjustment `K_T` is the
ISO 1996-2 [`tonal_adjustment`](/phonometry/reference/api/environment/measurement/#tonal_adjustment). The
full measurement pipeline (binning, regression to standardised wind speeds,
uncertainty budgets) is out of scope; these are the underlying closed forms.

> Auto-generated from the source docstrings by `scripts/generate_api_docs.py` (`make api-docs`). Do not edit by hand.

## apparent_sound_power_level

```python
apparent_sound_power_level(
    band_levels: float | NDArray[np.float64] | list[float],
    r1: float,
) -> float
```

A-weighted apparent sound power level `L_WA` (IEC 61400-11 Formula 26).

$L_{W\mathrm{A},i} = L_{p,i} - 6 + 10 \cdot \log_{10}(4\pi R_1^2/S_0)$ per
one-third-octave band, energy
summed over bands (Formula 27). The `−6 dB` accounts for the ground-board
pressure doubling; $S_0 = 1$ m².

**Parameters**

| Name | Description |
| :--- | :--- |
| `band_levels` | Background-corrected A-weighted band sound pressure levels `L_p,i`, in dB (scalar or per band). The 61400-11-specific background correction (Formula 23 subtraction with the 3-6 dB asterisk marking and the \<= 3 dB not-reported rule, subclause 9.3) is out of scope here and must be applied beforehand; note its rule set differs from the ISO 1996-2 correction in [`residual_sound_correction`](/phonometry/reference/api/environment/measurement/#residual_sound_correction). |
| `r1` | Slant distance `R1` to the rotor centre, in m. |

**Returns:** The apparent sound power level `L_WA`, in dB re 1 pW.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are invalid. |

## slant_distance

```python
slant_distance(
    hub_height: float,
    rotor_diameter: float,
    *,
    rotor_axis: str = 'horizontal',
) -> float
```

Slant distance `R1` from the rotor centre to the ground microphone.

With the reference microphone on the ground at the horizontal distance
`R0` and the rotor centre at height `H`, the slant distance is
$R_1 = \sqrt{H^2 + R_0^2}$. For a horizontal-axis turbine
$R_0 = H + D/2$
(IEC 61400-11 Formula 1); for a vertical-axis turbine $R_0 = H + D$
(Formula 2, with `H` the height of the equator of the rotor).

**Parameters**

| Name | Description |
| :--- | :--- |
| `hub_height` | Hub height `H` (ground to rotor centre; for a vertical-axis turbine, to the rotor equator), in m. |
| `rotor_diameter` | Rotor diameter `D`, in m. |
| `rotor_axis` | `"horizontal"` (Formula 1, the default) or `"vertical"` (Formula 2). |

**Returns:** The slant distance `R1`, in m.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If a dimension is not positive or `rotor_axis` is not one of the two orientations. |

## wind_turbine_tonality

```python
wind_turbine_tonality(
    levels: NDArray[np.float64] | list[float],
    frequencies: NDArray[np.float64] | list[float],
    *,
    tone_frequency: float | None = None,
) -> WindTurbineTonalityResult
```

Tonal audibility of a narrowband spectrum (IEC 61400-11 Formulae 30-34).

From a uniformly-spaced narrowband spectrum, screens the candidate as a
possible tone (subclause 9.5.2: a local maximum more than 6 dB above the
critical-band energy average excluding the maximum and its two adjacent
lines), classifies the lines in the critical band about the candidate into
masking noise and tone lines, forms the masking-noise level `L_pn`
(Formula 31), the tonality $\Delta L_\mathrm{tn} = L_{p\mathrm{t}} - L_{p\mathrm{n}}$
(Formula 32), the
audibility criterion `L_a` (Formula 34) and the tonal audibility
$\Delta L_\mathrm{a} = \Delta L_\mathrm{tn} - L_\mathrm{a}$ (Formula 33).

Per subclause 9.5.3 the tone lines are those above `L_pn,avg + 6 dB`
*and* within 10 dB of the highest such line; the frequency of the tone is
that highest line (9.5.4), which also anchors `L_a`. When the candidate
fails the 9.5.2 screening or no line classifies as "tone", the result
carries `has_identified_tone = False`: its numeric fields are
non-standard fallbacks and the spectrum must be excluded from the 9.5.1
bin averaging (see [`WindTurbineTonalityResult`](/phonometry/reference/api/environment/wind-turbine/#windturbinetonalityresult)).

Spectra must extend over the whole critical band: a truncated band leaves
the masking average over the surviving lines while Formula 31 still scales
to the full bandwidth, so a [`WindTurbineNoiseWarning`](/phonometry/reference/api/environment/wind-turbine/#windturbinenoisewarning) is issued.
Candidates below 20 Hz are outside the standard's analysis range (the
critical band would extend to negative frequencies) and are rejected.

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | Narrowband line levels, in dB (A-weighted, 1-2 Hz resolution). |
| `frequencies` | Line frequencies, in Hz (uniform spacing). |
| `tone_frequency` | Candidate tone frequency, in Hz; if `None` the highest-level line is used. |

**Returns:** A [`WindTurbineTonalityResult`](/phonometry/reference/api/environment/wind-turbine/#windturbinetonalityresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are invalid or the candidate lies below 20 Hz. |

## WindTurbineNoiseWarning

The tonality inputs leave the standard's stated domain of validity.

## WindTurbineTonalityResult

```python
WindTurbineTonalityResult(
    tone_frequency: float,
    critical_bandwidth: float,
    tone_level: float,
    masking_level: float,
    tonality: float,
    audibility_criterion: float,
    tonal_audibility: float,
    is_audible: bool,
    has_identified_tone: bool,
    frequencies: NDArray[np.float64],
    levels: NDArray[np.float64],
)
```

Tonal audibility of a narrowband spectrum (IEC 61400-11).

**Attributes**

| Name | Description |
| :--- | :--- |
| `tone_frequency` | The frequency of the identified tone: the spectral line with the highest level among the lines classified as "tone" (subclause 9.5.4; also the `f` of Formula 34). When no tone is identified (`has_identified_tone` is `False`) this falls back to the candidate line. |
| `critical_bandwidth` | The critical bandwidth about the candidate, Hz. |
| `tone_level` | Tone level `L_pt` (energy sum of the tone lines), in dB. |
| `masking_level` | Masking-noise level `L_pn`, in dB. |
| `tonality` | Tonality $\Delta L_\mathrm{tn} = L_{p\mathrm{t}} - L_{p\mathrm{n}}$, in dB. |
| `audibility_criterion` | The criterion `L_a` (Formula 34), in dB. |
| `tonal_audibility` | Tonal audibility $\Delta L_\mathrm{a} = \Delta L_\mathrm{tn} - L_\mathrm{a}$, in dB. |
| `is_audible` | Whether an identified tone is audible ($\Delta L_\mathrm{a} > 0$ *and* `has_identified_tone`). |
| `has_identified_tone` | Whether the candidate passed the 9.5.2 possible-tone screening *and* at least one spectral line was classified as "tone" (subclause 9.5.4). When `False` the numeric fields are non-standard fallbacks (the standard defines no tonality for such a spectrum) and the spectrum must be **excluded** from the 9.5.1 energy averaging of `ΔL_a,j,k` over the spectra of a bin. |
| `frequencies` | The narrowband line frequencies, in Hz. |
| `levels` | The narrowband line levels, in dB. |

### WindTurbineTonalityResult.plot()

```python
WindTurbineTonalityResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes
```

Plot the narrowband spectrum with the critical band and masking level.

### WindTurbineTonalityResult.report()

```python
WindTurbineTonalityResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str
```

Render a wind-turbine tonal audibility assessment fiche to a PDF.

Writes a one-page tonality-assessment report following
IEC 61400-11:2012+A1:2018 (subclauses 9.5.2 to 9.5.8): the standard-basis
line, an optional metadata header (source/situation, client, measurement
position, instrumentation and date), a two-panel body with the
critical-band / masking analysis in a metrics table (tone frequency,
critical bandwidth, tone level `L_pt`, masking-noise level `L_pn`,
tonality `ΔL_tn`, audibility criterion `L_a` and tonal audibility
`ΔL_a`) beside the narrowband-spectrum plot with the critical band,
masking level and tone marked, the boxed decisive tonal audibility
`ΔL_a` and the tone frequency with the audibility decision, an optional
verdict row and a footer with the fixed disclaimer.

**Parameters**

| Name | Description |
| :--- | :--- |
| `path` | Destination path of the PDF file. |
| `metadata` | Optional [`ReportMetadata`](/phonometry/reference/api/building/insulation/#reportmetadata); `None` produces a bare assessment fiche (body, result and disclaimer only). A supplied `requirement` is read as the maximum acceptable tonal audibility `ΔL_a` in dB (a lower audibility passes). |
| `engine` | Rendering back end; only `"reportlab"` is supported. |
| `verbose` | Accepted for signature parity with the other fiches; the metrics table already shows the full Formula 30-34 chain, so it has no effect. |
| `language` | Fiche language: `"en"` (default, English) or `"es"` (Spanish, with a comma decimal separator). |

**Returns:** The written `path` as a `str`.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `language` is not one of the supported languages, or if `engine` is not `"reportlab"`. |
| ImportError | If reportlab is not installed (`pip install phonometry[report]`), or matplotlib is missing for the embedded figure (`pip install phonometry[plot]`). |