Line

Line Configuration

Emission line configuration for spectral fitting.

class unite.line.config.Redshift(name=None, *, prior=None)[source]

Bases: Parameter

A named delta redshift parameter that can be shared between lines.

Default priors is uniform between -0.01 and 0.01.

Parameters:

  • name (str | None)

  • prior (Prior | None)

class unite.line.config.FWHM(name=None, *, prior=None)[source]

Bases: Parameter

A named FWHM parameter (km/s) that can be shared between lines.

Default prior is uniform between 0 and 1000 km/s.

Parameters:

  • name (str | None)

  • prior (Prior | None)

class unite.line.config.LineShape(name=None, *, prior=None)[source]

Bases: Parameter

A named generic shape parameter that can be shared between lines.

Used for dimensionless profile shape parameters such as Gauss-Hermite moments (h3, h4) or spectral indices. The default prior is a wide uniform Uniform(-10, 10); in practice the profile’s default_priors() provides a more specific default when no token is supplied explicitly.

Parameters:

  • name (str | None)

  • prior (Prior | None)

class unite.line.config.Flux(name=None, *, prior=None)[source]

Bases: Parameter

A named flux parameter that can be shared between lines.

Default prior is uniform between -3 and 3 (relative to initial guess).

Parameters:

  • name (str | None)

  • prior (Prior | None)

class unite.line.config.Tau(name=None, *, prior=None)[source]

Bases: Parameter

A named optical depth parameter for absorption lines.

Parametrizes the peak optical depth of the intrinsic (pre-LSF) profile: tau_0 = tau(lambda_center) where the wavelength-dependent optical depth is tau(lam) = tau_0 * phi_norm(lam) and phi_norm = phi / phi(center) is the profile normalized to unity at line center. The resulting transmission is T(lam) = exp(-tau(lam)).

tau_0 = 1 means the intrinsic profile has 1/e transmission (≈ 37%) at line center; tau_0 = 3 gives ≈ 5% transmission (mildly optically thick); values much above 6 are effectively black at line center.

Because the normalization uses the intrinsic (zero-LSF) profile peak, tau_0 is an instrument-independent property of the absorber. The observed absorption depth depends on how well the line is resolved: an unresolved line will show shallower absorption than tau_0 predicts at a single wavelength, but the model correctly accounts for this via LSF convolution.

For asymmetric profiles (GaussHermite with h3 ≠ 0, SkewVoigt with large alpha), the profile maximum lies away from the nominal center wavelength. tau_0 is defined as the optical depth at the nominal center, not the absolute maximum of the profile.

Default prior is uniform between 0 and 10.

Parameters:

  • name (str | None)

  • prior (Prior | None)

class unite.line.config.ConfigMatrices(wavelengths, strengths, profile_codes, flux_names, flux_matrix, z_names, z_matrix, p0_names, p0_matrix, p1v_names, p1v_matrix, p1d_names, p1d_matrix, p2_names, p2_matrix, tau_names, tau_matrix, is_tau, line_zorders, applies_matrix, priors)[source]

Bases: object

Precomputed indicator matrices mapping unique parameters to per-line arrays.

Each matrix has shape (n_unique_params, n_lines). A 1 at position [i, j] means unique parameter i contributes to line j. Matrix-vector products turn a stacked vector of sampled values into a per-line array, replacing a Python loop at JIT trace time.

Profile parameters are split into three slots matching the positional arguments of _integrate_single_line:

  • Slot 0 (p0): primary velocity FWHM (always fwhm_*, converted to wavelength before vmap).

  • Slot 1 (p1): secondary parameter — either a velocity FWHM (fwhm_lorentz / fwhm_exp, stored in p1v_*) or a dimensionless shape parameter (h3, stored in p1d_*). The two sub-matrices are summed after appropriate unit conversion: p1 = p1v_kms * centers / C + p1d.

  • Slot 2 (p2): tertiary dimensionless parameter (h4), pass-through.

Parameters:
wavelengths: Array

Rest-frame line wavelengths (raw floats; units must match spectra). Shape (n_lines,).

strengths: Array

Multiplet relative flux strengths. Shape (n_lines,).

profile_codes: Array

Integer profile codes for lax.switch dispatch. Shape (n_lines,).

flux_names: list[str]

NumPyro site names for unique flux parameters (rows of flux_matrix).

flux_matrix: Array

Indicator matrix mapping flux parameters to lines. Shape (n_flux, n_lines).

z_names: list[str]

NumPyro site names for unique redshift parameters.

z_matrix: Array

Indicator matrix mapping redshift parameters to lines. Shape (n_z, n_lines).

p0_names: list[str]

NumPyro site names for slot-0 (primary FWHM) parameters.

p0_matrix: Array

Indicator matrix for slot-0 parameters. Shape (n_p0, n_lines).

p1v_names: list[str]

NumPyro site names for velocity FWHM parameters in slot 1.

p1v_matrix: Array

Indicator matrix for slot-1 velocity parameters. Shape (n_p1v, n_lines).

p1d_names: list[str]

NumPyro site names for dimensionless shape parameters in slot 1.

p1d_matrix: Array

Indicator matrix for slot-1 dimensionless parameters. Shape (n_p1d, n_lines).

p2_names: list[str]

NumPyro site names for slot-2 (tertiary dimensionless) parameters.

p2_matrix: Array

Indicator matrix for slot-2 parameters. Shape (n_p2, n_lines).

tau_names: list[str]

NumPyro site names for unique tau (optical depth) parameters.

tau_matrix: Array

Indicator matrix mapping tau parameters to lines. Shape (n_tau, n_lines).

is_tau: Array

Boolean mask indicating which lines are absorption lines. Shape (n_lines,).

line_zorders: Array

Depth-ordering integer for each line. Shape (n_lines,). Tau absorbers at zorder Z attenuate components with zorder < Z.

applies_matrix: Array

Static boolean matrix encoding which tau lines attenuate which emission lines. applies_matrix[j, k] is True when line_zorders[k] > line_zorders[j] and is_tau[k]. Shape (n_lines, n_lines).

priors: dict[str, Prior]
class unite.line.config.LineConfiguration[source]

Bases: object

Configuration of spectral lines for spectral fitting.

All lines are added via add_line(). Pass a scalar center for a single line, or a sequence of wavelengths for a multiplet (lines sharing one flux parameter with relative strengths).

Shared kinematics are expressed by passing the same Redshift or FWHM instance to multiple calls.

Examples

>>> z = Redshift('nlr', prior=Uniform(0, 0.5))
>>> fwhm = FWHM('nlr', prior=Uniform(0, 1000))
>>> config = LineConfiguration()
>>> config.add_line('Ha', 6564.61, z, fwhm=fwhm)
>>> config.add_line('[NII]', [6585.27, 6549.86], z,
...     fwhm=fwhm, strength=[2.95, 1.0])
add_line(name, center, *, profile='gaussian', redshift=None, flux=None, tau=None, strength=1.0, zorder=None, **param_kwargs)[source]

Add one spectral line.

Return type:

None

Parameters:
namestr

Unique identifier for the line (e.g. 'Ha', '[OIII]5007', 'Ha_narrow'). Line names must be unique within a LineConfiguration; adding a second line with the same name raises ValueError.

centerfloat, Quantity, or sequence thereof

Rest-frame wavelength(s).

redshiftRedshift, optional

Redshift parameter token. A fresh Redshift() is created if not provided.

fluxFlux, optional

Flux parameter token for emission lines. A fresh Flux() is created if not provided. Cannot be used with absorption profiles.

tauTau, optional

Optical depth parameter token for absorption lines. A fresh Tau() is created if not provided. Cannot be used with emission profiles.

strengthfloat or sequence of float, optional

Relative flux strength. For multiplets, broadcast to match the number of centers. Default 1.0.

zorderint, optional

Depth-ordering integer. Tau absorbers at zorder Z attenuate all components (emission lines and continuum) with zorder < Z. Defaults to 1 for absorption lines (tau token supplied) and 0 for emission lines.

profilestr or Profile, optional

Line profile. Default 'gaussian'.

**param_kwargsParameter

Named parameter tokens keyed by the profile’s param_names(). Missing parameters are filled from default_priors(). Examples: fwhm_gauss=FWHM('narrow'), h3=Param('narrow_h3', prior=Uniform(-0.5, 0.5)).

Raises:
ValueError

If name is already used by another line in this configuration.

TypeError

If flux is passed for an absorption profile, or tau is passed for an emission profile.

Parameters:
add_lines(name, centers, *, profile='gaussian', redshift=None, flux=None, tau=None, strength=1.0, zorder=None, **param_kwargs)[source]

Add multiple lines, each with an independent name.

Each entry in centers becomes one line with a unique name. When name is a single string, names are auto-generated as '{name}_{center.value:g}' (e.g. 'NII_6585', 'NII_6550'). When name is a sequence, it must have the same length as centers. All other arguments may be supplied as a single value (broadcast to every line) or as a sequence of the same length as centers.

Return type:

None

Parameters:
namestr | Sequence[str]

Single name or sequence of names, one per center.

centersQuantity

Rest-frame wavelengths. Must be non-empty.

profilestr or Profile, optional

Line profile shared by all lines. Default 'gaussian'.

redshiftRedshift or sequence thereof, optional

Redshift token(s). A single value is shared across all lines; a sequence assigns one token per line.

fluxFlux or sequence thereof, optional

Flux token(s). Same broadcasting rule as redshift.

tauTau or sequence thereof, optional

Optical depth token(s). Same broadcasting rule as flux.

strengthfloat or sequence of float, optional

Relative flux strengths. Default 1.0.

**param_kwargsParameter or sequence of Parameter

Profile parameter tokens. Each value follows the same broadcasting rule.

Raises:
ValueError

If centers is empty, if name sequence has the wrong length, or if any sequence argument has a length other than 1 or len(centers).

TypeError

If any token has the wrong type for its slot.

Parameters:
build_matrices()[source]

Build precomputed indicator matrices from this configuration.

Return type:

ConfigMatrices

Returns:
ConfigMatrices

Parameter-to-line mapping matrices and line metadata.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Parameters are grouped into named sections by kind ('redshift', 'fwhm_gauss', 'flux', etc.). Within each section the dict key is simply the parameter’s name, so there is no redundant prefix. Parameter expression bounds may only reference parameters in the same section; cross-kind references raise TypeError.

Return type:

dict

Returns:
dict

Ordered keys are the section names followed by 'lines'.

property wavelengths: list[Quantity]

Rest-frame wavelengths as a list of Quantity values (one per line).

property centers: Quantity

Rest-frame wavelengths of all lines in this configuration.

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

LineConfiguration

Parameters:
ddict

As produced by to_dict().

Returns:
LineConfiguration
Parameters:

d (dict)

to_yaml()[source]

Serialize to a YAML string.

Return type:

str

Returns:
str
classmethod from_yaml(text)[source]

Deserialize from a YAML string.

Return type:

LineConfiguration

Parameters:
textstr

YAML string as produced by to_yaml().

Returns:
LineConfiguration
Parameters:

text (str)

save(path)[source]

Save to a YAML file.

Return type:

None

Parameters:
pathstr or Path

Output file path.

Parameters:

path (str | Path)

classmethod load(path)[source]

Load from a YAML file.

Return type:

LineConfiguration

Parameters:
pathstr or Path

Path to a YAML file written by save().

Returns:
LineConfiguration
Parameters:

path (str | Path)

merge(other, *, strict=True)[source]

Merge another LineConfiguration into a new one.

Return type:

LineConfiguration

Parameters:
otherLineConfiguration

Configuration to merge.

strictbool

If True (default), raise ValueError on any token name collision between the two configs. If False, same-named tokens of the same type are treated as shared (the token from self is kept); same-named tokens of different types still raise.

Returns:
LineConfiguration

New configuration containing lines from both self and other.

Raises:
ValueError

On name collisions (strict mode) or type mismatches.

Parameters:

Line Profiles

Concrete line profile implementations.

class unite.line.library.Profile[source]

Bases: ABC

Abstract base class for spectral line profiles.

A profile declares which parameters it requires (via param_names() and default_priors()) and provides an integrate() method that computes the profile integral over wavelength bins.

Each concrete subclass carries an integer code for dispatch in JAX arrays, and supports serialization via to_dict() / from_dict().

code: int

Integer code for this profile type, used in JAX arrays.

abstractmethod param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

abstractmethod default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate(low, high, center, lsf_fwhm, **params)[source]

Integrate the profile over wavelength bins.

Delegates to integrate_branch() by mapping keyword arguments to positional slots (p0, p1, p2) in param_names() order.

Return type:

Array

Parameters:
lowArrayLike

Lower wavelength edges of bins.

highArrayLike

Upper wavelength edges of bins.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

**paramsArrayLike

Parameter values, keyed by the names from param_names().

Returns:
Array

Fractional flux integrated in each bin (sums to 1 over all bins).

Parameters:
evaluate(wavelength, center, lsf_fwhm, **params)[source]

Evaluate the normalised profile at wavelength points.

Delegates to evaluate_branch() by mapping keyword arguments to positional slots (p0, p1, p2) in param_names() order.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

**paramsArrayLike

Parameter values, keyed by the names from param_names().

Returns:
Array

Normalised profile value at each wavelength point (1/wavelength units).

Parameters:
abstractmethod integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Return type:

Callable[..., Array]

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

abstractmethod evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Return type:

Callable[..., Array]

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

abstractmethod to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

abstractmethod classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

Profile

Parameters:

d (dict)

unite.line.library.profile_from_dict(d)[source]

Deserialize a Profile from a dictionary using the ‘type’ key.

Return type:

Profile

Parameters:
ddict

Dictionary with a 'type' key matching a registered profile class.

Returns:
Profile
Raises:
KeyError

If the type is not registered.

Parameters:

d (dict)

class unite.line.library.Gaussian[source]

Bases: Profile

Gaussian (normal) line profile.

Requires a single parameter fwhm_gauss. The instrumental LSF is added in quadrature: total_fwhm = sqrt(lsf_fwhm² + fwhm_gauss²).

code: int = 0

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

Gaussian

Parameters:

d (dict)

class unite.line.library.Cauchy[source]

Bases: Profile

Cauchy (Lorentzian) line profile.

Requires a single parameter fwhm_lorentz. The LSF is not convolved — this profile is a pure Lorentzian.

Note: This profile is implemented as a PseudoVoigt with LSF=0 for consistency with the scientific assumptions of the package (all lines are convolved with instrumental LSF).

code: int = 1

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

Cauchy

Parameters:

d (dict)

class unite.line.library.PseudoVoigt[source]

Bases: Profile

Pseudo-Voigt line profile (Thompson et al. 1987).

Requires two parameters: fwhm_gauss for the Gaussian component and fwhm_lorentz for the Lorentzian component. The instrumental LSF is added in quadrature to the Gaussian component.

code: int = 2

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

PseudoVoigt

Parameters:

d (dict)

class unite.line.library.Laplace[source]

Bases: Profile

Laplace (double-exponential) line profile.

Requires a single parameter fwhm_exp. The LSF is not convolved — this profile is a pure Laplace distribution.

code: int = 3

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

Laplace

Parameters:

d (dict)

class unite.line.library.SEMG[source]

Bases: Profile

Symmetric Exponentially Modified Gaussian (SEMG) line profile.

A Gaussian (with LSF) convolved with a symmetric Laplace (double-exponential) distribution. Requires two parameters: fwhm_gauss for the intrinsic Gaussian component and fwhm_exp for the Laplacian component. The instrumental LSF is added in quadrature to the Gaussian component.

code: int = 4

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

SEMG

Parameters:

d (dict)

class unite.line.library.GaussHermite[source]

Bases: Profile

Gauss-Hermite line profile.

A Gaussian (with LSF) modified by Hermite polynomial corrections for skewness (h3) and kurtosis (h4). Requires three parameters: fwhm_gauss for the intrinsic Gaussian FWHM, h3 for the skewness coefficient, and h4 for the kurtosis coefficient. The instrumental LSF is added in quadrature to the Gaussian component.

code: int = 5

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

GaussHermite

Parameters:

d (dict)

class unite.line.library.SplitNormal[source]

Bases: Profile

Split-normal (two-sided Gaussian) line profile.

A Gaussian with different standard deviations on each side of the mean. Requires two parameters: fwhm_blue for the blue (left) side and fwhm_red for the red (right) side. The instrumental LSF is added in quadrature to both components.

code: int = 6

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

SplitNormal

Parameters:

d (dict)

class unite.line.library.BoxGauss[source]

Bases: Profile

Boxcar distribution convolved with a Gaussian.

The intrinsic profile is a uniform rectangular (boxcar) distribution of full width fwhm_box centred at zero (area = 1), convolved with a Gaussian whose FWHM is the quadrature sum of fwhm_gauss and lsf_fwhm. As fwhm_box → 0 the profile reduces to a pure Gaussian; as fwhm_gauss → 0 (and lsf_fwhm → 0) it approaches the sharp rectangular distribution.

Requires two parameters: fwhm_box for the boxcar full width and fwhm_gauss for the intrinsic Gaussian component.

code: int = 8

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

BoxGauss

Parameters:

d (dict)

class unite.line.library.SkewVoigt[source]

Bases: Profile

Skew pseudo-Voigt line profile.

A pseudo-Voigt profile multiplied by a skew factor [1 + erf(alpha * (x - c) / (sqrt(2) * sigma_g))], where sigma_g is the standard deviation of the Gaussian component. The profile integrates to 1 for any value of alpha because the skew factor is odd and the pseudo-Voigt is even.

Convolution with the Gaussian LSF rescales the skewness parameter to

\[\begin{split}\\alpha_\\text{eff} = \\frac{\\alpha\\,\\sigma_g} {\\sqrt{\\sigma_\\text{tot}^2 + \\alpha^2\\sigma_\\text{lsf}^2}}\end{split}\]

where \(\\sigma_\\text{tot} = \\sqrt{\\sigma_g^2 + \\sigma_\\text{lsf}^2}\). The skewness is reduced by the LSF and vanishes entirely when fwhm_gauss = 0 (no intrinsic Gaussian component).

Requires three parameters: fwhm_gauss for the Gaussian component, fwhm_lorentz for the Lorentzian component, and alpha for the skewness (positive values shift flux redward).

code: int = 7

Integer code for this profile type, used in JAX arrays.

param_names()[source]

Return names of parameters this profile requires.

Return type:

tuple[str, ...]

Returns:
tuple of str

For example, ('fwhm_gauss',) for Gaussian, ('fwhm_gauss', 'fwhm_lorentz') for pseudo-Voigt, or ('fwhm_gauss', 'h3', 'h4') for Gauss-Hermite.

default_priors()[source]

Return sensible default priors for each parameter.

The keys must match param_names(). These are used when the user does not supply an explicit token for a parameter.

Return type:

dict[str, Prior]

Returns:
dict of str to Prior

For example, {'fwhm_gauss': Uniform(0, 1000)}.

integrate_branch()[source]

Return a JAX-compatible branch callable for lax.switch dispatch.

The returned function must have the fixed signature:

fn(low, high, center, lsf_fwhm, p0, p1, p2) -> Array

Parameters correspond to param_names() in order: p0 is param_names()[0], p1 is param_names()[1], p2 is param_names()[2]. Unused slots receive zero from the model builder and must be ignored.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

evaluate_branch()[source]

Return a JAX-compatible branch callable for pointwise evaluation.

The returned function must have the fixed signature:

fn(wavelength, center, lsf_fwhm, p0, p1, p2) -> Array

Returns the normalised profile value at each wavelength point.

Returns:
callable

A pure-JAX function suitable as a lax.switch branch.

to_dict()[source]

Serialize to a YAML-safe dictionary.

Return type:

dict

classmethod from_dict(d)[source]

Deserialize from a dictionary.

Return type:

SkewVoigt

Parameters:

d (dict)

unite.line.library.resolve_profile(profile)[source]

Convert a profile string or instance to a Profile object.

Return type:

Profile

Parameters:
profilestr or Profile

Profile name (case-insensitive) or instance.

Returns:
Profile
Raises:
ValueError

If the string is not a recognized profile alias.

Parameters:

profile (str | Profile)

Integration Functions

JAX-jitted line profile integration and evaluation kernels.

Integration kernels (integrate_*) compute the fraction of a normalized profile that falls wi_absthin each wavelength bin [low, high]. Evaluation kernels (evaluate_*) compute the normalized profile value (probability density) at arbitrary wavelength points.

All functions are pure JAX wi_absth no numpyro dependency and are designed to be called from wi_absthin jax.jit()-compiled model code.

unite.line.functions.integrate_gaussian(low, high, center, lsf_fwhm, fwhm)[source]

Integrate a Gaussian profile over wavelength bins.

Return type:

Array

Parameters:
lowArrayLike

Lower bin edges.

highArrayLike

Upper bin edges.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhmArrayLike

Intrinsic Gaussian FWHM.

Returns:
jnp.ndarray

Integrated fraction per bin.

Parameters:
unite.line.functions.evaluate_gaussian(wavelength, center, lsf_fwhm, fwhm)[source]

Evaluate a normalised Gaussian profile at wavelength points.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhmArrayLike

Intrinsic Gaussian FWHM.

Returns:
jnp.ndarray

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_voigt(low, high, center, lsf_fwhm, fwhm_g, fwhm_l)[source]

Integrate a Voigt profile over wavelength bins via the extended pseudo-Voigt.

Uses the Ida, Ando & Toraya (2000) extended pseudo-Voigt approximation, which achieves < 0.12% peak-height deviation from the true Voigt profile using a four-component mixture: Gaussian, Lorentzian, irrational, and hyperbolic-sech². The LSF Gaussian FWHM is added in quadrature to the intrinsic Gaussian FWHM before computing the extended-pseudo-Voigt parameters.

Return type:

Array

Parameters:
lowArrayLike

Lower bin edges.

highArrayLike

Upper bin edges.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_gArrayLike

Intrinsic Gaussian component FWHM.

fwhm_lArrayLike

Lorentzian component FWHM.

Returns:
jnp.ndarray

Integrated fraction per bin.

Parameters:
unite.line.functions.evaluate_voigt(wavelength, center, lsf_fwhm, fwhm_g, fwhm_l)[source]

Evaluate a normalised Voigt profile at wavelength points via the Faddeeva function.

Computes the exact Voigt profile using the Humlicek (1982) W4 rational approximation to the Faddeeva function, which is accurate to ~1e-4 relative error across the upper half-plane.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_gArrayLike

Intrinsic Gaussian component FWHM.

fwhm_lArrayLike

Lorentzian component FWHM.

Returns:
jnp.ndarray

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_gaussianLaplace(low, high, center, lsf_fwhm, fwhm_g, fwhm_l)[source]

Integrate a symmetric EMG (Gaussian convolved wi_absth Laplace) over wavelength bins.

The LSF is added in quadrature to the Gaussian component, then the symmetric EMG CDF is evaluated analytically using a numerically stable erfcx form. See the SEMG derivation for details.

Return type:

Array

Parameters:
lowjnp.ndarray

Low wavelength edges of bins.

highjnp.ndarray

High wavelength edges of bins.

centerjnp.ndarray

Line centers.

lsf_fwhmjnp.ndarray

Instrumental LSF FWHM.

fwhm_gjnp.ndarray

Intrinsic Gaussian component FWHM.

fwhm_ljnp.ndarray

Laplace component FWHM (related to scale b by FWHM = 2 b ln 2).

Returns:
jnp.ndarray

Integrated fraction per bin (sums to 1 over all bins).

Parameters:
unite.line.functions.evaluate_gaussianLaplace(wavelength, center, lsf_fwhm, fwhm_g, fwhm_l)[source]

Evaluate a normalised Gaussian-Laplace (EMG) profile at wavelength points.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_gArrayLike

Intrinsic Gaussian component FWHM.

fwhm_lArrayLike

Laplacian component FWHM.

Returns:
jnp.ndarray

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_split_normal(low, high, center, lsf_fwhm, fwhm_blue, fwhm_red)[source]

Integrate a split-normal (two-sided Gaussian) profile over wavelength bins.

The split-normal distribution has different standard deviations on each side of the mean. The left side (blue, shorter wavelengths) uses fwhm_blue, and the right side (red, longer wavelengths) uses fwhm_red.

Return type:

Array

Parameters:
lowArrayLike

Lower bin edges.

highArrayLike

Upper bin edges.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_blueArrayLike

Blue side (left) Gaussian FWHM.

fwhm_redArrayLike

Red side (right) Gaussian FWHM.

Returns:
jnp.ndarray

Integrated fraction per bin.

Parameters:
unite.line.functions.evaluate_split_normal(wavelength, center, lsf_fwhm, fwhm_blue, fwhm_red)[source]

Evaluate a normalised split-normal profile at wavelength points.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_blueArrayLike

Blue side (left) Gaussian FWHM.

fwhm_redArrayLike

Red side (right) Gaussian FWHM.

Returns:
jnp.ndarray

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_boxGauss(low, high, center, lsf_fwhm, fwhm_box, fwhm_gauss)[source]

Integrate a boxcar-Gaussian convolution profile over wavelength bins.

The intrinsic profile is a uniform rectangular (boxcar) distribution of width fwhm_box centred at zero, convolved with a Gaussian whose FWHM is the quadrature sum of fwhm_gauss and lsf_fwhm.

Return type:

Array

Parameters:
lowArrayLike

Lower bin edges.

highArrayLike

Upper bin edges.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_boxArrayLike

Full width of the boxcar distribution.

fwhm_gaussArrayLike

Intrinsic Gaussian component FWHM, combined with lsf_fwhm in quadrature.

Returns:
Array

Integrated fraction per bin.

Parameters:
unite.line.functions.evaluate_boxGauss(wavelength, center, lsf_fwhm, fwhm_box, fwhm_gauss)[source]

Evaluate a normalised boxcar-Gaussian convolution profile at wavelength points.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_boxArrayLike

Full width of the boxcar distribution.

fwhm_gaussArrayLike

Intrinsic Gaussian component FWHM, combined with lsf_fwhm in quadrature.

Returns:
Array

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_gaussHermite(low, high, center, fwhm_lsf, fwhm_g, h3, h4)[source]

Integrate a Gauss-Hermite profile over wavelength bins.

Uses the closed-form CDF derived from the orthonormal probabilists’ Hermite expansion. Convolving wi_absth the Gaussian LSF rescales the shape parameters as h_m' = h_m * (sigma_g / sigma_tot)^m. See the Gauss-Hermite derivation for details.

Return type:

Array

Parameters:
lowjnp.ndarray

Low wavelength edges of bins.

highjnp.ndarray

High wavelength edges of bins.

centerjnp.ndarray

Line centers.

fwhm_lsfjnp.ndarray

Instrumental LSF FWHM.

fwhm_gjnp.ndarray

Gaussian component FWHM.

h3jnp.ndarray

Gauss-Hermite h3 (skewness) coefficient.

h4jnp.ndarray

Gauss-Hermite h4 (kurtosis) coefficient.

Returns:
jnp.ndarray

Integrated fraction per bin (sums to 1 over all bins).

Parameters:
unite.line.functions.evaluate_gaussHermite(wavelength, center, fwhm_lsf, fwhm_g, h3, h4)[source]

Evaluate a normalised Gauss-Hermite profile at wavelength points.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

fwhm_lsfArrayLike

Instrumental LSF FWHM.

fwhm_gArrayLike

Gaussian component FWHM.

h3ArrayLike

Gauss-Hermite h3 coefficient.

h4ArrayLike

Gauss-Hermite h4 coefficient.

Returns:
jnp.ndarray

Normalised profile value at each wavelength point.

Parameters:
unite.line.functions.integrate_skewVoigt(low, high, center, lsf_fwhm, fwhm_g, fwhm_l, alpha)[source]

Integrate a skew pseudo-Voigt profile over wavelength bins.

Uses the same extended pseudo-Voigt approximation as integrate_voigt, multiplied by the skew correction integrated via the error function. The skewness parameter is rescaled after convolution with the LSF via the Gaussian-body exact formula with an FXIG boost correction for the Lorentzian component.

Return type:

Array

Parameters:
lowArrayLike

Lower bin edges.

highArrayLike

Upper bin edges.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM at the line center.

fwhm_gArrayLike

Intrinsic Gaussian component FWHM.

fwhm_lArrayLike

Lorentzian component FWHM.

alphaArrayLike

Skewness parameter relative to sqrt(fwhm_g**2 + fwhm_l**2).

Returns:
Array

Integrated fraction per bin.

Parameters:
unite.line.functions.evaluate_skewVoigt(wavelength, center, lsf_fwhm, fwhm_g, fwhm_l, alpha)[source]

Evaluate a normalised skew pseudo-Voigt profile at wavelength points.

Evaluates V_pV(x) * [1 + erf(alpha_eff * (x-c) / w0)] where V_pV is the LSF-convolved pseudo-Voigt (Thompson et al.) and alpha_eff is the effective skewness after convolution, computed via the Gaussian-body exact formula with an FXIG boost correction for the Lorentzian component.

Return type:

Array

Parameters:
wavelengthArrayLike

Wavelength points at which to evaluate the profile.

centerArrayLike

Line center wavelength.

lsf_fwhmArrayLike

Instrumental line spread function FWHM.

fwhm_gArrayLike

Intrinsic Gaussian component FWHM.

fwhm_lArrayLike

Lorentzian component FWHM.

alphaArrayLike

Skewness parameter relative to sqrt(fwhm_g**2 + fwhm_l**2).

Returns:
Array

Normalised profile value at each wavelength point (1/wavelength units).

Parameters: