Development and contributing

Setting up the development environment

1. Clone the repository with

git clone git@github.com:tfp-photonics/treams.git

or

git clone https://github.com/tfp-photonics/treams.git

and enter the directory

cd treams

2. This step is optional, but you might want to create an environment where treams and the development tools are created

conda env create --name treams-dev python

Activate the environment with:

conda activate treams-dev

3. Setup the package with

pip install -e .

This last step makes the program available in the environment independently of the current folder. This is especially necessary for correctly building the documentation.

Running tests

To install the required packages for testing use

pip install treams[test,coverage,io]

Tests can be run using pytest with

python -m pytest

but for development a more fine grained selection can be made by passing a directory or file as an argument. Additionally, the option -k allows to define keywords when selecting test.

Some integration tests for the module treams.lattice take a long time to finish and are therefore disabled by default. You can add them with the option --runslow.

If coverage reports should be included one can use the option --cov src/treams (which requires pytest-cov to be installed). However, this will only report on the pure python files. To also get coverage reports for the cython part, it is necessary to compile it with linetracing support. This can be achieved by setting the environment variable CYTHON_COVERAGE, for example with

CYTHON_COVERAGE=1 pip install -e .

Make sure that new C code files are generated and that those files are compiled. Enabling the tracing for getting code coverage slows down the integration tests considerably. For the coverage calculation only the unit tests are used.

Some test for importing and exporting need gmsh. These tests can be activated with --rungmsh analogous to the option --runslow above.

Building the documentation

To install the required packages for testing use

pip install treams[docs]

The documentation is built with sphinx by using

sphinx-build -b html docs docs/_build/html

from the root directory of the package to build the documentation as html pages. Some figures are automatically created, which requires matplotlib.

The doctests can be run with

sphinx-build -b doctest docs docs/_build/doctest

Building the code on Windows

The main issue with using treams on Windows is the compilation step. For Windows Python is usually compiled with MSVC for Visual Studio. However, especially for calculations with complex numbers, Cython creates code that conforms to the (C99-) standard. Thus, it is not compatible with the non-standard implementation of complex numbers by Microsoft.

Below you find three tested ways, how one can use treams with Windows. The first two ways actually use a non-Windows version of Python, but have a more straightforward installation procedure. However, the last one works with Windows’ version of Python e.g. when installed with conda under Windows.

Windows Subsystem for Linux

The Windows Subsystem for Linux (WSL) exists on recent versions of Windows. To install it, open the command line interpreter (cmd.exe) and type wsl –install. This step might be enough to be able to run a Linux kernel. Within WSL all instructions from the rest of the description can be used, e.g. with the distribution’s Python or a conda-installed Python.

Sometimes it is necessary to use additional steps to install WSL.

Pure MSYS2

Using MSYS2, it is also possible to compile and install treams. First, install MSYS2 and update it according to the instructions. Then, also install python and, if you want, the dependencies of treams. Otherwise, the dependencies are installed by pip.

Compilation with mingw-w64

This is approach is different from the others, since it finally combines binaries from two different compilers. Although it works and was tested on some systems, it is not guaranteed that it will work for all systems. The following part describes, how treams can be built for Windows.

After installing MSYS2 use it to install mingw-w64-x86_64-gcc.

The compilation is steered from the command line. First go into the directory of treams. Then, set up your path by prepending the direction for MSYS2’s mingw64 binaries with set PATH=C:\msys64\mingw64\bin;%PATH% (adjust accordingly if you have installed MSYS2 with non-default parameters). Check that gcc from MSYS2 is recognized correctly but make sure that the version of python that is found on the path corresponds to the Windows Python. With this setup, building binaries should work with python -m build.

Continuous integration

Using Github actions the steps above (building the documentation, running the doctests, running the tests with a coverage report, and building for all platforms) are implemented to run automatically on specific triggers. The relevant files in the .gihub/workflows directory can be also used as examples in addition to the description above.