sheap.SheaProducts.Utils.CombineUtils module

Combine FWHM utilities for line profiles

Helpers to compute the full width at half maximum (FWHM) for different profile families, with optional uncertainty propagation and batched (vmap) evaluation.

Notes

  • For some analytic profiles, the FWHM is read directly from named shape parameters. For example:

    • Gaussian / Lorentzian: .. math:

      \mathrm{FWHM} = \text{fwhm}

    • Top-hat: .. math:

      \mathrm{FWHM} = \text{width}

    • Pseudo-Voigt: .. math:

      \mathrm{FWHM} \approx 0.5346\,\text{FWHM}_L
+ \sqrt{0.2166\,\text{FWHM}_L^2 + \text{FWHM}_G^2}

  • For other profiles (e.g., skewed shapes), a numeric half‑maximum search is performed around the peak.

#TODO change name from fwhm_conv to convination -> utils

compute_fwhm_split(profile, amp, center, extras)[source]

Compute the FWHM of a single line component for a given profile.

The function uses analytic formulas when available (Gaussian, Lorentzian, Top-hat, Pseudo‑Voigt). Otherwise, it estimates the half‑maximum width numerically around the peak.

Parameters:

  • profile (str) – Profile key (must exist in PROFILE_LINE_FUNC_MAP), e.g. "gaussian", "lorentzian", "top_hat", "voigt_pseudo", etc.

  • amp (jnp.ndarray) – Peak amplitude (scalar).

  • center (jnp.ndarray) – Line center (scalar).

  • extras (jnp.ndarray) – Remaining shape parameters in the order required by the profile, i.e. they correspond to param_names[2:].

Returns:

The full width at half maximum for the component (scalar).

Return type:

jnp.ndarray

Notes

  • Pseudo‑Voigt approximation: .. math:

    \mathrm{FWHM} \approx 0.5346\,\text{FWHM}_L
+ \sqrt{0.2166\,\text{FWHM}_L^2 + \text{FWHM}_G^2}

  • Numeric fallback scans a symmetric grid around the center and finds the left/right half‑max crossings.

compute_fwhm_split_with_error(profile, amp, center, extras, amp_err, center_err, extras_err)[source]

Compute FWHM and its 1σ uncertainty for a single component.

Uncertainty is propagated via the Jacobian of FWHM with respect to all input parameters (amp, center, extras):

\[\sigma_{\mathrm{FWHM}}^2 = \sum_i \left( \frac{\partial\,\mathrm{FWHM}}{\partial p_i} \, \sigma_{p_i} \right)^2\]
Parameters:

  • profile (str) – Profile key for compute_fwhm_split().

  • amp (jnp.ndarray) – Scalar amplitude, scalar center, and extras vector for the profile.

  • center (jnp.ndarray) – Scalar amplitude, scalar center, and extras vector for the profile.

  • extras (jnp.ndarray) – Scalar amplitude, scalar center, and extras vector for the profile.

  • amp_err (jnp.ndarray) – Matching 1σ uncertainties for the corresponding parameters.

  • center_err (jnp.ndarray) – Matching 1σ uncertainties for the corresponding parameters.

  • extras_err (jnp.ndarray) – Matching 1σ uncertainties for the corresponding parameters.

Returns:

  • fwhm_val (jnp.ndarray) – Estimated FWHM (scalar).

  • fwhm_uncertainty (jnp.ndarray) – Propagated 1σ uncertainty (scalar).

Return type:

Tuple[jax.numpy.ndarray, jax.numpy.ndarray]

Notes

Uses jax.jacfwd() to compute the gradient of the FWHM function with respect to the concatenated parameter vector.

make_batch_fwhm_split(profile)[source]

Create a batched FWHM evaluator for a given profile.

This returns a function that computes the full width at half maximum (FWHM) for multiple objects and multiple line components in parallel, using JAX’s vmap() for vectorization.

Parameters:

profile (str) – Profile name (must exist in PROFILE_LINE_FUNC_MAP), e.g. "gaussian", "lorentzian", "voigt_pseudo", etc.

Returns:

A function with signature:

fwhm_batch(amp, center, extras) -> jnp.ndarray

where - amp has shape (n_objects, n_lines), - center has shape (n_objects, n_lines), - extras has shape (n_objects, n_lines, n_extras),

and the result is a (n_objects, n_lines) array of FWHM values.

Return type:

callable

Notes

  • Analytic shortcuts are used for common profiles (Gaussian, Lorentzian, Top-hat, pseudo-Voigt).

  • For other profiles, a numeric search is performed around the line center to locate the half-maximum crossing.

make_batch_fwhm_split_with_error(profile)[source]

Vectorized (batched) FWHM + uncertainty evaluator for a profile.

Returns a function that accepts batched inputs for values and their uncertainties and computes both FWHM and its propagated 1σ error using two levels of vmap (over lines, then over batch).

Parameters:

profile (str) – Profile key for compute_fwhm_split_with_error().

Returns:

A function batcher(amp, center, extras, amp_err, center_err, extras_err) that returns (fwhm_val, fwhm_uncertainty) with shapes matching the leading batch dimensions of the inputs.

Return type:

Callable