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, https://github.com/sbrisard/janus.git.

Prerequisites

Janus requires Python 3k. The serial version depends on FFTW (version 3) only, while the parallel (MPI-based) version also requires mpi4py.

Todo

The present version of setup.py tries to install the parallel version of the code if it detects that mpi4py is installed. In other words, if mpi4py is installed, the MPI-enabled version of FFTW must be installed.

Configuration (all platforms)

Compilation and installation is configured through the 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).

Two sections of this file must be filed: [fftw] and [fftw_mpi] (if you are compiling the MPI-enabled version of Janus):

[fftw]
include_dirs = …
library_dirs = …
libraries = …
[fftw_mpi]
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 MPI and 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 libopenmpi-dev openmpi-bin libfftw3-bin libfftw3-dev libfftw3-mpi-dev libfftw3-mpi3 petsc-dev cython3 python3-numpy python3-h5py python3-mpi4py python3-petsc4py 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
[fftw_mpi]
libraries = fftw3_mpi

Then, issue the standard commands in a console:

python3 setup.py install --user

Compilation and installation under MacOS

Compilation and installation under Windows

The parallel version of this code is not tested under Windows. You must first download and install the precompiled binaries of FFTW for Windows. Assuming you have uncompressed this archive in C:\opt\fftw-3.3.4-dll64, the ``setup.cfg file reads:

[fftw]
include_dirs = C:\opt\fftw-3.3.4-dll64
library_dirs = C:\opt\fftw-3.3.4-dll64
libraries = libfftw3-3

Note that the library name must not be stripped of the lib prefix (libfftw3-3.dll → libfftw3).

Compilation with Anaconda and Visual Studio

If you use Anaconda (which is highly recommended) then open the Anaconda console and issue the standard command:

python setup.py install --user

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 serial tests, issue the following command at the root of the project:

python -m pytest tests

To run all parallel tests (assuming you compiled the MPI-enabled version of Janus), issue the following command at the root of the project:

mpiexec -np 3 pytest tests/parallel

where the total number of processes can be adjusted (an odd number should preferably be used, as it is more likely to reveal bugs).

Todo

How to print only messages from root process with pytest?