FEATFLOW2 - Featflow

The software package FEATFLOW2

The software package FEATFLOW2 is the successor of the original software package FEATFLOW. Based on the techniques and ideas of the original package, this finite element library exploits all possibilities of the Fortran 90 language to perform highly efficient finite element calculations, while still being flexible enough to be used for academic purposes.

Some of the main highlights read as follows:

Based on the Fortran 90/95 programming language standard. No more 6-letters variables and subroutine names.
Fully documented source code.
Automated build system based on shell and perl scripts. Auto tuning of the code to the current processor, compiler, etc., for most up-to-date computer systems like
- Linux
- Sun Solaris
- Windows/Cygwin
- Mac OS X
Simple extension of the makefile system to new processors and compiler settings.
Multiple compiler configurations can be maintained simultaneously (e.g. precompiled libraries for debug and release mode).
Preprocessor support.
Support for Cygwin/Windows via GFortran
Support for native Windows. Project files for Visual Studio + Intel Fortran.
Basic support for OpenMP.
Basic support for CUDA (in development).
Support for ParaView output files for postprocessing.
Support for h-adaptivity.
Highly advanced numerical solver algorithms like geometrical multigrid.
Highly advanced discretisation methods such as limiter-based stabilisation techniques for convection-dominated flows

Example applications already realized with this code or in development:

Standard examples (Poisson, heat equation, laminar Stokes, Navier-Stokes,...)
Allen-Cahn equations (not in the package)
Linear elasticity (not in the package)
Particulate flow (not in the package)
Shallow water (not in the package)
Compressible (M)HD (not in the package)
Optimal Control of the Poisson equation, heat equation, Navier-Stokes equations (not in the package)

The package is under heavy development and is therefore labeled as BETA software. Any user who likes to download and test the software is welcome, but we remark that we can only give very limited support for this project.

Prerequisites

The following prerequisites are necessary to download and compile the software:

An SVN client (e.g., TortoiseSVN in Windows)
A Fortran 90 compiler (e.g., gfortran, Intel Fortran compiler or similar)
Linux, Unix, Mac OS X (with GCC + GFortran + wget + perl), Windows (with Cygwin and Fortran compiler + wget + make + perl) or Windows with Visual Studio and Intel Fortran compiler
An internet connection
500 MB disc space (depending on the configuration)
ParaView for postprocessing of VTK files

Software repository

The source code of FeatFlow2 is available at the following github repository:

https://github.com/tudo-math-ls3/FeatFlow2

Organization

The package is organized in the following directories:

applications: Contains the main applications like a poisson example, a heat equation example, cc2d for laminar Stokes/Navier-Stokes in 2D and others.
area51 (missing in anonymous version): Here you can put your own applications. Just copy one of the main examples from the applications/ folder to this folder and change as you like.
benchmark (missing in anonymous version): This directory contains a benchmark system we use for regression tests and for massive computations on cluster systems.
bin: Basic shell scripts and makefile system
codefragments (missing in anonymous version): This directory contains a collection of code fragments and examples how to use portions of the kernel. The code here is not automatically build and does not belong to any application or to the kernel, but is intended as a copy-and-paste source for user applications.
docs: Documentation system
kernel: The basic FEATFLOW2 kernel with all mathematical basics (finite element spaces, linear solvers, etc.)
templates: Template scripts for different architectures for the creation of makefiles.
thirdparty: Contains the basic libraries in a compressed form or download routines for these (as we are not allowed to distribute the source of all libraries with our package). The makefile system will automatically download these libraries via an existing Internet connection in Linux/Unix, Mac OS X, and Windows.
tools: Auxiliary programs (e.g., creation of EPS files from meshes)
tutorials: A set of tutorials, in correspondence to this Website
userapps (missing in anonymous version): This directory contains several experimental applications in development by the FeatFlow2 users. Once development is finished, these applications will be moved to the main application directory.

The makefile system in Linux/Unix and Mac OS X

As an example application, we show here how to compile the poisson example under a Linux/gcc/gfortran based system. Proceed as follows:

1.) Switch to applications/poisson

cd applications/poisson

2.) Create a makefile script via a configure command. This will look at your system, detect your CPU and your compiler settings:

./configure

Note: This is not the usual "configure" command which is provided by many Linux software packages. We wrote this configure on our own. It is a specialized shell/perl script and creates you a makefile "GNUmakefile".

3.) Compile the application

make

Note: During the first build, the makefile system will automatically download some basic libraries from the internet, untar/unzip the libraries and compile them (e.g., AMD, UMFPACK, LAPACK).

4.) Run the application

./poisson

5.) Start paraview and open one of the VTK files in the gmv/ subdirectory. These files were produced by the application and represent the solution of a poisson equation on the unit square.

You can configure the makefile system in various ways. This can be done by passing appropriate parameters to the ./configure command. Here some examples:

./configure --help

Print all parameters.
./configure --no-opt --debug

Configures the makefile to not use optimization and to generate debug symbols.
./configure --list-ids

Print all configuration IDs which are valid vor this system. Every ID stands for one compiler setting.

./configure --id=...

Configure the makefile to use a special compiler setting. The ID "..." can be one of the IDs you got with the "--list-ids" parameter.

For example, --list-ids may output you

Valid build IDs (for pc64-opteron6100-linux hosts) match
against the following regular expressions:

...
(pc|pc64)-.*-.*-g95-.*
(pc|pc64)-.*-.*-gcc-.*
(pc|pc64)-.*-.*-intel-.*
...

Use any of these build IDs as argument for the --id 
option. The current build ID for nightwish is:

  pc64-opteron6100-linux-gcc-blas

Then you can enforce the use of the intel compiler by forcing the build ID which stands for the Intel compiler by replacing "gcc" by "intel":

./configure --id=pc64-opteron6100-linux-intel-blas

Note that you can have multiple IDs precompiled simultaneously. You can switch between two IDs by using ./configure --id=... followed by a make.

If you want to cross-compile for a specific build ID which does not fit to the host where the compilation is done you need to specify the "--force-id" flag:

    ./configure --id=pc64-opteron6100-linux-intel-blas --force-id

Furthermore, the make process itself can be influenced by various parameters, e.g.,

make help

Print all parameters.
make clean

Delete all object files and force a complete rebuild with the next "make" for the current build id.

VERY VERY HELPFUL, TO BE DONE AT FIRST IF YOUR COMPILER DOES NOT WANT TO COMPILE THE CODE AFTER AN UPDATE!!!
make id

Show the current compiler settings
make purge

Delete all object files for all IDs. That way, you do a complete tabula-rasa...

Customizing the makefiles

If you want to customize the makefiles to a system which is not yet supported, you have to modify the compiler files as follows:

If you have a completely new CPU, modify bin/guess_id which detects the CPU to generate a basic build ID. You may easily find out if this is the case by invoking the command
```
./bin/guess_id
```
in the Featflow2 main directory. If this command returns a generic string such as
```
pc64-x86-linux
```
then you CPU is not yet detected correctly by the guess_id script.
Once you added a new CPU you may have to adjust the actual compiler settings to use optimisation flags taylored to the new CPU. Some compilers (GCC version 4.2 or better, Intel compiler suite 11.0 or better) support automatic tuning for the host, where the compilation is done. In this case it suffices to enable this feature:
```
./configure --id=pc64-opteron6100-linux-intel-blas --opt=NATIVE
```
If you need to cross-compile or your compiler does not support automatic tuning then you have to define appropriate compiler settings manually. In the templates/ directory you find several template makefiles which belong to one of the following categories:
ARCH_CPU-xxx.mk

Architecture and CPU specific settings (you only need to modify these files if you port FEATFLOW2 to a completely new architecture such as the POWER-architecture by IBM)

BLAS-xxx.mk

Settings for BLAS library to be used (you only need to modify these files if your system has a BLAS implementation which is not yet supported by FEATFLOW2)

COMP-xxx.mk

Generic compiler settings such as arguments passed to the linker (you only need to modify these files if your system has a compiler suite which is not yet supported by FEATFLOW2 such as the NAG compiler suite; another situation in which you may have to modify these files is if you added a new architecture and need to specify generic compiler settings for this particular architecture)

OS-xxx.mk

Operating system specific settings (you only need to modify these files if you port FEATFLOW2 to a completely new operating system such as BSD-type OSes)

CFLAGSOPT-xxx-yyy.mk
These files contain a list of manually defined optimisation flags for various combinations of architectures and compiler suites. Each block defines optimisation flags to be used for architecture xxx and compiler suite yyy:
```
# CPUs based on AMD Family 10h cores with x86-64 instruction set
# support. (This supersets MMX, SSE, SSE2, SSE3, SSE4A, 3DNow!,
# enhanced 3DNow!, ABM and 64-bit instruction set extensions.)
ifeq ($(call match,$(ID),(pc|pc64)-(opteron4100|opteron6100)-.*-intel-.*),yes)
ifeq ($(call intelminversion,11,1),yes)
CFLAGSOPTF77  := -xSSE3
CFLAGSOPTF90  := -xSSE3
CFLAGSOPTC    := -xSSE3
CFLAGSOPTCXX  := -xSSE3
LDFLAGSOPT    := -xSSE3
else
CFLAGSOPTF77  := -xT
CFLAGSOPTF90  := -xT
CFLAGSOPTC    := -xT
CFLAGSOPTCXX  := -xT
LDFLAGSOPT    := -xT
endif
endif
```
The above example illustrates that is is even possible to use different settings depending on the actual compiler version which is necessary in case the command line options have changed over time or some optimization flags are not available in older compiler versions.

To add support for a new CPU create a new block of this type based on the existing templates and adjust it to your needs.

Compiling applications with CYGWIN in Windows

Compiling applications using the CYGWIN environment is basically the same as using a Unix/Linux system, see above. However, one has to take care that a couple of additional tools are installed using the SETUP of CYGWIN. The following tools have to be installed:

Devel / GCC4-GFORTRAN
Devel / GCC4-G++
Devel / MAKE
Interpreters / Perl
Web / WGET

and all their dependencies (which are detected automatically by the CYGWIN setup).

Compiling applications in native Windows

With the appropriate tools, Featflow 2 can be compiled natively in a Windows environment. However, there is a bit preparation necessary, as some libraries have to be compiled in advance. The process is done automatically as far as possible.

The following tools are necessary:

Visual Studio 2010 or higher
Intel Fortran Compiler 12 or higher

For downloading of the SVN repository, a SVN implementation is needed, e.g. TortoiseSVN. After the checkout has been completed, the following scripts have to be executed manually (e.g. with a double-click):

thirdparty/getlibs_win.cmd: Downloads external libraries from the internet and extracts the sourcefiles on the local hard disc.
thirdparty/buildlibs_win32.cmd and/or buildlibs_win64.cmd: Invokes the Visual Studio compiler and pre-compiles all libraries as well as the Featflow-2 kernel. Compiler detection and compilation should be done automatically and will take a while.

buildlibs_win32.cmd compiles the libraries using a 32 bit compiler, while buildlibs_win64.cmd applies a 64 bit compiler for the compilation. You should compile the version which you plan to use later.

Afterwards, one can find appropriate .sln project files in every project directory, which can be opened with Visual Studio. For example, there is a file applications/poisson/poisson.sln which defines the complete project settings for the Poisson equation. Open the .sln file of your choice. Afterwards, you have the choice between four targets: Debug/Release in 32 or 64 bit mode. Choose a target which fits to the libraries compiled in the previous step, then you can compile and run the project.

Remark: Currently, there are still some project files in the directory winXXXX of every application. These directories contain project files for Visual Studio 2003 and are deprecated. They will be removed in future.