Skip to content

D
dorie
Commit 35bd26cb authored by Lukas Riedel's avatar Lukas Riedel
Browse files
Options

Update README.md 

* Raise DUNE versions to v2.6
* Raise dependency versions to packages included in Ubuntu 18.04
* Remove badges
* Fix 'docker build' command with path to Dockerfile
* Update installation instructions for Ubuntu
* Move interactive Docker session further down
parent 8a1cf220
Hide whitespace changes
Inline Side-by-side
Showing with 38 additions and 37 deletions
README.md
View file @ 35bd26cb
# Welcome to DORiE!
(__D__UNE-__O__perated __Ri__chards equation solving __E__nvironment)
| Current Release | Current `master` |
| :-------------: | :--------------: |
| N/A | [![pipeline status](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/badges/master/pipeline.svg)](https://ts-gitlab.iup.uni-heidelberg.de/dorie/dorie/commits/master) |
DORiE is a software suite for solving Richard's Equation. The core feature is a C++ PDE-solver powered by [DUNE](https://dune-project.org/) and the [DUNE-PDELab](https://dune-project.org/modules/dune-pdelab/) module. It implements a Discontinous Galerkin (DG) discretization scheme on structured rectangular / cubic and unstructured simplex grids in two and three spatial dimensions, and makes use of advanced features like adaptive grid refinement.
The suite encapsulates a documentation and various tools for program setup, program testing, and output analysis, which are mostly written in Python.
......@@ -25,7 +21,7 @@ This setup is intended for users who simply want to start computations with DORi
Install Docker on your machine. Then, use `git clone` to download the DORiE repository into a suitable directory on your machine. Enter the directory, and call
docker build -t dorie .
docker build -f docker/dorie.dockerfile -t dorie .
Docker will use a prepared image from Dockerhub and install DORiE into it. You can now call DORiE via the Docker deamon from any directory `dir` on your machine:
......@@ -43,29 +39,33 @@ Installing all packages manually can be quite an effort, but useful for develope
Whenever possible, dependencies should be installed using a package manager, like [APT](https://wiki.ubuntuusers.de/APT/) on Ubuntu or [Homebrew](http://brew.sh/) on Mac. Manual installation on a Windows environment is strongly discouraged!
### Dependencies
Depending on your system configuration, there will be more packages necessary to install DORiE on your machine. See the step-by-step manual for further details.
Depending on your system configuration, there will be more packages necessary to
install DORiE on your machine. See the step-by-step manual for further details.
The specified versions are the _supported_ ones, where compatibility is ensured
by CI tests.
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| CMake | >= 2.8.12 |
| GCC | >= 5 | Alternatively: LLVM Clang >=6
| CMake | 3.10.2 |
| GCC | 7.3 | Alternatively: LLVM Clang >=6
| git |
| pkg-config |
| HDF5 | | with MPI support
| FFTW3 | | with MPI support
| Python | 3.x |
| pip | 3.x |
| MPI | | Tested with OpenMPI
| SuperLU | 4.3 or 5.x |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.5
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.5
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.5
| [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) | releases/2.5
| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.5
| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.5
| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.5
| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.5
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.5
| HDF5 | 1.10 | with MPI support
| FFTW3 | 3.3.7 | with MPI support
| Python | 3.6 |
| pip | 3.6 |
| MPI | | Tested with OpenMPI 2.1.1
| SuperLU | 5.2 |
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.6
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.6
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.6
| [dune-uggrid](https://gitlab.dune-project.org/staging/dune-uggrid) | releases/2.6
| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.6
| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.6
| [dune-functions](https://gitlab.dune-project.org/staging/dune-functions) | releases/2.6
| [dune-typetree](https://gitlab.dune-project.org/staging/dune-typetree) | releases/2.6
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.6
| [dune-randomfield](https://gitlab.dune-project.org/oklein/dune-randomfield) | master
......@@ -73,17 +73,17 @@ Depending on your system configuration, there will be more packages necessary to
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | master | Handles system tests
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | | Builds documentation
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | 1.8.13 | Builds documentation
| [METIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 5 | For parallel runs
| [ParMETIS](http://glaros.dtc.umn.edu/gkhome/views/metis) | 4 | For parallel runs
### Step-by-step Instructions
These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
These instructions are suitable for a clean **Ubuntu** or **macOS** setup. The main difference between the two systems is the package manager. Debian-based systems have the APT manager already built in. On Mac, we recommend installing [Homebrew](http://brew.sh/). If you prefer to use [MacPorts](https://www.macports.org/), you need to check if some of the packages require different installation options than displayed here.
If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.html) on your machine, you don't need to install Python or Pip. Simply skip these packages when using the package managers for installing the software. However, notice the warnings when compiling DORiE below!
1. **Mac OS X** users need to start by installing the Apple Command Line Tools by executing
1. **macOS** users need to start by installing the Apple Command Line Tools by executing
xcode-select --install
......@@ -92,12 +92,12 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
**Ubuntu:**
apt update
apt install cmake doxygen gcc-5 g++-5 gfortran-5 \
apt install cmake doxygen gcc g++ gfortran \
git libatlas-base-dev libfftw3-dev libfftw3-mpi-dev \
libfreetype6-dev libhdf5-mpi-dev libopenmpi-dev libpng-dev \
libsuperlu-dev libxft-dev python3-dev python3-pip
**Mac OS X:**
**macOS:**
brew update
brew install cmake doxygen gcc libpng open-mpi \
......@@ -111,7 +111,7 @@ If you installed [Anaconda](https://conda.io/docs/user-guide/install/download.ht
apt install libmetis-dev libparmetis-dev
**Mac OS X:** _Support is dropped because ParMETIS is currently unavailable from Homebrew._
**macOS:** _Support is dropped because ParMETIS is currently unavailable from Homebrew._
**Parallel runs without these two packages are possible but not supported!**
......@@ -156,14 +156,6 @@ The following software packages are cross-platform, so you should be able to fin
# Usage
## Start an interactive Docker session
In case you built DORiE using `docker build` and want to start an interactive session, e.g. to build the documentation or do some debugging, you can do so by specifying a custom entrypoint for the container:
docker run -i -t --entrypoint=/bin/bash -v <dir>:/sim dorie
This way, an interactive bash session inside the container will be started (instead of directly running DORiE). Note that DUNE and DORiE are located in `/opt/dune`.
## Documentation
The documentation of the current `master` branch can be found [online](http://dorie-docs.gitballoon.com) (password: `richards`).
......@@ -211,6 +203,15 @@ or
dorie <command> --help
## Start an interactive Docker session
In case you built DORiE using `docker build` and want to start an interactive session, e.g. to build the documentation or do some debugging, you can do so by specifying a custom entrypoint for the container:
docker run -i -t --entrypoint=/bin/bash -v <dir>:/sim dorie
This way, an interactive bash session inside the container will be started (instead of directly running DORiE). Note that DUNE and DORiE are located in `/opt/dune`.
## Troubleshooting
CMake heavily caches the results of its configuration process. In case you encounter errors or strange behavior, especially after an update, you should delete the DORiE build folder (called `build-cmake` by default) and re-install DORiE using `dunecontrol`.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment