Installation#

For the moment, no precompiled binaries are available, and Janus must be compiled from sources, using setuptools.

The sources can be retrieved from Github, sbrisard/janus.git.

Prerequisites#

Janus requires Python 3k, and depends on FFTW (version 3) only.

Configuration (all platforms)#

Compilation and installation is configured through the optional setup.cfg file, which must be created in the root directory of the project if necessary (this file must reside in the same directory as setup.py).

If setup.cfg does not exist, or provides no entry in its [fftw] section, defaults suitable for a conda environment are used: libraries = fftw3 on all platforms and, on Windows, the Library\include and Library\lib subdirectories of the environment, where conda installs FFTW. Within the janus conda environment (see environment.yml), setup.cfg is therefore not needed. It must be created in all other cases (e.g. FFTW installed by the system package manager in a non-standard location, or precompiled binaries downloaded from fftw.org).

The FFTW settings are given in the [fftw] section:

[fftw]
include_dirs = …
library_dirs = …
libraries = …
include_dirs#

The path to the FFTW headers files (optional).

library_dirs#

The path to the FFTW shared libraries (optional).

libraries#

The name of the FFTW libraries.

All these entries can be (comma separated) lists. Examples are provided below for several platforms.

Compilation and installation under Linux#

Make sure that the FFTW packages are properly installed, including the dev packages (that include header files). On Ubuntu platforms, the following packages must be installed:

sudo apt-get install libfftw3-bin libfftw3-dev cython3 python3-numpy python3-h5py python3-pytest python3-scipy python3-sphinx

Usually, for linux platforms, it is not necessary to set the include_dirs and library_dirs values. Also, the library names must be stripped of the lib prefix (libfftw3.so.3.5.7 → fftw3). On Ubuntu platforms, the setup.cfg file can be as simple as:

[fftw]
libraries = fftw3

Then, issue the standard commands in a console:

python3 setup.py install --user

Compilation and installation under MacOS#

Compilation and installation under Windows#

Compilation with MinGW/MSYS#

Set the following values:

[build_ext]
include_dirs = C:\PATH\TO\HEADERS
library_dirs = C:\PATH\TO\BINARIES
libraries = fftw3-3

Todo

Complete installation procedure with MinGW.

Test your installation#

Testing the installation of Janus requires pytest. To run all tests, issue the following command at the root of the project:

python -m pytest tests

Build the documentation#

The documentation is written with Sphinx, and its sources are located in the sphinx/ directory. Since the API reference is extracted from the docstrings of the compiled modules, Janus must be compiled and installed first.

The HTML version of the documentation is published on GitHub Pages. It is built and deployed by the docs workflow of GitHub Actions (.github/workflows/docs.yml) at each push to the master branch; there is nothing to do by hand. The same workflow builds the documentation at each push to another branch, and for each pull request, without deploying it. The build fails on any Sphinx warning.

To build the HTML documentation locally, issue the following command at the root of the project:

python -m sphinx -b html -E sphinx sphinx/_build/html

then open sphinx/_build/html/index.html in a browser. Add -W --keep-going to check, as the workflow does, that the build produces no warning. Alternatively, make html (make.bat html under Windows), from the sphinx/ directory, builds into the same directory; the other targets of these files (make latexpdf…) also build into sphinx/_build/.