spectrum_broadening

Numerical routines for line broadening of stick spectra.

A stick spectrum is a list of discrete lines, each given by a wavenumber (in cm^-1) and an intensity. Broadening convolves each line with a Gaussian (or Lorentzian) kernel on a regular wavenumber grid using the peak-height convention: the broadened profile of a single line reaches exactly the line intensity at the line position, no area normalization is applied. This reproduces the legacy build_spectrum.sh awk implementation, which calculates I(grid) = sum_k I_k * exp(-alpha * (grid - nu_k)^2) with a default alpha of 0.0025 cm^-2 (FWHM of about 33.3 cm^-1) on a grid from 10 cm^-1 (inclusive) to 4000 cm^-1 (exclusive) with a step of 0.25 cm^-1.

Summary

Functions:

alpha_from_fwhm	Convert a Gaussian full width at half maximum to the exponent alpha.
broaden	Broaden a stick spectrum on a wavenumber grid.
fwhm_from_alpha	Convert a Gaussian exponent alpha to the full width at half maximum.
read_stick_spectrum	Read a two-column stick spectrum file.
wavenumber_grid	Build the regular wavenumber grid of the broadened spectrum.

Reference

alpha_from_fwhm(

fwhm: PositiveReal,

) → float

Convert a Gaussian full width at half maximum to the exponent alpha.

The Gaussian kernel is exp(-alpha * delta_nu^2), so the full width at half maximum is 2 * sqrt(ln(2) / alpha) and therefore alpha = 4 * ln(2) / fwhm^2.

Parameters:

fwhm (PositiveReal) – The full width at half maximum in cm^-1.

Returns:

The Gaussian exponent alpha in cm^-2.

Return type:

float

Raises:

SpectrumBroadeningError – If the full width at half maximum is not positive.

broaden(

wavenumbers: Np1DNumberArray,

intensities: Np1DNumberArray,

grid: Np1DNumberArray,

alpha: PositiveReal = 0.0025,

kernel: str = 'gaussian',

) → Np1DNumberArray

Broaden a stick spectrum on a wavenumber grid.

Each grid point accumulates the contributions of all sticks using the peak-height convention. For the Gaussian kernel the broadened spectrum is I(g) = sum_k I_k * exp(-alpha * (g - nu_k)^2). For the Lorentzian kernel the broadened spectrum is I(g) = sum_k I_k * gamma^2 / ((g - nu_k)^2 + gamma^2) where the half width at half maximum gamma = sqrt(ln(2) / alpha) is chosen such that both kernels share the same full width at half maximum for a given alpha.

The calculation uses a vectorized outer difference between the grid and the stick positions and is chunked along the grid axis to keep the memory footprint bounded for large inputs. All accumulation is performed in float64.

Parameters:

• wavenumbers (Np1DNumberArray) – The stick positions in cm^-1.

• intensities (Np1DNumberArray) – The stick intensities. Must have the same length as the stick positions.

• grid (Np1DNumberArray) – The wavenumber grid in cm^-1.

• alpha (PositiveReal, optional) – The Gaussian exponent alpha in cm^-2, by default 0.0025.

• kernel (str, optional) – The broadening kernel, either gaussian or lorentzian, by default gaussian.

Returns:

The broadened intensities on the grid as a float64 array.

Return type:

Np1DNumberArray

Raises:

SpectrumBroadeningError – If alpha is not positive, the kernel is unknown or the stick positions and intensities have different lengths.

fwhm_from_alpha(

alpha: PositiveReal,

) → float

Convert a Gaussian exponent alpha to the full width at half maximum.

Parameters:

alpha (PositiveReal) – The Gaussian exponent alpha in cm^-2.

Returns:

The full width at half maximum in cm^-1.

Return type:

float

Raises:

SpectrumBroadeningError – If alpha is not positive.

read_stick_spectrum(

filename: str,

) → tuple[Np1DNumberArray, Np1DNumberArray]

Read a two-column stick spectrum file.

The file must contain one line per stick with the wavenumber in cm^-1 in the first column and the intensity in the second column. Blank lines and lines starting with # are ignored. Additional columns are ignored as well.

Parameters:

filename (str) – The stick spectrum file to read.

Returns:

The wavenumbers and intensities of the sticks as float64 arrays.

Return type:

Tuple[Np1DNumberArray, Np1DNumberArray]

Raises:

SpectrumBroadeningError – If the file does not exist or contains a malformed line.

wavenumber_grid(

wavenumber_min: Real = 10.0,

wavenumber_max: Real = 4000.0,

wavenumber_step: PositiveReal = 0.25,

) → Np1DNumberArray

Build the regular wavenumber grid of the broadened spectrum.

The grid starts at wavenumber_min and increases in steps of wavenumber_step while staying strictly below wavenumber_max, exactly like the legacy awk loop for (i = min; i < max; i += step). The default grid therefore contains 15960 points from 10.0 cm^-1 to 3999.75 cm^-1.

Parameters:

• wavenumber_min (Real, optional) – The first grid point in cm^-1, by default 10.0.

• wavenumber_max (Real, optional) – The exclusive upper bound of the grid in cm^-1, by default 4000.0.

• wavenumber_step (PositiveReal, optional) – The grid spacing in cm^-1, by default 0.25.

Returns:

The wavenumber grid as a float64 array.

Return type:

Np1DNumberArray

Raises:

SpectrumBroadeningError – If the step is not positive or the upper bound is not larger than the lower bound.

DEFAULT_ALPHA = 0.0025

Default Gaussian exponent alpha in cm^-2 (legacy BROAD setting).

DEFAULT_WAVENUMBER_MAX = 4000.0

Default (exclusive) last grid point in cm^-1.

DEFAULT_WAVENUMBER_MIN = 10.0

Default first grid point in cm^-1.

DEFAULT_WAVENUMBER_STEP = 0.25

Default grid spacing in cm^-1.

KERNELS = ('gaussian', 'lorentzian')

Supported broadening kernels.