README.md

AMDiS (Adaptive MultiDimensional Simulations) is a C++ library to solve a broad class of partial differential equations (PDEs) using adaptive finite elements. Here you can find some information and tutorials about AMDiS usage/installation/extension...

## Building

The AMDiS library uses [CMake](https://cmake.org) to build. To configure with CMake we suggest to create a build directory, and run:

```
mkdir build && cd build
cmake ../AMDiS
```

## Installing

To install the library you may provide an installation directory, by calling CMake with the additional argument:

```
cmake -DCMAKE_INSTALL_PREFIX:PATH=[install_dir] .
```

and just run the `install` target:

```
cmake --build . --target install
```

## Demos

Some demo programs using the AMDiS library are implemented in the subdirectory `demo`. To configure and build run CMake again, with the AMDiS installation directory specified:

```
mkdir demo/build && cd demo/build
cmake -DAMDIS_DIR:PATH=[install_dir]/share/amdis [-DCOMPONENT=(SEQUENTIAL|PARALLEL)] ..
cmake --build . --target all
```

The optional `COMPONENT` parameter set the variant of AMDiS to be used, i.e. sequential or parallel AMDiS. All AMDiS-dependent programs can be
configured using a `CMakeLists.txt` file similar to the following:

```
project("myproject")
cmake_minimum_required(VERSION 3.1)

find_package(AMDIS REQUIRED [SEQUENTIAL|PARALLEL] [VERSION>=1.1])

add_executable(mytarget src/mysource.cc)
target_include_directories(mytarget PRIVATE ${AMDIS_INCLUDE_DIRS})
target_compile_options(mytarget PRIVATE ${AMDIS_COMPILEFLAGS})
target_link_libraries(mytarget ${AMDIS_LIBRARIES})
```

## Tests

The tests are implemented in the subdirectory `test` and can be built and run by using the CMake:

```
mkdir test/build && cd test/build
cmake -DAMDIS_DIR:PATH=[install_dir]/share/amdis ..
cmake --build . --target all
```

## Documentation

The documentation is built using [Doxygen](http://www.doxygen.org). Simply run the command in the `doc` subdirectory:

```
cd AMDiS/doc
doxygen
```

Then html documentation is then generated in the `doc/html` folder.

## System requirements

AMDiS can be build with various c++ compilers, e.g.
- gcc, version >= 4.6
- clang, version >= 3.1
- intel, version >= 2013
- MSVC, version >= 11.0

A detailed overview about compiler compatibility is listed in the wiki-page [Compatibility](https://gitlab.math.tu-dresden.de/iwr/amdis/wikis/compatibility).

We assume the following libraries to be found in standard location:
- [boost](http://boost.org) (modules: system, iostreams, filesystem, program_options, and date_time), version >= 1.48
- [CMake](https://cmake.org), version >= 3.1

For the parallel AMDiS we require additionally
- [ParMETIS](http://glaros.dtc.umn.edu/gkhome/metis/parmetis/overview), version >= 4.0
- [PETSc](https://www.mcs.anl.gov/petsc), version >= 3.3

When PETSc is configured with ParMETIS, the version from PETSc can be used directly.

## CMake options
When configuring AMDiS several options can be modified. For an interactive gui, use either `ccmake`, or `cmake-gui`.

| Option         | Type | Description |
| -------------- | ---- | ----------- |
| ENABLE_MPI     | BOOL | Compile and link with mpi library |
| ENABLE_OPENMP  | BOOL | Compile and link to openMP threading library |
| ENABLE_UMFPACK | BOOL | Compile with support for suitesparse UMFPack library |
| ENABLE_PARALLEL_DOMAIN | BOOL | Switch to parallel AMDiS. Needs PETSc and ParMETIS to be installed. (Implies ENABLE_MPI) |
| PETSC_DIR | PATH | Path to the PETSc root directory, containing the lib/ and include/ subdirectories. |
| PARMETIS_DIR | PATH | Path to the ParMETIS root directory, containing the lib/ and include/ subdirectories. |
| ENABLE_ZOLTAN | BOOL | Compile support for graph paritioning library Zoltan. |
| ZOLTAN_DIR | PATH | PAth to the Zoltan root directory, containing lib/ and include/ subdirectories. |
| ENABLE_HYPRE | BOOL | Compile support for algebraic multigrif HYPRE library. |
| ENABLE_BDDCML | BOOL | Add support for the BDDCML library. |
| ENABLE_EXTENSIONS | BOOL | Add additional features, not yet part of the standard AMDiS. Experimental! Should be used with care. |
| ENABLE_COMPRESSION | BOOL | Allow compressed output of .vtk and .arh files. Need development files of zlib and libbz2 to be installed on the system. |