Welcome to speclib’s documentation!¶

API Reference¶

speclib: Tools for working with stellar spectral libraries.

class speclib.BinnedSpectralGrid(teff_bds, logg_bds, feh_bds, center, width, model_grid='phoenix', **kwargs)¶

Bases: object

Represents a multi-dimensional grid of binned spectra from a model library.

Supports trilinear interpolation over the parameter space.

teff_bds¶

The lower and upper bounds of the model temperatures to load.

Type:: iterable

logg_bds¶

The lower and upper bounds of the model logg values to load.

Type:: iterable

feh_bds¶

The lower and upper bounds of the model [Fe/H] to load.

Type:: iterable

center¶

The centers of the wavelength bins.

Type:: ~astropy.units.Quantity

width¶

The widths of the wavelength bins.

Type:: ~astropy.units.Quantity

lower¶

The lower bounds of the wavelength bins.

Type:: ~astropy.units.Quantity

upper¶

The upper bounds of the wavelength bins.

Type:: ~astropy.units.Quantity

fluxes¶

The fluxes of the model grid. Sorted by fluxes[teff][logg][feh].

Type:: dict

model_grid¶

Name of the model grid. Only phoenix is currently supported.

Type:: str

get_spectrum(teff, logg, feh)¶: Returns a binned spectrum for the given teff, logg, and feh.

get_spectrum(teff, logg, feh, interpolate=True)¶

Parameters:

teff (float) – Effective temperature of the model in Kelvin.
logg (float) – Surface gravity of the model in cgs units.
feh (float) – [Fe/H] of the model.
interpolate (bool, optional) – Whether to interpolate between grid points. If True (default), the spectrum will be trilinearly interpolated in (Teff, logg, [Fe/H]) space. If False, the nearest available grid point will be used without interpolation.

Returns:

flux – The interpolated flux array.

Return type:

~astropy.units.Quantity

class speclib.BinnedSpectrum(center, width, flux)¶

Bases: object

Represents a spectrum that has been binned into specified wavelength intervals.

Useful for simulating photometric measurements or spectral channels.

center¶

The centers of the wavelength bins.

Type:: ~astropy.units.Quantity

width¶

The widths of the wavelength bins.

Type:: ~astropy.units.Quantity

lower¶

The lower bounds of the wavelength bins.

Type:: ~astropy.units.Quantity

upper¶

The upper bounds of the wavelength bins.

Type:: ~astropy.units.Quantity

flux¶

The binned flux array.

Type:: ~astropy.units.Quantity

class speclib.Filter(name)¶

Bases: object

A photometric filter.

Loads filter metadata and response curve from local ECSV and text files.

name¶

Name of the filter.

Type:: str

wl_eff¶

Effective wavelength of the filter.

Type:: ~astropy.units.Quantity

bandwidth¶

Bandwidth of the filter.

Type:: ~astropy.units.Quantity

zeropoint_flux¶

Zeropoint flux of the filter.

Type:: ~astropy.units.Quantity

zeropoint_flux_err¶

Error on the zeropoint flux.

Type:: ~astropy.units.Quantity

response¶

Filter response curve as a spectrum.

Type:: ~speclib.Spectrum

resample(wavelength, taper=True)¶: Resample the filter response curve onto a new wavelength grid.

class speclib.SED(spec, filters, model_grid='phoenix')¶

Bases: object

A spectral energy distribution derived from a spectrum and a set of filters.

wavelength¶

Effective wavelengths of the filters.

Type:: ~astropy.units.Quantity

bandwidth¶

Bandwidths of the filters.

Type:: ~astropy.units.Quantity

flux¶

Filtered fluxes.

Type:: ~astropy.units.Quantity

classmethod from_grid(teff, logg, feh, filters, model_grid='phoenix')¶

Create an SED from a stellar model grid.

Parameters:

teff (float) – Effective temperature [K]
logg (float) – Surface gravity [cgs]
feh (float) – Metallicity [Fe/H]
filters (list) – List of ~speclib.Filter objects
model_grid (str) – Name of model grid (default ‘phoenix’)

Return type:

~speclib.SED

class speclib.SEDGrid(teff_bds, logg_bds, feh_bds, filters, model_grid='phoenix')¶

Bases: object

A grid of SEDs for quick interpolation.

teff_bds¶

The lower and upper bounds of the model temperatures to load.

Type:: iterable

logg_bds¶

The lower and upper bounds of the model logg values to load.

Type:: iterable

feh_bds¶

The lower and upper bounds of the model [Fe/H] to load.

Type:: iterable

wavelength¶

Effective wavelengths of the SED grid.

Type:: ~astropy.units.Quantity

bandwidth¶

Bandwidths of the interpolated SED grid.

Type:: ~astropy.units.Quantity

fluxes¶

The fluxes of the model grid. Sorted by fluxes[teff][logg][feh].

Type:: dict

model_grid¶

Name of the model grid. Only phoenix is currently supported.

Type:: str

get_SED(teff, logg, feh)¶: Returns a SED for the given teff, logg, and feh.

get_SED(teff, logg, feh)¶

Parameters:

teff (float) – Effective temperature of the model in Kelvin.
logg (float) – Surface gravity of the model in cgs units.
feh (float) – [Fe/H] of the model.

Returns:

flux – The interpolated flux array.

Return type:

~astropy.units.Quantity

class speclib.SpectralGrid(teff_bds, logg_bds, feh_bds, wavelength=None, spectral_resolution=None, model_grid='phoenix', **kwargs)¶

Bases: object

Represents a multi-dimensional grid of synthetic spectra from a model library.

Provides fast access to preloaded spectra and supports trilinear interpolation in (Teff, logg, [Fe/H]) space.

teff_bds¶

The lower and upper bounds of the model temperatures to load.

Type:: iterable

logg_bds¶

The lower and upper bounds of the model logg values to load.

Type:: iterable

feh_bds¶

The lower and upper bounds of the model [Fe/H] to load.

Type:: iterable

wavelength¶

Wavelengths of the interpolated spectrum.

Type:: ~astropy.units.Quantity

fluxes¶

The fluxes of the model grid. Sorted by fluxes[teff][logg][feh].

Type:: dict

model_grid¶

Name of the model grid. Only phoenix is currently supported.

Type:: str

get_flux(teff, logg, feh, interpolate=True)¶: Returns an interpolated flux array for the given teff, logg, and feh.

get_flux(teff, logg, feh, interpolate=True)¶

Parameters:

teff (float) – Effective temperature of the model in Kelvin.
logg (float) – Surface gravity of the model in cgs units.
feh (float) – [Fe/H] of the model.
interpolate (bool, optional) – Whether to interpolate between grid points. If True (default), the spectrum will be trilinearly interpolated in (Teff, logg, [Fe/H]) space. If False, the nearest available grid point will be used without interpolation.

Returns:

flux – The interpolated flux array as a 1-D vector aligned to self.wavelength.

Return type:

~astropy.units.Quantity

get_spectrum(teff, logg, feh, interpolate=True)¶: Deprecated alias for get_flux().

Deprecated since version 0.1.0: Use get_flux() instead.

class speclib.Spectrum(**kwargs)¶

Bases: Spectrum1D

A wrapper class for ~specutils.Spectrum1D with extended functionality for working with stellar model spectra.

This class adds capabilities to: - Load and interpolate spectra from various model grids - Resample spectra using synphot to conserve flux - Convolve spectra to lower resolution - Bin spectra into custom wavelength intervals

Parameters:: **kwargs (dict) – Arguments passed to the base Spectrum1D initializer.

from_grid(teff, logg, feh=0, wavelength=None, model_grid='phoenix')¶: Load a model spectrum from a library.

resample(wavelength)¶: Resample a spectrum while conserving flux.

bin(center, width)¶: Bin a model spectrum within specified wavelength bins.

bin(center, width)¶

Bin a model spectrum within specified wavelength bins.

Parameters:

center (~astropy.units.Quantity) – The centers of the wavelength bins.
width (~astropy.units.Quantity) – The widths of the wavelength bins.

Return type:

~speclib.BinnedSpectrum

classmethod from_grid(teff, logg, feh=0, alpha=0.0, wavelength=None, wl_min=None, wl_max=None, model_grid='phoenix', interpolate=True, verbose=False)¶

Load a model spectrum from a library.

Parameters:

teff (float) – Effective temperature of the model in Kelvin.
logg (float) – Surface gravity of the model in cgs units.
feh (float) – [Fe/H] of the model.
wavelength (~astropy.units.Quantity, optional) – Wavelengths of the interpolated spectrum.
wl_min (~astropy.units.Quantity, optional) – Minimum wavelength of the model spectrum.
wl_max (~astropy.units.Quantity, optional) – Maximium wavelength of the model spectrum.
model_grid (str, optional) – Name of the model grid.
verbose (bool, optional) – Print details for debugging.
interpolate (bool, optional) – Whether to interpolate between grid points. If True (default), the spectrum will be trilinearly interpolated in (Teff, logg, [Fe/H]) space. If False, the nearest available grid point will be used without interpolation.

Returns:

spec – A spectrum for the specified parameters.

Return type:

~speclib.Spectrum

regularize(delta_lambda=None)¶

Resample a spectrum to a regularly spaced wavelength grid.

Parameters:: delta_lambda (~astropy.units.Quantity, optional) – The spacing of the new wavelength grid. Defaults to the smallest spacing in the orignal grid.
Returns:: spec_new – A resampled spectrum.
Return type:: ~speclib.Spectrum

resample(wavelength, taper=False)¶

Resample a spectrum while conserving flux.

Parameters:: wavelength (~astropy.units.Quantity) – A new wavelength axis. Unit must be specified.
Returns:: spec_new – A resampled spectrum.
Return type:: ~speclib.Spectrum

set_spectral_resolution(spectral_resolution)¶

Set the spectral resolution by convolution with a Gaussian.

Parameters:: spectral_resolution (~astropy.units.Quantity) – The spectral resolution.
Returns:: spec_new – A spectrum with the desired spectral resolution.
Return type:: ~speclib.Spectrum

speclib.apply_filter(spec, filt)¶

Apply a photometric filter to a spectrum.

Parameters:

spec (~speclib.Spectrum) – The input spectrum.
filt (~speclib.Filter) – The filter object.

Returns:

flux – Filtered flux.

Return type:

~astropy.units.Quantity

speclib.download_file(remote_path, local_path, verbose=True)¶: Download a file via ftp.

speclib.download_newera_grid(grid_name: str, extract: bool | str = False, overwrite: bool = False, library_root: str | Path | None = None) → Path¶

Download a NewEra tarball if not already cached.

Parameters:

grid_name (str) – One of “newera_gaia”, “newera_lowres”, or “newera_jwst”.
extract (bool or {"missing", "all"}, optional) – Controls extraction behavior. False (default) keeps the tarball cached without unpacking. True or "missing" extracts only missing .txt members. "all" extracts every member in the archive.
overwrite (bool, optional) – If True, remove any existing files in the cache directory and re-download the tarball. Default is False.
library_root (str or Path, optional) – Base cache directory. Defaults to get_library_root().

Returns:

Path to the cached directory (e.g., ~/.speclib/libraries/newera_jwst).

Return type:

Path

Note

This function fetches reduced-resolution NewEra grids from the PHOENIX/1D NewEra V3.4 release (record 17935) hosted by FDR Hamburg, suitable for most applications (e.g., forward modeling, calibration).

speclib.download_phoenix_grid(overwrite=False)¶

speclib.mag_to_flux(mag, filt, mag_err=0, nsamples=100000)¶

Convert magnitude to flux using a filter zeropoint and propagate uncertainty.

Parameters:

mag (float) – Apparent magnitude.
filt (~speclib.Filter) – The filter.
mag_err (float, optional) – Uncertainty on the magnitude.
nsamples (int, optional) – Number of Monte Carlo samples (default 100,000).

Returns:

mean (~astropy.units.Quantity) – Mean flux.
std (~astropy.units.Quantity) – Standard deviation of the flux.