dftmodels 1.0.0__tar.gz

dftmodels-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sven Bodenstedt
+
+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.

dftmodels-1.0.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: dftmodels
+Version: 1.0.0
+Summary: Analytical DFT models with closed-form correction terms for bias-free spectral parameter estimation.
+License-Expression: MIT
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=2.0
+Requires-Dist: scipy>=1.15
+Requires-Dist: lmfit>=1.0
+Dynamic: license-file
+
+# dftmodels
+
+Analytical DFT models for spectral parameter estimation.
+
+## Overview
+
+Fitting peaks in DFT spectra with continuous Fourier transform (CFT) models (sinc functions, Lorentzians, and their window-convolved variants) introduces systematic errors in the estimated amplitude, frequency, phase, and linewidth. Three effects are responsible: the DFT sum gives full weight to the boundary samples where the trapezoidal-rule approximation gives half weight (boundary mismatch); sampling makes the spectrum periodic, introducing aliased copies at f ± k·f_s (aliasing); and the finite window modifies the spectral shape in a way that depends on both the window coefficients and the signal frequency (windowing). Each effect produces a deterministic, structured residual in the DFT.
+
+`dftmodels` provides closed-form analytical models that include these effects as additive correction terms: WINDOW (the CFT of the windowed signal), BASELINE (the boundary weight mismatch), and SAMPLING (aliased spectral copies up to a configurable order). Combined with least-squares fitting, these models form estimators whose variance can approach the Cramér–Rao bound (CRB).
+
+**When corrections matter.** Systematic bias is only the limiting factor when SNR is high and records are short. The SAMPLING correction becomes negligible above a crossover acquisition length that depends on window and noise level (see [Notebook 02](examples/02_dft_corrections.ipynb)). For long records or when noise dominates, a CFT-based sinc or Lorentzian model is adequate. The gains shown in the examples below are large by design — the signal parameters were chosen so that systematic bias is the limiting factor, not noise. The package is most relevant when that condition holds.
+
+## Installation
+
+```bash
+pip install dftmodels
+```
+
+Dependencies: Python ≥ 3.12, `numpy` ≥ 2.0, `scipy` ≥ 1.15, `lmfit` ≥ 1.0.
+
+## Examples
+
+Six notebooks in [examples/](examples/) work through the main topics in sequence.
+
+| Notebook | Topic |
+|---|---|
+| [01 — Normalizations](examples/01_dft_normalization.ipynb) | ASD, PSD, and CFT normalizations; Parseval's theorem |
+| [02 — DFT corrections](examples/02_dft_corrections.ipynb) | Origin and convergence of the three correction terms |
+| [03 — Precision fitting](examples/03_precision_fitting.ipynb) | Sinusoid parameter estimation; bias elimination; Cramér–Rao bound |
+| [04 — Decaying signals](examples/04_decaying_signals.ipynb) | Lorentzian fitting; exponential windows; line broadening |
+| [05 — Composite models](examples/05_composite_model.ipynb) | Simultaneous multi-peak fitting; spectral background |
+| [06 — Window comparison](examples/06_window_comparison.ipynb) | Window choice: Fisher information loss vs. sidelobe suppression |
+
+---
+
+### Normalizations
+
+Three normalizations are provided. **ASD** and **PSD** satisfy Parseval's theorem — ∫|ASD(f)|² df = ∫PSD(f) df = RMS² — and are appropriate for stationary signals. The normalization factor includes the window RMS (w_rms) to compensate for amplitude attenuation; this correction is exact in the limit N → ∞ and introduces a residual error of order 1/N. **CFT** normalization satisfies ∫X_CFT(f) df = x(0) and is appropriate for decaying signals, where total power depends on acquisition length and ASD peak height grows with T.
+
+![CFT vs ASD normalization](examples/figures/01_dft_normalization_fig01.svg)
+
+*Top: CFT normalization — the spectral integral converges to x(0) = A for both decaying (left cluster, 8–12 Hz) and stationary sinusoids (right cluster, 18–22 Hz), independent of T. Bottom: ASD normalization — for stationary sinusoids √∫|ASD|² = RMS is stable; for decaying sinusoids the integral grows with T.*
+
+*[Notebook 01](examples/01_dft_normalization.ipynb). Implementation: `NormType`, `DFTConfig.norm_factor` in [dft/config.py](dftmodels/dft/config.py).*
+
+---
+
+### DFT corrections
+
+An off-bin sinusoid produces a deterministic, structured residual in the DFT that is not captured by the WINDOW-only model. The figure below shows the residual reduction as corrections are applied in sequence. Without corrections, the RMS residual for a rectangular window at N = 100 samples is ~7×10⁻² V/√Hz; with all corrections at order 100 it drops to ~3×10⁻⁵ V/√Hz. For Hann and Nuttall windows, which taper to zero at both boundaries, the BASELINE correction is zero and the SAMPLING correction converges in a few orders; for rectangular and Bartlett windows, higher orders are required (see window sweep table in Notebook 02).
+
+![Correction convergence](examples/figures/02_dft_corrections_fig01.svg)
+
+The corrections become irrelevant above a crossover acquisition length where the noise floor dominates. The figure below sweeps N at fixed f_s and shows the normalized model error for each correction level alongside reference noise floors at fixed σ/A ratios. Below the crossover, the fit is model-limited; above it, noise-limited.
+
+![Corrections vs acquisition length](examples/figures/02_dft_corrections_fig02.svg)
+
+*[Notebook 02](examples/02_dft_corrections.ipynb). Implementation: `DFTCorrection`, `DFTCorrectionMode` in [dft/correction.py](dftmodels/dft/correction.py).*
+
+---
+
+### Precision fitting — sinusoid
+
+300 noise realizations of a rectangular-windowed sinusoid at f₀ = 10.42 Hz (0.42 bins from the nearest bin), T = 1 s, σ = 0.01 V. The table below compares four correction levels; the violin plots show the full error distribution.
+
+| | freq RMSE (mHz) | amp RMSE (mV) | phase RMSE (mrad) |
+|---|---|---|---|
+| CRB | 0.39 | 1.41 | 0.98 |
+| ★ None | 9.90 | 117.4 | 27.18 |
+| ★ All (order 10) | 0.41 | 1.47 | 1.43 |
+
+Frequency and amplitude RMSE approach the CRB once corrections eliminate the systematic bias.
+
+![Precision fitting violin plots](examples/figures/03_precision_fitting_fig01.svg)
+
+*[Notebook 03](examples/03_precision_fitting.ipynb). Implementation: `SineFourier` in [models/sinusoid.py](dftmodels/models/sinusoid.py).*
+
+---
+
+### Decaying signals
+
+For a decaying sinusoid x(t) = A·cos(2πf₀t + φ)·e^{−γt}, the CFT near f₀ is a complex Lorentzian: X(f) ≈ (Ae^{jφ}/2) / (γ + 2πj(f − f₀)). `SineFourier` with a nonzero `decay` parameter implements the exact analytical DFT expression and fits four parameters (frequency f₀, quadrature amplitudes Aᵢ = A cos φ and A_q = A sin φ, and decay rate γ); amplitude A, phase φ, and FWHM = γ/π are derived quantities. The Fisher information matrix for a decaying sinusoid has non-zero off-diagonal coupling between f and γ — the two parameters are not decoupled, unlike the pure sinusoid case.
+
+300 realizations at σ = 0.05 V, T = 5 s, γ = 0.5 s⁻¹:
+
+| | amp RMSE (mV) | phase RMSE (mrad) | freq RMSE (mHz) | decay RMSE (ms⁻¹) |
+|---|---|---|---|---|
+| CRB | 10.20 | 5.13 | 0.62 | 3.87 |
+| ★ None | 59.98 | 5.93 | 0.67 | 34.41 |
+| ★ All (order 10) | 10.03 | 5.14 | 0.61 | 3.83 |
+
+![Lorentzian bare vs corrected](examples/figures/04_decaying_signals_fig02.svg)
+
+Applying an exponential window w(t_n) = e^{−α·t_n/T} before the DFT shifts the effective decay to γ_eff = γ + α/T (line broadening). `LorentzianComplex` with `WindowType.EXPONENTIAL_ASYM` corrects for the window-induced decay shift and recovers the true γ from the broadened spectrum. A bare fit converges to γ_eff, biased by α/T.
+
+*[Notebook 04](examples/04_decaying_signals.ipynb). Implementation: `LorentzianComplex` in [models/lorentzian.py](dftmodels/models/lorentzian.py).*
+
+---
+
+### Composite models
+
+`CompositeModel` fits a weighted sum of named components simultaneously, with all parameters coupled through a shared covariance matrix. For overlapping spectral lines, sequential peak-by-peak fitting propagates subtraction errors; joint fitting avoids this. Each component's parameters are prefixed by name (`p1_frequency`, `p2_decay`, ...).
+
+A J-coupled quartet — four Lorentzian lines with 1:3:3:1 binomial amplitudes at spacing J = 2.5 Hz — illustrates the setup. A linear complex background b₀ + b₁f is included as a fifth component; fitting without it forces the peaks to absorb the baseline, distorting amplitude ratios.
+
+![Composite fit with decomposition](examples/figures/05_composite_model_fig01.svg)
+
+*Top: magnitude spectrum (grey), total fit (dashed), individual peak contributions (dotted), and background (dash-dot). Bottom: residuals with and without a background component in the model.*
+
+The corrected composite estimator approaches the CRB; outer peaks (A = 1 V) have proportionally larger uncertainty than inner peaks (A = 3 V).
+
+*[Notebook 05](examples/05_composite_model.ipynb). Implementation: `CompositeModel` in [models/composite.py](dftmodels/models/composite.py).*
+
+---
+
+### Window choice
+
+The CRB is determined by the raw, unweighted time-domain data and is independent of the window. Any non-rectangular window downweights samples near the record boundaries, discarding Fisher information. This loss cannot be recovered by corrections. For an isolated peak, the rectangular window is the only window whose RMSE approaches the CRB; all others inflate variance proportionally to their effective bandwidth.
+
+![Window RMSE comparison](examples/figures/06_window_comparison_fig00.svg)
+
+*RMSE for frequency (left) and amplitude (right) estimation across six windows at two fractional bin offsets δ = 0 and δ = 0.5. The CRB (dotted line) is the same for both offsets and all windows. N = 1000, f_s = 1000 Hz, σ = 0.05 V, 300 realizations.*
+
+The tradeoff reverses when a nearby peak is absent from the model. Its spectral sidelobes leak into the fit region; the rectangular window has the broadest sidelobe structure (∝ sinc), so its estimator is most sensitive to this. At worst-case interferer offset (δ = 0.484, +5 bins), the rectangular window has a frequency RMSE of 13.5 mHz vs. 2.3 mHz for Hamming.
+
+Window choice therefore depends on context: isolated peaks favour rectangular; peaks with unmodeled nearby components favour windowed estimators.
+
+*[Notebook 06](examples/06_window_comparison.ipynb).*
+
+---
+
+## Usage
+
+```python
+import numpy as np
+from dftmodels import (
+    SignalSeries, NormType, WindowType, DFTRange,
+    DFTCorrection, DFTCorrectionMode, SineFourier,
+)
+
+t  = np.arange(0, 1.0, 1 / 100.0)
+y  = 2.0 * np.cos(2 * np.pi * 10.42 * t + 0.5)
+y += np.random.normal(scale=0.01, size=len(t))
+
+fourier = SignalSeries(x=t, y=y).calculate_dft(
+    norm=NormType.ASD, window=WindowType.RECTANGULAR,
+    dft_range=DFTRange.SINGLE_SIDED, pad=10.0,
+)
+
+model  = SineFourier(fourier.dft_config, DFTCorrection(DFTCorrectionMode.ALL, order=10))
+params = model.make_params(
+    amplitude_i=2.0, amplitude_q=0.0, frequency=10.0,
+    frequency_min=8.0, frequency_max=13.0,
+)
+result = model.fit(fourier, params, mask=(fourier.x >= 8.0) & (fourier.x <= 13.0))
+
+print(f"Amplitude : {model.amplitude(result.params):.6f} V")
+print(f"Frequency : {model.center(result.params):.6f} Hz")
+print(f"Phase     : {model.phase(result.params):.6f} rad")
+```
+
+For decaying signals use `LorentzianComplex` with `NormType.CFT`. For simultaneous multi-peak fitting use `CompositeModel`. See the notebooks for detailed examples of each.
+
+## Models
+
+| Signal type | Model class | Windows |
+|---|---|---|
+| Sinusoid | `SineFourier` | All cosine-sum windows, Bartlett |
+| Decaying sinusoid | `LorentzianComplex` | Rectangular, Exponential |
+| Time-domain (decaying) sinusoid | `Sinusoid` | N/A |
+| Custom | `ModelBase.build_model(fn)` | N/A |
+
+## Limitations
+
+**Scope of corrections.** The correction terms reduce systematic bias from the finite, sampled, windowed DFT. An alternative that achieves the same result is to define the signal model in the time domain and compute the DFT numerically at each evaluation. The analytical corrections are a closed-form shortcut to that approach; they are most efficient when the signal model is simple and the number of evaluations is large. For short-duration signals with few samples, the time-domain approach may be simpler.
+
+**Noise model.** The Cramér–Rao bounds in the examples assume additive white Gaussian noise. Colored noise or non-Gaussian distributions will produce different variance floors; the model residuals remain unbiased but the optimality guarantee does not carry over.
+
+**Model vs. estimator.** The classes in this package are models, not estimators. Combined with a least-squares fitting procedure (`lmfit.Minimizer`), they form estimators. The CRB is a property of the estimator (model + fitting algorithm + noise model), not of the model alone.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

dftmodels-1.0.0/README.md

@@ -0,0 +1,183 @@
+# dftmodels
+
+Analytical DFT models for spectral parameter estimation.
+
+## Overview
+
+Fitting peaks in DFT spectra with continuous Fourier transform (CFT) models (sinc functions, Lorentzians, and their window-convolved variants) introduces systematic errors in the estimated amplitude, frequency, phase, and linewidth. Three effects are responsible: the DFT sum gives full weight to the boundary samples where the trapezoidal-rule approximation gives half weight (boundary mismatch); sampling makes the spectrum periodic, introducing aliased copies at f ± k·f_s (aliasing); and the finite window modifies the spectral shape in a way that depends on both the window coefficients and the signal frequency (windowing). Each effect produces a deterministic, structured residual in the DFT.
+
+`dftmodels` provides closed-form analytical models that include these effects as additive correction terms: WINDOW (the CFT of the windowed signal), BASELINE (the boundary weight mismatch), and SAMPLING (aliased spectral copies up to a configurable order). Combined with least-squares fitting, these models form estimators whose variance can approach the Cramér–Rao bound (CRB).
+
+**When corrections matter.** Systematic bias is only the limiting factor when SNR is high and records are short. The SAMPLING correction becomes negligible above a crossover acquisition length that depends on window and noise level (see [Notebook 02](examples/02_dft_corrections.ipynb)). For long records or when noise dominates, a CFT-based sinc or Lorentzian model is adequate. The gains shown in the examples below are large by design — the signal parameters were chosen so that systematic bias is the limiting factor, not noise. The package is most relevant when that condition holds.
+
+## Installation
+
+```bash
+pip install dftmodels
+```
+
+Dependencies: Python ≥ 3.12, `numpy` ≥ 2.0, `scipy` ≥ 1.15, `lmfit` ≥ 1.0.
+
+## Examples
+
+Six notebooks in [examples/](examples/) work through the main topics in sequence.
+
+| Notebook | Topic |
+|---|---|
+| [01 — Normalizations](examples/01_dft_normalization.ipynb) | ASD, PSD, and CFT normalizations; Parseval's theorem |
+| [02 — DFT corrections](examples/02_dft_corrections.ipynb) | Origin and convergence of the three correction terms |
+| [03 — Precision fitting](examples/03_precision_fitting.ipynb) | Sinusoid parameter estimation; bias elimination; Cramér–Rao bound |
+| [04 — Decaying signals](examples/04_decaying_signals.ipynb) | Lorentzian fitting; exponential windows; line broadening |
+| [05 — Composite models](examples/05_composite_model.ipynb) | Simultaneous multi-peak fitting; spectral background |
+| [06 — Window comparison](examples/06_window_comparison.ipynb) | Window choice: Fisher information loss vs. sidelobe suppression |
+
+---
+
+### Normalizations
+
+Three normalizations are provided. **ASD** and **PSD** satisfy Parseval's theorem — ∫|ASD(f)|² df = ∫PSD(f) df = RMS² — and are appropriate for stationary signals. The normalization factor includes the window RMS (w_rms) to compensate for amplitude attenuation; this correction is exact in the limit N → ∞ and introduces a residual error of order 1/N. **CFT** normalization satisfies ∫X_CFT(f) df = x(0) and is appropriate for decaying signals, where total power depends on acquisition length and ASD peak height grows with T.
+
+![CFT vs ASD normalization](examples/figures/01_dft_normalization_fig01.svg)
+
+*Top: CFT normalization — the spectral integral converges to x(0) = A for both decaying (left cluster, 8–12 Hz) and stationary sinusoids (right cluster, 18–22 Hz), independent of T. Bottom: ASD normalization — for stationary sinusoids √∫|ASD|² = RMS is stable; for decaying sinusoids the integral grows with T.*
+
+*[Notebook 01](examples/01_dft_normalization.ipynb). Implementation: `NormType`, `DFTConfig.norm_factor` in [dft/config.py](dftmodels/dft/config.py).*
+
+---
+
+### DFT corrections
+
+An off-bin sinusoid produces a deterministic, structured residual in the DFT that is not captured by the WINDOW-only model. The figure below shows the residual reduction as corrections are applied in sequence. Without corrections, the RMS residual for a rectangular window at N = 100 samples is ~7×10⁻² V/√Hz; with all corrections at order 100 it drops to ~3×10⁻⁵ V/√Hz. For Hann and Nuttall windows, which taper to zero at both boundaries, the BASELINE correction is zero and the SAMPLING correction converges in a few orders; for rectangular and Bartlett windows, higher orders are required (see window sweep table in Notebook 02).
+
+![Correction convergence](examples/figures/02_dft_corrections_fig01.svg)
+
+The corrections become irrelevant above a crossover acquisition length where the noise floor dominates. The figure below sweeps N at fixed f_s and shows the normalized model error for each correction level alongside reference noise floors at fixed σ/A ratios. Below the crossover, the fit is model-limited; above it, noise-limited.
+
+![Corrections vs acquisition length](examples/figures/02_dft_corrections_fig02.svg)
+
+*[Notebook 02](examples/02_dft_corrections.ipynb). Implementation: `DFTCorrection`, `DFTCorrectionMode` in [dft/correction.py](dftmodels/dft/correction.py).*
+
+---
+
+### Precision fitting — sinusoid
+
+300 noise realizations of a rectangular-windowed sinusoid at f₀ = 10.42 Hz (0.42 bins from the nearest bin), T = 1 s, σ = 0.01 V. The table below compares four correction levels; the violin plots show the full error distribution.
+
+| | freq RMSE (mHz) | amp RMSE (mV) | phase RMSE (mrad) |
+|---|---|---|---|
+| CRB | 0.39 | 1.41 | 0.98 |
+| ★ None | 9.90 | 117.4 | 27.18 |
+| ★ All (order 10) | 0.41 | 1.47 | 1.43 |
+
+Frequency and amplitude RMSE approach the CRB once corrections eliminate the systematic bias.
+
+![Precision fitting violin plots](examples/figures/03_precision_fitting_fig01.svg)
+
+*[Notebook 03](examples/03_precision_fitting.ipynb). Implementation: `SineFourier` in [models/sinusoid.py](dftmodels/models/sinusoid.py).*
+
+---
+
+### Decaying signals
+
+For a decaying sinusoid x(t) = A·cos(2πf₀t + φ)·e^{−γt}, the CFT near f₀ is a complex Lorentzian: X(f) ≈ (Ae^{jφ}/2) / (γ + 2πj(f − f₀)). `SineFourier` with a nonzero `decay` parameter implements the exact analytical DFT expression and fits four parameters (frequency f₀, quadrature amplitudes Aᵢ = A cos φ and A_q = A sin φ, and decay rate γ); amplitude A, phase φ, and FWHM = γ/π are derived quantities. The Fisher information matrix for a decaying sinusoid has non-zero off-diagonal coupling between f and γ — the two parameters are not decoupled, unlike the pure sinusoid case.
+
+300 realizations at σ = 0.05 V, T = 5 s, γ = 0.5 s⁻¹:
+
+| | amp RMSE (mV) | phase RMSE (mrad) | freq RMSE (mHz) | decay RMSE (ms⁻¹) |
+|---|---|---|---|---|
+| CRB | 10.20 | 5.13 | 0.62 | 3.87 |
+| ★ None | 59.98 | 5.93 | 0.67 | 34.41 |
+| ★ All (order 10) | 10.03 | 5.14 | 0.61 | 3.83 |
+
+![Lorentzian bare vs corrected](examples/figures/04_decaying_signals_fig02.svg)
+
+Applying an exponential window w(t_n) = e^{−α·t_n/T} before the DFT shifts the effective decay to γ_eff = γ + α/T (line broadening). `LorentzianComplex` with `WindowType.EXPONENTIAL_ASYM` corrects for the window-induced decay shift and recovers the true γ from the broadened spectrum. A bare fit converges to γ_eff, biased by α/T.
+
+*[Notebook 04](examples/04_decaying_signals.ipynb). Implementation: `LorentzianComplex` in [models/lorentzian.py](dftmodels/models/lorentzian.py).*
+
+---
+
+### Composite models
+
+`CompositeModel` fits a weighted sum of named components simultaneously, with all parameters coupled through a shared covariance matrix. For overlapping spectral lines, sequential peak-by-peak fitting propagates subtraction errors; joint fitting avoids this. Each component's parameters are prefixed by name (`p1_frequency`, `p2_decay`, ...).
+
+A J-coupled quartet — four Lorentzian lines with 1:3:3:1 binomial amplitudes at spacing J = 2.5 Hz — illustrates the setup. A linear complex background b₀ + b₁f is included as a fifth component; fitting without it forces the peaks to absorb the baseline, distorting amplitude ratios.
+
+![Composite fit with decomposition](examples/figures/05_composite_model_fig01.svg)
+
+*Top: magnitude spectrum (grey), total fit (dashed), individual peak contributions (dotted), and background (dash-dot). Bottom: residuals with and without a background component in the model.*
+
+The corrected composite estimator approaches the CRB; outer peaks (A = 1 V) have proportionally larger uncertainty than inner peaks (A = 3 V).
+
+*[Notebook 05](examples/05_composite_model.ipynb). Implementation: `CompositeModel` in [models/composite.py](dftmodels/models/composite.py).*
+
+---
+
+### Window choice
+
+The CRB is determined by the raw, unweighted time-domain data and is independent of the window. Any non-rectangular window downweights samples near the record boundaries, discarding Fisher information. This loss cannot be recovered by corrections. For an isolated peak, the rectangular window is the only window whose RMSE approaches the CRB; all others inflate variance proportionally to their effective bandwidth.
+
+![Window RMSE comparison](examples/figures/06_window_comparison_fig00.svg)
+
+*RMSE for frequency (left) and amplitude (right) estimation across six windows at two fractional bin offsets δ = 0 and δ = 0.5. The CRB (dotted line) is the same for both offsets and all windows. N = 1000, f_s = 1000 Hz, σ = 0.05 V, 300 realizations.*
+
+The tradeoff reverses when a nearby peak is absent from the model. Its spectral sidelobes leak into the fit region; the rectangular window has the broadest sidelobe structure (∝ sinc), so its estimator is most sensitive to this. At worst-case interferer offset (δ = 0.484, +5 bins), the rectangular window has a frequency RMSE of 13.5 mHz vs. 2.3 mHz for Hamming.
+
+Window choice therefore depends on context: isolated peaks favour rectangular; peaks with unmodeled nearby components favour windowed estimators.
+
+*[Notebook 06](examples/06_window_comparison.ipynb).*
+
+---
+
+## Usage
+
+```python
+import numpy as np
+from dftmodels import (
+    SignalSeries, NormType, WindowType, DFTRange,
+    DFTCorrection, DFTCorrectionMode, SineFourier,
+)
+
+t  = np.arange(0, 1.0, 1 / 100.0)
+y  = 2.0 * np.cos(2 * np.pi * 10.42 * t + 0.5)
+y += np.random.normal(scale=0.01, size=len(t))
+
+fourier = SignalSeries(x=t, y=y).calculate_dft(
+    norm=NormType.ASD, window=WindowType.RECTANGULAR,
+    dft_range=DFTRange.SINGLE_SIDED, pad=10.0,
+)
+
+model  = SineFourier(fourier.dft_config, DFTCorrection(DFTCorrectionMode.ALL, order=10))
+params = model.make_params(
+    amplitude_i=2.0, amplitude_q=0.0, frequency=10.0,
+    frequency_min=8.0, frequency_max=13.0,
+)
+result = model.fit(fourier, params, mask=(fourier.x >= 8.0) & (fourier.x <= 13.0))
+
+print(f"Amplitude : {model.amplitude(result.params):.6f} V")
+print(f"Frequency : {model.center(result.params):.6f} Hz")
+print(f"Phase     : {model.phase(result.params):.6f} rad")
+```
+
+For decaying signals use `LorentzianComplex` with `NormType.CFT`. For simultaneous multi-peak fitting use `CompositeModel`. See the notebooks for detailed examples of each.
+
+## Models
+
+| Signal type | Model class | Windows |
+|---|---|---|
+| Sinusoid | `SineFourier` | All cosine-sum windows, Bartlett |
+| Decaying sinusoid | `LorentzianComplex` | Rectangular, Exponential |
+| Time-domain (decaying) sinusoid | `Sinusoid` | N/A |
+| Custom | `ModelBase.build_model(fn)` | N/A |
+
+## Limitations
+
+**Scope of corrections.** The correction terms reduce systematic bias from the finite, sampled, windowed DFT. An alternative that achieves the same result is to define the signal model in the time domain and compute the DFT numerically at each evaluation. The analytical corrections are a closed-form shortcut to that approach; they are most efficient when the signal model is simple and the number of evaluations is large. For short-duration signals with few samples, the time-domain approach may be simpler.
+
+**Noise model.** The Cramér–Rao bounds in the examples assume additive white Gaussian noise. Colored noise or non-Gaussian distributions will produce different variance floors; the model residuals remain unbiased but the optimality guarantee does not carry over.
+
+**Model vs. estimator.** The classes in this package are models, not estimators. Combined with a least-squares fitting procedure (`lmfit.Minimizer`), they form estimators. The CRB is a property of the estimator (model + fitting algorithm + noise model), not of the model alone.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

dftmodels-1.0.0/dftmodels/__init__.py

@@ -0,0 +1,42 @@
+from importlib.metadata import version
+from .stats import cramer_rao_bound
+
+__version__ = version("dftmodels")
+from .dft import (
+    DFTConfig,
+    NormType,
+    DFTRange,
+    WindowType,
+    DFTCorrection,
+    DFTCorrectionMode,
+    SignalSeries,
+    FourierSeries,
+)
+from .models import (
+    FourierModelBase,
+    Sinusoid,
+    SineFourier,
+    CompositeModel,
+    ModelBase,
+)
+
+__all__ = [
+    "__version__",
+    # Stats
+    "cramer_rao_bound",
+    # DFT
+    "DFTConfig",
+    "NormType",
+    "DFTRange",
+    "WindowType",
+    "DFTCorrection",
+    "DFTCorrectionMode",
+    "SignalSeries",
+    "FourierSeries",
+    # Models
+    "FourierModelBase",
+    "ModelBase",
+    "Sinusoid",
+    "SineFourier",
+    "CompositeModel",
+]

dftmodels-1.0.0/dftmodels/dft/__init__.py

@@ -0,0 +1,15 @@
+from .config import DFTConfig, NormType, DFTRange, WindowType, get_window_array
+from .correction import DFTCorrection, DFTCorrectionMode
+from .series import SignalSeries, FourierSeries
+
+__all__ = [
+    "DFTConfig",
+    "NormType",
+    "DFTRange",
+    "WindowType",
+    "get_window_array",
+    "DFTCorrection",
+    "DFTCorrectionMode",
+    "SignalSeries",
+    "FourierSeries",
+]

dftmodels-1.0.0/dftmodels/dft/config.py

@@ -0,0 +1,170 @@
+from dataclasses import dataclass, replace, field
+from enum import Enum
+from functools import cached_property
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+class WindowType(str, Enum):
+    # Cosine-sum windows
+    RECTANGULAR      = "rectangular"
+    HAMMING          = "hamming"
+    HANN             = "hann"
+    DIRICHLET        = "rectangular"  # alias for RECTANGULAR
+    BLACKMAN         = "blackman"
+    NUTTAL           = "nuttal"
+    BLACKMAN_NUTTAL  = "blackman-nuttal"
+    BLACKMAN_HARRIS  = "blackman-harris"
+    FLAT_TOP         = "flat-top"
+
+    # For Debug Only
+    # COS4N            = "cos-4n"
+    # COS6N            = "cos-6n"
+    # COS8N            = "cos-8n"
+
+    # Other
+    EXPONENTIAL_ASYM = "exponential-asymmetric"
+    BARTLETT         = "bartlett"
+
+
+
+def get_window_array(window: WindowType, n: int, **params) -> NDArray[np.floating]:
+    match window:
+        case WindowType.RECTANGULAR:
+            return np.ones(n)
+        case WindowType.HAMMING:
+            return 25/46 - 21/46 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.HANN:
+            return 0.5 - 0.5 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.BLACKMAN:
+            return (7938 
+                - 9240 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 1430 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+            ) / 18608
+        case WindowType.NUTTAL:
+            return (355_768 \
+                - 487_396 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 144_232 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -  12_604 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+            ) / 1_000_000
+        case WindowType.BLACKMAN_NUTTAL:
+            return (3_635_819 \
+                - 4_891_775 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 1_365_995 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -   106_411 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+            ) / 10_000_000
+        case WindowType.BLACKMAN_HARRIS:
+            return (4_243_801 \
+                - 4_973_406 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 782_793 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+            ) / 10_000_000
+        case WindowType.FLAT_TOP:
+            return (215_578_950 \
+                - 416_631_580 * np.cos(2 * np.pi * np.arange(n) / (n - 1))
+                + 277_263_158 * np.cos(4 * np.pi * np.arange(n) / (n - 1))
+                -  83_578_947 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+                +   6_947_368 * np.cos(8 * np.pi * np.arange(n) / (n - 1))
+            ) / 1_000_000_000
+        case WindowType.BARTLETT:
+            return np.bartlett(n)
+        # case WindowType.COS6N:
+        #     return .5 - .5 * np.cos(6 * np.pi * np.arange(n) / (n - 1))
+        # case WindowType.COS8N:
+        #     return .5 - .5 * np.cos(8 * np.pi * np.arange(n) / (n - 1))
+        case WindowType.EXPONENTIAL_ASYM:
+            return np.exp(-np.arange(n) * params.get("alpha", 1.0) / (n - 1))
+        case _:
+            raise ValueError(f"Unsupported window type: {window}")
+
+
+class NormType(str, Enum):
+    CFT     = "continuous_fourier_transform"
+    ASD     = "amplitude_spectral_density"
+    ASD_ABS = "amplitude_spectral_density_absolute"
+    PSD     = "power_spectral_density"
+
+
+class DFTRange(str, Enum):
+    DOUBLE_SIDED = "double_sided"
+    SINGLE_SIDED = "single_sided"
+
+
+@dataclass(frozen=True)
+class DFTConfig:
+    number_of_samples: int
+    sample_rate: float
+    pad: float = 1.0
+    window: WindowType = WindowType.RECTANGULAR
+    window_params: dict = field(default_factory=dict)  # <--- NEW
+    norm_type: NormType = NormType.ASD
+    dft_range: DFTRange = DFTRange.DOUBLE_SIDED
+
+    def __post_init__(self):
+        if self.number_of_samples <= 0:
+            raise ValueError("number_of_samples must be a positive integer")
+        if self.sample_rate <= 0:
+            raise ValueError("sample_rate must be positive")
+        if self.pad < 1.0:
+            raise ValueError("pad cannot be less than 1.0")
+        if self.window not in WindowType:
+            raise ValueError(f"Unsupported window type: {self.window}")
+        if self.norm_type not in NormType:
+            raise ValueError(f"Unsupported norm type: {self.norm_type}")
+        if self.dft_range not in DFTRange:
+            raise ValueError(f"Unsupported DFT range: {self.dft_range}")
+
+    @cached_property
+    def number_of_samples_fft(self) -> int:
+        return round(self.number_of_samples * self.pad)
+
+    @cached_property
+    def window_array(self) -> NDArray[np.floating]:
+        return get_window_array(self.window, self.number_of_samples, **self.window_params)
+
+    @cached_property
+    def norm_factor(self) -> float:
+        if self.norm_type in (NormType.ASD, NormType.ASD_ABS):
+            return self._asd_norm()
+        elif self.norm_type == NormType.PSD:
+            return self._asd_norm() ** 2
+        elif self.norm_type == NormType.CFT:
+            return self._cft_norm()
+        raise ValueError(f"Unsupported norm type: {self.norm_type}")
+
+    def _cft_norm(self) -> float:
+        wa = self.window_array
+        if wa[0] == 0.0:
+            raise ValueError('Zero-valued window is incompatible with CFT normalization')
+        factor = 2.0 if self.dft_range == DFTRange.SINGLE_SIDED else 1.0
+        return factor / self.sample_rate / wa[0]
+
+    def _asd_norm(self) -> float:
+        wa = self.window_array
+        n = self.number_of_samples
+        window_rms = np.sqrt(np.sum(wa ** 2) / n)
+        factor = np.sqrt(2.0) if self.dft_range == DFTRange.SINGLE_SIDED else 1.0
+        return factor / np.sqrt(self.sample_rate * n) / window_rms
+
+    @cached_property
+    def frequency_step(self) -> float:
+        return self.sample_rate / self.number_of_samples_fft
+
+    @cached_property
+    def frequency_min(self) -> float:
+        if self.dft_range == DFTRange.SINGLE_SIDED:
+            return 0.0
+        n = self.number_of_samples_fft
+        df = self.frequency_step
+        return -(self.sample_rate + df) / 2 if n % 2 == 0 else -self.sample_rate / 2
+
+    @cached_property
+    def frequency_max(self) -> float:
+        if self.dft_range == DFTRange.SINGLE_SIDED:
+            return self.sample_rate / 2
+        n = self.number_of_samples_fft
+        df = self.frequency_step
+        return (self.sample_rate - df) / 2 if n % 2 == 0 else self.sample_rate / 2
+
+    def copy(self) -> 'DFTConfig':
+        return replace(self)

dftmodels-1.0.0/dftmodels/dft/correction.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass
+from enum import IntFlag, auto
+
+
+class DFTCorrectionMode(IntFlag):
+    NONE          = 0
+    BASELINE_ONLY = auto()
+    SAMPLING_ONLY = auto()
+    WINDOW_ONLY   = auto()
+
+    WINDOW        = WINDOW_ONLY
+    BASELINE      = WINDOW_ONLY | BASELINE_ONLY
+    ALL           = WINDOW_ONLY | BASELINE_ONLY | SAMPLING_ONLY
+
+
+@dataclass(frozen=True)
+class DFTCorrection:
+    mode: DFTCorrectionMode
+    order: int = 10