API Reference¶

Functions¶

gaussfit_rs.fit_single_spectrum(*, spectrum, dopp_slit, spec_noise, guide_velocity, velocity_range, npix, npix_slack, dv, width_min, n_pixels=None, amplitude_rel_min, amplitude_rel_max, width_max, width_guess, xtol=1e-06, ftol=1e-06, gtol=1e-06, max_iter=2000)[source]¶

Fit a single Gaussian to one spectrum using the Rust backend.

The function searches for the brightest peak within guide_velocity ± velocity_range (km/s), normalises by that peak, then fits a bounded Levenberg-Marquardt Gaussian using the surrounding 2*npix pixel window.

Parameters:

spectrum – Spectral data, 1-D float32. All three arrays are trimmed to n_pixels before processing; pass pre-sliced arrays to avoid any copy overhead.
dopp_slit – Doppler velocity at each pixel [km/s], same length as spectrum.
spec_noise – 1-sigma noise estimate at each pixel (same units as spectrum).
guide_velocity – Expected line-centre velocity [km/s] used to locate the peak.
velocity_range – Half-width of the velocity search window around guide_velocity [km/s].
npix – Half-width of the fitting window around the peak (pixels).
npix_slack – Extra pixels added to the search window for the peak-finding step.
dv – Pixel scale [km/s per pixel]; used to compute velocity bounds.
width_min – Minimum allowed Gaussian sigma [km/s].
n_pixels – Number of pixels to use from the start of each array. Defaults to len(spectrum). Pass this when the arrays are longer than the intended fitting window.
amplitude_rel_min – Minimum allowed amplitude relative to the detected peak (e.g. 0.1).
amplitude_rel_max – Maximum allowed amplitude relative to the detected peak (e.g. 2.0).
width_max – Maximum allowed Gaussian sigma [km/s].
width_guess – Initial guess for the Gaussian sigma [km/s].
xtol – Convergence tolerance on the parameter step size (default 1e-6).
ftol – Convergence tolerance on the cost-function change (default 1e-6).
gtol – Convergence tolerance on the gradient norm (default 1e-6).
max_iter – Maximum LM iterations (default 2000).

Returns:

fit_results (ndarray, shape (8,), float32) – [amplitude, velocity, sigma, amplitude_err, velocity_err, sigma_err, reduced_chi2, flag]. See module docstring for details.
(i_left, i_right) (tuple[int, int]) – Pixel indices of the fitting window used (half-open, [i_left, i_right)).

Return type:

tuple[NDArray[np.float32], tuple[int, int]]

gaussfit_rs.fit_spectra_batch(*, spectra, dopp_slit, spec_noise, guide_velocity, velocity_range, npix, npix_slack, dv, width_min, n_pixels=None, amplitude_rel_min, amplitude_rel_max, width_max, width_guess, xtol=1e-06, ftol=1e-06, gtol=1e-06, max_iter=2000)[source]¶

Fit Gaussians to N spectra in parallel using all available CPU cores.

Equivalent to calling fit_single_spectrum() for each row of spectra, but processed concurrently in Rust via Rayon. The GIL is released for the duration of the computation.

Parameters:

spectra – Spectral data, shape (N, M), C-contiguous float32.
dopp_slit – Doppler velocity grid [km/s], shape (n_pixels,) — shared across all spectra (same wavelength solution assumed).
spec_noise – Per-spaxel noise, shape (N, M), C-contiguous float32.
n_pixels – Number of columns to use from the start of spectra. Defaults to the full column count spectra.shape[1].
guide_velocity, velocity_range, npix, npix_slack, dv, width_min,
amplitude_rel_min, amplitude_rel_max, width_max, width_guess,
xtol, ftol, gtol, max_iter – Same as fit_single_spectrum().

Returns:

fit_results (ndarray, shape (N, 8), float32) – One result row per input spectrum. Column layout same as fit_single_spectrum().
indices (ndarray, shape (N, 2), int32) – [:, 0] = i_left, [:, 1] = i_right for each spectrum.

Return type:

tuple[NDArray[np.float32], NDArray[np.int32]]

gaussfit_rs.fit_gaussian_f32(*, x, y, error, initial, lower_bounds, upper_bounds, xtol=1e-06, ftol=1e-06, gtol=1e-06, max_iter=2000)[source]¶

Fit a bounded Gaussian to (x, y ± error) data using the Rust backend.

Uses a Levenberg-Marquardt solver with box constraints on all three parameters (amplitude, mean, sigma).

Parameters:

x – Independent variable, shape (N,), float32. Must have at least 3 elements.
y – Observed values, shape (N,), float32.
error – 1-sigma uncertainties on y, shape (N,), float32. All values must be finite and non-zero.
initial – Starting guess [amplitude, mean, sigma], shape (3,).
lower_bounds – Lower bounds [amp_min, mean_min, sigma_min], shape (3,).
upper_bounds – Upper bounds [amp_max, mean_max, sigma_max], shape (3,).
xtol – Convergence tolerance on the parameter step size.
ftol – Convergence tolerance on the cost-function change.
gtol – Convergence tolerance on the gradient norm.
max_iter – Maximum number of outer LM iterations.

Returns:

ndarray, shape (8,), float32 – [amplitude, mean, sigma, amplitude_err, mean_err, sigma_err, reduced_chi2, flag]. flag is FLAG_SUCCESS (0) on convergence or FLAG_NO_CONVERGENCE (2) otherwise.

Return type:

NDArray[np.float32]

gaussfit_rs.fit_gaussian_f64(*, x, y, error, initial, lower_bounds, upper_bounds, xtol=1e-10, ftol=1e-10, gtol=1e-10, max_iter=2000)[source]¶

Fit a bounded Gaussian to (x, y ± error) data in double precision.

Identical to fit_gaussian_f32() but operates on float64 arrays throughout. Use when the data span a wide dynamic range or when f32 rounding would be significant.

Parameters and return value have the same structure as fit_gaussian_f32(), but all arrays are float64. Default tolerances are tighter (1e-10) to exploit the extra precision.