PyMolFit

PyMolFit is an independent pure-Python package for modelling and correcting telluric absorption in astronomical spectra. It is based on the concepts, workflow, and radiative-transfer approach of the original ESO Molecfit, with a Python API for both spectrum files and wavelength-flux arrays.

PyMolFit does not import or run Molecfit and is not affiliated with or endorsed by ESO.

Installation

python -m pip install pymolfit

Install plotting support for the tutorial notebooks:

python -m pip install "pymolfit[interactive]"

PyMolFit supports Python 3.10 and newer.

Correct A Spectrum File

The main API is correct():

from pymolfit import correct

result = correct(
    input_path="spectrum.fits",
    wavelength_medium="air",
)

wavelength = result.corrected.wavelength
corrected_flux = result.corrected.flux

Use wavelength_medium="vacuum" for vacuum wavelengths. The argument may be omitted only when the FITS metadata declares the wavelength medium unambiguously.

For table-based echelle products, PyMolFit uses common order/detector columns to preserve real physical groups and common quality columns such as QUAL or DQ to exclude flagged pixels. Wide orders may be divided into smaller radiative-transfer chunks for memory control, but those chunks continue to share one smooth wavelength-alignment model for their physical order.

Results remain in memory unless an output is requested:

from pymolfit import save_corrected_txt, save_fit_product_ecsv

save_corrected_txt(result, "corrected_spectrum.txt")
save_fit_product_ecsv(result, "fit_product.ecsv")

The text file contains a compact corrected spectrum. The ECSV product also contains the fitted transmission, model, masks, metadata, and provenance. The printed fit summary reports the resolved atmosphere and line data, numerical chunks versus physical groups, fitted parameters, masked-pixel counts, and residual line-alignment diagnostics.

Correct Wavelength And Flux Arrays

Arrays do not have a FITS header, so observing metadata is supplied with an Observation:

from pymolfit import Observation, correct

observation = Observation(
    time="2025-09-28T07:44:51",
    latitude_deg=-24.627,
    longitude_deg=-70.404,
    altitude_m=2635.0,
    airmass=1.18,
    resolving_power=140_000,
    wavelength_frame="observatory",
    instrument="ESPRESSO",
)

result = correct(
    wavelength=wavelength,
    flux=flux,
    wavelength_unit="angstrom",
    wavelength_medium="air",
    observation=observation,
)

wavelength_medium states whether the numbers are air or vacuum wavelengths. wavelength_frame separately states their velocity reference frame. Supported frames are observatory, barycentric, and heliocentric.

Select Fitting Regions Interactively

PyMolFit can save fit and exclusion windows without manually copying wavelength values from a plot:

from pymolfit import load_spectrum, select_telluric_regions

spectrum = load_spectrum(
    "spectrum.fits",
    wavelength_medium="air",
)

selector = select_telluric_regions(
    spectrum,
    output_path="telluric_regions.ecsv",
)

Candidate telluric transitions from the AER catalogue are marked automatically and colored by molecule. To create an initial selection automatically, enter a line count such as 100 and press Automatic. PyMolFit proposes fit windows around the transitions with the strongest expected atmospheric absorption, using both AER line intensity and the representative atmospheric column of each molecule. Automatic windows extend 12 sampled detector pixels to either side of each line by default, retaining the line core, wings, and nearby continuum needed to constrain alignment and instrumental broadening. It skips lines in detector/order gaps and merges overlapping windows. These proposals can be edited like any manual selection.

For manual editing, first zoom or pan to the desired area. Choose Fit or Exclude, enable the Draw regions checkbox, and drag rectangles around the lines; only their horizontal wavelength limits are stored. Drawing stays active until you clear the checkbox. Every stored region is numbered on the plot and listed in the side panel. Edit the filename field if needed, then press Save All once to write the complete collection. In a Jupyter notebook, run %matplotlib widget before opening the selector.

On later runs, the same output_path is detected and loaded automatically, so the selector window is skipped. Pass reuse_existing=False to reopen the saved regions for editing.

The ECSV file records both region types and their wavelength unit and air/vacuum medium. Apply it directly without transcribing any endpoints:

from pymolfit import correct

result = correct(
    input_path="spectrum.fits",
    wavelength_medium="air",
    region_file="telluric_regions.ecsv",
)

region_file cannot be combined with explicit fit_ranges or exclude_ranges.

Tutorials

The runnable notebooks in tutorials/ cover:

1. Correcting part of a spectrum
2. Correcting a full spectrum
3. Expert parameters
4. Correcting wavelength-flux arrays
5. Selecting telluric fit regions interactively

Start with Tutorial 1 for a short example or Tutorial 2 for a complete one-dimensional echelle spectrum.

Molecular And Atmospheric Data

The standard workflow automatically obtains the versioned AER molecular line catalogue, verifies its checksum, and caches it under ~/.cache/pymolfit/aer. It is not bundled in the Python wheel, and the normal workflow does not require a HITRAN API key.

Users may instead provide their own HITRAN .par files or other supported line and continuum data.

Scientific Basis And References

PyMolFit builds on the methods and scientific data developed by several projects. Publications using PyMolFit should cite the relevant upstream resources:

• ESO Molecfit: Smette et al. 2015, A&A 576, A77 and Kausch et al. 2015, A&A 576, A78
• AER LBLRTM line-by-line radiative-transfer methods and data
• AER MT_CKD atmospheric continuum model
• HITRAN molecular spectroscopic data
• MIPAS atmospheric reference profiles
• NOAA GDAS meteorological profiles

PyMolFit uses NumPy, SciPy, and Astropy.

Development

git clone https://github.com/nikolasvalsamidis97/PyMolFit.git
cd PyMolFit
python -m pip install -e ".[dev,plot]"
python -m pytest

Report problems through the GitHub issue tracker.

Licensing And Third-Party Data

PyMolFit's original Python code is available under the BSD 3-Clause License. Scientific datasets and derived coefficient tables retain their upstream terms and attribution requirements. See THIRD_PARTY_NOTICES.md for the included and automatically downloaded data.