Schemas reference¶

All configuration and result types are frozen Pydantic v2 models. Import directly from tldecpy: from tldecpy import PeakSpec, MultiFitResult.

Input schemas¶

tldecpy.schemas.PeakSpec ¶

Bases: PygcdBaseModel

Input specification for one TL peak component.

Attributes:

Name	Type	Description
`name`	`str \| None`	Human-readable component identifier (e.g. `"P1"`). Used as a prefix in parameter names within `MultiFitResult.hit_bounds` and `PeakResult.uncertainties`. Auto-assigned as `"P<n>"` if omitted.
`model`	`str`	Kinetic model key. Accepted values include canonical keys (`"fo_rq"`, `"fo_rb"`, `"go_kg"`, `"otor_lw"`, `"cont_gauss"` …), family short-names (`"fo"`, `"go"`), and registered aliases. Call `tl.list_models()` for the full list.
`init`	`dict[str, float]`	Initial parameter values passed to the optimizer. Required keys depend on the model family: FO / SO / GO / MO / OTOR: `"Tm"` (K), `"Im"` (counts), `"E"` (eV). GO also requires `"b"` (1–2); OTOR requires `"R"` (0–1); MO requires `"alpha"` (0–1). Continuous (`"cont_gauss"`, `"cont_exp"`): `"Tn"` (K), `"In"` (counts), `"E0"` (eV), `"sigma"` (eV). Legacy aliases `"Tm"`, `"Im"`, `"E"` are accepted. Missing keys receive model-specific defaults inside the fitter.
`bounds`	`(dict[str, tuple[float, float]] \| None, optional)`	Parameter bounds as `{name: (lower, upper)}`. If omitted, automatic bounds are derived from `init` values inside the fitter. Explicit bounds override automatic ones.
`fixed`	`(dict[str, float \| bool] \| None, optional)`	Parameters held constant during optimisation. Two forms: `{"b": 1.8}` — `b` is fixed to 1.8 regardless of `init`. `{"b": True}` — `b` is fixed to `init["b"]`. `{"b": False}` — `b` is free (same as omitting it).

Examples:

>>> import tldecpy as tl
>>> peak = tl.PeakSpec(
...     name="P1",
...     model="fo_rq",
...     init={"Tm": 450.0, "Im": 5000.0, "E": 1.2},
...     bounds={"Tm": (400.0, 500.0), "E": (0.8, 2.0)},
... )
>>> go_peak = tl.PeakSpec(
...     model="go_kg",
...     init={"Tm": 490.0, "Im": 3000.0, "E": 1.5, "b": 1.8},
...     fixed={"b": True},          # hold kinetic order fixed
... )

tldecpy.schemas.BackgroundSpec ¶

Bases: PygcdBaseModel

Input specification for background contribution in TL fits.

Attributes:

Name	Type	Description
`type`	`{'linear', 'exponential', 'none'}`	Background functional form.
`init`	`dict[str, float] \| None`	Initial parameter values.
`bounds`	`dict[str, tuple[float, float]] \| None`	Optional parameter bounds.
`fixed`	`dict[str, float] \| None`	Optional fixed parameter values.

tldecpy.schemas.RobustOptions ¶

Bases: PygcdBaseModel

Robust loss and weighting options for TL curve fitting.

Attributes:

Name	Type	Description
`loss`	`{"linear", "soft_l1", "huber", "cauchy", "arctan", "tukey"}, default="linear"`	Residual loss function :math:`\rho(r)` applied to the normalised residuals before summing the cost: `"linear"` — :math:`r^2` (ordinary least squares, default). `"soft_l1"` — :math:`2(\sqrt{1+r^2}-1)`, smooth L1. `"huber"` — quadratic for :math:`\|r\|<1`, linear otherwise. `"cauchy"` — :math:`\ln(1+r^2)`, heavy-tailed downweighting. `"arctan"` — :math:`\arctan(r^2)`, bounded loss. `"tukey"` — biweight (requires `loss_param`). `"lm"` optimizer supports only `"linear"`.
`f_scale`	`float, default=1.0`	Residual scale parameter. Residuals with absolute value < `f_scale` are treated as inliers (OLS regime); larger residuals are robustly downweighted. Set to approximately the noise floor of the detector in the same units as `y`.
`loss_param`	`(float \| None, optional)`	Extra loss parameter used by Tukey biweight (the Tukey constant `c`). Ignored for other losses.
`weights`	`{"none", "poisson"}, default="none"`	Residual weighting strategy. `"none"` — all channels equally weighted. `"poisson"` — each residual is divided by :math:`\sqrt{I_i}`, giving inverse-variance weighting for Poisson (counting) noise.
`multi_start`	`int, default=0`	Number of randomised restarts with ±10 % parameter perturbation. The best-cost solution is returned. `0` disables restarts.
`ci_bootstrap`	`bool, default=False`	If `True`, compute 95 % bootstrap confidence intervals via residual resampling. Results are stored in `PeakResult.ci_95`. Requires `n_bootstrap` extra full solves — can be slow.
`n_bootstrap`	`int, default=100`	Number of bootstrap iterations when `ci_bootstrap=True`. Use 200–500 for publication-quality intervals.

Examples:

>>> import tldecpy as tl
>>> # Robust fit with Poisson weighting
>>> opts = tl.RobustOptions(
...     loss="soft_l1",
...     f_scale=5.0,
...     weights="poisson",
... )
>>> # Bootstrap confidence intervals
>>> opts_ci = tl.RobustOptions(
...     loss="soft_l1",
...     f_scale=5.0,
...     ci_bootstrap=True,
...     n_bootstrap=200,
... )

tldecpy.schemas.FitOptions ¶

Bases: PygcdBaseModel

Solver and uncertainty configuration for multi-peak fitting.

Attributes:

Name	Type	Description
`local_optimizer`	`{"trf", "dogbox", "lm"}, default="trf"`	Local least-squares method passed to `scipy.optimize.least_squares`: `"trf"` — Trust Region Reflective. Supports box bounds and all robust losses. Recommended for most fits. `"dogbox"` — Dogleg method. Supports bounds and robust losses; faster on well-conditioned small problems. `"lm"` — Levenberg-Marquardt. Does not support box bounds natively (soft penalties are used) and only supports `loss="linear"`. Use for simple, unconstrained problems.
`max_nfev`	`(int \| None, optional)`	Maximum number of objective function evaluations. `None` lets SciPy choose a default (≈ 100 × number of parameters).
`ftol`	`float, default=1e-8`	Relative cost-function reduction tolerance for convergence.
`xtol`	`float, default=1e-8`	Relative parameter-step size tolerance for convergence.
`gtol`	`float, default=1e-8`	Gradient norm tolerance for convergence.
`uncertainty`	`(UncertaintyOptions \| None, optional)`	If provided and `uncertainty.enabled=True`, a full uncertainty budget is computed after fitting and attached to `MultiFitResult`.

Examples:

>>> import tldecpy as tl
>>> opts = tl.FitOptions(local_optimizer="trf")
>>> opts_uc = tl.FitOptions(
...     local_optimizer="trf",
...     uncertainty=tl.UncertaintyOptions(
...         enabled=True,
...         noise_pct=1.0,
...         calibration_pct=0.5,
...     ),
... )

tldecpy.schemas.UncertaintyOptions ¶

Bases: PygcdBaseModel

Configuration for uncertainty propagation in TL deconvolution.

Attributes:

Name	Type	Description
`enabled`	`bool`	Enables uncertainty evaluation when `True`.
`include_parameter_covariance`	`bool`	Includes covariance from the Jacobian-based local linearization.
`noise_pct`	`float`	Type-A noise contribution as percentage of fitted maximum intensity.
`noise_from_residuals`	`bool`	Uses residual statistics to estimate Type-A noise.
`calibration_pct`	`float`	Type-B calibration contribution in percent.
`heating_rate_pct`	`float`	Relative uncertainty in heating rate :math:`\beta`.
`reader_drift_pct`	`float`	Type-B reader drift contribution in percent.
`uc_metric_min_rel_intensity`	`float`	Minimum relative fitted intensity used to define ROI for `u_c` metrics.
`uc_metric_noise_sigma_factor`	`float`	Residual-noise multiplier used in ROI definition.
`correlations`	`dict[str, float]`	Correlation coefficients keyed as `sourceA:sourceB`.
`export_report`	`bool`	Whether to attach uncertainty report payloads to fit outputs.
`validation_mode`	`{'none', 'monte_carlo', 'bootstrap'}`	Validation mode for uncertainty cross-checking.
`n_validation_samples`	`int`	Number of validation samples/iterations.
`validation_seed`	`int \| None`	Random seed for reproducible validation runs.
`threshold_fom`	`float`	Recommended upper bound for figure-of-merit.
`threshold_uc_global`	`float`	Recommended upper bound for global uncertainty criterion.
`threshold_uc_p95`	`float`	Recommended upper bound for 95th percentile uncertainty criterion.

tldecpy.schemas.BoundsSpec ¶

Bases: PygcdBaseModel

Bounds definition for a scalar parameter.

Attributes:

Name	Type	Description
`min`	`float`	Lower bound.
`max`	`float`	Upper bound.

tldecpy.schemas.SimulationOptions ¶

Bases: PygcdBaseModel

ODE simulation options for synthetic TL curve generation.

Attributes:

Name	Type	Description
`method`	`str`	`scipy.integrate.solve_ivp` method name.
`rtol`	`float`	Relative integration tolerance.
`atol`	`float`	Absolute integration tolerance.
`points`	`int`	Number of output sample points.

Result schemas¶

tldecpy.schemas.MultiFitResult ¶

Bases: PygcdImmutableModel

Aggregated output of a multi-peak TL deconvolution.

Attributes:

Name	Type	Description
`peaks`	`list[PeakResult]`	Fitted peak components.
`background`	`BGResult \| None`	Optional fitted background component.
`y_obs`	`ndarray`	Observed intensity :math:`I(T)`.
`y_hat_total`	`ndarray`	Total fitted intensity :math:`\hat{I}(T)`.
`residuals`	`ndarray`	Residual vector :math:`I(T)-\hat{I}(T)`.
`metrics`	`Metrics`	Fit-quality and uncertainty metrics.
`converged`	`bool`	Optimizer convergence flag.
`message`	`str`	Optimizer termination message.
`n_iter`	`int`	Number of function evaluations/iterations.
`hit_bounds`	`dict[str, bool]`	Indicates which parameters touched optimization bounds.
`jac_cond`	`float`	Jacobian condition number estimate.
`loss_used`	`str`	Robust loss function effectively used by the solver.
`uc_curve`	`ndarray \| None`	Channel-wise combined uncertainty criterion in percent.
`uncertainty_budget`	`dict[str, float]`	Global uncertainty contribution summary.
`uncertainty_report`	`dict[str, Any] \| None`	Optional technical uncertainty report payload.
`uncertainty_validation`	`dict[str, Any] \| None`	Optional validation diagnostics (MC/bootstrap vs local linearization).

tldecpy.schemas.Metrics ¶

Bases: PygcdImmutableModel

Goodness-of-fit and uncertainty summary metrics.

Attributes:

Name	Type	Description
`FOM`	`float`	Figure of Merit in percent.
`R2`	`float`	Coefficient of determination.
`RCS`	`float`	Reduced chi-square surrogate.
`SSR`	`float`	Sum of squared residuals.
`AIC`	`float`	Akaike information criterion.
`BIC`	`float`	Bayesian information criterion.
`uc_global`	`float \| None`	Global combined uncertainty criterion in percent.
`uc_max`	`float \| None`	Maximum channel-wise combined uncertainty in percent.
`uc_p95`	`float \| None`	95th percentile channel-wise combined uncertainty in percent.
`contrib_E`	`float \| None`	Contribution associated with activation-energy parameters.
`contrib_Tm`	`float \| None`	Contribution associated with characteristic-temperature parameters.
`contrib_Im`	`float \| None`	Contribution associated with characteristic-intensity parameters.
`contrib_bg`	`float \| None`	Contribution associated with background parameters.

tldecpy.schemas.PeakResult ¶

Bases: PygcdImmutableModel

Fitted result for one deconvolved TL peak.

Attributes:

Name	Type	Description
`name`	`str`	Peak/component label.
`model`	`str`	Kinetic model key used in fitting.
`params`	`dict[str, float]`	Estimated parameter values.
`y_hat`	`ndarray`	Fitted peak contribution :math:`\hat{I}_{\text{peak}}(T)`.
`area`	`float`	Integrated area under the fitted peak.
`ci_95`	`dict[str, tuple[float, float]] \| None`	Optional 95% confidence interval bounds by parameter.
`uncertainties`	`dict[str, float]`	Parameter standard uncertainties.

tldecpy.schemas.BGResult ¶

Bases: PygcdImmutableModel

Fitted result for the background component.

Attributes:

Name	Type	Description
`type`	`str`	Background model type.
`params`	`dict[str, float]`	Estimated background parameters.
`y_hat`	`ndarray`	Fitted background signal.
`uncertainties`	`dict[str, float]`	Standard uncertainties for background parameters.

tldecpy.schemas.FitResult ¶

Bases: PygcdImmutableModel

Legacy single-peak result schema retained for compatibility.

Attributes:

Name	Type	Description
`params`	`dict[str, float]`	Estimated parameters.
`cov`	`ndarray \| None`	Optional covariance matrix.
`metrics`	`dict[str, float]`	Legacy metric payload.
`y_hat`	`ndarray`	Fitted signal.
`residuals`	`ndarray`	Residual signal.
`converged`	`bool`	Convergence flag.
`message`	`str`	Solver termination message.
`model_type`	`str`	Model key used during fitting.

tldecpy.schemas.SimulationResult ¶

Bases: PygcdImmutableModel

Output schema for ODE-based TL simulations.

Attributes:

Name	Type	Description
`T`	`ndarray`	Temperature grid in kelvin.
`I`	`ndarray`	Simulated intensity signal.
`states`	`dict[str, ndarray] \| None`	Optional ODE state trajectories keyed by state name.
`time`	`ndarray \| None`	Optional integration-time vector.

tldecpy.schemas.VersionInfo ¶

Bases: PygcdImmutableModel

Package and API version information.

Attributes:

Name	Type	Description
`version`	`str`	Package version.
`api_version`	`str`	Public API version.
`build`	`str \| None`	Optional build tag.

tldecpy.schemas.ErrorDetail ¶

Bases: PygcdImmutableModel

Serializable error payload for API integrations.

Attributes:

Name	Type	Description
`error_code`	`str`	Stable error identifier.
`message`	`str`	Human-readable error message.
`hint`	`str \| None`	Optional remediation hint.