Installation

This section describe the requirements and installation steps for PETGEM.

Requirements

PETGEM is known to run on various flavors of Linux clusters. Its requirements are:

  • PETSc (builded version for COMPLEX-VALUED NUMBERS) for the use of direct/iterative parallel solvers

  • Python 3 (versions 3.5.2, 3.6.3 and 3.6.9 have been tested)

  • Numpy for arrays manipulation

  • Scipy for numerical operations

  • Singleton-decorator

  • Sphinx and LaTeX (textlive) to generate documentation

  • Petsc4py for parallel computations on distributed-memory platforms. It allows the use of parallel direct/iterative solvers from PETSc

  • Mpi4py for parallel computations on distributed-memory platforms.

  • h5py for input/output tasks.

On Linux, consult the package manager of your preference. PETGEM can be used without any installation by running the kernel from the top-level directory of the distribution.

Install PETGEM

  • Following commands may require root privileges

  • Download PETSc (PETSc 3.7, 3.8, 3.9, 3.12, 3.14, and 3.17 have been tested)

  • Uncompress the PETSc archive (in this example, using PETSc 3.17.0):

    $ tar zxvf petsc-3.17.0.tar.gz

  • Configure and build PETSc. The configuration options depend on the calculations you want to perform (complex- or real-valued) as well as your compiler/MPI/Blas/Lapack setup. For PETGEM executions, PETSC MUST BE BUILD FOR COMPLEX-VALUED NUMBERS. In order to avoid incompatibilities between PETSC, petsc4py and PETGEM, we highly recommend the following configuration lines. Please, visit PETSc website for advanced configuration options. If you have a clean environment (not working MPI/Blas/Lapack), then run:

    $ cd petsc-3.17.0
$ export PETSC_DIR=$PWD
$ export PETSC_ARCH=arch-linux2-c-debug

  • If you do not want support for MUMPS, run following configure line:

    $ ./configure --with-cc=gcc --with-cxx=g++ --with-fc=gfortran  --download-mpich --download-fblaslapack --with-scalar-type=complex

  • If you want support for MUMPS, please add following options to previous configure line:

    $ --download-mumps --download-scalapack --download-parmetis --download-metis --download-ptscotch --download-cmake

  • Further, to activate GPUs support, please add following options to previous configure line:

    $ --with-cuda=1 --with_cuda_dir=PATH

    where PATH is the directory of your CUDA libraries.

  • Then, build and install PETSc:

    $ make $PETSC_DIR $PETSC_ARCH all
$ make $PETSC_DIR $PETSC_ARCH test
$ make $PETSC_DIR $PETSC_ARCH streams

  • Ensure your mpicc compiler wrapper is on your search path:

    $ export PATH="${PETSC_DIR}/${PETSC_ARCH}/bin:${PATH}"

  • Ensure you have a Numpy installed:

    $ pip3 install numpy

  • And finally, install PETGEM with its dependencies (Scipy , Singleton-decorator, Sphinx, Petsc4py, Mpi4py, h5py) by typing:

    $ pip3 install petgem

Downloading and building PETGEM

The PETGEM package is available for download at Python Package Index (PyPI), at GitHub, and the Download section of this project website.

  • Configure and install PETSc (see Install PETGEM section)

  • Ensure you have a Numpy installed:

    $ pip3 install numpy

  • Download PETGEM (PETGEM 1.0.0 have been tested)

  • Uncompress the PETGEM archive:

    $ tar zxvf petgem-1.0.0.tar.gz
$ cd petgem-1.0.0

  • After unpacking the release tarball, the distribution is ready for building. Some environment configuration is needed to inform the PETSc location. As in Install PETGEM section, you can set the environment variables PETSC_DIR and PETSC_ARCH indicating where you have built/installed PETSc:

    $ export PETSC_DIR=/usr/local/petsc
$ export PETSC_ARCH=arch-linux2-c-debug

  • Alternatively, you can edit the file setup.cfg and provide the required information below [config] section:

    [config]
petsc_dir = /usr/local/petsc
petsc_arch = arch-linux2-c-debug

  • Build the distribution by typing:

    $ python3 setup.py build

  • After building, the distribution is ready for installation (this option may require root privileges):

    $ python3 setup.py install

Build documentation

PETGEM is documented in PDF and HTML format using Sphinx and LaTeX. The documentation source is in the doc/ directory. The following steps summarize how to generate PETGEM documentation.

  • Move to the PETGEM doc directory:

    $ cd doc

  • Generate the PETGEM documentation in HTML format by typing:

    $ make html

  • Or, if you prefer the PDF format by typing:

    $ make latexpdf

  • The previous steps will build the documentation in the doc/build directory. Alternatively, you can modify this path by editing the file setup.cfg and provide the required information below [build_sphinx] section:

    [build_sphinx]
source-dir = doc/source
build-dir  = usr/local/path-build
all_files  = 1