epyr.relaxation

EPyR Tools - Relaxation Fitting Module

Time-domain decay and recovery models for T1/T2 EPR relaxation measurements, with a curve-fitting layer mirroring epyr.lineshapes.fitting.

epyr.relaxation.mono_exponential(t, amplitude, T, offset=0.0)[source]

Compute a single-rate exponential decay.

V(t) = amplitude * exp(-t / T) + offset

Parameters:

t (np.ndarray) – Time axis, in the unit chosen by the caller (e.g. ns or us).
amplitude (float) – Signal amplitude at t = 0, relative to offset.
T (float) – Decay (or recovery) time constant, in the same unit as t.
offset (float, optional) – Asymptotic signal level as t approaches infinity (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

epyr.relaxation.stretched_exponential(t, amplitude, T, beta, offset=0.0)[source]

Compute a stretched-exponential decay.

V(t) = amplitude * exp(-(t / T) ** beta) + offset

beta = 1 reduces to a mono-exponential decay. beta < 1 describes a distribution of relaxation rates, common in pulsed EPR echo decays.

Parameters:

t (np.ndarray) – Time axis, in the unit chosen by the caller.
amplitude (float) – Signal amplitude at t = 0, relative to offset.
T (float) – Characteristic decay time constant, in the same unit as t.
beta (float) – Stretching exponent (dimensionless).
offset (float, optional) – Asymptotic signal level as t approaches infinity (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

epyr.relaxation.biexponential(t, amplitude1, tau1, amplitude2, tau2, offset=0.0)[source]

Compute a two-component exponential decay.

V(t) = amplitude1 * exp(-t / tau1) + amplitude2 * exp(-t / tau2) + offset

Parameters:

t (np.ndarray) – Time axis, in the unit chosen by the caller.
amplitude1 (float) – Amplitude of the first component at t = 0.
tau1 (float) – Decay time constant of the first component, same unit as t.
amplitude2 (float) – Amplitude of the second component at t = 0.
tau2 (float) – Decay time constant of the second component, same unit as t.
offset (float, optional) – Asymptotic signal level as t approaches infinity (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

Notes

tau1 and tau2 are not necessarily T1 or T2: either component can represent either relaxation process, depending on the experiment.

epyr.relaxation.inversion_recovery(t, amplitude, T1, offset=0.0)[source]

Compute an inversion-recovery T1 curve.

V(t) = amplitude * (1 - 2 * exp(-t / T1)) + offset

Parameters:

t (np.ndarray) – Delay time after inversion, in the unit chosen by the caller.
amplitude (float) – Fully-recovered signal amplitude relative to offset.
T1 (float) – Spin-lattice relaxation time, same unit as t.
offset (float, optional) – Baseline signal level (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

epyr.relaxation.saturation_recovery(t, amplitude, T1, offset=0.0)[source]

Compute a saturation-recovery T1 curve.

V(t) = amplitude * (1 - exp(-t / T1)) + offset

Parameters:

t (np.ndarray) – Delay time after saturation, in the unit chosen by the caller.
amplitude (float) – Fully-recovered signal amplitude relative to offset.
T1 (float) – Spin-lattice relaxation time, same unit as t.
offset (float, optional) – Baseline signal level (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

epyr.relaxation.gamma_gaussian_decay(t, amplitude, Gamma0, GammaG, offset=0.0)[source]

Compute an echo decay with homogeneous and spectral-diffusion terms.

V(t) = amplitude * exp(-Gamma0 * t) * exp(-(GammaG * t) ** 2) + offset

Gamma0 captures the homogeneous (exponential) relaxation rate. GammaG captures an additional Gaussian-shaped decay from spectral diffusion.

Parameters:

t (np.ndarray) – Time axis, in the unit chosen by the caller.
amplitude (float) – Signal amplitude at t = 0, relative to offset.
Gamma0 (float) – Homogeneous decay rate, in inverse time units (1 / t unit).
GammaG (float) – Gaussian (spectral-diffusion) decay rate, in inverse time units.
offset (float, optional) – Asymptotic signal level as t approaches infinity (default: 0.0).

Returns:

Signal values, same shape as t.

Return type:

np.ndarray

epyr.relaxation.fit_relaxation(t_data, y_data, model='mono_exponential', initial_params=None, bounds=None, mask=None, plot=True, time_unit='', **fit_kwargs)[source]

Fit time-domain relaxation data with the specified decay/recovery model.

Parameters:

t_data (np.ndarray) – Time axis, in the unit chosen by the caller (e.g. ns or us).
y_data (np.ndarray) – Relaxation signal (real-valued; take np.abs() of a complex echo signal before calling this function).
model (str, optional) – Relaxation model name (default: ‘mono_exponential’). See SUPPORTED_MODELS for the full list as models are added.
initial_params (dict, optional) – Initial parameter guesses. Auto-estimated from data if None.
bounds (dict, optional) – Parameter bounds as {name: (lower, upper)}, overriding data-derived defaults.
mask (np.ndarray of bool, optional) – Boolean array of the same length as t_data. True selects a point for fitting; False excludes it. If None, all non-NaN points are used.
plot (bool, optional) – Display a fit plot with residuals panel (default: True).
time_unit (str, optional) – Cosmetic time-unit label for the plot axis and summary (e.g. ‘ns’). Does not affect fitting (default: ‘’).
**fit_kwargs – Additional keyword arguments passed to scipy.optimize.curve_fit.

Returns:

Fit parameters, errors, statistics, fitted curve, and residuals.

Return type:

RelaxationFitResult

Examples

>>> from epyr.relaxation import fit_relaxation
>>> import numpy as np
>>> t = np.linspace(0, 100, 200)
>>> y = 5.0 * np.exp(-t / 15.0) + 1.0
>>> result = fit_relaxation(t, y, 'mono_exponential', plot=False)
>>> print(result.summary())

epyr.relaxation.fit_multiple_decays(t_data, y_data, models=None, mask=None, plot=True)[source]

Fit relaxation data with multiple models and compare by reduced chi-squared.

Parameters:

t_data (np.ndarray) – Time axis, in the unit chosen by the caller.
y_data (np.ndarray) – Relaxation signal.
models (list of str, optional) – Models to fit. Default: [‘mono_exponential’, ‘stretched_exponential’, ‘biexponential’]. The recovery models and ‘gamma_gaussian_decay’ are excluded by default since they assume a specific data shape rather than being interchangeable candidates for a generic decay.
mask (np.ndarray of bool, optional) – Boolean array selecting points to include (True = include). Passed unchanged to each fit_relaxation call.
plot (bool, optional) – Display a side-by-side comparison plot (default: True).

Returns:

Dict subclass mapping model name to RelaxationFitResult for all attempted fits. Printing it shows a comparison table of R-squared, chi-squared, and every fitted parameter across all models.

Return type:

RelaxationFitComparison

Notes

Models are ranked by reduced chi-squared, not R-squared: R-squared is biased toward models with more free parameters, since extra parameters can only reduce the residual sum of squares on the same data.

class epyr.relaxation.RelaxationFitResult(model, parameters, parameter_errors, fitted_curve, residuals, r_squared, chi_squared, success, message, covariance_matrix=None, t_fit=None)[source]

Container for relaxation fit results.

Parameters:

model (str)
parameters (Dict[str, float])
parameter_errors (Dict[str, float])
fitted_curve (ndarray)
residuals (ndarray)
r_squared (float)
chi_squared (float)
success (bool)
message (str)
covariance_matrix (ndarray | None)
t_fit (ndarray | None)

model

Name of the fitted relaxation model.

Type:: str

parameters

Fitted parameter values keyed by parameter name.

Type:: dict

parameter_errors

Standard errors of fitted parameters (square root of covariance diagonal).

Type:: dict

fitted_curve

Model evaluated at the fitted points (t_fit).

Type:: np.ndarray

residuals

Data minus model at the fitted points.

Type:: np.ndarray

r_squared

Coefficient of determination R-squared.

Type:: float

chi_squared

Reduced chi-squared: sum of squared residuals divided by degrees of freedom.

Type:: float

success

True if curve_fit converged.

Type:: bool

message

Convergence message or error description.

Type:: str

covariance_matrix

Full parameter covariance matrix returned by curve_fit.

Type:: np.ndarray or None

t_fit

Time values used for fitting, after NaN removal and masking.

Type:: np.ndarray or None

model: str

parameters: Dict[str, float]

parameter_errors: Dict[str, float]

fitted_curve: ndarray

residuals: ndarray

r_squared: float

chi_squared: float

success: bool

message: str

covariance_matrix: ndarray | None = None

t_fit: ndarray | None = None

summary()[source]

Return a formatted string summarizing fit quality and parameters.

Return type:: str

__init__(model, parameters, parameter_errors, fitted_curve, residuals, r_squared, chi_squared, success, message, covariance_matrix=None, t_fit=None)

Parameters:

model (str)
parameters (Dict[str, float])
parameter_errors (Dict[str, float])
fitted_curve (ndarray)
residuals (ndarray)
r_squared (float)
chi_squared (float)
success (bool)
message (str)
covariance_matrix (ndarray | None)
t_fit (ndarray | None)

Return type:

None

class epyr.relaxation.RelaxationFitComparison[source]

Dict of model name to RelaxationFitResult, with a tabular __repr__.

Behaves exactly like a plain dict (subscripting, iteration, .items(), …). Printing it shows R-squared, chi-squared, and every fitted parameter side by side for all models, so the full comparison is visible without looping over individual summary() calls.

Modules

`fitting`	T1/T2 relaxation fitting module.
`models`	Time-domain relaxation models for EPR T1/T2 measurements.