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.

You want to become a contributor? Welcome! First follow the install procedure for developpers below. Then, you can have a look at all the GitHub opened issues. and tackle specifically one of the Good First Issues.

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 .[dev] -v

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

  • [dev] is optional, but installs additional developer packages that may be useful for testing and linting your code.

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 .[dev]

Note

The command pip install -e .[dev] 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.

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 linting below).

Testing RADIS

Test status

Test routines are performed automatically by Travis CI whenever a change is made on the GitHub repository. See the current test status below:

https://travis-ci.com/radis/radis

It is a good practice to perform these tests locally to detect potential errors before pushing. To run the tests locally, assuming you cloned the source code (see the Install section ), run the following command in the radis directory:

cd radis
pytest

The whole test procedure takes 5 - 10 min. You can use pytest filtering keys to run specific tests only

Select tests

You can select or ignore some tests with the -m option, for instance run only the fast tests with:

pytest -m fast --cov=./

The list of tags is:

  • fast : each test should run under 1s

  • needs_connection : requires an internet connection

  • needs_python3 : a Python-3 only test

  • needs_config_file: needs ~/radis.json to be defined.

Plus some tags for user-defined [HITEMP-2010] databases, as given in the Configuration file section

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

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

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

The default test routine run on Travis CI is (see the radis/.gitlab-ci.yml file):

pytest -m "not needs_config_file" --cov=./;

Which ignores all test that rely on the [HITEMP-2010] databases, as they cannot (yet) be downloaded automatically on the test machine.

Write new tests

Any function starting with test will be picked by pytest. Use assert statements within the function to test properties of your objects. Ex:

def test_positive(a):
    assert a>0

Tips: make sure you don’t open any figure by default in your test routines, else it will be stuck when called by pytest. Or, force a non-blocking behaviour adding the following lines within your test function:

if plot:
    import matplotlib.pyplot as plt
    plt.ion()   # dont get stuck with Matplotlib if executing through pytest

You can refer to Pull Request: https://github.com/radis/radis/pull/495 to see how test cases are written when a new feature is added.

See: https://github.com/statsmodels/statsmodels/issues/3697

Test files

To make the errors as reproducible as possible, try to use the test files provided in the Test files are provided in the radistestfiles and radistestvalidation folders. They contain examples of line databases, spectra, or energy levels. The path to these test files can be retrieved 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
1   5    1  3.740024  1.110000e-38  5.999000e-09  ...  1.0       1   0   3   3
2   5    1  3.775024  9.233000e-34  1.947000e-08  ...  1.0       1   0   2   2
3   5    1  3.810028  5.706000e-29  4.130000e-08  ...  1.0       1   0   1   1
4   5    1  3.845033  3.300000e-24  7.207000e-08  ...  1.0       1   0   0   0
5   5    1  7.409906  1.815000e-43  2.726000e-09  ...  3.0       1   1   4   4
6   5    1  7.479900  8.621000e-38  5.746000e-08  ...  3.0       1   1   3   3
7   5    1  7.549901  7.177000e-33  1.867000e-07  ...  3.0       1   1   2   2
8   5    1  7.619908  4.436000e-28  3.961000e-07  ...  3.0       1   1   1   1

[9 rows x 16 columns]

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)
Populations Stored
----------------------------------------
   CO                [1]
Physical Conditions
----------------------------------------
   Tgas                 1500 K
   Trot                 1500 K
   Tvib                 1500 K
   isotope              1
   mole_fraction        0.5
   molecule             CO
   path_length          0.01 cm
   pressure_mbar        1013.25 mbar
   rot_distribution     boltzmann
   self_absorption      True
   state                X
   thermal_equilibrium  True
   vib_distribution     boltzmann
   wavelength_max       4801.3089 nm
   wavelength_min       4401.1999 nm
   wavenum_max          2272.1077 cm-1
   wavenum_min          2082.7654 cm-1
Computation Parameters
----------------------------------------
   Tref                 296 K
   broadening_max_width  10 cm-1
   cutoff               1e-25 cm-1/(#.cm-2)
   db_assumed_sorted    True
   dbformat             hitran
   dbpath               d:/github/radis/radis/test/files/hitran_co_3iso_2000_2300cm.par
   levelsfmt            neq
   parfuncfmt           hapi
   pseudo_continuum_threshold  0
   wavenum_max_calc     2277.1104 cm-1
   wavenum_min_calc     2077.7654 cm-1
   waveunit             cm-1
   wstep                0.005 cm-1
Information
----------------------------------------
   calculation_time     0.14 s
   chunksize            10000000.0
   db_use_cached        True
----------------------------------------

Debugging

See the printdbg() function in radis.misc, and the DEBUG_MODE global variable.

Code coverage

Code coverage makes sure every line in RADIS is properly tested. See the current code coverage status (click the badge for more details):

https://codecov.io/gh/radis/radis

If you want to see the test coverage report locally use codecov that is interfaced with pytest through the --cov=./ command:

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

Performance benchmarks

RADIS performance is tested against past versions on a dedicated project : radis-benchmark.

Results can be found on : 🔗 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, please report an Issue on GitHub.

You can also ask for advice on the Q&A forum or the community chat:

Gitter Slack