Installation

This page describes the core installation and build steps for elfe3D_GPR.

System Prerequisites

  • a modern Fortran compiler (Fortran 2008 or later compiler for .f90 sources; tested on gfortran),

  • make,

  • OpenBLAS (with libopenblas-dev, for example),

  • TetGen for mesh generation (tested on tetgen version 1.5, might not work with version 1.6),

  • MUMPS for the direct linear algebra solver,

  • Python 3.10+ for the Python I/O wrapper.

Platforms

So far, elfe3D_GPR is only available for Linux. Windows users can use a Windows Subsystem for Linux (WSL) to run elfe3D_GPR simulations (this has also been tested).

Note

In fact, the Python I/O module allows users to run the Fortran executables of tetgen and elfe3D_GPR directly from a jupyter notebook on both, a native-Linux install and a Windows-WSL install.

Build the Fortran solver

You can find the source code for elfe3D_GPR on https://github.com/emsig/elfe3D_GPR.

On a Linux/WSL machine, you can start with opening the Command Prompt/Terminal, and execute the following git commands to download it:

cd <empty folder location> #replace with a path of your choice
git clone https://github.com/emsig/elfe3D_GPR.git
cd elfe3D_GPR

Install TetGen

TetGen can be downloaded from <https://wias-berlin.de/software/index.jsp?id=TetGen>. Otherwise, you can also simply:

apt policy tetgen       # Checks which tetgen version is available - ideally 1.5
sudo apt install tetgen

Install MUMPS

MUMPS is available at <https://mumps-solver.org>. Build it from source and copy the required headers into the elfe3D_GPR/ source tree.

wget https://mumps-solver.org/MUMPS_5.7.3.tar.gz
tar zxvf MUMPS_5.7.3.tar.gz
cd MUMPS_5.7.3
cp Make.inc/Makefile.debian.SEQ Makefile.inc
sudo apt install libmetis-dev libparmetis-dev libscotch-dev libptscotch-dev libatlas-base-dev openmpi-bin libopenmpi-dev liblapack-dev libscalapack-openmpi-dev
make all

Copy the required header files into the Fortran source directory:

cp MUMPS/libseq/mpif.h elfe3D_GPR/.
cp MUMPS/include/zmumps_root.h elfe3D_GPR/.
cp MUMPS/include/zmumps_struc.h elfe3D_GPR/.

Make elfe3D_GPR

Update the MUMPS_LIB_DIR and FCC variables in elfe3D_GPR/Makefile to point to your installed MUMPS library directory and the Fortran compiler:

FCC = <example_fortran_compiler_like_gfortran>
MUMPS_LIB_DIR = /path/to/your/MUMPS_5.7.3/lib

Compile the solver:

cd elfe3D_GPR
make all

Set the OpenMP thread count to avoid oversubscription:

export OMP_NUM_THREADS=<number_of_threads>

Once the make process succeeds, you can simply run the solver from the folder containing your input files:

cd in_<experiment_name>
../elfe3d_gpr

Note

You can run the Fortran simulation independent of the Python I/O module. Right after the make process, if you run ./elfe3d_gpr from a directory containing elfe3D_input.txt, it will solve the homogeneous air model or whichever case is described by the provided input files.

You can verify the results of this simulation by referring against the plots in the example notebook examples/01_homogeneous_free-space.ipynb.

If you are not interested in using the Python I/O module, you can continue directly at Quick Start where we explain the input files that elfe3D_GPR uses to define a GPR simulation, and the subsequent output files.

Install the Python I/O Module

If you would like to use the Python I/O module, you can continue with checking the active Python environment and package tools:

python --version
python -m pip --version
python -m pip install --upgrade pip setuptools wheel

The Python I/O module is implemented in the io/ folder and packaged under the namespace elfe3d_gpr_io. Install it from the repository root:

cd .. #to go up one directory from elfe3D_GPR into the repository root, might not be necessary depending on your current directory location.
pip install -e .

The supported import namespace is used as:

from elfe3d_gpr_io.runner import ProjectPaths, run_tetgen, run_solver
from elfe3d_gpr_io.inputs.survey import GPRSurvey

You should now be ready to run your first simulation using elfe3D_GPR and its accompanying Python module! You can read more from the Quick Start guide, or head to examples/01_homogeneous_free-space.ipynb directly. The first notebook has detailed comments along with a complete workflow through your first elfe3D_GPR simulation using the Python module, including visualizing simulation results.