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.

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.

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. 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.

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]

Sources

Install

This is the developper documentation, if you want to access the latest features, modify the code, or contribute. 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

  1. 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.

Update

Whenever you want to update your local copy of Radis, run:

git pull
pip install -e .

For development or documentation updates, use pip install -e .[dev] or pip install -e .[docs] respectively.

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.

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

Package Structure

The package is structured to exclude tests and documentation from the main installation:

  • Tests are available when installing with pip install -e .[dev]

  • Documentation tools are available with pip install -e .[docs]

  • The main installation (pip install radis or pip install -e .) includes only the core package

Update your changes online (push)

Submit a Pull Request from GitHub.

Online tests will be run automatically. They will check for:

  • Physics test cases, to ensure that the code is still working as expected (see Test Section to run them locally).

  • Code format (see Code Style and Linting).

  • Dependency synchronization between pyproject.toml and environment.yml

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 Travis (see the radis/.travis.yml file) is:

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"

This routine excludes all tests that require large database files.

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