Developer Guide¶

Contribute¶

RADIS is an open-source project, and therefore anyone can contribute, whether you already know spectroscopy or not.

You want to become a contributor ? Welcome ! First step is to read the Contributing Guide .

If you want to contribute and have no specific project in mind, have a look at the GitHub opened issues. For a First Time contribution, you can tackle one of the Issues displayed as Good First Issue.

Also, join the community chat, where you’ll get a lot of help :

Slack Gitter

Finally, you can also suggest or vote for new features below:

https://feathub.com/radis/radis?format=svg

Sources¶

To modify RADIS, you will need to clone the Git repository. See the detailed installation procedure below.

For a First Time contribution, you can tackle one of the Issues displayed as Good First Issue. Learn more in the Contribute section.

Install¶

You can either install RADIS from pip, the Python package manager. But if you want to access the latest features, or modify the code and contribute, we suggest that you Fork the source code from GitHub.

Use-only version : cant modify the code

In a terminal, run:

pip install --user radis -v

The ‘pip’ module has to be installed (by default if you’ve installed Python with Anaconda).

If you later want to update the package:

pip install radis --upgrade

Developer version: to modify the code and contribute to the project.

We suggest that you 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:

In a terminal, run:

git clone https://github.com/<GITHUB USERNAME>/radis.git
cd radis
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.

For a best experience, it is recommended to install Radis on an Anaconda Python distribution, in an isolated environment. You can create a radis environment with all dependencies with:

cd radis
conda env create --file environment.yml

Then install radis in the radis environment:

conda activate radis
pip install -e .

Test your changes¶

If you want to modify the source code, you need to ensure that you don’t break any of the existing tests. Refer to the Test Section to learn how to run the tests locally.

Update your changes¶

Submit a Pull Request from GitHub.

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

  • Physical test cases

  • Code format (see Code linting below)

Code linting¶

Radis follows Black style for code linting to maintain consistent coding style across modules. 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

Alternatively, 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. Exemple:

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

Update¶

With Pip you can keep the package up-to-date with:

pip install radis --upgrade

If using the latest developer version (cloned from GitHub and installed with pip install -e .[dev]), use git to pull the latest changes.

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

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.

Test¶

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

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

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

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

Report errors¶

If you encounter any error, open an Issue on GitHub

To simplify the debugging process, provide a code snippet that reproduces the error. If you need a line database, spectrum, or energy level, try to use one of the test files.

Debugging¶

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