common-slope-nmf 0.1.0__tar.gz

common_slope_nmf-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremy Bai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

common_slope_nmf-0.1.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: common-slope-nmf
+Version: 0.1.0
+Summary: Physically constrained IS-NMF/SAGE for common-slope room-acoustic decay estimation.
+Author: Jeremy Bai
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jeremybbq/common_slope_nmf
+Project-URL: Repository, https://github.com/jeremybbq/common_slope_nmf
+Project-URL: Issues, https://github.com/jeremybbq/common_slope_nmf/issues
+Project-URL: Changelog, https://github.com/jeremybbq/common_slope_nmf/releases
+Keywords: acoustics,decay,nmf,reverberation,room-impulse-response,sage
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: numpy>=1.23
+Requires-Dist: scipy>=1.10
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: experiments
+Requires-Dist: h5py>=3.7; extra == "experiments"
+Requires-Dist: matplotlib>=3.7; extra == "experiments"
+Provides-Extra: decayfitnet
+Requires-Dist: onnx>=1.15; extra == "decayfitnet"
+Requires-Dist: onnxruntime>=1.16; extra == "decayfitnet"
+Requires-Dist: torch>=2.0; extra == "decayfitnet"
+Dynamic: license-file
+
+# Common-slope joint estimation of decay and amplitude using parameterized nonnegative matrix factorization
+
+Estimate shared frequency dependent decay rates (or reverberation time, RT), and the amplitudes of the decays in each recording of room impulse responses (RIRs).
+
+![A fixed-frequency slice of the stacked RIR spectrograms forms a space–time power matrix, which is factored into per-position amplitudes and exponential decays shared by every position](https://raw.githubusercontent.com/jeremybbq/common_slope_nmf/main/assets/nmf-overview.png)
+
+At one frequency, the powers of all RIRs form a space–time matrix (blue frame). It is factored into per-position amplitudes and a few exponential decays shared by every position; the right panel shows one RIR (green frame) with its two fitted decays.
+
+The exponential decay fit uses an Itakura–Saito divergence loss (the corresponding negative log-likelihood from the complex-Gaussian variance model) and a SAGE optimizer.
+
+For RIRs indexed with $r$, frequency $f$, and time frame $n$ at elapsed time $\tau_n$, the model variance is
+
+```math
+V_{rfn} = b_{rf} + \sum_{k=1}^{K} a_{rfk} \, e^{-\lambda_{fk} \tau_n}
+```
+
+The rates $\lambda_{fk}$ are shared. The amplitudes $a_{rfk}$ and floors $b_{rf}$ stay non-negative and can differ by recording.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install common-slope-nmf
+```
+
+The experiments from the paper are not in the standalone PyPI package. To run them, clone the repository and set it up with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --extra experiments --extra test
+uv run pytest
+```
+
+`uv sync` creates `.venv` and installs the package in editable mode.
+
+NumPy and SciPy are required.
+
+## Quick start
+
+The fit takes STFT power of shape `(R, F, N)` (RIRs, frequencies, frames) and the elapsed time of each frame in seconds. Frame zero is the decay origin, so the RIRs must already start at a common onset.
+
+From waveforms, with `rirs` a real array of shape `(R, L)`:
+
+```python
+from common_slope_nmf import rir_stft_power
+
+stft = rir_stft_power(
+    rirs,
+    sample_rate_hz,
+    frame_size_samples=512,
+    hop_size_samples=256,
+    fft_size_samples=512,
+    minimum_frequency_hz=125.0,
+    maximum_frequency_hz=8_000.0,
+)
+observed_power, frame_time_s = stft.observed_power, stft.frame_time_s
+```
+
+The values shown are the defaults. The window is Hann, sizes are in samples, and `stft.frequencies_hz` holds the bins kept between the two frequency limits.
+
+Then estimate `n_components` shared decays per frequency:
+
+```python
+import numpy as np
+from common_slope_nmf import fit_decay, init_decay, rate_to_t60
+
+n_components = 2
+
+# One pooled decay rate per frequency, a few-frame estimate of the total amplitude, and the noise floor.
+rate, amplitude, floor = init_decay(observed_power, frame_time_s)
+result = fit_decay(
+    observed_power,
+    frame_time_s,
+    initial_rates_per_s=np.repeat(rate[:, None], n_components, axis=1),
+    initial_amplitudes=np.repeat(amplitude[:, :, None] / n_components, n_components, axis=2),
+    initial_noise_floor=floor,
+)
+t60_s = rate_to_t60(result.rates_per_s)
+```
+
+`result.rates_per_s` is of size `(F, K)`, `result.amplitudes` is `(R, F, K)`, and `result.noise_floor` is `(R, F)`.
+
+## Experiments
+
+Run all experiments from the repository root. The `plot_*` scripts draw figures from those saved results. For example,
+
+```bash
+uv run python -m experiments.synthetic.convergence
+uv run python -m experiments.synthetic.plot_convergence --results output/[PATH]/loss_convergence_results.npz
+```
+
+Measured coupled-room RIRs ([Meeting Room to Hallway, v1.3](https://doi.org/10.5281/zenodo.6375520)), read from `--dataset-dir`:
+
+```bash
+uv run python -m experiments.room_to_hallway.sage_fit --dataset-dir PATH
+uv run python -m experiments.room_to_hallway.plot_sage_fit --results output/RUN
+```
+
+`experiments.room_to_hallway.decayfitnet_benchmarks` compares these fits with DecayFitNet and CommonSlopeAnalysis. It needs `uv sync --extra decayfitnet` and an external DecayFitNet checkout; see [THIRD_PARTY_NOTICES.md](https://github.com/jeremybbq/common_slope_nmf/blob/main/THIRD_PARTY_NOTICES.md).
+
+## License
+
+MIT. Notices for adapted third-party code are in [THIRD_PARTY_NOTICES.md](https://github.com/jeremybbq/common_slope_nmf/blob/main/THIRD_PARTY_NOTICES.md).

common_slope_nmf-0.1.0/README.md

@@ -0,0 +1,103 @@
+# Common-slope joint estimation of decay and amplitude using parameterized nonnegative matrix factorization
+
+Estimate shared frequency dependent decay rates (or reverberation time, RT), and the amplitudes of the decays in each recording of room impulse responses (RIRs).
+
+![A fixed-frequency slice of the stacked RIR spectrograms forms a space–time power matrix, which is factored into per-position amplitudes and exponential decays shared by every position](https://raw.githubusercontent.com/jeremybbq/common_slope_nmf/main/assets/nmf-overview.png)
+
+At one frequency, the powers of all RIRs form a space–time matrix (blue frame). It is factored into per-position amplitudes and a few exponential decays shared by every position; the right panel shows one RIR (green frame) with its two fitted decays.
+
+The exponential decay fit uses an Itakura–Saito divergence loss (the corresponding negative log-likelihood from the complex-Gaussian variance model) and a SAGE optimizer.
+
+For RIRs indexed with $r$, frequency $f$, and time frame $n$ at elapsed time $\tau_n$, the model variance is
+
+```math
+V_{rfn} = b_{rf} + \sum_{k=1}^{K} a_{rfk} \, e^{-\lambda_{fk} \tau_n}
+```
+
+The rates $\lambda_{fk}$ are shared. The amplitudes $a_{rfk}$ and floors $b_{rf}$ stay non-negative and can differ by recording.
+
+## Install
+
+Python 3.10 or newer.
+
+```bash
+pip install common-slope-nmf
+```
+
+The experiments from the paper are not in the standalone PyPI package. To run them, clone the repository and set it up with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv sync --extra experiments --extra test
+uv run pytest
+```
+
+`uv sync` creates `.venv` and installs the package in editable mode.
+
+NumPy and SciPy are required.
+
+## Quick start
+
+The fit takes STFT power of shape `(R, F, N)` (RIRs, frequencies, frames) and the elapsed time of each frame in seconds. Frame zero is the decay origin, so the RIRs must already start at a common onset.
+
+From waveforms, with `rirs` a real array of shape `(R, L)`:
+
+```python
+from common_slope_nmf import rir_stft_power
+
+stft = rir_stft_power(
+    rirs,
+    sample_rate_hz,
+    frame_size_samples=512,
+    hop_size_samples=256,
+    fft_size_samples=512,
+    minimum_frequency_hz=125.0,
+    maximum_frequency_hz=8_000.0,
+)
+observed_power, frame_time_s = stft.observed_power, stft.frame_time_s
+```
+
+The values shown are the defaults. The window is Hann, sizes are in samples, and `stft.frequencies_hz` holds the bins kept between the two frequency limits.
+
+Then estimate `n_components` shared decays per frequency:
+
+```python
+import numpy as np
+from common_slope_nmf import fit_decay, init_decay, rate_to_t60
+
+n_components = 2
+
+# One pooled decay rate per frequency, a few-frame estimate of the total amplitude, and the noise floor.
+rate, amplitude, floor = init_decay(observed_power, frame_time_s)
+result = fit_decay(
+    observed_power,
+    frame_time_s,
+    initial_rates_per_s=np.repeat(rate[:, None], n_components, axis=1),
+    initial_amplitudes=np.repeat(amplitude[:, :, None] / n_components, n_components, axis=2),
+    initial_noise_floor=floor,
+)
+t60_s = rate_to_t60(result.rates_per_s)
+```
+
+`result.rates_per_s` is of size `(F, K)`, `result.amplitudes` is `(R, F, K)`, and `result.noise_floor` is `(R, F)`.
+
+## Experiments
+
+Run all experiments from the repository root. The `plot_*` scripts draw figures from those saved results. For example,
+
+```bash
+uv run python -m experiments.synthetic.convergence
+uv run python -m experiments.synthetic.plot_convergence --results output/[PATH]/loss_convergence_results.npz
+```
+
+Measured coupled-room RIRs ([Meeting Room to Hallway, v1.3](https://doi.org/10.5281/zenodo.6375520)), read from `--dataset-dir`:
+
+```bash
+uv run python -m experiments.room_to_hallway.sage_fit --dataset-dir PATH
+uv run python -m experiments.room_to_hallway.plot_sage_fit --results output/RUN
+```
+
+`experiments.room_to_hallway.decayfitnet_benchmarks` compares these fits with DecayFitNet and CommonSlopeAnalysis. It needs `uv sync --extra decayfitnet` and an external DecayFitNet checkout; see [THIRD_PARTY_NOTICES.md](https://github.com/jeremybbq/common_slope_nmf/blob/main/THIRD_PARTY_NOTICES.md).
+
+## License
+
+MIT. Notices for adapted third-party code are in [THIRD_PARTY_NOTICES.md](https://github.com/jeremybbq/common_slope_nmf/blob/main/THIRD_PARTY_NOTICES.md).

common_slope_nmf-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+`common_slope_nmf/baseline.py` adapts the common-decay clustering procedure from Georg Götz's [CommonSlopeAnalysis](https://github.com/georg-goetz/CommonSlopeAnalysis). The room-to-hallway benchmark calls filtering, Schroeder integration, and network inference from an external [DecayFitNet](https://github.com/georg-goetz/DecayFitNet) checkout. The ONNX weights and input transforms are not included in this repository.
+
+## DecayFitNet
+
+Copyright (c) 2021 Georg Götz
+
+## CommonSlopeAnalysis
+
+Copyright (c) 2023 Georg Götz
+
+Both projects are provided under the MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

common_slope_nmf-0.1.0/common_slope_nmf/__init__.py

@@ -0,0 +1,67 @@
+"""Research package for constrained multi-slope IS-NMF decay estimation."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("common-slope-nmf")
+except PackageNotFoundError:
+    __version__ = "0.1.0"
+
+from .loss import is_divergence
+from .model import (
+    exponential_features,
+    exponential_variance,
+    rate_to_t60,
+    t60_to_rate,
+)
+from .preprocess import fit_linear_decay, head_power, tail_power
+from .rir import (
+    STFTPower,
+    global_energy_onset,
+    rir_stft_power,
+    select_stft_frames,
+)
+from .sage import (
+    AmplitudeFit,
+    DecayFit,
+    fit_amplitudes,
+    fit_decay,
+    init_decay,
+    update_rates_newton,
+)
+from .synth import (
+    SynthData,
+    sample_complex_gaussian,
+    sample_stft_power,
+    sample_power,
+    sample_simplex_amplitudes,
+    sample_t60,
+)
+
+__all__ = [
+    "__version__",
+    "AmplitudeFit",
+    "SynthData",
+    "DecayFit",
+    "STFTPower",
+    "exponential_features",
+    "exponential_variance",
+    "fit_amplitudes",
+    "fit_decay",
+    "fit_linear_decay",
+    "global_energy_onset",
+    "head_power",
+    "init_decay",
+    "is_divergence",
+    "rate_to_t60",
+    "rir_stft_power",
+    "select_stft_frames",
+    "sample_complex_gaussian",
+    "sample_stft_power",
+    "sample_power",
+    "sample_simplex_amplitudes",
+    "sample_t60",
+    "tail_power",
+    "t60_to_rate",
+    "update_rates_newton",
+]

common_slope_nmf-0.1.0/common_slope_nmf/baseline.py

@@ -0,0 +1,135 @@
+"""Common-slope clustering of DecayFitNet energy decay times.
+
+DecayFitNet filtering, Schroeder integration, resampling, and network inference stay in an external DecayFitNet checkout. This module keeps the common-decay-time clustering from Georg Götz's MATLAB analysis that the Python toolbox does not provide.
+
+References
+----------
+[1] G. Götz, S. J. Schlecht, and V. Pulkki, "Common-slope modeling of late reverberation," IEEE/ACM Trans. Audio, Speech, Lang. Process., vol. 31, pp. 3945-3957, 2023. https://doi.org/10.1109/TASLP.2023.3317572
+[2] G. Götz, R. Falcón Pérez, S. J. Schlecht, and V. Pulkki, "Neural network for multi-exponential sound energy decay analysis," J. Acoust. Soc. Am., vol. 152, no. 2, pp. 942-953, 2022. https://doi.org/10.1121/10.0013416
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def _histogram_edges(
+    minimum: float, maximum: float, resolution: float
+) -> NDArray[np.float64]:
+    lower = np.floor(minimum / resolution) * resolution
+    upper = np.ceil(maximum / resolution) * resolution
+    return np.arange(lower, upper + resolution / 2.0, resolution)
+
+
+def _kmedians_1d(
+    values: NDArray[np.float64],
+    n_clusters: int,
+    *,
+    seed: int,
+    n_init: int = 5,
+    max_iter: int = 10_000,
+) -> tuple[NDArray[np.int64], NDArray[np.float64]]:
+    generator = np.random.default_rng(seed)
+    unique = np.unique(values)
+    if unique.size < n_clusters:
+        raise ValueError("fewer distinct positive values than requested clusters.")
+    best_cost = np.inf
+    best_labels = np.empty(values.size, dtype=np.int64)
+    best_centers = np.empty(n_clusters, dtype=np.float64)
+    for _ in range(n_init):
+        centers = generator.choice(unique, size=n_clusters, replace=False).astype(float)
+        labels = np.full(values.size, -1, dtype=np.int64)
+        for _ in range(max_iter):
+            updated_labels = np.argmin(
+                np.abs(values[:, np.newaxis] - centers[np.newaxis, :]), axis=1
+            )
+            if np.array_equal(updated_labels, labels):
+                break
+            labels = updated_labels
+            for cluster in range(n_clusters):
+                members = values[labels == cluster]
+                if members.size:
+                    centers[cluster] = np.median(members)
+        cost = float(np.sum(np.abs(values - centers[labels])))
+        if cost < best_cost:
+            best_cost = cost
+            best_labels = labels.copy()
+            best_centers = centers.copy()
+    return best_labels, best_centers
+
+
+def determine_common_decay_times(
+    t60_s: ArrayLike,
+    n_common_slopes: int,
+    *,
+    histogram_resolution_s: float = 0.05,
+    seed: int = 42,
+) -> tuple[NDArray[np.float64], NDArray[np.int64]]:
+    """Cluster per-RIR energy decay times into Georg-style common slopes.
+
+    Positive entries of ``t60_s`` are clustered by one-dimensional L1 k-medians. Each common time is the center of the most populated histogram bin within its sorted cluster.
+
+    Returns
+    -------
+    common_t60_s, cluster_sizes
+        Sorted shared energy decay times in seconds, shape ``(K,)``, and the number of positive DecayFitNet samples assigned to each cluster, shape ``(K,)``.
+    """
+
+    values = np.asarray(t60_s, dtype=np.float64)
+    positive = values[np.isfinite(values) & (values > 0.0)].ravel()
+    if n_common_slopes <= 0:
+        raise ValueError("n_common_slopes must be positive.")
+    if positive.size < n_common_slopes:
+        raise ValueError("too few positive decay times for requested clusters.")
+    if not np.isfinite(histogram_resolution_s) or histogram_resolution_s <= 0.0:
+        raise ValueError("histogram_resolution_s must be finite and positive.")
+    labels, centers = _kmedians_1d(
+        positive, n_common_slopes, seed=seed
+    )
+    cluster_order = np.argsort(centers)
+    edges = _histogram_edges(
+        float(np.min(positive)),
+        float(np.max(positive)),
+        histogram_resolution_s,
+    )
+    common = np.empty(n_common_slopes, dtype=np.float64)
+    cluster_sizes = np.empty(n_common_slopes, dtype=np.int64)
+    for output_index, cluster_index in enumerate(cluster_order):
+        members = positive[labels == cluster_index]
+        if members.size == 0:
+            raise RuntimeError("k-medians produced an empty common-slope cluster.")
+        counts, _ = np.histogram(members, bins=edges)
+        peak = int(np.argmax(counts))
+        common[output_index] = np.mean(edges[peak : peak + 2])
+        cluster_sizes[output_index] = members.size
+    return common, cluster_sizes
+
+
+def edc_to_equivalent_rir_power_amplitudes(
+    amplitudes_edc: ArrayLike,
+    t60_s: ArrayLike,
+    sample_rate_hz: float,
+) -> NDArray[np.float64]:
+    """Convert EDC coefficients to discrete-time RIR power amplitudes.
+
+    ``amplitudes_edc`` and ``t60_s`` must broadcast on their final slope axis.
+    The returned power amplitudes use the same absolute energy units multiplied
+    by ``1 - exp(-6 log(10)/(fs*T60))``. They remain band-filter dependent and
+    are not numerically identical to STFT-bin variance amplitudes.
+
+    Returns
+    -------
+    ndarray
+        Equivalent unit-origin per-sample RIR power amplitudes, with the
+        broadcast shape of ``amplitudes_edc`` and ``t60_s``.
+    """
+
+    amplitudes = np.asarray(amplitudes_edc, dtype=np.float64)
+    t60 = np.asarray(t60_s, dtype=np.float64)
+    if np.any(amplitudes < 0.0) or not np.all(np.isfinite(amplitudes)):
+        raise ValueError("amplitudes_edc must contain finite non-negative values.")
+    if np.any(t60 <= 0.0) or not np.all(np.isfinite(t60)):
+        raise ValueError("t60_s must contain finite positive values.")
+    factor = -np.expm1(-6.0 * np.log(10.0) / (sample_rate_hz * t60))
+    return amplitudes * factor

common_slope_nmf-0.1.0/common_slope_nmf/loss.py

@@ -0,0 +1,64 @@
+"""Itakura--Saito criterion for complex-Gaussian variance models."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .util import _positive_array
+
+Reduction = Literal["none", "sum", "mean"]
+
+
+def _matching_power_and_variance(
+    observed_power: ArrayLike,
+    model_variance: ArrayLike,
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    power = _positive_array("observed_power", observed_power)
+    variance = _positive_array("model_variance", model_variance)
+    if power.shape != variance.shape:
+        raise ValueError("observed_power and model_variance must have the same shape.")
+    return power, variance
+
+
+def _reduce(
+    values: NDArray[np.float64], reduction: Reduction
+) -> float | NDArray[np.float64]:
+    if reduction == "none":
+        return values
+    if reduction == "sum":
+        return float(np.sum(values))
+    if reduction == "mean":
+        return float(np.mean(values))
+    raise ValueError("reduction must be 'none', 'sum', or 'mean'.")
+
+
+def is_divergence(
+    observed_power: ArrayLike,
+    model_variance: ArrayLike,
+    *,
+    reduction: Reduction = "sum",
+) -> float | NDArray[np.float64]:
+    """Evaluate the Itakura--Saito divergence ``d_IS(Y | V)``.
+
+    Parameters
+    ----------
+    observed_power
+        Strictly positive observed energy/power ``Y``.
+    model_variance
+        Strictly positive model variance ``V`` with the same shape and energy/power units as ``observed_power``.
+    reduction
+        ``"sum"`` or ``"mean"`` returns a scalar; ``"none"`` returns the elementwise divergence with the same shape as ``Y`` and ``V``.
+
+    Returns
+    -------
+    float or ndarray
+        ``Y / V - log(Y / V) - 1`` after the requested reduction. The divergence is dimensionless and invariant to a common positive scale applied to ``Y`` and ``V``.
+    """
+
+    power, variance = _matching_power_and_variance(observed_power, model_variance)
+    log_ratio = np.log(power) - np.log(variance)
+    values = np.expm1(log_ratio) - log_ratio
+    return _reduce(values, reduction)

common_slope_nmf-0.1.0/common_slope_nmf/model.py

@@ -0,0 +1,129 @@
+"""Physical parameter transforms and exponential variance construction."""
+
+from __future__ import annotations
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .util import _nonnegative_array, _positive_array
+
+_T60_RATE_PRODUCT = 6.0 * np.log(10.0)
+
+
+def t60_to_rate(t60_s: ArrayLike) -> float | NDArray[np.float64]:
+    """Convert energy-decay ``T60`` values in seconds to rates in ``s^-1``.
+
+    Parameters
+    ----------
+    t60_s
+        Positive scalar or array of energy/power ``T60`` values in seconds.
+
+    Returns
+    -------
+    float or ndarray
+        Decay rates with the same shape as ``t60_s``. A scalar input returns a scalar. The convention is ``rate = 6 log(10) / T60``.
+    """
+
+    t60 = _positive_array("t60_s", t60_s)
+    rate = _T60_RATE_PRODUCT / t60
+    return float(rate) if rate.ndim == 0 else rate
+
+
+def rate_to_t60(rate_per_s: ArrayLike) -> float | NDArray[np.float64]:
+    """Convert energy-decay rates in ``s^-1`` to ``T60`` values in seconds.
+
+    Parameters
+    ----------
+    rate_per_s
+        Positive scalar or array of exponential energy-decay rates in inverse seconds.
+
+    Returns
+    -------
+    float or ndarray
+        Energy/power ``T60`` values with the same shape as ``rate_per_s``. A scalar input returns a scalar.
+    """
+
+    rate = _positive_array("rate_per_s", rate_per_s)
+    t60 = _T60_RATE_PRODUCT / rate
+    return float(t60) if t60.ndim == 0 else t60
+
+
+def exponential_features(
+    frame_time_s: ArrayLike, rate_per_s: ArrayLike
+) -> NDArray[np.float64]:
+    """Construct unit-origin exponential energy-decay features.
+
+    Parameters
+    ----------
+    frame_time_s
+        One-dimensional time vector of STFT frame elapsed time in seconds, shape ``(N,)``. Values must be finite and non-negative. Frame zero is the decay origin.
+    rate_per_s
+        Positive decay rates in inverse seconds, shape ``(..., K)``. A scalar is interpreted as one component.
+
+    Returns
+    -------
+    ndarray
+        Exponential features ``exp(-rate * time)``, shape ``(..., K, N)``. Every feature equals one at frame time zero.
+    """
+
+    frame_time_s = _nonnegative_array("frame_time_s", frame_time_s)
+    if frame_time_s.ndim != 1:
+        raise ValueError("frame_time_s must be one-dimensional.")
+
+    rates = np.atleast_1d(_positive_array("rate_per_s", rate_per_s))
+    return np.exp(-rates[..., np.newaxis] * frame_time_s)
+
+
+def exponential_variance(
+    frame_time_s: ArrayLike,
+    rate_per_s: ArrayLike,
+    amplitudes: ArrayLike,
+    noise_floor: ArrayLike = 0.0,
+) -> NDArray[np.float64]:
+    """Evaluate a non-negative sum of exponential variance components.
+
+    Parameters
+    ----------
+    frame_time_s
+        Time vector of STFT frame elapsed time in seconds, shape ``(N,)``. Frame zero is the decay origin.
+    rate_per_s
+        Positive shared rates in inverse seconds, shape ``(..., K)``. For the full model this is commonly ``(F, K)``.
+    amplitudes
+        Non-negative energy/variance amplitudes at ``frame_time_s == 0``, with a shape broadcastable with ``rate_per_s``. This is commonly ``(R, F, K)``.
+    noise_floor
+        Non-negative time-invariant variance, broadcastable to the parameter batch shape after the component axis is removed. This is commonly ``(R, F)``.
+
+    Returns
+    -------
+    ndarray
+        Total variance, shape ``broadcast(rate_per_s, amplitudes)[:-1] + (N,)``. A scalar rate and scalar amplitude produce shape ``(N,)``.
+    """
+
+    frame_time_s = _nonnegative_array("frame_time_s", frame_time_s)
+    if frame_time_s.ndim != 1:
+        raise ValueError("frame_time_s must be one-dimensional.")
+
+    rates = np.atleast_1d(_positive_array("rate_per_s", rate_per_s))
+    weights = np.atleast_1d(_nonnegative_array("amplitudes", amplitudes))
+
+    try:
+        rates, weights = np.broadcast_arrays(rates, weights)
+    except ValueError as exc:
+        raise ValueError(
+            "rate_per_s and amplitudes must have broadcast-compatible shapes."
+        ) from exc
+
+    components = weights[..., np.newaxis] * np.exp(
+        -rates[..., np.newaxis] * frame_time_s
+    )
+    variance = np.sum(components, axis=-2)
+
+    floor = _nonnegative_array("noise_floor", noise_floor)
+    try:
+        floor = np.broadcast_to(floor, variance.shape[:-1])
+    except ValueError as exc:
+        raise ValueError(
+            "noise_floor must broadcast to the parameter batch shape."
+        ) from exc
+
+    return variance + floor[..., np.newaxis]