API Models#
Models summaries#
- class satlas2.models.models.ExponentialDecay(a: float, tau: float, name: str = 'ExponentialDecay', prefunc: callable = None)[source]
Model for an exponential decay
- Parameters:
a (float) – Amplitude of the exponential
tau (float) – Half-life of the exponential
name (str, optional) – Name of the model, by default ‘ExponentialDecay’
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.Polynomial(p: ArrayLike, name: str = 'Polynomial', prefunc: callable = None)[source]
Model class for a polynomial response
- Parameters:
p (ArrayLike) – Polynomial coefficients, from the highest order down to the constant (as in
numpy.polyval()). The parameters are named after their order:p0is the constant,p1the linear coefficient, …name (str) – Name of the model
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.SkewedVoigt(A: float, mu: float, FWHMG: float, FWHML: float, skew: float, name: str = 'SkewedVoigt', prefunc: callable = None)[source]
Model for a skewed Voigt peak by the error function. Negative skew value is left-skewed, positive skew value is right-skewed.
- Parameters:
A (float) – Amplitude of the peak
mu (float) – Position of the peak
FWHMG (float) – Gaussian FWHM
FWHML (float) – Lorentzian FWHM
skew (float) – Skew of the peak, as defined in
satlas2.lineshapes.skew()name (str, optional) – Name of the model, by default ‘SkewedVoigt’
prefunc (callable, optional) – Transform of the input, by default None
- class satlas2.models.models.PiecewiseConstant(values: ArrayLike, bounds: ArrayLike, name: str = 'PiecewiseConstant', prefunc: callable = None)[source]
Model class for a PiecewiseConstant response
- Parameters:
values (ArrayLike) – Background values between bounds, starting at -inf
bounds (ArrayLike) – Bounds for background values
name (str, optional) – Name of the model
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.Voigt(A: float, mu: float, FWHMG: float, FWHML: float, name: str = 'Voigt', prefunc: callable = None)[source]
Model for a Voigt lineshape
- Parameters:
A (float) – Amplitude of the profile
mu (float) – Position of the peak
FWHMG (float) – Gaussian FWHM of the peak
FWHML (float) – Lorentzian FWHM of the peak
name (str, optional) – Name of the model, by default ‘Voigt’
prefunc (callable, optional) – Transform function of the input, by default None
Methods
Calculate the total FWHM of the profiles, with uncertainty, taking the correlations into account.
- class satlas2.models.hfsModel.HFS(I: float, J: ArrayLike, A: TypeAliasForwardRef('ArrayLike') | None = None, B: TypeAliasForwardRef('ArrayLike') | None = None, C: TypeAliasForwardRef('ArrayLike') | None = None, df: float = 0, fwhmg: float = 50, fwhml: float = 50, name: str = 'HFS', peak: str = 'voigt', peak_kwargs: dict | None = None, N: int | None = None, offset: float = 0, poisson: float = 0, scale: float = 1.0, racah: bool = True, order: int = 1, use_saturation: bool = False, saturation: float = 0.0, prefunc: Callable | None = None)[source]
Initializes a hyperfine spectrum Model with the given hyperfine parameters.
- Parameters:
I (float) – Integer or half-integer value of the nuclear spin
J (ArrayLike) – A sequence of 2 spins, respectively the J value of the lower state and the J value of the higher state
A (ArrayLike, optional) – A sequence of 2 A values, respectively for the lower and the higher state, by default [0, 0]
B (ArrayLike, optional) – A sequence of 2 B values, respectively for the lower and the higher state, by default [0, 0]
C (ArrayLike, optional) – A sequence of 2 C values, respectively for the lower and the higher state, by default [0, 0]
df (float, optional) – The centroid of the spectrum, by default 0
fwhmg (float, optional) – The Gaussian FWHM of the Voigt profile, by default 50
fwhml (float, optional) – The Lorentzian FWHM of the Voigt profile, by default 50
name (str, optional) – Name of the model, by default ‘HFS’
peak (str, optional) – peak function to use, by default ‘voigt’
peak_kwargs (dict, optional) – additional fitting parameters for skew and custom peaks. The
"skewvoigt"peak needs a"skew"parameter, defined as insatlas2.lineshapes.skew()N (int, optional) – Number of sidepeaks to be generated, by default None
offset (float, optional) – Offset in units of x for the sidepeak, by default 0
poisson (float, optional) – The poisson factor for the sidepeaks, by default 0
scale (float, optional) – The amplitude of the entire spectrum, by default 1.0
racah (bool, optional) – Use individual amplitudes are setting the Racah intensities, by default True
order (int, optional) – Define the order of the transition, used to calculate the allowed transitions and initial intensities, by default 1
use_saturation (bool, optional) – If True, apply the saturation model to transition amplitudes. Defaults to False. Cannot be combined with racah. Adds a Saturation parameter to the model; the (fixed) amplitudes are recalculated whenever its value changes.
saturation (float, optional) – Saturation parameter (>= 0). Only used when use_saturation is True; otherwise the value is ignored. The value controls the exponential mapping between Racah intensities and saturated amplitudes.
prefunc (callable, optional) – Transformation to be applied on the input before evaluation, by default None
Notes
Saturation. With
use_saturation=Truethe amplitudes of the lines are not free parameters but follow from theSaturationparameter. TheAmp<line>parameters are fixed and are recalculated every time the value ofSaturationis set, so they always correspond to the current saturation: after a fit or a random walk they, and the results dataframe, show the amplitudes belonging to the fitted saturation.This is done in the model, and not by giving each
Amp<line>parameter an lmfit expression ofSaturation, for two reasons:The amplitudes are normalised to the strongest line, so the expression of every line has to contain the terms of all lines. Evaluating these expressions is slow: for a spectrum with 24 lines it takes about 6 ms per change of the saturation, more than ten times the cost of evaluating the spectrum itself, which would dominate every fit and random walk.
The model must give the correct spectrum without a
Fitter, e.g. when plotting. Expressions only exist inside lmfit, so the calculation would have to be duplicated in the model.
Expressions remain the right tool for relations chosen by the user, such as
setExpr().Methods
Calculate the total FWHM of the profiles, with uncertainty, taking the correlations into account.
pos()Returns the positions of the peaks in MHz in the hyperfine spectrum
Extensive models#

Implementation of the various common Models.
- class satlas2.models.models.ExponentialDecay(a: float, tau: float, name: str = 'ExponentialDecay', prefunc: callable = None)[source]#
Bases:
ModelModel for an exponential decay
- Parameters:
a (float) – Amplitude of the exponential
tau (float) – Half-life of the exponential
name (str, optional) – Name of the model, by default ‘ExponentialDecay’
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.PiecewiseConstant(values: ArrayLike, bounds: ArrayLike, name: str = 'PiecewiseConstant', prefunc: callable = None)[source]#
Bases:
ModelModel class for a PiecewiseConstant response
- Parameters:
values (ArrayLike) – Background values between bounds, starting at -inf
bounds (ArrayLike) – Bounds for background values
name (str, optional) – Name of the model
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.Polynomial(p: ArrayLike, name: str = 'Polynomial', prefunc: callable = None)[source]#
Bases:
ModelModel class for a polynomial response
- Parameters:
p (ArrayLike) – Polynomial coefficients, from the highest order down to the constant (as in
numpy.polyval()). The parameters are named after their order:p0is the constant,p1the linear coefficient, …name (str) – Name of the model
prefunc (callable, optional) – Transform function for the input, by default None
- class satlas2.models.models.SkewedVoigt(A: float, mu: float, FWHMG: float, FWHML: float, skew: float, name: str = 'SkewedVoigt', prefunc: callable = None)[source]#
Bases:
VoigtModel for a skewed Voigt peak by the error function. Negative skew value is left-skewed, positive skew value is right-skewed.
- Parameters:
A (float) – Amplitude of the peak
mu (float) – Position of the peak
FWHMG (float) – Gaussian FWHM
FWHML (float) – Lorentzian FWHM
skew (float) – Skew of the peak, as defined in
satlas2.lineshapes.skew()name (str, optional) – Name of the model, by default ‘SkewedVoigt’
prefunc (callable, optional) – Transform of the input, by default None
- class satlas2.models.models.Voigt(A: float, mu: float, FWHMG: float, FWHML: float, name: str = 'Voigt', prefunc: callable = None)[source]#
Bases:
ModelModel for a Voigt lineshape
- Parameters:
A (float) – Amplitude of the profile
mu (float) – Position of the peak
FWHMG (float) – Gaussian FWHM of the peak
FWHML (float) – Lorentzian FWHM of the peak
name (str, optional) – Name of the model, by default ‘Voigt’
prefunc (callable, optional) – Transform function of the input, by default None
Implementation of the HFSModel class, currently only supplied with a Voigt profile.
- class satlas2.models.hfsModel.HFS(I: float, J: ArrayLike, A: TypeAliasForwardRef('ArrayLike') | None = None, B: TypeAliasForwardRef('ArrayLike') | None = None, C: TypeAliasForwardRef('ArrayLike') | None = None, df: float = 0, fwhmg: float = 50, fwhml: float = 50, name: str = 'HFS', peak: str = 'voigt', peak_kwargs: dict | None = None, N: int | None = None, offset: float = 0, poisson: float = 0, scale: float = 1.0, racah: bool = True, order: int = 1, use_saturation: bool = False, saturation: float = 0.0, prefunc: Callable | None = None)[source]#
Bases:
ModelInitializes a hyperfine spectrum Model with the given hyperfine parameters.
- Parameters:
I (float) – Integer or half-integer value of the nuclear spin
J (ArrayLike) – A sequence of 2 spins, respectively the J value of the lower state and the J value of the higher state
A (ArrayLike, optional) – A sequence of 2 A values, respectively for the lower and the higher state, by default [0, 0]
B (ArrayLike, optional) – A sequence of 2 B values, respectively for the lower and the higher state, by default [0, 0]
C (ArrayLike, optional) – A sequence of 2 C values, respectively for the lower and the higher state, by default [0, 0]
df (float, optional) – The centroid of the spectrum, by default 0
fwhmg (float, optional) – The Gaussian FWHM of the Voigt profile, by default 50
fwhml (float, optional) – The Lorentzian FWHM of the Voigt profile, by default 50
name (str, optional) – Name of the model, by default ‘HFS’
peak (str, optional) – peak function to use, by default ‘voigt’
peak_kwargs (dict, optional) – additional fitting parameters for skew and custom peaks. The
"skewvoigt"peak needs a"skew"parameter, defined as insatlas2.lineshapes.skew()N (int, optional) – Number of sidepeaks to be generated, by default None
offset (float, optional) – Offset in units of x for the sidepeak, by default 0
poisson (float, optional) – The poisson factor for the sidepeaks, by default 0
scale (float, optional) – The amplitude of the entire spectrum, by default 1.0
racah (bool, optional) – Use individual amplitudes are setting the Racah intensities, by default True
order (int, optional) – Define the order of the transition, used to calculate the allowed transitions and initial intensities, by default 1
use_saturation (bool, optional) – If True, apply the saturation model to transition amplitudes. Defaults to False. Cannot be combined with racah. Adds a Saturation parameter to the model; the (fixed) amplitudes are recalculated whenever its value changes.
saturation (float, optional) – Saturation parameter (>= 0). Only used when use_saturation is True; otherwise the value is ignored. The value controls the exponential mapping between Racah intensities and saturated amplitudes.
prefunc (callable, optional) – Transformation to be applied on the input before evaluation, by default None
Notes
Saturation. With
use_saturation=Truethe amplitudes of the lines are not free parameters but follow from theSaturationparameter. TheAmp<line>parameters are fixed and are recalculated every time the value ofSaturationis set, so they always correspond to the current saturation: after a fit or a random walk they, and the results dataframe, show the amplitudes belonging to the fitted saturation.This is done in the model, and not by giving each
Amp<line>parameter an lmfit expression ofSaturation, for two reasons:The amplitudes are normalised to the strongest line, so the expression of every line has to contain the terms of all lines. Evaluating these expressions is slow: for a spectrum with 24 lines it takes about 6 ms per change of the saturation, more than ten times the cost of evaluating the spectrum itself, which would dominate every fit and random walk.
The model must give the correct spectrum without a
Fitter, e.g. when plotting. Expressions only exist inside lmfit, so the calculation would have to be duplicated in the model.
Expressions remain the right tool for relations chosen by the user, such as
setExpr().