Developer Guide

RADIS is an open-source project, and therefore anyone can contribute, whether you already know spectroscopy or not. The project is organized around a GitHub repository.

Installation for developers

This is the installation procedure for developpers. For the user documentation, see the use-only install.

  1. Fork the RADIS repository and use that url for the clone step below. This will make submitting changes easier in the long term for you.

  2. In a terminal, run:

    git clone https://github.com/<YOUR GITHUB USERNAME>/radis.git

  3. For a best experience, it is recommended to install Radis on top of an Anaconda Python distribution, in an isolated environment. We recommend to use the faster, local-optimization libmamba solver for Anaconda. You can create a radis environment with all dependencies with:

    cd radis
conda env create --file environment.yml --solver=libmamba

  4. Then install Radis in the radis-env environment:

    conda activate radis-env
pip install -e . -v

  • The -e (editable) argument creates a link from the local folder ./ into Python site-packages.

  • For development, you can install additional packages with pip install -e .[dev] These include tools for testing and linting your code.

  • For documentation development, use pip install -e .[docs] to install additional packages needed for building the documentation.

To make sure the install worked, run the first example from the Quick Start page. Then, you’re all set.

Note

The command pip install -e . is different from pip install radis --upgrade. The former will install the latest version from the local folder, which may be more recent than the latest release on PyPI.

GitHub repository

Getting Started

New to open source? Welcome! 👋 Here’s how to get started:

  1. Look for Good First Issues - these are specifically tagged to help new contributors.

  2. The Documentation TODO List is also a great place to start.

Making Changes

We use the GitHub Flow for all code changes:

  1. Fork the repository

  2. Create a branch for your feature

  3. Make your changes

  4. Open a Pull Request (PR)

  5. Address review comments

  6. Get merged!

For small changes (like fixing typos), you can edit directly on GitHub and open a PR.

Keeping Your Fork Updated

If you’re a regular contributor, keep your fork in sync with the main repository:

  1. Add the upstream remote:

    git remote add upstream git://github.com/radis/radis.git
git fetch upstream

  2. Create new branches from the latest upstream version:

    git branch -b [NEW_BRANCH] upstream/develop

  3. Update your branch with upstream changes:

    git pull --rebase upstream [NEW_BRANCH]

  4. Push to your fork:

    git push -u origin [NEW-BRANCH]

Contributing Securely: HITRAN Credentials

Some RADIS features (e.g., fetching HITEMP databases from HITRAN) require a valid HITRAN account. These credentials are provided to GitHub Actions as secrets:

  • HITRAN_EMAIL

  • HITRAN_PASSWORD

These tests can be ran using pytest -m "needs_HITRAN_credentials". Due to GitHub’s security model, repository secrets are never exposed to forks, see also the GitHub documentation . If you push changes to your own fork and run workflows there, those workflows will not have access to HITRAN_EMAIL or HITRAN_PASSWORD.

Option 1: Continue working in your fork (with your own secrets)

If you prefer to work in your fork:

  1. Navigate to Settings → Secrets and variables → Actions on your fork’s GitHub page.

  2. Add the following repository secrets:

    • HITRAN_EMAIL → your HITRAN account email

    • HITRAN_PASSWORD → your HITRAN account password

  3. Workflows in your fork will then use your credentials when fetching HITEMP databases.

  4. Once your changes are ready, open a Pull Request (PR) against the main repository. A manual review will be required to allow all the tests to be ran on radis/radis repository.

Note

You must have a valid HITRAN registration before adding these.

Note

Only the GitHub actions on your fork will have access to your secrets. This way, you do the tests on your side before asking for changes to be merged on radis/radis repository.

Option 2: Work on a branch inside the main radis/radis repository. Applies to regular contributors.

  1. Request Write, Maintain, or Admin access from the RADIS maintainers.

  2. Push your work to a branch inside the main repository, for example feature/my-new-test.

  3. When workflows run there, they will have access to the official secrets.

RADIS will use these environment variables for authentication.

Code Style and Linting

We use the Black and Flake8 coding style to ensure consistent code formatting. Code style is checked using CI services which run automatically on each pull request. The linting is executed by the file linting.yml in the .github/workflows folder.

Black is automatically installed when radis is set-up in developer mode.

To format any file/files:

black /path/to/file/or/directory/

You can include Black coding style directly in some text editors

Black coding style can be checked automatically before each commit. For that all you need to do is to run the following command once:

cd radis
pre-commit install

On each commit, format will be fixed if it was incorrect. All you need to do is to commit a second time. Example:

$ git commit -am "test"
black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted [ALL FAILING FILES]
All done!
1 file reformatted.

$ git commit -am "test"
black....................................................................Passed
[develop XXX] test
 1 file changed, 1 insertion(+)

Note that pre-commit will always require you to commit again after a test was failed, because it’s safer. If for any reason you want to skip formatting you can commit with the --no-verify argument.

Dependency Management

RADIS uses modern Python packaging with pyproject.toml for pip installations and environment.yml for conda installations. These files are kept in sync through automated tests.

Adding Dependencies

When adding new dependencies:

  1. Add them to both pyproject.toml and environment.yml

  2. Run the sync test locally: python radis/test/test_sync_dependencies.py

  3. Choose the appropriate dependency group:

    • Core dependencies: Add to both files’ main section

    • Development tools: Add to [project.optional-dependencies].dev in pyproject.toml

    • Documentation tools: Add to [project.optional-dependencies].docs in pyproject.toml

Testing RADIS

Test Status

Test routines are automatically executed by Travis CI whenever changes are made to the GitHub repository.

It is recommended to run these tests locally to identify potential errors before pushing changes. To run the tests locally, assuming you have cloned the source code (see the Install section), execute the following command in the radis directory:

cd radis
pytest

The entire test procedure takes approximately 5–10 minutes. You can use pytest filtering keys to run specific tests only.

Selecting Tests

You can select or exclude specific tests using the -m option. For example, to run only the fast tests, use:

pytest -m fast

Commonly used tags include:

  • fast: Tests that run in under 1 second.

  • needs_connection: Requires an internet connection.

  • needs_config_file: Requires the ~/radis.json configuration file.

Additional tags for user-defined [HITEMP-2010] databases, as described in the Configuration file section:

  • needs_db_HITEMP_CO2_DUNHAM: Requires the HITEMP-CO2-DUNHAM database in ~/radis.json.

  • needs_db_HITEMP_CO_DUNHAM: Requires the HITEMP-CO-DUNHAM database in ~/radis.json.

  • needs_db_CDSD_HITEMP_PC: Requires the CDSD-HITEMP-PC database in ~/radis.json.

The default test routine executed on GitHub actions (see the radis/.travis.yml file) are:

pytest -m "fast and not needs_db_CDSD_HITEMP_PCN and not needs_db_CDSD_HITEMP and not needs_db_CDSD_HITEMP_PC"
pytest -m "not fast and not needs_cuda and not download_large_databases and not needs_db_CDSD_HITEMP and not needs_db_CDSD_HITEMP_PCN and not needs_db_CDSD_HITEMP_PC and not needs_db_HITEMP_CO2_DUNHAM and not needs_db_HITEMP_CO_DUNHAM"

Writing New Tests

Any function starting with test will be automatically detected by pytest. Use assert statements within the function to validate object properties. For example:

def test_positive(a):
    assert a > 0

Tip: Ensure that no figures are opened by default in your test routines, as this may cause the process to hang when executed by pytest. To enforce non-blocking behavior, add the following lines within your test function:

if plot:
    import matplotlib.pyplot as plt
    plt.ion()  # Prevent Matplotlib from blocking execution during pytest

Refer to previous pull requests for examples of test cases written for new features (e.g., #495 or #3697).

Test Files

To ensure errors are reproducible, use the test files provided in the radis/test/files and radis/test/validation directories. These files include examples of line databases, spectra, and energy levels. You can retrieve the paths to these test files using the getTestFile() and getValidationCase() functions, respectively.

Load a line database file:

from radis.test.utils import getTestFile
from radis.api.hitranapi import hit2df
df = hit2df(getTestFile("hitran_CO_fragment.par"))

print(df)  # Replace with your test code

>>> Out:
       id  iso       wav           int             A  ...  gpp  branch  jl  vu  vl
0   5    1  3.705026  2.354000e-44  2.868000e-10  ...  1.0       1   0   4   4
...

Load a Spectrum object:

from radis.test.utils import getTestFile
from radis import load_spec
s = load_spec(getTestFile("CO_Tgas1500K_mole_fraction0.5.spec"))

print(s)  # Replace with your test code

>>> Out:
    Spectrum Name:  CO_Tgas1500K_mole_fraction0.5.spec
Spectral Arrays
----------------------------------------
   abscoeff         (37,870 points)
...

Debugging

Use the printdbg() function in radis.misc and the DEBUG_MODE global variable for debugging.

Code Coverage

Code coverage ensures that every line in RADIS is properly tested. View the current code coverage status (click the badge for details):

Code Coverage

To view the test coverage report locally, use codecov, which is integrated with pytest through the --cov=./ command:

pip install codecov pytest-cov
cd radis/test
pytest --cov=./

Performance Benchmarks

RADIS performance is benchmarked against previous versions in a dedicated project: radis-benchmark.

Results are available at: 🔗 https://radis.github.io/radis-benchmark/

Benchmarks

Architecture

The RADIS modules are organized with the following flow chart

https://radis.readthedocs.io/en/latest/_images/RADIS_flow_chart.svg

The upper part shows the successive calculation steps of the Line-by-Line module. These steps appear clearly in the source code of the eq_spectrum() and non_eq_spectrum() methods of the SpectrumFactory. See details at the end of this file.

Methods are written in Factory objects inherited with the following scheme:

DatabankLoader > BaseFactory > BroadenFactory > BandFactory > SpectrumFactory

The Input Conditions in the left part, and the Computation Parameters on the right part, are the input parameters of the different RADIS front-ends:

The Input databases are either automatically downloaded from [HITRAN-2020], or defined locally in a Configuration file

The bottom part includes the post-processing modules of RADIS, in particular:

Methods from the Flow Chart: this methods are called successively from the radis.lbl.factory.SpectrumFactory.eq_spectrum() and radis.lbl.factory.SpectrumFactory.non_eq_spectrum() methods.

Help

If you encounter any problem:

  1. Check if it’s a known issue in our GitHub Issues

  2. If not, please open a new issue with:

    • A quick summary

    • Steps to reproduce

    • Expected vs actual behavior

    • Any relevant notes or attempted solutions

You can also ask for advice on the community chat:

Gitter Slack