pyofdr 1.0.0__tar.gz

pyofdr-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Meoli
+
+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.

pyofdr-1.0.0/LICENSES/colorednoise-MIT.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2014-2017 Felix Patzelt
+
+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.

pyofdr-1.0.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: pyofdr
+Version: 1.0.0
+Summary: OFDR simulator for distributed fiber sensing
+Author-email: "A. Meoli" <alessandro.meoli@unicampania.it>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ameoli/PyOFDR
+Project-URL: Issues, https://github.com/ameoli/PyOFDR/issues
+Keywords: ofdr,fiber sensing,rayleigh,interferometry,simulation
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: LICENSES/colorednoise-MIT.txt
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pint>=0.22
+Requires-Dist: h5py>=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Provides-Extra: tutorials
+Requires-Dist: matplotlib; extra == "tutorials"
+Requires-Dist: jupyterlab; extra == "tutorials"
+Requires-Dist: ipykernel; extra == "tutorials"
+Dynamic: license-file
+
+# PyOFDR
+[![Tests](https://github.com/ameoli/PyOFDR/actions/workflows/tests.yml/badge.svg)](https://github.com/ameoli/PyOFDR/actions/workflows/tests.yml)
+![license](https://img.shields.io/github/license/ameoli/PyOFDR)
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+
+PyOFDR simulates optical frequency domain reflectometry (OFDR) in Python. Give it a fiber, a laser sweep and a receiver. It returns the digitized beat signal for each fiber core. You can use these traces to check a strain recovery algorithm against a known input, study receiver noise or try different sweep and sampling settings.
+
+![Distributed strain shift recovered from PyOFDR](https://raw.githubusercontent.com/ameoli/PyOFDR/main/docs/img/strain_shift.png)
+
+*1000 microstrain applied to a 1 m segment of a 10 m fiber, recovered from a single PyOFDR run by sub-spectrum cross-correlation against an unstrained baseline.*
+
+## Status
+
+PyOFDR runs on the NumPy backend and requires Python 3.10 or later. CI runs on Windows and Ubuntu with Python 3.10, 3.11 and 3.12. The [pipeline validation section](https://github.com/ameoli/PyOFDR/blob/main/docs/theory.md#pipeline-level-validation) gives the tested cases and their numerical tolerances.
+
+## What's simulated
+| Stage | Modelled |
+|---|---|
+| **Source** | linear sweep + nonlinearity + ripple, phase noise (Wiener + flicker + RW), RIN, coherence roll-off |
+| **Interferometer** | main Mach-Zehnder, auxiliary MZI for k-clock resampling, optical circulator, weak FBG arrays |
+| **Fiber** | Rayleigh backscatter, attenuation, macrobend loss, discrete reflectors, chromatic dispersion (GVD), stochastic n(z), multiple-scattering ghosts, MCF core-to-core crosstalk |
+| **Perturbations** | static + dynamic strain (harmonic, impulsive, thermal relaxation, random vibration), Cox shear-lag coating coupling, distributed temperature with strain-T cross-sensitivity |
+| **Detection** | single-ended or balanced photodetection, shot, thermal and dark-current noise, photodiode saturation and nonlinearity, Butterworth low-pass filter |
+| **ADC** | clip, quantize, jitter, DNL/INL, ENOB |
+| **Output** | HDF5 streaming, multi-sweep campaigns |
+
+For equations and model limits, see the [theory guide](https://github.com/ameoli/PyOFDR/blob/main/docs/theory.md). The [configuration reference](https://github.com/ameoli/PyOFDR/blob/main/docs/config_reference.md) describes the YAML fields and units. The [architecture guide](https://github.com/ameoli/PyOFDR/blob/main/docs/architecture.md) follows a sweep through the simulation and describes the output arrays.
+
+## Install
+
+To install the published package from PyPI, run `python -m pip install pyofdr` in a virtual environment.
+
+For the basic YAML configuration, notebooks and tests, clone the repository and create a virtual environment.
+
+```bash
+git clone https://github.com/ameoli/PyOFDR.git
+cd PyOFDR
+python -m venv .venv
+```
+
+Activate it with `.\.venv\Scripts\Activate.ps1` in PowerShell or `source .venv/bin/activate` on Linux and macOS. Then install the package from the repository root.
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+From the repository root, run the [basic configuration](https://github.com/ameoli/PyOFDR/blob/main/configs/ofdr_basic.yaml). It simulates a 10 m fiber and a 40 nm sweep in 10 ms at 200 MS/s. `info` shows the spatial spacing and Nyquist limit. `validate` checks the configuration, and `run` writes the simulated sweep to HDF5.
+
+```bash
+pyofdr info configs/ofdr_basic.yaml
+pyofdr validate configs/ofdr_basic.yaml
+pyofdr run configs/ofdr_basic.yaml -o out.h5
+```
+
+In `out.h5`, `sweeps/0000/digital_main` holds the ADC counts with shape `(1, 2000000)` for this configuration. To work in Python, run the same sweep in memory and compute its reflectogram. The helper uses the FFT spacing stored in the acquisition.
+
+```python
+from pyofdr.analysis.demodulation import reflectogram_from_acq
+from pyofdr.core.campaign import run_campaign
+from pyofdr.core.config import load_config
+
+cfg = load_config("configs/ofdr_basic.yaml")
+acq = run_campaign(cfg)[0]
+H, z = reflectogram_from_acq(acq, core=0)
+print(acq.digital_main.shape)  # (1, 2000000)
+print(z[1] - z[0])             # FFT bin spacing in metres
+```
+
+## Examples
+From the repository root, install the tutorials and start JupyterLab in the same environment:
+
+```bash
+python -m pip install -e ".[tutorials]"
+python -m jupyterlab examples/
+```
+
+Open a notebook and run all cells from the beginning. The examples load the basic YAML configuration relative to the notebook directory.
+
+- [00: Fiber signature](https://github.com/ameoli/PyOFDR/blob/main/examples/00_fiber_signature.ipynb) compares Rayleigh statistics with theory.
+- [01: Reflectogram basics](https://github.com/ameoli/PyOFDR/blob/main/examples/01_reflectogram_basics.ipynb) maps ADC samples to distance and compares repeated sweeps.
+- [02: Reflector loss and linewidth](https://github.com/ameoli/PyOFDR/blob/main/examples/02_reflector_loss_and_linewidth.ipynb) measures round-trip attenuation, coherence loss and peak width.
+- [03: Strain recovery](https://github.com/ameoli/PyOFDR/blob/main/examples/03_strain_recovery.ipynb) recovers an imposed strain from two Rayleigh traces.
+- [04: Noise budget](https://github.com/ameoli/PyOFDR/blob/main/examples/04_noise_budget.ipynb) compares predicted and measured shot, thermal and quantization noise.
+
+## Tests
+
+Install the test dependencies in the same environment and run the suite from the repository root.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest tests/ -q
+```
+
+## Citing
+If you use PyOFDR in published work, please cite it.
+
+```bibtex
+@software{pyofdr,
+  author = {Meoli, Alessandro},
+  title  = {PyOFDR: an end-to-end Python simulator for Optical Frequency Domain Reflectometry},
+  year   = {2026},
+  url    = {https://github.com/ameoli/PyOFDR},
+}
+```
+
+## References
+- Froggatt and Moore, *High-spatial-resolution distributed strain measurement in optical fiber with Rayleigh scatter*, Appl Opt 1998.
+- Soller et al., *High resolution OFDR for characterization of components and assemblies*, Opt Express 2005.
+- Hartog, *An Introduction to Distributed Optical Fibre Sensors*, CRC 2017.
+
+## License
+PyOFDR is distributed under the [MIT license](https://github.com/ameoli/PyOFDR/blob/main/LICENSE).
+
+### Third-party
+The laser noise generator uses [colorednoise](https://github.com/felixpatzelt/colorednoise) by Felix Patzelt. Its [MIT license](https://github.com/ameoli/PyOFDR/blob/main/LICENSES/colorednoise-MIT.txt) is included in the source and wheel distributions.
+
+## Issues and contributions
+Report bugs and feature requests in [GitHub Issues](https://github.com/ameoli/PyOFDR/issues). For simulation bugs, include the YAML configuration and the command that reproduces the problem. Pull requests are welcome.
+
+Maintainers can follow the [release instructions](https://github.com/ameoli/PyOFDR/blob/main/docs/releasing.md) to publish a tagged version on PyPI.

pyofdr-1.0.0/README.md

@@ -0,0 +1,122 @@
+# PyOFDR
+[![Tests](https://github.com/ameoli/PyOFDR/actions/workflows/tests.yml/badge.svg)](https://github.com/ameoli/PyOFDR/actions/workflows/tests.yml)
+![license](https://img.shields.io/github/license/ameoli/PyOFDR)
+![python](https://img.shields.io/badge/python-3.10%2B-blue)
+
+PyOFDR simulates optical frequency domain reflectometry (OFDR) in Python. Give it a fiber, a laser sweep and a receiver. It returns the digitized beat signal for each fiber core. You can use these traces to check a strain recovery algorithm against a known input, study receiver noise or try different sweep and sampling settings.
+
+![Distributed strain shift recovered from PyOFDR](https://raw.githubusercontent.com/ameoli/PyOFDR/main/docs/img/strain_shift.png)
+
+*1000 microstrain applied to a 1 m segment of a 10 m fiber, recovered from a single PyOFDR run by sub-spectrum cross-correlation against an unstrained baseline.*
+
+## Status
+
+PyOFDR runs on the NumPy backend and requires Python 3.10 or later. CI runs on Windows and Ubuntu with Python 3.10, 3.11 and 3.12. The [pipeline validation section](https://github.com/ameoli/PyOFDR/blob/main/docs/theory.md#pipeline-level-validation) gives the tested cases and their numerical tolerances.
+
+## What's simulated
+| Stage | Modelled |
+|---|---|
+| **Source** | linear sweep + nonlinearity + ripple, phase noise (Wiener + flicker + RW), RIN, coherence roll-off |
+| **Interferometer** | main Mach-Zehnder, auxiliary MZI for k-clock resampling, optical circulator, weak FBG arrays |
+| **Fiber** | Rayleigh backscatter, attenuation, macrobend loss, discrete reflectors, chromatic dispersion (GVD), stochastic n(z), multiple-scattering ghosts, MCF core-to-core crosstalk |
+| **Perturbations** | static + dynamic strain (harmonic, impulsive, thermal relaxation, random vibration), Cox shear-lag coating coupling, distributed temperature with strain-T cross-sensitivity |
+| **Detection** | single-ended or balanced photodetection, shot, thermal and dark-current noise, photodiode saturation and nonlinearity, Butterworth low-pass filter |
+| **ADC** | clip, quantize, jitter, DNL/INL, ENOB |
+| **Output** | HDF5 streaming, multi-sweep campaigns |
+
+For equations and model limits, see the [theory guide](https://github.com/ameoli/PyOFDR/blob/main/docs/theory.md). The [configuration reference](https://github.com/ameoli/PyOFDR/blob/main/docs/config_reference.md) describes the YAML fields and units. The [architecture guide](https://github.com/ameoli/PyOFDR/blob/main/docs/architecture.md) follows a sweep through the simulation and describes the output arrays.
+
+## Install
+
+To install the published package from PyPI, run `python -m pip install pyofdr` in a virtual environment.
+
+For the basic YAML configuration, notebooks and tests, clone the repository and create a virtual environment.
+
+```bash
+git clone https://github.com/ameoli/PyOFDR.git
+cd PyOFDR
+python -m venv .venv
+```
+
+Activate it with `.\.venv\Scripts\Activate.ps1` in PowerShell or `source .venv/bin/activate` on Linux and macOS. Then install the package from the repository root.
+
+```bash
+python -m pip install -e .
+```
+
+## Quick start
+
+From the repository root, run the [basic configuration](https://github.com/ameoli/PyOFDR/blob/main/configs/ofdr_basic.yaml). It simulates a 10 m fiber and a 40 nm sweep in 10 ms at 200 MS/s. `info` shows the spatial spacing and Nyquist limit. `validate` checks the configuration, and `run` writes the simulated sweep to HDF5.
+
+```bash
+pyofdr info configs/ofdr_basic.yaml
+pyofdr validate configs/ofdr_basic.yaml
+pyofdr run configs/ofdr_basic.yaml -o out.h5
+```
+
+In `out.h5`, `sweeps/0000/digital_main` holds the ADC counts with shape `(1, 2000000)` for this configuration. To work in Python, run the same sweep in memory and compute its reflectogram. The helper uses the FFT spacing stored in the acquisition.
+
+```python
+from pyofdr.analysis.demodulation import reflectogram_from_acq
+from pyofdr.core.campaign import run_campaign
+from pyofdr.core.config import load_config
+
+cfg = load_config("configs/ofdr_basic.yaml")
+acq = run_campaign(cfg)[0]
+H, z = reflectogram_from_acq(acq, core=0)
+print(acq.digital_main.shape)  # (1, 2000000)
+print(z[1] - z[0])             # FFT bin spacing in metres
+```
+
+## Examples
+From the repository root, install the tutorials and start JupyterLab in the same environment:
+
+```bash
+python -m pip install -e ".[tutorials]"
+python -m jupyterlab examples/
+```
+
+Open a notebook and run all cells from the beginning. The examples load the basic YAML configuration relative to the notebook directory.
+
+- [00: Fiber signature](https://github.com/ameoli/PyOFDR/blob/main/examples/00_fiber_signature.ipynb) compares Rayleigh statistics with theory.
+- [01: Reflectogram basics](https://github.com/ameoli/PyOFDR/blob/main/examples/01_reflectogram_basics.ipynb) maps ADC samples to distance and compares repeated sweeps.
+- [02: Reflector loss and linewidth](https://github.com/ameoli/PyOFDR/blob/main/examples/02_reflector_loss_and_linewidth.ipynb) measures round-trip attenuation, coherence loss and peak width.
+- [03: Strain recovery](https://github.com/ameoli/PyOFDR/blob/main/examples/03_strain_recovery.ipynb) recovers an imposed strain from two Rayleigh traces.
+- [04: Noise budget](https://github.com/ameoli/PyOFDR/blob/main/examples/04_noise_budget.ipynb) compares predicted and measured shot, thermal and quantization noise.
+
+## Tests
+
+Install the test dependencies in the same environment and run the suite from the repository root.
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest tests/ -q
+```
+
+## Citing
+If you use PyOFDR in published work, please cite it.
+
+```bibtex
+@software{pyofdr,
+  author = {Meoli, Alessandro},
+  title  = {PyOFDR: an end-to-end Python simulator for Optical Frequency Domain Reflectometry},
+  year   = {2026},
+  url    = {https://github.com/ameoli/PyOFDR},
+}
+```
+
+## References
+- Froggatt and Moore, *High-spatial-resolution distributed strain measurement in optical fiber with Rayleigh scatter*, Appl Opt 1998.
+- Soller et al., *High resolution OFDR for characterization of components and assemblies*, Opt Express 2005.
+- Hartog, *An Introduction to Distributed Optical Fibre Sensors*, CRC 2017.
+
+## License
+PyOFDR is distributed under the [MIT license](https://github.com/ameoli/PyOFDR/blob/main/LICENSE).
+
+### Third-party
+The laser noise generator uses [colorednoise](https://github.com/felixpatzelt/colorednoise) by Felix Patzelt. Its [MIT license](https://github.com/ameoli/PyOFDR/blob/main/LICENSES/colorednoise-MIT.txt) is included in the source and wheel distributions.
+
+## Issues and contributions
+Report bugs and feature requests in [GitHub Issues](https://github.com/ameoli/PyOFDR/issues). For simulation bugs, include the YAML configuration and the command that reproduces the problem. Pull requests are welcome.
+
+Maintainers can follow the [release instructions](https://github.com/ameoli/PyOFDR/blob/main/docs/releasing.md) to publish a tagged version on PyPI.

pyofdr-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyofdr"
+version = "1.0.0"
+description = "OFDR simulator for distributed fiber sensing"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "LICENSES/colorednoise-MIT.txt"]
+requires-python = ">=3.10"
+authors = [
+    {name = "A. Meoli", email = "alessandro.meoli@unicampania.it"},
+]
+keywords = ["ofdr", "fiber sensing", "rayleigh", "interferometry", "simulation"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+    "numpy>=1.24",
+    "scipy>=1.10",
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "pint>=0.22",
+    "h5py>=3.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/ameoli/PyOFDR"
+Issues = "https://github.com/ameoli/PyOFDR/issues"
+
+[project.scripts]
+pyofdr = "pyofdr.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+tutorials = ["matplotlib", "jupyterlab", "ipykernel"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pyofdr-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pyofdr-1.0.0/src/pyofdr/__init__.py

@@ -0,0 +1,3 @@
+"""PyOFDR -- OFDR simulator for distributed fiber sensing."""
+
+__version__ = "1.0.0"

pyofdr-1.0.0/src/pyofdr/analysis/__init__.py

@@ -0,0 +1 @@
+"""Analytical tools that derive system figures of merit from the config."""

pyofdr-1.0.0/src/pyofdr/analysis/budget.py

@@ -0,0 +1,278 @@
+"""Analytical OFDR budget calculator.
+
+Config-based estimates -- no simulation. Covers:
+  - geometric quantities (dz, max beat frequency, Nyquist headroom)
+  - optical power chain (laser -> splitter -> circulator -> fiber)
+  - Rayleigh backscatter at near/far end
+  - receiver noise floor (shot, thermal, dark, RIN, quantization)
+  - NEP referred to optical input
+  - dynamic range
+  - phase-noise RMS at the far end (kept separate from the current RSS)
+  - strain / temperature sensitivity + max unambiguous strain
+
+Noise quantities are input-referred current standard deviations. Receiver
+noise is integrated over the digital Butterworth noise bandwidth; ADC noise
+is added afterwards over the full Nyquist band. RIN in the current pipeline
+is multiplicative on the beat, so its estimate needs the noiseless pre-filter
+beat RMS. Missing RIN input yields NaN rather than a reference-arm DC estimate.
+
+See issue #43.
+"""
+
+from __future__ import annotations
+
+import math
+from functools import lru_cache
+from typing import Any
+
+from scipy.integrate import quad
+
+from pyofdr.core.config import compute_derived
+from pyofdr.core.config_models import RootConfig
+from pyofdr.utils.constants import C, E_CHARGE
+from pyofdr.utils.units import dB_to_linear
+
+
+@lru_cache(maxsize=128)
+def _noise_bandwidth(fs: float, bandwidth: float, order: int) -> float:
+    """One-sided integral of the digital Butterworth |H(f)|^2, in Hz.
+
+    Use the same 0.99-Nyquist cutoff clamp as AntiAliasFilter. The bilinear
+    substitution x = tan(pi*f/fs)/tan(pi*fc/fs) resolves even narrow filters
+    without a frequency grid tied to fs. Split at x=1 (the cutoff).
+    """
+    cutoff = min(bandwidth, 0.99 * fs / 2.0)
+    a = math.tan(math.pi * cutoff / fs)
+
+    def integrand(x):
+        if x <= 1.0:
+            gain_sq = 1.0 / (1.0 + x ** (2 * order))
+        else:
+            inverse_power = x ** (-2 * order)
+            gain_sq = inverse_power / (1.0 + inverse_power)
+        return gain_sq / (1.0 + (a * x) ** 2)
+
+    area = quad(integrand, 0.0, 1.0, epsabs=1e-10)[0]
+    area += quad(integrand, 1.0, math.inf, epsabs=1e-10)[0]
+    return fs * a / math.pi * area
+
+
+def compute_budget(
+    cfg: dict[str, Any], *, beat_rms_current: float | None = None,
+) -> dict[str, float]:
+    """Return budget quantities in SI for the configured receiver mode.
+
+    ``beat_rms_current`` is sqrt(mean(I_beat**2)) in A, before the receiver
+    filter, from a noiseless linear run (including any optical leakage).
+    It is required only when source RIN is enabled. Then sigma_rin, sigma_analog,
+    sigma_total, nep_total and dynamic_range_dB are NaN if it is omitted;
+    sigma_receiver still reports the known additive receiver contribution.
+
+    Estimates assume reference-dominated shot noise, a linear unsaturated
+    detector, weak unclipped white RIN, and settled filter statistics. ADC
+    quantization uses the uniform-error approximation; ENOB extra noise is
+    included, but jitter and DNL/INL are not. No post-ADC filtering is assumed.
+    Phase-noise RMS is a separate theoretical quantity, not a prediction of
+    the MZI's stochastic white-FM pedestal (which is not simulated).
+    """
+    if beat_rms_current is not None and (
+        not math.isfinite(beat_rms_current) or beat_rms_current < 0
+    ):
+        raise ValueError("beat_rms_current must be finite and nonnegative (A)")
+    cfg = RootConfig(**cfg).model_dump()
+
+    src_ = cfg["source"]
+    opt  = cfg["optics"]
+    fib  = cfg["fiber"]
+    det  = cfg["detection"]
+    adc  = cfg["adc"]
+
+    P_laser = src_["power"]
+    wl      = src_["center_wavelength"]
+    lw      = src_["linewidth"]
+    rin     = src_["rin_dB_per_Hz"]
+    eta     = opt["splitting_ratio"]
+    IL_circ = opt["circulator"]["insertion_loss_dB"]
+
+    # use the homogeneous terms only -- segments are a refinement that
+    # this first pass doesn't try to account for
+    alpha_dB_km = fib["attenuation_dB_per_km"]
+    R_dB        = fib["rayleigh_coefficient_dB"]
+    L           = fib["length"]
+    n_core      = fib["n_core"]
+
+    R_resp = det["responsivity"]
+    NEP    = det["thermal_nep"]
+    I_dark = det["dark_current"]
+    B      = det["bandwidth"]
+    I_sat  = det["saturation_current"]
+
+    bits = adc["bits"]
+    V_fs = adc["voltage_range"]
+    Z    = adc["input_impedance"]
+    fs   = adc["sample_rate"]
+    noise_bandwidth = _noise_bandwidth(fs, B, det["filter_order"])
+
+    # --- optical power chain (all linear [W]) --------------------------
+    il_circ_lin = dB_to_linear(-IL_circ)
+    P_ref_arm   = eta * P_laser
+    P_to_fiber  = (1.0 - eta) * P_laser * il_circ_lin
+
+    # one-way power attenuation coefficient [1/m]
+    alpha_m   = alpha_dB_km * math.log(10.0) / 10.0 / 1000.0
+    R_per_m   = dB_to_linear(R_dB)       # backscattered power per metre of fiber
+
+    def _back_from(z):
+        # power backscattered by a 1-m slab at z, through the circulator back
+        return P_to_fiber * R_per_m * math.exp(-2.0 * alpha_m * z) * il_circ_lin
+
+    P_back_near = _back_from(0.0)
+    P_back_far  = _back_from(L)
+
+    # --- receiver -------------------------------------------------------
+    # Keep I_dc_ref as the pre-recombiner reference-arm equivalent current.
+    # The 50/50 recombiner sends half to each PD, in both receiver modes.
+    I_dc = R_resp * P_ref_arm
+    I_dc_pd = 0.5 * I_dc
+    n_pd = 2 if det["balanced"] else 1
+
+    sigma_shot = (
+        math.sqrt(2.0 * E_CHARGE * n_pd * I_dc_pd * noise_bandwidth)
+        if det["shot_noise"] else 0.0
+    )
+    # One TIA after the subtraction node; dark current is specified per PD.
+    sigma_thermal = R_resp * NEP * math.sqrt(noise_bandwidth)
+    sigma_dark = math.sqrt(2.0 * E_CHARGE * n_pd * I_dark * noise_bandwidth)
+
+    # The simulator propagates RIN on the beat in BOTH modes. Reference-arm
+    # common-mode DC RIN is not propagated, so I_dc*sqrt(RIN*B) is not its floor.
+    if rin is not None:
+        rin_lin   = 10.0 ** (rin / 10.0)
+        sigma_rin = (
+            beat_rms_current * math.sqrt(rin_lin * noise_bandwidth)
+            if beat_rms_current is not None else math.nan
+        )
+    else:
+        sigma_rin = 0.0
+
+    # ADC is downstream of the analog filter: its error has NOT been filtered.
+    sigma_q_V_tot = V_fs / (2 ** bits) / math.sqrt(12.0)
+    sigma_quant = sigma_q_V_tot / Z
+    enob = adc["enob"]
+    sigma_adc_extra = 0.0
+    if enob is not None and enob < bits:
+        sigma_enob = V_fs / (2.0 ** enob * math.sqrt(12.0)) / Z
+        sigma_adc_extra = math.sqrt(sigma_enob ** 2 - sigma_quant ** 2)
+
+    sigma_receiver = math.sqrt(sigma_shot ** 2 + sigma_thermal ** 2 + sigma_dark ** 2)
+    sigma_analog = math.hypot(sigma_receiver, sigma_rin)
+    sigma_total = math.sqrt(sigma_analog ** 2 + sigma_quant ** 2 + sigma_adc_extra ** 2)
+
+    nep_total = sigma_total / R_resp     # integrated sampled noise, W RMS
+
+    # A reference-current proxy unless a saturation limit is supplied;
+    # this does not account for ADC clipping or nonlinear detector gain.
+    I_max = I_sat if I_sat is not None else n_pd * I_dc_pd
+    if math.isnan(sigma_total):
+        dynamic_range_dB = math.nan
+    elif sigma_total > 0:
+        dynamic_range_dB = 20.0 * math.log10(I_max / sigma_total)
+    else:
+        dynamic_range_dB = math.inf
+
+    # --- phase noise at the far end ------------------------------------
+    # Lorentzian source, round-trip delay tau = 2 n L / c:
+    # <Dphi^2> = 2*pi*lw*tau.   Meaningful only when tau << 1/lw.
+    tau_far   = 2.0 * n_core * L / C
+    sigma_phi = math.sqrt(2.0 * math.pi * lw * tau_far) if lw > 0 else 0.0
+
+    # --- strain / temperature sensitivity ------------------------------
+    # Rayleigh spectral shift (Froggatt-Moore):
+    #   Dnu / nu = - ((1-p_e)*eps + (alpha_L + xi)*DT)
+    nu_c       = C / wl
+    p_e = cfg["strain"]["photoelastic_coefficient"]
+    alpha_L = cfg["temperature"]["thermal_expansion"]
+    xi = cfg["temperature"]["thermo_optic"]
+    d_nu_d_eps = -(1.0 - p_e) * nu_c       # Hz per unit strain
+    d_nu_d_T   = -(alpha_L + xi) * nu_c    # Hz per K
+
+    # --- max unambiguous strain ----------------------------------------
+    # Absolute ceiling from the spectral shift method: the cross-correlation
+    # window can track a shift up to +/- delta_nu/2. Processing with a finite
+    # gauge length makes this tighter in practice.
+    derived  = compute_derived(cfg)
+    delta_nu = derived["delta_nu"]
+    eps_max  = (delta_nu / 2.0) / abs(d_nu_d_eps)
+
+    out = {
+        "P_laser":          P_laser,
+        "P_ref_arm":        P_ref_arm,
+        "P_to_fiber":       P_to_fiber,
+        "P_back_near":      P_back_near,
+        "P_back_far":       P_back_far,
+        "I_dc_ref":         I_dc,
+        "I_dc_pd":          I_dc_pd,
+        "sigma_shot":       sigma_shot,
+        "sigma_thermal":    sigma_thermal,
+        "sigma_dark":       sigma_dark,
+        "sigma_rin":        sigma_rin,
+        "sigma_quant":      sigma_quant,
+        "sigma_adc_extra":  sigma_adc_extra,
+        "sigma_receiver":   sigma_receiver,
+        "sigma_analog":     sigma_analog,
+        "sigma_total":      sigma_total,
+        "nep_total":        nep_total,
+        "dynamic_range_dB": dynamic_range_dB,
+        "bandwidth":        B,
+        "filter_cutoff":    min(B, 0.99 * fs / 2.0),
+        "noise_bandwidth":  noise_bandwidth,
+        "sigma_phi_far":    sigma_phi,
+        "tau_far":          tau_far,
+        "d_nu_d_eps":       d_nu_d_eps,
+        "d_nu_d_T":         d_nu_d_T,
+        "eps_max":          eps_max,
+    }
+    out.update(derived)
+    return out
+
+
+def _dBm(p):
+    return 10.0 * math.log10(p * 1000.0) if p > 0 else float("-inf")
+
+
+def print_budget(cfg: dict[str, Any], *, beat_rms_current: float | None = None) -> None:
+    """Pretty-print the budget for a config dict."""
+    b = compute_budget(cfg, beat_rms_current=beat_rms_current)
+    print("PyOFDR power & noise budget:")
+    print(f"  Spatial resolution:   {b['dz']*1e3:.3f} mm")
+    print(f"  Max beat freq:        {b['f_beat_max']*1e-6:.1f} MHz "
+          f"(Nyquist {b['f_nyquist']*1e-6:.0f} MHz)")
+    print(f"  Laser power:          {_dBm(b['P_laser']):+.1f} dBm")
+    print(f"  Reference arm:        {_dBm(b['P_ref_arm']):+.1f} dBm")
+    print(f"  Into fiber:           {_dBm(b['P_to_fiber']):+.1f} dBm")
+    print(f"  Backscatter /m near:  {_dBm(b['P_back_near']):+.1f} dBm")
+    print(f"  Backscatter /m far:   {_dBm(b['P_back_far']):+.1f} dBm")
+    print(f"  Ref current per PD:   {b['I_dc_pd']*1e3:.3f} mA")
+    print(f"  Filter cutoff:        {b['filter_cutoff']*1e-6:.3f} MHz")
+    print(f"  Receiver noise bandwidth: {b['noise_bandwidth']*1e-6:.3f} MHz")
+    print("  Noise estimates (input-referred current):")
+    print(f"    shot:               {b['sigma_shot']*1e9:.3f} nA")
+    print(f"    thermal:            {b['sigma_thermal']*1e9:.3f} nA")
+    print(f"    dark:               {b['sigma_dark']*1e9:.3f} nA")
+    if math.isnan(b["sigma_rin"]):
+        print("    RIN:                unavailable; supply beat_rms_current (A)")
+    else:
+        print(f"    RIN (beat):         {b['sigma_rin']*1e9:.3f} nA")
+    print(f"    receiver additive:  {b['sigma_receiver']*1e9:.3f} nA")
+    print(f"    quantization:       {b['sigma_quant']*1e9:.3f} nA")
+    print(f"    ADC ENOB extra:     {b['sigma_adc_extra']*1e9:.3f} nA")
+    if math.isnan(b["sigma_total"]):
+        print("    total / NEP / Dynamic range: unavailable without beat RMS")
+    else:
+        print(f"    total (sampled):    {b['sigma_total']*1e9:.3f} nA")
+        print(f"  NEP (sampled total):  {b['nep_total']*1e9:.2f} nW")
+        print(f"  Dynamic range (proxy): {b['dynamic_range_dB']:.1f} dB")
+    print(f"  Phase noise (far, theoretical): {b['sigma_phi_far']*1e3:.2f} mrad RMS")
+    print(f"  Strain sensitivity:   {b['d_nu_d_eps']*1e-12:.2f} MHz/ustrain")
+    print(f"  Temp sensitivity:     {b['d_nu_d_T']*1e-9:.3f} GHz/K")
+    print(f"  Max |strain|:         {b['eps_max']*1e6:.0f} ustrain")