SFEMaNS  version 5.3
Reference documentation for SFEMaNS
Installation Instructions

Installation of required software

PETSc for parallel computing (required)

SFEMaNS uses the sofware PETSc to do the linear algebra in parallel. The following documentation describes the procedure to install PETSc. We refer to https://www.mcs.anl.gov/petsc/download/index.html for more information about PETSc. Since it is more efficient to use the native PETSc of your cluster, you may want to ask your root administrator to install it for you. If you do so, you need to specify that you want the version petsc-3.15.1 and that it needs to include blaslapack, hypre, mumps, scalapack, metis, parmetis and blacs.

Here is the procedure to install PETSc by yourself:

  1. First go to the directory where you want to install petsc and dowload it with the command:
    wget http://ftp.mcs.anl.gov/pub/petsc/release-snapshots/petsc-3.15.1.tar.gz
  2. Untar the file with the following command:
    tar -xvf petsc-3.15.1.tar.gz
    This creates a directory named petsc-3.15.1.
  3. Go into the directory petsc-3.15.1 and defined the following environnement variable:
    cd petsc-3.15.1
    export PETSC_DIR=$PWD
    export PETSC_ARCH=linux-gnu-c
    Note that depending of the work environment, the command export can be replaced by setenv or equivalent.
  4. Configure petsc with the command:
    ./configure --configModules=PETSc.Configure --optionsModule=config.compilerOptions --download-f-blaslapack=1 --with-shared-libraries=1 --download-hypre=1 --download-mumps=1 --download-scalapack=1 --download-metis=1 --download-parmetis=1 --download-blacs=1 --with-debugging=0 --with-x=0
  5. Then type the command:
    make all
    make check

The installation of petsc-3.15.1 is now complete.

FFTW for Fast Fourier Transform (required)

To compute nonlinear terms efficiently, SFEMaNS uses the package FFTW (Fast Fourier Transform in the West). If it is not yet installed in your work environment, either ask your root administrator to install it or follow the instructions in http://www.fftw.org/download.html .

ARPACK and PARPACK for eigen value problem (optional)

SFEMaNS can solve eigenvalue problem using the software ARPACK. If you do not plan to solve such problems, you don't need to install ARPACK. Notice that to solve eigenvalue problems, you will be required to uncomment a few lines in the file main.f90 as describeb in the next section.

The following describes the procedure to install ARPACK by yourself. We refer to http://www.caam.rice.edu/software/ARPACK/ for more information on ARPACK and its installation.

  1. First download ARPACK and PARPACK:
    wget http://www.caam.rice.edu/software/ARPACK/SRC/arpack96.tar.gz
    wget http://www.caam.rice.edu/software/ARPACK/SRC/patch.tar.gz
    wget http://www.caam.rice.edu/software/ARPACK/SRC/parpack96.tar.gz
    wget http://www.caam.rice.edu/software/ARPACK/SRC/ppatch.tar.gz
  2. Extract these files with the following commands:
    tar -xvf arpack96.tar.gz
    tar -xvf patch.tar.gz
    tar -xvf parpack96.tar.gz
    tar -xvf ppatch.tar.gz
    This creates a directory called ARPACK.
  3. Go into this directory:
    cd ARPACK
  4. Edit the file ARmake.inc. Here are the main steps to follow.
    1. To start with a suitable ARmake.inc, you need to know which environment you are using (SUN4, SP2, ...).
    2. Copy the suitable ARmake.inc from the directory ARMAKES. For example for sun4, type the command:
      cp ARMAKES/ARMAKES/ARmake.MPI-SUN4 ARmake.inc
    3. Open the file ARmake.inc.
    4. Edit the path to the ARPACK directory (variable called home).
    5. Check that the compilation program and flags are the correct one. For example, set the compilers FC and PFC to mpif90, set the FFLAGS and PFFLAGS to -O, set the correct path to the command make (type "which make" in your terminal to know its path). The above list is not exhaustive, more information are provided by ARPACK's developers in the file README of the directory ARPACK.
  5. Type the command:
    make lib
    make plib

The installation of arpack and parpack is now complete.

Dowload and installation of SFEMaNS

In this section, we describe how to download SFEMaNS and how to get an executable called a.exe. We also provide information on how to check that SFEMaNS and the above sofwares are installed correctly.

Download

Download SFEMaNS_v5.3 with the following command:

wget http://math.tamu.edu/~guermond/DOWNLOADS/SFEMaNS_v5.3.tar.gz

Then move the file SFEMaNS_v5.3.tar.gz where you want to install the code SFEMaNS. Untar it with the command:

tar -xvf SFEMaNS_v5.3.tar.gz

Define the following environment variable in your .bashrc:

export SFEMaNS_DIR= the_path_you_chose_for_SFEMaNS

Note that depending of your shell environment, the command export can be replaced by setenv or equivalent.

IMPORTANT: this last step is required as the code SFEMaNS needs to know this variable when compiling the executable. As a consequence, we ask every user to add this line in his .bashrc or equivalent.

Compilation of the executable a.exe

To generate an executable of the code SFEMaNS, the following files are needed:

  1. make.inc that defines environment variable (path to PETSc, FFTW, ARPACK) and compilation options.
  2. my_make that allows to generate a file called makefile. This file contains the tree of the code (which module need which modules, etc.).
  3. main.f90 that is used to set the desired outputs with the subroutine my_post_processing.
  4. condlim.f90 that is used to set the initial conditions, boundary conditions and source term of the problem considered.
  5. read_user_data.f90 that is used to add new variable in the code. For instance, such variable can be used in the condlim to change the amplitude of a forcing term.

Templates of each of the above files are available in the following directory: $SFEMaNS_DIR/TEMPLATE. We refer to the section Computations with SFEMaNS for more details on how to generate your own executable and set properly your data file.

Check Installation

The code SFEMaNS presents more than 30 tests that mainly involve manufactured solutions. They have been implemented so one can check the correct installation of the code. It also allows developpers to check the consistency of the new features they implement. To run these test, follows the intructions below:

  1. Create a directory for your applications with SFEMaNS. For instance, type the command:
    mkdir MY_APPLICATIONS_SFEMaNS_v5.3
  2. Go into this directory and type the following command:
    cp -rf $SFEMaNS_DIR/TEMPLATE CHECK_INSTALLATION
  3. Go in the directory CHECK_INSTALLATION.
    cd CHECK_INSTALLATION
  4. If ARPACK is installed, you can uncomment the following sections in the file main.f90:
    1. Line 6
      USE arpack_mhd
    2. The section "EIGENVALUE PROBLEMS/ARPACK" (lines 72 to 91)
  5. Rename the file make.in_template and my_make_template as follows:
    mv make.inc_template make.inc
    mv my_make_template my_make
  6. Edit the file make.inc.
    1. Set RACINE_FFTW. It is the directory that contains include/fftw3.h. To know this path, type the following command:
      locate fftw3.h
      The result is RACINE_FFTW/include/fftw3.h.
    2. Set LIB_FFTW. It is the result of the command:
      locate libfftw3.so
    3. Set PETSC_DIR (see compilation of PETSc).
    4. Set PETSC_ARCH (see compilation of PETSc).
    5. Set the preprocessor option: PREPROC.
    6. Set the compilation option OPT (-O3, -C, etc.).
    7. If ARPACK is installed, set PA_LIB as follows:
      PA_LIB= path_to_arpack/parpack_MPI-SUN4.a path_to_arpack/libarpack_SUN4.a
      Note that the the name of the files parpack_MPI-SUN4.a and libarpack_SUN4.a needs to be change for system other than sun4.
    8. All the other variables should not require any modification.
  7. Generate a makefile with the command:
    ./my_make
  8. Compile the executable a.exe with the command:
    make a.exe -j 8
    The option -j 8 means 8 processors are used to do the compilation. It can be removed or used with a different number of processors.
  9. Edit the shell debug_SFEMaNS_template as follows:
    1. Set the first and last test numbers to check with the variables iter_beg and iter_end. As SFEMaNS_v5.3 presents 40 tests, we have \(1 \leq \text{iter_beg} \leq \text{iter_end} \leq 40\). In order to check all the tests, set iter_beg to 1 and iter_end to 40.
    2. Define the program used to run MPI program (mpirun, mpiexec). It is done by setting the variable MY_MPIRUN as follows:
      export MY_MPIRUN=mpirun
  10. Run the shell debug_SFEMaNS_template with the following command:
    ./debug_SFEMaNS_template
    For each test, a "OK" should be displayed. It means the test is performed correctly. We note that the test 14 is disabled by default because it requires ARPACK. The ouput of each test, which can be found in the files called fort.10_T*, are compared with reference values. These reference values are at the end of the files $SFEMaNS_DIR/MHD_DATA_TEST_CONV_PETSC/debug_data_* where * is the number of the test considered.