astrocook.fitting.voigt_fitter module#

astrocook.fitting.voigt_fitter.convolve_flux(flux: ndarray, x_ang: ndarray, resol: Any, resol_unit: str = 'R') → ndarray[source]#

Convolves a flux array with a Gaussian kernel defined by resolution.

Handles both constant resolution (scalar) and variable resolution (array) across the wavelength grid.

Parameters:

  • flux (np.ndarray) – The input flux array (either normalized 0-1 or physical units).

  • x_ang (np.ndarray) – The wavelength grid in Angstroms. Must match flux length.

  • resol (float or np.ndarray) – Resolution value(s). - If float: Constant resolution across the spectrum. - If array: Pixel-by-pixel resolution (must match flux length).

  • resol_unit (str, optional) – Unit of the resolution value: - 'R': Resolving Power (\(R = \lambda / \Delta\lambda\)). - 'km/s': FWHM velocity. Defaults to 'R'.

Returns:

The convolved flux array with the same shape as input.

Return type:

np.ndarray

class astrocook.fitting.voigt_fitter.VoigtFitterV2(spectrum: SpectrumV2, system_list: SystemListV2, check_stop=None)[source]#

Bases: object

Engine for fitting Voigt profiles to spectral data.

This class orchestrates the optimization process. It handles:

  1. Resolution Logic: determining effective resolution (R or FWHM) from columns or metadata.

  2. Dynamic Masking: identifying relevant pixels for the fit to speed up computation.

  3. Optimization: utilizing scipy.optimize.least_squares to minimize residuals.

  4. Vectorization: calculating optical depths for multiple lines simultaneously.

Parameters:

  • spectrum (SpectrumV2) – The spectral data to fit. Must have a valid normalization (continuum) or be pre-normalized.

  • system_list (SystemListV2) – The list of absorption components to model.

__init__(spectrum: SpectrumV2, system_list: SystemListV2, check_stop=None)[source]#
prepare_fit_context(z_window_kms: float = 20.0) → Tuple[ndarray, ndarray][source]#

Prepares the internal state for fitting (masks, background, vectorized data).

Returns:

(lower_bounds, upper_bounds) for the free parameters.

Return type:

tuple

get_fit_context_data() → Dict[str, Any][source]#

Retrieve all internal data required for external likelihood calculations.

Extracts the sliced arrays, fit masks, and the model computation function used by the frequentist fitter, allowing external engines (like Bayesian samplers) to evaluate the exact same physical model. Must be called after prepare_fit_context().

Returns:

A dictionary containing: - 'x': The wavelength grid array. - 'y': The normalized flux array. - 'dy': The normalized flux error array. - 'mask': The boolean fit mask array. - 'compute_model': A callable function that takes a free parameter vector and returns the normalized model array.

Return type:

dict

fit(max_nfev: int = 2000, method: str = 'trf', z_window_kms: float = 20.0, verbose: int = 0) → Tuple[SystemListV2, ndarray, Any][source]#

Execute the Voigt profile optimization.

Performs a least-squares fit of the active components to the spectrum. Includes automatic spatial pre-filtering (fitting only pixels near the lines) and vectorized optical depth calculation.

Parameters:

  • max_nfev (int, optional) – Maximum number of function evaluations for the optimizer. Defaults to 2000.

  • method (str, optional) – Optimization method (e.g., 'trf', 'lm'). Defaults to 'trf'.

  • z_window_kms (float, optional) – Velocity window (km/s) around component centers to include in the fit mask. Defaults to 20.0.

  • verbose (int, optional) – Verbosity level for scipy.optimize.least_squares. Defaults to 0.

Returns:

A tuple containing:

  1. new_system_list (SystemListV2): A new system list containing the optimized parameter values and errors.

  2. final_model_flux (np.ndarray): The full model flux array (physical units), evaluated on the entire grid.

  3. res (OptimizeResult): The raw result object from scipy.optimize.

Return type:

tuple

compute_model_flux() → Tuple[ndarray, ndarray][source]#

Compute the model flux for the current parameters.

Calculates the Voigt profile model based on the current state of the system list, without performing any fitting/optimization.

Returns:

A tuple containing: 1. wavelength (np.ndarray): The wavelength grid in Angstroms. 2. model_flux (np.ndarray): The computed model flux (physical units).

Return type:

tuple