3. How to install

Mandyoc installation is very simple and it consists of installing both PETSc and Mandyoc.

Warning

The following installation steps work for both Linux and macOS machines only and no tests were made to install Mandyoc on Windows machines yet.

3.1. Dependencies

To build Mandyoc, the following requirements are needed:

  • PETSc (currently tested on version v3.15.5)

  • gcc

  • make

  • git (recommended, but not strictly needed)

If you do not already have a PETSc installation, you may need a Fortran compiler.

Additionally, the following additional software is needed to run the examples that come with Mandyoc:

  • Python 3.5+

With required python packages:

  • numpy

  • matplotlib

  • pandas

  • jupyterlab

To run the tests, some additional python packages are required:

  • pytest

  • numpy

To build the documentation, further python packages are necessary:

  • sphinx

  • sphinx_rtd_theme

3.2. PETSc Installation

Mandyoc requires the PETSc library to run. Check out the PETSc installation for details.

Note

The following steps its a example installation with minimum requirements to run Mandyoc.

Requirements:

  • CMake

The first step is to download PETSc (v3.15.5) release from PETSc website or clone the repository into your machine. Mandyoc might work with latest release of PETSc, but this is not guaranteed since new versions might introduce breaking changes.

Clone the repository to your desired location:

git clone -b v3.15.5 https://gitlab.com/petsc/petsc.git

Second, configure the PETSc build and set up the installation directory.

cd path/to/petsc
./configure \
  PETSC_DIR=/path/to/petsc \
  PETSC_ARCH=arch-label-optimized \
  --with-debugging=0 \
  --with-cc=gcc \
  --with-cxx=g++ \
  --with-fc=gfortran \
  --download-fblaslapack \
  --download-mpich \
  --download-mumps \
  --download-scalapack \
  --download-parmetis \
  --download-metis

Note

This example installation uses the gfortran compiler. You may use another Fortran compiler changing the --with-fc flag. It is also possible to configure PETSc without Fortran by using --with-fc=0 and changing --download-fblaslapack to --download-f2cblaslapack.

Note

By default, Mandyoc uses direct solvers (LU and Cholesky) provided by MUMPS. This requires additional external packages. Refer to PETSc documentation for further information.

Note

If you want to build a development version of Mandyoc its recommended to build a debug version of PETSc by setting --with-debugging=1. In this case, you may set PETSC_ARCH=arch-label-debug.

Note

If you prefer openmpi, you need to swith --download-mpich to --download-openmpi.

Check the installation with:

make all check

Or follow the instructions that pop up on the terminal.

For further information about the PETSc library, check out the PETSc website.

Finally, add a symlink of mpirun to ~/.local/bin:

ln -s /path/to/petsc/arch-label-optimized/bin/mpirun ~/.local/bin/mpirun

Note

Make sure the directory ~/.local/bin exists, otherwise the above command will fail.

You can create it by running mkdir -p ~/.local/bin.

3.3. Mandyoc Installation

To install the Mandyoc in your machine, you need to clone or download the latest release of the code from the Mandyoc repository. To clone the repository, navigate to the directory you wish to install Mandyoc and type:

git clone https://github.com/ggciag/mandyoc
cd mandyoc

Before to install Mandyoc, you mast set an environment variable which indicates the path to PETSc installation folder:

export PETSC_DIR=/path/to/petsc

Build Mandyoc by running:

make all

Next, install Mandyoc with:

make install

By default, it will be installed in ~/.local/bin.

Note

Make sure the directory ~/.local/bin exists, otherwise the above command will fail. You can change the installation location setting INSTALL_PATH variable by running:

make INSTALL_PATH=/path/to/install/mandyoc install

Note

To print Mandyoc runtime options, run mandyoc with -flags command line argument.

Check Mandyoc installation with:

make test

Note

You need python and some python packages to run the last commmand succesfully. Check out requirements in Dependencies section.

3.4. Docker Container

We provide a Docker container image for Mandyoc. Docker is an implementation of container virtualization. Citing their documentation “it is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings”.

Visit the Dockerhub Mandyoc repository to find out more on how to use the container to run Mandyoc.

Note

To use the Mandyoc docker image, it is required to install the Docker Engine. Find out more on Install Docker Engine page.

3.5. Examples

The benchmarks and other experiments are located in the examples folder of the Mandyoc repository.

Inside each example folder, you find a Jupyter notebook with detailed explanation and instructions on how to run the experiment.