Installation

Obtain the Repository

Currently it is possible to use the program either by compiling from source or by using Docker image. In both cases it is recommended to obtain the repository first, since it contains example config files and postprocessing scripts:

1. Install git. On Debian GNU/Linux:

sudo apt-get install git-core

2. Clone the repository to your local computer:

git clone https://github.com/epicf/ef your-ef-dir

Docker

The simplest way to try the program is to use Docker. Docker allows to package a program and part of the operating system environment necessary to run it into a self-contained "image". On any other machine where Docker is installed, it is possible to download the image and run it in isolated environment. In some sense, the concept is similar to virtual machines, but more lightweight.

1. Install Docker:

sudo apt-get install docker.io

It might be necessary to add your usual user to the docker group:

sudo usermod -aG docker $USER

2. Pull one of the Ef images from Docker Hub:

docker pull epicf/ef:dev

3. To run the program with given config use the following command:

cd your-folder-with-config
docker run -v ${PWD}:/app/run your-image-name your-config.conf

for example:

cd your-ef-dir/examples/single_particle_in_magnetic_field
docker run -v ${PWD}:/app/run epicf/ef:dev single_particle_in_magnetic_field.conf

Note on -v ${PWD}:/app/run: by default, docker images are run in isolated environments and are not allowed to modify host system in any way. -v ${PWD}:/app/run mounts you current working directory (after cd your-folder-with-config command it should be the directory with your config file) to the /app/run directory of the image, so that when files are written to /app/run inside the image those files are visible in the ${PWD} of the host.

Compile from Source

1. Install git and development tools ( compilers, make, etc... ):

sudo apt-get install build-essential

2. Install dependencies( boost, petsc, hdf5 ). Make sure to install *-dev packages, since they contain header files necessary for compilation:

sudo apt-get install libboost-all-dev petsc-dev libhdf5-dev

3. Compile:

cd your-ef-dir 
make 

Optional Dependencies

1. Hdftools and hdfview are helpfull in order to examine output *.h5 files. Hdftools are console, hdfview is graphical.

sudo apt-get install hdf5-tools hdfview

2. While there are many tools to work with hdf5 files, examples in the repositories use python and h5py library. Apart from it, python3, numpy and matplotlib are necessary.

sudo apt-get install python3 python3-h5py python3-numpy python3-matplotlib

3. Ef comes with experimental FreeCAD module to simplify preparation of config files. FreeCAD is a parametric 3d-modelling software. To use the module, install FreeCAD and create a link from it's module directory (typically, ~/.FreeCAD/Mod), to freecad folder in the Ef distribution.

sudo apt-get install freecad
mkdir -p ~/.FreeCAD/Mod
ln -s your-ef-dir/freecad/ ~/.FreeCAD/Mod/ef

4. Paraview support. To perform complex visualization of large amount of data several excellent tools exist. Two of them are Paraview and Visit. Ef comes with Paraview 'plugin'. Install Paraview and create a link from Paraview macros directory to 'paraview/ef.py' script in Ef distribution.

sudo apt-get install paraview
mkdir -p ~/.config/ParaView/Macros
ln -s your-ef-dir/paraview/ef.py ~/.config/ParaView/Macros/ef.py

Arch Linux Installation

sudo pacman -Sy git boost hdf5-openmpi wget python2 python-h5py-openmpi
git clone http://github.com/epicf/ef
cd ef
git checkout master-arch-install # or `git checkout dev-arch-install` 
sh arch_install_petsc.sh # install PETSc into your-ef-dir/lib/
make

Note on Installation on HPC Clusters

Some libraries might be missing in the system. You'll have to either contact system administrator to install all missing libraries system-wide, or to install them locally (which is more likely). The following script, used on Scientific Linux, might be usefull.

Before compilation, you'll have to specify pathes to these libraries in Makefile. Example Makefile is attached.

Before running the program, you have to ensure that libraries you installed are seen in LD_LIBRARIES_PATH. This requires exporting them each time you log in into system:

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${HOME}/petsc/opt/lib/