Elmer > Sources and compilation
Tehdyt toimenpiteet

Sources and Compilation

When to compile?

Ready-compiled binaries exist for a few platforms. If these work with your system there may be no reason to compile Elmer from the source codes. Even most of the code development may be done without compiling the main program as new solvers may be dynamically linked. However, local compilation usually gives the best performance and is often needed for non-standard systems. Also it is often useful to download the source code just for checking the functionalities of different solvers when the documentation is not completed.

These instructions may partially be out of date. Also they do not cover the compilation of ElmerGU. For further instructions look at the section on compilation on www.elmerfem.org/elmerwiki.

Obtaining the source code

Elmer development uses the subversion version control system available at http://sourceforge.net/projects/elmerfem. There are some old "releases" but in general the "trunk" is preferred since it includes all latest features and bug fixes. You may obtain a complete snapshot of the current source codes, for example with

svn checkout svn://svn.code.sf.net/p/elmerfem/code/trunk elmerfem

The code may also be viewed under "Code" and you can get a up-to-date tar ball by clicking at "Download GNU tarball" at the bottom of the page. There are also some older tarballs available at

With the current update frequency these should mainly be used for historic reference.

Quick start

Make sure you have a working f90 compiler (preferably one that is listed in this table). Then pick an installation directory, e.g., /opt/elmer, /home/username or /usr. Then compile the elmer source packages in the following order: matc, umfpack, mathlibs, elmergrid, meshgen2d, eio, hutiter, fem, and optionally post, using the normal procedure of ./configure ; make ; make install, or use the following convenience script:

#!/bin/sh -f 
# Compile Elmer modules and install it
#

# replace these with your compilers:
export CC=gcc
export CXX=g++
export FC=gfortran
export F77=gfortran

modules="matc umfpack mathlibs elmergrid meshgen2d eio hutiter fem"
for m in $modules; do
cd $m
./configure --prefix=/opt/elmer
make
make install
cd ..
done

Step by step instructions


Basically the following instructions are written in the Linux/Unix point of view. If you are using Windows, take a look at the bottom of the page first.


First, check out the list of supported platforms and compilers to get a feeling of the chances you have of compiling Elmer. If your platform and compiler isn't listed, there is a chance that you won't be able to compile Elmer.

Create a directory where you will compile the source.

> mkdir -p /tmp/elmersrc
> cd /tmp/elmersrc

Decide where you want to install elmer. Good choices are eg. /home/username or /opt/elmer, but /usr shouldn't cause any harm to your system either. In this case, we will use /opt/elmer. The packages will be installed under prefix as follows:

.
|-- bin
|-- include
| `-- elmer
|-- lib
`-- share
|-- elmerfront
| |-- lib
| `-- tcl
| `-- images
|-- elmerpost
| |-- help
| |-- lib
| `-- tcl
`-- elmersolver
|-- include
`-- lib


Compiling each package


Get the recent packages and compile everything (repeat the ./configure ; make ; make install for each package) or use this script.

If something fails (which is likely), there are several things you can do. First of all, you might be able to make the code compile by specifying the compilers manully. Also, another possible cause for compilation failure is that libraries are missing or broken. You can help configure by manually specifying libraries using environment variables or command line arguments to ./configure. If all hope is lost -- send a message to the mailing list elmerdiscussion@postit.csc.fi.


Manually specifying compilers


To override the default compilers found by configure, you can use the environment variables: CC, CXX, F77 and FC. For example, the following will cause configure to use GNU compilers:

> export CC=gcc
> export CXX=g++
> export FC=gfortran
> export F77=g77
> ./configure


Manually specifying libraries


If you want to specify your own blas and lapack, you can eg.

> ./configure --with-blas="/home/username/lib/libblas.a"

or use the environment variable:

> BLAS_LIBS="-L/some/convoluted/path/lib -lblas3.1.03"

There are other variables and command line switches for specifying other libraries as well. See ./configure --help for a detailed listing.


Manually compiling solvers


The elmerf90 command is provided to help compiling your own solvers, it is a wrapper script to the compiler that was used to compile the elmer that is in the PATH.

elmerf90 MySolver.f90 -o MySolver.so 


Debugging


By default, Elmer is compiled with optimization and without debugging information. To get any meaningful debugging information, you can either use the elmer-specific --with-debug switch for configure, or manually specify the compiler flags before configure:

> ./configure --with-debug

or

> CFLAGS="-g" CXXFLAGS="-g" FFLAGS="-g" FCFLAGS="-g" ./configure


Testing the build


The fem module contains a set of tests that can be used to test that the solver really works. The tests can be invoked with make check:

> cd fem
> make check
-- cut --
testing: 1dtests [PASSED]
testing: 1sttime [PASSED]
testing: 2ndtime [PASSED]
-- cut --
testing: streamlines [PASSED]
testing: ThermalCompress [PASSED]
testing: TimeAdapt [PASSED]
Tests completed, passed: 52 out of total 52 tests

but also seperately from the tests subdirectory of the fem module using the runtests script:

> cd fem/tests
> ./runtests PoissonBEM
$ELMER_HOME undefined, setting it to ../src
testing: PoissonBEM [PASSED]
Tests completed, passed: 1 out of total 1 tests

If a test fails, a test.log file will be left in the test directory for debugging purposes.


MPI


There are two packages that need special care if you intend to use the MPI version of elmer: mathlibs (parpack) and fem. If the mpi libraries are not in a trivial place, then you will need specify the location to the configure script. For this purpose there are several command line arguments provided:

--with-mpi-dir     # Specify a dir containing--lib/, include/ and bin/
--with-mpi-lib-dir # Give location of libmpi.{a|so}* or libmpich.{a|so}
--with-mpi-inc-dir # Specify location of mpif.h
--with-mpi-bin-dir # Specify location of mprun

Usually, the --with-mpi-dir will suffice, eg. on Sun:

./configure --with-mpi-dir=/opt/SUNWhpc/

But sometimes there is a tricky situation (in this case, for 64 bit mpi libs), and you will need something like this:

./configure --with-mpi-lib-dir=/opt/SUNWhpc/lib/sparcv9 \
--with-mpi-inc-dir=/opt/SUNWhpc/include/v9

A good way to look for MPI library directory is to `locate libmpi` or compiling a simple test program with mpf90 (if provided) with verbose compilation options to see which directories and libraries are used.


Testing MPI


There are many different MPI environments, so it is difficult to give a set of commands.

Basic MPICH2 style test

> cd tests/heateq-par
> mpirun -np 2 ../../src/ElmerSolver_mpi

On IBM, the solver executable is linked with mpxlf90, so no mpirun/mprun is needed

> ../../src/ElmerSolver_mpi -nprocs 4 -pfile
hosts.lst


Common errors


If you have several versions of Elmer compiled with different compilers, you are likely to face problems, as the shared objects and module files are usually not compatible between compilers. Make sure that you have the correct libelmersolver.so and binaries (ElmerSolver) in the LD_LIBRARY_PATH and PATH.

Another source of potential problems are the ELMER_HOME and ELMER_LIB environment variables. Make sure they point to the correct locations, or unset them, if you haven't relocated your binaries.


Compilers known to work


Compiler Remarks
GNU (gcc, g++, g77, gfortran, g95) ok
Intel 7.1,8.1,9.0 (icc, ifort|ifc) ok
Pathscale (pathcc, pathCC, pathf90) ok
Portlan group 6.0-4 (pgcc, pgCC, pgf90) ok
Sun Studio ok
IBM Fortran ok
HP fortran and Visual C++ ok
Absoft barely compiles

A good rule is to try compiling everything with compilers of the same vendor. The only exception is maybe ifort and pathscale, which work fairly well together with the gnu c and c++ compilers.

gfortran can be downloaded from http://gcc.gnu.org/wiki/GFortranBinaries

and g95 can be dowloaded from http://www.g95.org/


Platforms known to work


Elmer has been known to compile and function on the following platforms:

OS Architecture Working modules
Linux x86, x86-64 S,P,F
FreeBSD x86 S,P
Sun Solaris sparcv7, sparcv9 S,P,F
IBM AIX Power4 S
Apple OS X 10.3 PPC S,P
Windows 2000,XP x86 S,P,F

Legend: S=Solver P=Post F=Front


Windows


It is possible to compile ElmerSolver for Windows in a Unix/Linux fashion. In order to do this, you will have to install the latest MinGW/MSYS environment on your Windows system (see http://www.mingw.org for more details).

You will also need to install GNU-binutils (2.17.50 or later), msysDTK (1.0.1 or later), mingw-runtime (3.13 or later), wget (1.9.1 or later), and the GNU Compiler Collection (GCC) version 4 (gcc-core, gcc-g++, gcc-gfortran, gcc-obj). The packages are available from:

   http://sourceforge.net/project/showfiles.php?group_id=2435

As of 17. Sept. 2007, GCC 4 with sjlj-exception handling is recommended.

Disclaimer: The MinGW-port of GCC 4 is currently a "technology preview version" of the forthcoming stable release. Please keep this in mind if you decide to use it.

Compiling the software: Before running the configuration scripts, you should set up the following environment variables (if you are using the automated convenience script, please edit the file accordingly):

$ export CC=gcc-sjlj
$ export CXX=g++-sjlj
$ export FC=gfortran-sjlj
$ export F77=gfortran-sjlj
$ export LDFLAGS=-L/mingw/lib/gcc/mingw32/4.2.1-sjlj


Please make sure that LDFLAGS has been set correctly according to your MinGW/MSYS installation.

Running the Solver: Make sure that the variable ELMER_HOME has been set and points to the installation directory defined in the prefix of the configuration scripts. Also make sure that ELMER_HOME/bin and ELMER_HOME/lib are contained in PATH:

$ export ELMER_HOME=/where/ever/elmer/was/installed
$ export PATH=$ELMER_HOME/bin:$ELMER_HOME/lib:$PATH
These instructions have been tested with Windows XP SP2.