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: p0 is the constant, p1 the 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

calculateFWHM()

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 in satlas2.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=True the amplitudes of the lines are not free parameters but follow from the Saturation parameter. The Amp<line> parameters are fixed and are recalculated every time the value of Saturation is 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 of Saturation, 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

calculateFWHM()

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#

Inheritance diagram of satlas2.models.hfsModel, satlas2.models.models

Implementation of the various common Models.

class satlas2.models.models.ExponentialDecay(a: float, tau: float, name: str = 'ExponentialDecay', prefunc: callable = None)[source]#

Bases: Model

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.PiecewiseConstant(values: ArrayLike, bounds: ArrayLike, name: str = 'PiecewiseConstant', prefunc: callable = None)[source]#

Bases: Model

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.Polynomial(p: ArrayLike, name: str = 'Polynomial', prefunc: callable = None)[source]#

Bases: Model

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: p0 is the constant, p1 the 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: Voigt

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.Voigt(A: float, mu: float, FWHMG: float, FWHML: float, name: str = 'Voigt', prefunc: callable = None)[source]#

Bases: Model

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

calculateFWHM() → Tuple[float, float][source]#

Calculate the total FWHM of the profiles, with uncertainty, taking the correlations into account.

Returns:

Tuple of the form (value, uncertainty)

Return type:

Tuple[float, float]

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: Model

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 in satlas2.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=True the amplitudes of the lines are not free parameters but follow from the Saturation parameter. The Amp<line> parameters are fixed and are recalculated every time the value of Saturation is 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 of Saturation, 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().

calculateFWHM() → tuple[float, float][source]#

Calculate the total FWHM of the profiles, with uncertainty, taking the correlations into account.

Returns:

Tuple of the form (value, uncertainty)

Return type:

tuple[float, float]

pos() → ArrayLike[source]#

Returns the positions of the peaks in MHz in the hyperfine spectrum

Return type:

ArrayLike