2. Installation

2.1. Getting the code

The code is available on a GitLab hosted repository: https://gitlab.com/polmag/PORTA. In order to clone it, just do:

git clone https://gitlab.com/polmag/PORTA.git

or using SSH:

git clone git@gitlab.com:polmag/PORTA.git

Note

Although getting PORTA via git is the recommended way, a zip file of the project can also be downloaded at https://gitlab.com/polmag/PORTA/-/archive/master/PORTA-master.zip.

2.2. Code directory structure

The directory structure of a clean version of PORTA is as follows:

.
|-- src
|   |-- porta
|   |-- portal
|   `-- modules
|   |   |-- twolevel
|   |   |-- multilevel
|   |   `-- contpol
|-- tests
|   |-- twolevel-module
|   |-- multilevel-module
|   `-- contpol-module
|-- docs
|   |-- UserManual
|   |-- Modules-Dev
|   `-- Papers
`-- tools
    `-- gui

  • The src directory contains the source code for the three main parts of PORTA, as described in section Structure of the code:

    • porta: the PORTA wrapper

    • portal: the PORTA library with all the functionality for radiative transfer, I/O, etc.

    • modules: the problem-specific libraries implementing a physics of interaction of the radiation with matter. Currently there are three implemented modules shipping with PORTA (twolevel, multilevel, and contpol), which are described in section List of publicly available modules.

  • The tests directory contains sample scripts and files that exercise each of the provided modules. They are useful to become familiar with how PORTA works and to verify the correct functioning of PORTA for each of the provided modules. They are described in section Tests

  • The docs directory contains:

    • UserManual: the “source code” for this User Manual.

    • Modules-Dev: Doxygen generated developer documentation for each of the provided PORTA modules. (The contents for this directory will be available in a future release of PORTA, and it will be useful for those users intending to write their own modules for PORTA.)

    • Papers: Copies of papers describing the PORTA code in more detail. For publications with results obtained thanks to PORTA, see section Publications (If you use PORTA for your own research, we would ask you to contact us to include in that list any generated publications.)

  • The tools directory contains a tool (PORTA GUI) to aid with visualization of the files used and generated by PORTA. For details see section Visualization

2.3. Dependencies

Compilation of PORTA depends on a number of tools and libraries (though these are very common and likely already installed in most supercomputers): the make build automation tool, a C compiler, and two libraries: MPI and HDF5 (compiled with parallel support). (Dependencies for the PORTA GUI visualization tool are described separately in section Visualization ).

Note

We have tested PORTA with different C compilers (gcc, PGI and Intel), and with different MPI libraries (OpenMPI and MPICH).

Warning

It is important that the software stack (C compiler, MPI and HDF5) is properly configured. If compiling the libraries from the source code, we recommend to compile first the MPI library and then, making sure this library is used, to compile HDF5 with parallel support.

2.3.1. Sample dependencies installation

Though the mentioned dependencies can be met in many different ways, depending on the system where we intend to run PORTA, we give below a few examples to serve as a guide. In other systems the names of the packages/libraries will be different, but the procedure and names should be similar. In case of trouble, contact your system administrator for advice on how to install these dependencies in your particular system.

Ubuntu (tested with versions 18.04LTS and 19.04)

$ sudo apt-get install git make gcc libhdf5-openmpi-dev

Fedora (tested with Fedora 29)

$ sudo dnf install git make gcc hdf5-openmpi-devel redhat-rpm-config
$ module load mpi

LaPalma supercomputer

As many other supercomputing systems, LaPalma uses the Environment Modules tool to load different software environments, and loading the PORTA dependencies is as simple as:

$ module load intel/2018.2 openmpi/intel/3.0.1 szip/intel hdf5/intel/openmpi

Note

For advanced users that want to have different compilers/libraries installed in the same system, we recommend the use of Spack. With it, different compiler/libraries versions can coexist in the same system and can be easily installed without root permissions.

PizDaint supercomputer

As LaPalma, Piz Daint also uses Environment Modules, and loading the PORTA dependencies is as simple as (this assumes we want to use the provided Cray compilers, but we could also compile PORTA with the Intel or the GNU compilers):

$ module load PrgEnv-cray cray-hdf5-parallel

2.4. Compilation

To get a working version of PORTA you need to perform two steps: configuration and compilation.

  1. Configuration

Before the actual compilation of PORTA, you need to configure it, which can be done with the configure script provided in the top level of the PORTA project. You can see the options that can be passed to the configure script by running ./configure --help:

$ ./configure --help
usage: ./configure [options]
options:
  --prefix=<path> :                     installation prefix [default = .]
  --module=<path> :                     module directory [default = twolevel]
  --smode=[FULL|I|IQU_NOSA|IQU_SA|IQU_ETAI_RHOV|IV]
                                        Stokes mode of the executable PORTA
  --compiler=[gnu|intel|pgi|cray]       compiler used [default = gnu]
  --debug :                             if debug compile with debug symbols
                                            (i.e. -g -O0), [default = -O3]
  --no_hz :                             deactivates Hanle-Zeeman in formal solution
  --no_thread_io :                      avoid threaded I/O for standard output/error
                                             and log data (see section 2.4 of the
                                             documentation)
  --cflags=<custom_flags> :             use custom cflags <custom_flags>
  --no_shuffle_freq :                   do not shuffle frequencies between processes
                                            (only for debugging)

 WARNING: all invalid options are silently ignored

Most of the times you probably only want to modify the prefix and module options. For example, to configure PORTA to run the test available in the directory tests/multilevel-module you could do the following:

$ ./configure --module=multilevel --prefix=$PWD/tests/multilevel-module
generating makefile ...
configuration complete, type make to build.
$

but if not using the GNU compiler suite, then you should at least make sure to provide the –compiler* option. For example, to compile in Piz Daint with the Cray compiler, you could do:

$ ./configure --module=multilevel --prefix=$PWD/tests/multilevel-module --compiler=cray

which specifies:

  • that the module to be used is multilevel (relative to the directory src/modules, so this would be using the module in src/modules/multilevel),

  • that after compilation it will install the PORTA executable and libraries in the directory $PWD/tests/multilevel-module ($PWD refers to the current working directory, but you could provide an absolute directory path instead).

Warning

The generation of standard output/error and log data in PORTA uses an advanced MPI feature (MPI_THREAD_MULTIPLE) which can impact severely the performance of some I/O operations when using some old network drivers/libraries (so far we only encountered this problem when using old versions of OpenMPI and the hcoll component of the Mellanox InfiniBand driver).

In most cases this will not be a problem, but you can easily see if this is a problem in your environment by running the provided twolevel test (see section Twolevel module test), and checking the time it takes to get to the first set of Jacobi iterations. Search for the output message starting with [1] STARTING JACOBI ITERATION WITH 10 ITERS. Given the small domain size of this test, you should see that the time to get there should be very small (e.g. T = 1.000000e+00 sec). If you see a much larger time (e.g. T = 9.000000e+01 sec), then you should ask your cluster administrator to upgrade the required drivers, or, if that is not feasible, configure PORTA with the –no_thread_io option (but keep in mind that with this option the log messages generated by PORTA are not cleanly produced: some messages will simply not be registered, while others will be intermixed).

  1. Compilation

If the software stack as described in Dependencies is correctly set, then compilation is now straightforward using make.

$ make
mkdir -p /scratch/porta/build
h5pcc  -O3   -shlib -DSMODE_FULL -std=c99 -c -I/scratch/porta/src  \
    -L/scratch/porta/tests/multilevel-module src/porta/cmaster.c   \
    -o /scratch/porta/build/cmaster.o

[...]

make[1]: Leaving directory '/scratch/porta/src/modules/multilevel'
h5pcc  -O3   -shlib -DSMODE_FULL -std=c99                                 \
    -o "/scratch/porta/tests/multilevel-module/porta"                     \
    /scratch/porta/build/cmaster.o /scratch/porta/build/cslave.o          \
    /scratch/porta/build/porta.o -L/scratch/porta/tests/multilevel-module \
    -lportal -lmultilevel -Wl,-rpath,./
$

Note

To remove the code compiled from a previous make command, you can run make clean

If the compilation didn’t produce any errors, then you should have the following three files in the directory specified in the prefix option above: porta, libportal.so, and libmultilevel.so (this third file will be dependent on the module option specified in the configure command above). For example:

$ ls -lt tests/multilevel-module/
-rwxr-xr-x  1 can30003 can30  342248 Dec  9 13:02 porta
-rwxr-xr-x  1 can30003 can30  269736 Dec  9 13:02 libmultilevel.so
-rwxr-xr-x  1 can30003 can30  494032 Dec  9 13:02 libportal.so

If PORTA was compiled without issues, then you can now run the code, as specified in section Running the code.