Installation#

FEPX can be installed from a binary package (Debian and Ubuntu) or built from its source with CMake. Both give the executable fepx, its manual page (man fepx) and the tutorial cases of Tutorials, ready to run.

Debian and Ubuntu package#

Each release provides a package for Ubuntu 24.04 LTS, Ubuntu 26.04 LTS and Debian 13, built with the distribution’s default MPI (Open MPI) and with the HDF5 output. Download the package of your distribution release (a package installs only on the release it was built for) and install it with:

$ sudo apt install ./fepx_<version>-1_amd64.deb

apt installs the libraries FEPX needs (the Fortran run-time library, Open MPI, HDF5) and mpirun (package mpi-default-bin). The package installs:

  • /usr/bin/fepx, the executable;

  • /usr/share/man/man1/fepx.1.gz, the manual page;

  • /usr/share/doc/fepx/, the README, the licence and examples/, one directory per tutorial case (see The installed tutorial cases).

Remove it with sudo apt remove fepx.

Building from source#

Requirements#

FEPX is written in Fortran 2018 and runs on Unix-like systems. It needs:

  • a Fortran 2018 compiler: GNU gfortran (tested) or Intel ifx (supported, not yet tested);

  • an MPI implementation providing the mpi_f08 Fortran module (Open MPI or MPICH);

  • CMake 3.20 or newer;

  • optionally, for the HDF5 output (output_format hdf5, see Simulation Results (simulation.cfg)): the serial HDF5 library with its Fortran interface, and for its tests the HDF5 tools;

  • for the test suite: Python 3 with NumPy.

On Debian and Ubuntu:

$ sudo apt install gfortran libopenmpi-dev openmpi-bin cmake python3-numpy
$ sudo apt install libhdf5-dev hdf5-tools    # for the HDF5 output

On macOS, with Homebrew:

$ brew install gcc open-mpi cmake numpy
$ brew install hdf5-mpi                      # for the HDF5 output

Homebrew’s hdf5-mpi is a parallel HDF5 built with Homebrew’s Open MPI, which FEPX then uses serially (the configuration warns about it); it works because FEPX is built with the same Open MPI. On arm64 processors (Apple silicon, and aarch64 Linux), FEPX is compiled without fused multiply-add contraction (-ffp-contract=off), so that its results are those of an x86-64 build.

The source#

Each release provides a source tarball, fepx-<version>.tar.gz, and a separate test-data tarball, fepx-<version>-testdata.tar.gz, which holds the reference results of the regression tests (see Testing). Unpack the source, and, to run the regression tests, the test data over it (both unpack into fepx-<version>/):

$ tar -xzf fepx-<version>.tar.gz
$ tar -xzf fepx-<version>-testdata.tar.gz      # optional: the regression tests
$ cd fepx-<version>

Build and install#

From the top directory of the source:

$ cmake -S src -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/.local
$ cmake --build build -j
$ cmake --install build

This builds build/fepx and installs it, in the layout of the package above, under the prefix: bin/fepx, share/man/man1/fepx.1.gz and share/doc/fepx/ (the default prefix is /usr/local, which needs sudo cmake --install build). Add the prefix’s bin to the PATH if it is not there already. The build directory can be used without installing: run build/fepx.

CMake options#

Options are given to the first command, cmake -S src -B build, as -D<option>=<value>:

  • -DCMAKE_BUILD_TYPE=<type>: how the code is compiled, which sets its speed and the checks made while it runs:

    • Release (the default): optimized, for production runs;

    • Debug: no optimization, with run-time checks (array bounds, floating-point exceptions, uninitialized values), for use with a debugger; 4 to 6 times slower than Release;

    • Checked: the run-time checks of Debug in optimized code, to look for errors in longer runs; about 1.5 times slower than Release.

  • -DCMAKE_INSTALL_PREFIX=<directory>: where cmake --install installs FEPX (default /usr/local).

  • -DFEPX_ENABLE_HDF5=<value>: the optional HDF5 output (output_format hdf5):

    • AUTO (the default): built when the serial HDF5 library with its Fortran interface is found (and, with the test suite, the HDF5 tools h5ls, h5dump, h5diff; without them a warning says that the HDF5 output is not built);

    • ON: required (the configuration fails without them);

    • OFF: FEPX is built without HDF5, writes the text files only, and output_format hdf5 is then an error that says so.

    The configuration’s last line says which: HDF5 output: ON or OFF. A serial HDF5 is used (only one process writes the file), so any MPI works with it.

  • -DMPI_Fortran_COMPILER=<MPI Fortran wrapper>: the MPI to build with, when several are installed (default: the one CMake finds first, usually mpif90). For example, MPICH on Debian and Ubuntu: -DMPI_Fortran_COMPILER=mpif90.mpich -DMPIEXEC_EXECUTABLE=/usr/bin/mpiexec.mpich. FEPX must then be run with that MPI’s mpirun.

  • -DFEPX_INSTALL_RPATH=<value>: whether the installed executable keeps the paths of the MPI and HDF5 libraries it was built with:

    • ON (the default): it runs without LD_LIBRARY_PATH when they are outside the system directories (e.g. from an environment module or /opt);

    • OFF: for distribution packages.

  • -DFEPX_WERROR=<value>: ON turns compiler warnings into errors (default OFF).

  • -DBUILD_TESTING=<value>: OFF skips the test suite and its Python requirement (default ON).

The Debian package itself is made from a build with -DCMAKE_BUILD_TYPE=Release -DFEPX_ENABLE_HDF5=ON -DFEPX_INSTALL_RPATH=OFF, by cpack -G DEB in the build directory.

Testing#

FEPX comes with unit tests, verification tests (analytic solutions), regression tests (against earlier FEPX results) and MPI tests on 1, 2 and 4 ranks. Run them from the top directory with:

$ ctest --test-dir build --output-on-failure

Labels select subsets, e.g. ctest --test-dir build -L mpi (MPI tests only), -L regression or -L docs (this manual’s checks). Three labels divide the suite by run time:

  • quick: the unit tests and a selection of the other tests that reaches every source file and every configuration keyword, a few minutes in all (ctest --test-dir build -L quick);

  • full: every test but the tutorial cases, the default check of a change;

  • tutorial: the tutorial cases (about 30 minutes), which full leaves out.

The regression tests need the reference results of the test-data tarball; without them they are not defined, and the configuration says so.

The installed tutorial cases#

share/doc/fepx/examples/ (/usr/share/doc/fepx/examples/ for the package) holds one directory per tutorial case of Tutorials, with its configuration file, its mesh as simulation.msh and its other input files. To run one, copy its directory and run FEPX in the copy:

$ cp -r /usr/share/doc/fepx/examples/simple_simulation .
$ cd simple_simulation
$ mpirun -np 4 fepx

The case restart_cycle2 continues the simulation of restart_cycle1 (see Simulation Restart), and postprocessing/ holds the script of the post-processing tutorial.