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.
Pyharp can be installed via pip:
pip install pyharpWe support Linux and Mac operation systems with Python version 3.10+.
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/pyharpIf you already cloned Pyharp, initialize the submodule from the repository root:
git submodule update --init --recursive external/MT_CKD_H2OIf 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_H2OThe 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,2500Use 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,10000Use --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 autokeeps the built-in HITRAN default filename mapping underhitran/--cia-model 2011resolvesH2-H2_2011.ciaorH2-He_2011.ciafrom HITRAN--cia-model 2018 --h2-state eq|nmresolvesH2-H2_eq_2018.ciaorH2-H2_nm_2018.ciafrom HITRAN--cia-model xiz|orton --h2-state eq|nmselects one of the legacy H2-H2 or H2-He tables underorton_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.
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/pyharpThis 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.
- Python 3.10+
- Linux or macOS
- netCDF
- python virtual environment (venv)
brew install netcdfsudo yum install netcdfsudo apt-get install libnetcdf-devAfter 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.
The python library can be installed by running the following command in the root directory:
pip install -e .To test the installation, import pyharp in a python shell:
import pyharpThe build is successful if you do not see any error messages.
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
Maintained by @chengcli — feel free to reach out with ideas, feedback, or collaboration proposals.