pyRadtran

A complete Python wrapper for libRadtran radiative transfer simulations, built on Pydantic for validation and xarray for output.

Prerequisites

This library is a Python wrapper around libRadtran. You must install libRadtran (Fortran binary + data files) separately before using pyRadtran.

1. Install libRadtran: Follow the official installation guide or use a package manager:

   • conda: conda install -c conda-forge libradtran
   • apt (Debian/Ubuntu): sudo apt install libradtran
   • Source: Download from libradtran.org and compile with make

2. Set the data path: Ensure the libRadtran data directory is available. You will pass it to Runner.execute(...) via the data_path argument (e.g. /usr/local/share/libRadtran/data).

Installation

pip install pyradtran

With optional plotting support:

pip install pyradtran[plot]

For development:

git clone https://github.com/openEarthModelling/pyRadtran.git
cd pyRadtran
pip install -e ".[dev]"

Quick Start

from pyradtran import Scene, Runner

scene = (
    Scene()
    .set_atmosphere(profile="us", altitude=2.663)
    .set_source_solar(sza=30.0)
    .set_wavelength(250.0, 1200.0)
    .set_solver(method="disort", streams=16)
    .set_output(quantities=["lambda", "edir"], quantity="transmittance")
)

result = Runner.execute(scene, data_path="/usr/local/share/libRadtran/data")
result.edir.plot()

See the documentation for more examples, including aerosol configurations, 3D scenes, and satellite simulations.

Key Features

• Fluent Scene Builder — configure atmospheres, sources, wavelengths, solvers, and aerosols through a chainable API.
• Aerosol Modelling — OPAC presets, custom OPAC, external aerosol files, and composite aerosols with Mie scattering.
• Convenience Functions — pre-configured setups for 3D, cloudy, lidar, polarized, satellite, solar, and thermal simulations.
• Type-Safe — built on Pydantic v2 for runtime validation and excellent IDE autocompletion.
• Typed — ships py.typed for full type-checker support.

Documentation

Full documentation is hosted on GitHub Pages, including API reference, tutorials, and example notebooks.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines on development setup, testing, and submitting pull requests.

License

This project is licensed under the MIT License.

Note: pyRadtran calls the libRadtran binary at runtime. libRadtran is licensed under the GNU GPL v2. Because pyRadtran interacts with libRadtran as a separate program (via subprocess), the pyRadtran code itself is not considered a derivative work under the GPL and is released under the MIT license. Users who use pyRadtran must comply with both the MIT terms and the libRadtran GPL terms.

Citation

If you use pyRadtran in your research, please cite it. A CITATION.cff file is included in this repository for your convenience.