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

We decided to make the code accessible from the

main SVN repository. This way the latest features (as well as the latest bugs) are directly available.

For a simple anonymous checkout, if you use Linux/Unix, enter the following command:

svn co --username=anonymous 
   https://svn.mathematik.tu-dortmund.de:20443/svn/Featflow2

If you have a Featflow2 developer account, enter the following command:

svn co --username=$USER 
   https://svn.mathematik.tu-dortmund.de:20443/svn/Featflow2

In Windows, you can use, e.g., TortoiseSVN to check out the code.

Featflow developers cannot only checkout the code but also commit changes to the repository. Moreover, some features which are still under development are not available in the anonymous public version of 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.