Pyharp: Python-first High-performance Atmosphere Radiation Package

Pyharp is the one-stop tool for calculating the radiation flux of planetary atmospheres, from terrestrial to giant planets. Detailed documentation and examples are available at https://pyharp.readthedocs.io.

Installation

Pyharp can be installed via pip:

pip install pyharp

We support Linux and Mac operation systems with Python version 3.10+.

Spectroscopy workflow

Pyharp also includes pyharp.spectra, a pure-Python spectroscopy workflow for HITRAN line data, HITRAN CIA data, single-state absorption spectra, transmittance products, diagnostic plots, and gas-mixture overview figures. The former standalone spectra library now lives under the pyharp.spectra namespace.

The main library entry points are available from pyharp.spectra:

from pathlib import Path

from pyharp.spectra import (
    AbsorptionSpectrum,
    SpectroscopyConfig,
    SpectralBandConfig,
    compute_absorption_spectrum,
)

band = SpectralBandConfig(
    name="single_state",
    wavenumber_min_cm1=20.0,
    wavenumber_max_cm1=2500.0,
    resolution_cm1=1.0,
)
config = SpectroscopyConfig(
    output_path=Path("output/h2o_absorption_300K_1bar.nc"),
    hitran_cache_dir=Path("hitran"),
    species_name="H2O",
)
spectrum: AbsorptionSpectrum = compute_absorption_spectrum(
    config=config,
    band=band,
    temperature_k=300.0,
    pressure_pa=1.0e5,
)

SpectroscopyConfig.hitran_cache_dir stores downloaded HITRAN line and CIA files. SpectroscopyConfig.output_path controls where NetCDF products are written by CLI helpers and is also used to create parent output directories.

H2O continuum calculations use the MT_CKD_H2O coefficient file at external/MT_CKD_H2O/data/absco-ref_wv-mt-ckd.nc relative to the Pyharp repository root. It is tracked as a Git submodule. Clone Pyharp with submodules to fetch it immediately:

git clone --recurse-submodules https://github.com/chengcli/pyharp

If you already cloned Pyharp, initialize the submodule from the repository root:

git submodule update --init --recursive external/MT_CKD_H2O

If you are using command line argument outside of pyharp, clone MT_CKD directly:

mkdir -p external && cd external && git clone https://github.com/AER-RC/MT_CKD_H2O

The pyharp-dump CLI writes NetCDF spectroscopy products for single species, CIA pairs, and gas mixtures:

pyharp-dump xsection --species H2O --temperature-k 300 --pressure-bar 1 --wn-range=20,2500
pyharp-dump xsection --pair H2-H2 --temperature-k 300 --pressure-bar 1 --wn-range=20,10000
pyharp-dump xsection --pair H2-H2 --cia-model xiz --h2-state eq --temperature-k 300 --pressure-bar 1 --wn-range=20,10000
pyharp-dump transmission --species H2O --path-length-km 1 --wn-range=20,2500

Use repeated --wn-range=min,max values to write one NetCDF file per band. When you also pass --output, pyharp appends _<wnmin>_<wnmax> to the requested stem for each generated file. Use --output-dir to place auto-generated filenames under a different directory without overriding the filename pattern. For state-grid dumps, the auto-generated state section is written as <min_temp>_<max_temp>K_<min_pres>_<max_pres>bar, where temperature bounds come from the full (temperature + del_temperature) grid. Use --temperature-k and --pressure-bar as paired comma-separated vectors, for example --temperature-k 300,400 --pressure-bar 1,10. Add --del-temperature-k to evaluate temperature anomalies around each base state, for example --del-temperature-k -10,-5,0,5,10. Dump outputs are written on (del_temperature, pressure, wavenumber), include a temperature(pressure) variable for the base temperatures, store the pressure coordinate in Pa, and still retain degenerate del_temperature and pressure dimensions when only one state is requested. Across pyharp.spectra, wavenumber ranges are interpreted as inclusive at both ends: --wn-range=20,22 with 1 cm^-1 resolution samples 20, 21, and 22. See the pyharp-dump CLI documentation for the full command reference, output naming conventions, and NetCDF schema.

Plotting diagnostics are available from one entry point, pyharp-plot. It provides CIA binary coefficient, molecular cross-section, attenuation, transmission, and overview plot subcommands:

pyharp-plot binary --pair H2-H2 --temperature-k 300 --wn-range=20,10000
pyharp-plot binary --pair H2-H2 --cia-model 2018 --h2-state eq --temperature-k 300 --wn-range=20,10000
pyharp-plot binary --pair H2-H2 --cia-model xiz --h2-state eq --temperature-k 300 --wn-range=20,10000
pyharp-plot xsection --species CO2 --temperature-k 300 --pressure-bar 1 --wn-range=20,2500
pyharp-plot attenuation --species CO2 --temperature-k 300 --pressure-bar 1 --wn-range=20,2500
pyharp-plot transmission --composition H2O:0.1,H2:0.9 --temperature-k 300 --pressure-bar 1 --path-length-km 1 --wn-range=25,2500
pyharp-plot overview --species H2O CO2 --temperature-k 300 --pressure-bar 1 --wn-range=20,2500 --wn-range=2500,10000

Use --pair for CIA pairs, --species for molecules, and --composition for gas mixtures such as H2O:0.1,H2:0.9. All plot commands accept --wn-range=min,max; overview accepts multiple --wn-range values for multi-page PDFs. These ranges include both endpoints, so adjacent repeated ranges such as 20,2500 and 2500,10000 both include 2500. Use --output to choose the output path. Without --output, plots are written under --output-dir (default output/) with names derived from the target, plot type, temperature, pressure, and wavenumber range. For plot commands that use pressure, --temperature-k and --pressure-bar also accept matched comma-separated vectors such as --temperature-k 300,400 --pressure-bar 1,10. pyharp-plot then runs one plot per (T,P) pair in parallel. For xsection, attenuation, and transmission, one explicit --output path reused across multiple state pairs is expanded with _<temperature>K_<pressure>bar suffixes. For overview, all state/range pages are combined into one PDF.

Molecular line calculations also accept --broadening-composition BROADENER:FRACTION,..., for example air:0.8,self:0.2 or H2:0.85,He:0.15. If a requested foreign broadener is unavailable in the HITRAN table for the active absorber, Pyharp falls back to air for that fraction.

CIA pair workflows now derive the backend directly from --cia-model:

• --cia-model auto keeps the built-in HITRAN default filename mapping under hitran/
• --cia-model 2011 resolves H2-H2_2011.cia or H2-He_2011.cia from HITRAN
• --cia-model 2018 --h2-state eq|nm resolves H2-H2_eq_2018.cia or H2-H2_nm_2018.cia from HITRAN
• --cia-model xiz|orton --h2-state eq|nm selects one of the legacy H2-H2 or H2-He tables under orton_xiz_cia/

If a requested HITRAN pair/model/state combination does not have a configured file, pyharp raises an error rather than silently falling back to another CIA dataset. HITRAN 2011 does not distinguish eq vs nm, while xiz and orton require an explicit H2 spin-state choice through --h2-state.

See the pyharp-plot CLI documentation for command-specific options and more examples.

Supported built-in HITRAN line species are CH4, CO2, H2, H2O, H2S, N2, and NH3. Built-in CIA pair resolution includes the self pairs for these species where HITRAN CIA data is configured, plus CO2-CH4, CO2-H2, H2-He, and N2-CH4.

pyharp.spectra does not provide a fixed reference-column radiative-transfer experiment. Use the core Pyharp radiative-transfer APIs for column RT calculations, and use pyharp.spectra for spectroscopy inputs, diagnostics, single-state products, and overview plots.

Development

If you want to further develop Pyharp, you will need to install it locally, which allows you to modify the source code and test. Open a Linux or Mac terminal and clone this repo using the following command:

git clone https://github.com/chengcli/pyharp

This will copy all source files into your local computer. You will need to install a few system libraries before installing Pyharp. All following instructions are executed under the pyharp/ directory.

System required for building locally

• Python 3.10+
• Linux or macOS
• netCDF
• python virtual environment (venv)

MacOS installation

brew install netcdf

RedHat installation

sudo yum install netcdf

Ubuntu installation

sudo apt-get install libnetcdf-dev

Build C++ library

After you completed the installation steps, you can build the pyharp library. We will build the package in-place, meaning that the build (binary files) are located under pyharp/build/bin. To do so, make a new directory named build

mkdir build

All build files will be generated and placed under this directory. It is completely safe to delete the whole directory if you want another build. cd to build and cmake

cd build
cmake ..

This command tells the cmake command to look for CMakeFiles.txt in the parent directory, and start configuring the compile environment. Then compile the code by

make -j4

This comman will use 4 cores to compile the code in parallel. Once complete, all executable files will be placed in build/bin.

Build python package locally (dev mode)

The python library can be installed by running the following command in the root directory:

pip install -e .

Test the installation

To test the installation, import pyharp in a python shell:

import pyharp

The build is successful if you do not see any error messages.

Contributing

Contributions are welcome! Please open an issue or PR if you’d like to:

• Find a bug
• Suggest new functions
• Add examples
• Improve documentation
• Expand test coverage

Contact

Maintained by @chengcli — feel free to reach out with ideas, feedback, or collaboration proposals.