---
title: "metrology.inversion"
description: "Public API of phonometry.metrology.inversion (auto-generated)."
sidebar:
  label: "inversion"
---

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

Regularized spectral inversion with frequency-dependent regularization.

Inverting a measured transfer function -- to equalize a measurement
loudspeaker, flatten a microphone response or post-process an acquired
impulse response -- cannot be a plain reciprocal `1/H(f)`: wherever the
system radiates little energy (outside its passband, in deep notches) the
reciprocal explodes and the inverse filter amplifies nothing but noise.
Mueller & Massarani ("Transfer-Function Measurement with Sweeps", JAES
49(6), 2001, Secs. 3.1 and 4.5) therefore confine the inversion to the
transmission band: unity equalization in-band and a controlled, bounded
gain outside.

This module implements that behaviour with the frequency-dependent
Tikhonov regularization of Kirkeby & Nelson ("Digital Filter Design for
Inversion Problems in Sound Reproduction", JAES 47(7/8), 1999, Eq. (17)):

`H_inv(f) = conj(H(f)) / (|H(f)|**2 + epsilon(f))`,

where the regularization profile `epsilon(f)` is small inside the band
`[f1, f2]` (the filter equalizes to unity within an analytic bound) and
large outside (the out-of-band gain is capped at `1/(2*sqrt(epsilon))`,
the maximum of `x/(x**2 + epsilon)`), with a smooth geometric cross-fade
over a transition zone bordering the band edges. A modeling delay makes
the mixed-phase inverse causal (Kirkeby & Nelson Sec. 2.4: the inverse of
a non-minimum-phase response is anticausal and must be delayed to be
realisable).

The closed forms above are the module's oracles: in-band the equalized
magnitude `|H*H_inv|` deviates from unity by exactly
`epsilon/( |H|**2 + epsilon )`, and out-of-band the filter gain never
exceeds the `1/(2*sqrt(epsilon))` bound.

## InverseFilterResult

```python
InverseFilterResult(
    inverse: np.ndarray,
    frequencies: np.ndarray,
    spectrum: np.ndarray,
    response_spectrum: np.ndarray,
    regularization: np.ndarray,
    f_range: tuple[float, float],
    delay: int,
    fs: float,
    flatness_db: float,
    max_gain_db: float,
)
```

A regularized inverse filter with its achieved equalization.

Returned by [`regularized_inverse_filter`](/phonometry/reference/api/spectra/inversion/#regularized_inverse_filter). The causal filter
samples live in `inverse` (the equalized response arrives `delay`
samples late; `apply` compensates it). `spectrum` is the
complex inverse spectrum *including* the modeling delay;
`regularization` is the `epsilon(f)` profile actually used, and
`flatness_db` reports how flat the equalized magnitude
`|H(f) * H_inv(f)|` actually is across the requested band.

**Attributes**

| Name | Description |
| :--- | :--- |
| `inverse` | Inverse-filter samples (time domain, length `n_fft`). |
| `frequencies` | Frequency grid of the design, in Hz. |
| `spectrum` | Complex inverse spectrum on `frequencies`, including the `exp(-j*2*pi*f*delay/fs)` modeling delay. |
| `response_spectrum` | Complex spectrum of the measured response the filter was designed from, on the same grid. |
| `regularization` | The frequency-dependent profile `epsilon(f)` (absolute units of `\|H\|**2`). |
| `f_range` | `(f1, f2)` band equalized to unity, in Hz. |
| `delay` | Modeling delay of the filter, in samples. |
| `fs` | Sample rate, in Hz. |
| `flatness_db` | Largest deviation of the equalized magnitude `20*log10\|H*H_inv\|` from 0 dB inside `[f1, f2]`. |
| `max_gain_db` | Largest filter gain *outside* the transition-padded band, peak-normalized as `20*log10(max\|H_inv\| * peak_h)` where `peak_h` is the peak of `\|H\|` -- the achieved out-of-band boost the regularization allowed where the measurement carries no signal. |

### InverseFilterResult.apply()

```python
InverseFilterResult.apply(x: list[float] | np.ndarray) -> np.ndarray
```

Equalize a signal with the inverse filter.

Convolves `x` with the filter and removes the modeling delay, so
the output is time-aligned with the input and has the same length.
Feeding the response the filter was designed from returns (in-band)
a band-limited unit impulse at sample 0.

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | The signal to equalize (1-D). |

**Returns:** The equalized, delay-compensated signal, `len(x)` samples.

### InverseFilterResult.plot()

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

Plot the measured, inverse and equalized magnitudes.

One panel: `|H|`, `|H_inv|` and the equalized product
`|H*H_inv|` in dB over log-frequency, with the equalized band
shaded. Requires matplotlib (`pip install phonometry[plot]`).

**Parameters**

| Name | Description |
| :--- | :--- |
| `language` | Label language, `"en"` (default) or `"es"`. |

### InverseFilterResult.size

*property*

Number of samples in the inverse filter.

## regularized_inverse_filter

```python
regularized_inverse_filter(
    response: list[float] | np.ndarray | Any,
    fs: float | None = None,
    *,
    f_range: tuple[float, float],
    regularization_inside: float = 1e-06,
    regularization_outside: float = 1.0,
    transition_octaves: float = 0.3333333333333333,
    n_fft: int | None = None,
    delay: int | None = None,
) -> InverseFilterResult
```

Design a regularized inverse filter for a measured impulse response.

Computes the frequency-dependent Tikhonov inverse of Kirkeby & Nelson
(JAES 47(7/8), 1999, Eq. (17)),

`H_inv(f) = conj(H(f)) / (|H(f)|**2 + epsilon(f))`,

with `epsilon(f)` small across `[f1, f2]` and large outside, so the
filter equalizes the response to unity in-band while the out-of-band
gain stays bounded by `1/(2*sqrt(epsilon_outside))` -- the behaviour
Mueller & Massarani (JAES 49(6), 2001, Secs. 3.1/4.5) obtain by
band-passing the plain inverse. A modeling delay of `delay` samples
(default half the FFT block) shifts the generally anticausal inverse of
a mixed-phase response into a causal filter (Kirkeby & Nelson,
Sec. 2.4).

Both regularization levels are *relative* to the peak of `|H|**2`
(like the scalar `regularization` of [`phonometry.impulse_response`](/phonometry/reference/api/rooms/room-ir/#impulse_response),
which this generalises): in-band the equalized magnitude deviates from
unity by at most `regularization_inside * max|H|**2 / min|H|**2` --
the analytic residue `epsilon/(|H|**2 + epsilon)` -- and the achieved
figure is reported as [`InverseFilterResult.flatness_db`](/phonometry/reference/api/spectra/inversion/#inversefilterresult).

Use the result's [`InverseFilterResult.apply`](/phonometry/reference/api/spectra/inversion/#inversefilterresultapply) to equalize
recordings (or the excitation, for pre-emphasis) and read
[`InverseFilterResult.spectrum`](/phonometry/reference/api/spectra/inversion/#inversefilterresult) to apply it spectrally.

**Parameters**

| Name | Description |
| :--- | :--- |
| `response` | Measured impulse response (1-D array), or an [`phonometry.ImpulseResponseResult`](/phonometry/reference/api/rooms/room-ir/#impulseresponseresult) from the sweep/MLS/Golay front ends (its sample rate is used when `fs` is omitted). |
| `fs` | Sample rate in Hz. Optional when `response` carries one. |
| `f_range` | `(f1, f2)` band, in Hz, over which the response is equalized to unity. Choose it inside the band actually excited and radiated; inverting unexcited regions only amplifies noise. |
| `regularization_inside` | In-band regularization, as a fraction of the peak spectral power `max\|H\|**2`. Default 1e-6. |
| `regularization_outside` | Out-of-band regularization, same units. Default 1.0, which caps the out-of-band gain at 6 dB below the peak-normalised unity (`1/(2*sqrt(1)) = 0.5`). |
| `transition_octaves` | Width of the geometric cross-fade between the two regularization levels, in octaves outside each band edge. Default 1/3. |
| `n_fft` | FFT block length of the design (also the filter length). Default: the next power of two of `2*len(response)`, so the circular design has room for the anticausal (delayed) part. |
| `delay` | Modeling delay in samples. Default `n_fft // 2`. |

**Returns:** An [`InverseFilterResult`](/phonometry/reference/api/spectra/inversion/#inversefilterresult).
