sheap.Profiles.Combine module

Log-Lambda Profile Combination Utilities

This module defines utilities for combining multiple emission-line components evaluated in logarithmic wavelength space, using velocity-based parameterizations.

It provides:

  • PROFILE_LINE_FUNC_MAP_loglambda : A registry mapping canonical profile names (e.g. "gaussian", "lorentzian", "skewed_gaussian") to their corresponding log-lambda profile functions.

  • SPAF_loglambda : A SPAF (Sum Profiles Amplitude Free) constructor for log-lambda profiles, enabling physically motivated combinations of multiple emission lines with shared kinematic parameters.

The profiles referenced here operate internally in log(lambda) space via the transformation:

\[v = c \, \ln(\lambda / \lambda_0)\]

ensuring exact symmetry in velocity space for Doppler-broadened features.

SPAF allows multiple lines to: - Share kinematic parameters (velocity shift, FWHM, and shape parameters) - Enforce fixed or semi-fixed amplitude ratios (e.g. doublets, multiplets) - Be modeled with a reduced number of free parameters

Notes

  • Only profiles registered in PROFILE_LINE_FUNC_MAP_loglambda can be combined using SPAF_loglambda.

  • Base profiles must be decorated with @with_param_names and include at least "amplitude" and "lambda0" in their parameter list.

  • Physical bounds and initial values for the combined parameters are handled by the constraint-building utilities elsewhere in sheap.

Examples

from sheap.Profiles.combine import SPAF_loglambda

# Hα + [NII] doublet with fixed 3:1 ratio
centers = [6548.05, 6583.45]
rules = [(0, 1.0, 0), (1, 3.0, 0)]

G = SPAF_loglambda(
    centers=centers,
    amplitude_rules=rules,
    profile_name="gaussian",
)

# params = [amplitude0, vshift_kms, fwhm_v_kms]
y = G(x_lambda, params)
SPAF_loglambda(centers, amplitude_rules, profile_name)[source]

SPAF (Sum Profiles Amplitude Free) wrapper for log-lambda line profiles.

This builds a composite profile made of multiple lines that share the same shape parameters (e.g., vshift_kms, fwhm_v_kms, and any extra shape params like alpha, eta, or tau_kms), while allowing a flexible set of free amplitudes combined through amplitude_rules.

Parameters:

  • centers (list[float]) – Per-line rest wavelengths \(\lambda_0\) (Å). These are required and injected as the last parameter of the base profile for each line.

  • amplitude_rules (list[(line_idx, coefficient, free_amp_idx)]) –

    For each line: amp_line = coefficient * free_amplitudes[free_amp_idx].

    Example for a doublet with fixed 2:1 ratio sharing the same free amp 0:

    [(0, 1.0, 0), (1, 0.5, 0)]

  • profile_name (str) –

    Name of the base profile to use. It must exist in PROFILE_LINE_FUNC_MAP_loglambda and be decorated with @with_param_names.

    The base profile must include at least these parameter names: "amplitude" and "lambda0". Any additional parameters are treated as shared across all lines.

Returns:

A callable G(x_lambda, params) decorated with @with_param_names.

The parameter layout is:

  • [amplitude0, ..., amplitude{Nfree-1}, <shared_params...>]

where <shared_params...> are all base parameters except amplitude and lambda0 (in the same order as the base profile’s param_names).

Return type:

ProfileFunc

Notes

  • This works for any log-lambda base profile with signature base_func(x_lambda, params) and param_names containing "amplitude" and "lambda0".

  • Shape parameters are shared across all lines; only amplitudes are combined via amplitude_rules.

SPAF_loglambda_old(centers, amplitude_rules, profile_name)[source]

SPAF (Sum Profiles Amplitude Free) for log-lambda profiles.

Parameters:

  • centers (list[float]) – Per-line rest wavelengths λ0 (Å). These are required and injected as the last parameter of the base profile.

  • amplitude_rules (list[(line_idx, coefficient, free_amp_idx)]) –

    For each line: amp_line = coefficient * free_amplitudes[free_amp_idx]. Example for a doublet with fixed 2:1 ratio sharing the same free amp 0:

    [(0, 1.0, 0), (1, 0.5, 0)]

  • base_func (Callable) – A profile with param_names == [“amp”,”vshift_kms”,”fwhm_v_kms”,”lambda0”].

  • profile_name (str)

Returns:

params layout:
[ amplitude0, amplitude1, …, amplitude_{Nfree-1},

shift_kms, # shared Δv for the whole group fwhm_v_kms ] # shared FWHM in km/s

Return type:

ProfileFunc G(x, params)