Commit e9b613e2 authored by Lukas Riedel's avatar Lukas Riedel 📝

Readme: Added manual install instruction for Ubuntu. Deleted deprecated sections

parent 40ef9f03
......@@ -3,12 +3,20 @@
[![build status](http://shangrila.iup.uni-heidelberg.de:30000/ci/projects/1/status.png?ref=master)](http://shangrila.iup.uni-heidelberg.de:30000/ci/projects/1?ref=master)
## Installation Instructions
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/). It implements a Discontinous Galerkin (DG) discretization scheme on structured rectangular 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.
DORiE is developed and maintained by the [DORiE Developers](mailto:dorieteam@iup.uni-heidelberg.de) of the [TS-CCEES](http://ts.iup.uni-heidelberg.de/) research group at IUP Heidelberg, in collaboration with [Ole Klein](https://conan.iwr.uni-heidelberg.de/people/oklein/) and the [Scientific Computing Group](https://conan.iwr.uni-heidelberg.de/) of IWR Heidelberg, supervised by [Kurt Roth](http://ts.iup.uni-heidelberg.de/people/prof-dr-kurt-roth/).
# Installation Instructions
DORiE is a [DUNE](https://dune-project.org/) module and requires several other DUNE modules as well as third party software packages. Installation can be handled manually on your local machine, but it's recommended to use the virtualization software [Docker](https://www.docker.com/) instead.
In any case, DORiE is configured, build, and installed via the [DUNE Buildsystem](https://dune-project.org/doc/installation/), using the `dunecontrol` script to handle DUNE-internal dependencies.
### Docker Installation
## Docker Installation
Install Docker on your machine. Then, download the [DORiE DUNE Environment Repository](https://hub.docker.com/r/dorie/dune-env/) from [Dockerhub](https://hub.docker.com/), by executing
docker pull dorie/dune-env
......@@ -29,7 +37,7 @@ Next, `git clone` the DORiE repository into the shared folder. Enter the contain
to build DORiE.
#### Update DUNE
### Update DUNE
The DUNE modules in the repository might be outdated. You can update to the newest versions by calling
dunecontrol update
......@@ -38,119 +46,129 @@ Then compile all modules again by executing
dunecontrol all
## Quick installation
More comprehensive installation instructions of the current `master` branch can be found [in the online documentation](http://dorie-docs.gitballoon.com) (password: `richards`).
0. __Mac OS:__ Make sure you have the most recent version of the Command Line Tools installed (just run `xcode-select --install`).
1. Follow our [Git Tutorial](http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/wikis/git-tutorial) to clone the repository to a suitable location on your computer. Make sure the path to the repository does not contain any spaces, as this will break most of the configure scripts.
2. Run the install.sh script by calling
bash install.sh
You will be prompted to enter your password. You need to have `sudo` rights on your machine to install DORiE.
## Manual Installation
Installing all packages manually can be quite an effort, but useful for developers who want to easily access documentation material and source files of the dependency packages. 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 the software on your machine. See the step-by-step manual for further details.
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| CMake | >= 3.0 |
| doxygen |
| GCC | >= 5 |
| git |
| pkg-config |
| HDF5 | | MPI library
| FFTW3 | | MPI library
| METIS |
| ParMETIS |
| Python | 3 |
| Python Pip | 3 |
| OpenMPI | >= 2 |
| SuperLU | >=5 |
| ----- | ----- | ----- |
| Breathe | | Install via `pip` |
| Sphinx | | Install via `pip` |
| VirtualEnv | | Install via `pip` |
| ----- | ----- | ----- |
[UG](https://gitlab.dune-project.org/ug/ug) | 3.12.1 | Follow the [IWR Installation Instructions](http://www.iwr.uni-heidelberg.de/frame/iwrwikiequipment/software/ug)
| [dune-common](https://gitlab.dune-project.org/core/dune-common) | releases/2.4
| [dune-geometry](https://gitlab.dune-project.org/core/dune-geometry) | releases/2.4
| [dune-grid](https://gitlab.dune-project.org/core/dune-grid) | releases/2.4
| [dune-istl](https://gitlab.dune-project.org/core/dune-istl) | releases/2.4
| [dune-localfunctions](https://gitlab.dune-project.org/core/dune-localfunctions) | releases/2.4
| [dune-typetree](https://gitlab.dune-project.org/pdelab/dune-typetree) | releases/2.4
| [dune-pdelab](https://gitlab.dune-project.org/pdelab/dune-pdelab) | releases/2.4
| [dune-python](https://gitlab.dune-project.org/quality/dune-python) | releases/2.4
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.4
### Ubuntu Manual Installation
The following instructions follow the installation instructions on a 'clean' Ubuntu system and are similarly executed to create the DORiE Docker image from an Ubuntu Docker image.
1. Install the third party software using `apt-get`:
*Note*: This will try to install some large dependencies with the package managers `apt-get` (Linux) or MacPorts (OSX). If this fails for some reason, you will have to make sure to install these packages to your system manually.
3. The DORiE installation routine provides multiple options:
* `doriecontrol install core`: Install only packages needed to compile and run DORiE (minimal installation).
* `doriecontrol install all`: Install the core packages as well as documentation tools and the testing suite (full installation).
Choose one of the two commands and run it from the command line.
4. Grab a cup of your favorite beverage.
5. Once everything is installed without errors, you can start runs with
dorie run INIFILE
For more information, type
bash install.sh help
or
doriecontrol help
or
dorie help
## Usage
1. Create some folder(s) that you would like to hold the input and output files of the run.
2. Call
dorie create
to create a set of dummy input files in your current folder.
3. Modify the input to your liking. Make sure to specify all parameters that are set to `UNDEFINED`. The Parameter Cheat Sheet in the `doc/` directory of the repository provides information on the meaning of all parameters, including recommended values.
4. Start the run with
dorie run INIFILE [OPTIONS]
You may get a list of the available commands and options by executing
dorie help
## Recommended third-party software
The following software packages are too large or too specialized to be bundled with DORiE, but are nonetheless recommended.
They are cross-platform, so you should be able to find a release that fits your operating system.
apt-get update && apt-get install -y \
autoconf \
bison \
cmake \
doxygen \
flex \
gcc-5 \
g++-5 \
gfortran-5 \
git \
libatlas-base-dev \
libfftw3-dev \
libfftw3-mpi-dev \
libfreetype6-dev \
libhdf5-mpi-dev \
libmetis-dev \
libopenmpi-dev \
libpng-dev \
libscotchparmetis-dev \
libsuperlu-dev \
libxft-dev \
python3-dev \
python3-pip
2. Install the necessary Python packages using `pip`:
python3 -m pip install virtualenv
python3 -m pip install sphinx
python3 -m pip install breathe
3. Clone UG into a suitable folder on your machine and `git checkout` the specified version. Install it by calling
autoreconf -is
./configure --prefix=<dir> --enable-parallel --without-x --enable-dune --enable-system-heap
make && make install
Replace `<dir>` with a installation directory of choice.
4. Clone the DUNE modules and DORiE into a suitable folder on your machine. Make sure that you `git checkout` the specified branches. Enter the folder, and call
./dune-common/bin/dunecontrol all -DCMAKE_CXX_FLAGS="-O3"
If you installed software into paths not appended to your `PATH` variable, you will have to add a custom options file to make sure that CMake finds all packages. See the [DUNE Installation Instructions](https://dune-project.org/doc/installation/) for details. CMake will throw an error if required packages are not found.
## Recommended Third-Party Software
The following software packages are cross-platform, so you should be able to find a release that fits your operating system:
* [Gmsh](http://gmsh.info/): An open-source CAD that can be used to create the `.msh` files used by DORiE to define triangular meshes.
* [ParaView](http://www.paraview.org/): A powerful post-processing tool for VTK files. Offers both visualization and data analysis tools.
* [Python VTK tools](http://www.vtk.org/Wiki/VTK/Examples/Python): If you want to write your own post-processing in python, you may use these tools which supply readers for binary VTK files.
## Documentation
The documentation of the current `master` branch can be found [online](http://dorie-docs.gitballoon.com) (password: `richards`).
If you want to install the dependencies and build the documentation yourself (e.g. because you are using an older version of DORiE), you can use some convenience functions provided by `doriecontrol`.
# Usage
If you did not choose the full installation routine, you have to install the documentation tools separately before building the doc. Do so by calling
doriecontrol install doc
_After_ installing DORiE, you can create the documentation by calling
doriecontrol make doc
## Documentation
It can then be found in the `doc/` directory of your repository.
The documentation of the current `master` branch can be found [online](http://dorie-docs.gitballoon.com) (password: `richards`).
## Troubleshooting
In case you encounter errors or strange behavior, you should first take a look at the [List of Known Bugs](http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/issues?assignee_id=&author_id=&label_name=bug&milestone_id=&scope=all&sort=created_desc&state=opened). For problems related to the installation, refer to the sections below.
The documentation can be built after DORiE has been properly configured (i.e., by calling `dunecontrol`). Enter the build directory of DORiE (`dorie/build-cmake`) and execute
### Something went wrong during the install.sh script
* Make sure you ran the script with `bash`.
* Look through the output of the script. If you see any errors, try to resolve them.
* If nothing works, open an issue, or send the output of the script to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).
make doc
### I ran 'doriecontrol install all / core', but DORiE doesn't work
This is probably due to an error while building one of the dependencies. Have a look at the installation.log file in the main directory. Search for errors, maybe you can detect which package failed to build, and resolve the error yourself. If this doesn't work, open an issue, or send the installation.log file to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).
The documentation files can now be found in the subfolder `dorie/build-cmake/doc`.
Note that if you just want to rebuild one specific package, you don't have to work through the whole build process again - just use the command
## Usage
doriecontrol install PACKAGES
The DORiE executables each expect a single `.ini` configuration file as input.
e.g.,
./dorie config.ini
doriecontrol install openmpi dune dorie
to rebuild OpenMPI, DUNE, and DORiE.
## Troubleshooting
In case you encounter errors or strange behavior, you should first take a look at the [List of Known Bugs](http://shangrila.iup.uni-heidelberg.de:30000/dorie/dorie/issues?assignee_id=&author_id=&label_name=bug&milestone_id=&scope=all&sort=created_desc&state=opened). For problems related to the installation, refer to the sections below.
### DORiE is running, but I suspect that something is wrong
You can execute system tests in order to ensure that DORiE is running correctly and producing the expected results. You will need to install the testing suite first (this is _not_ done by default) and rebuild DORiE:
doriecontrol install testing dorie
Then, you can run the system tests:
You can execute system tests in order to ensure that DORiE is running correctly and producing the expected results. Navigate to the build directory (`dorie/build-cmake`) end execute
doriecontrol test
make test
You will be informed whether each test has been passed or failed, and you may find additional output in the DORiE build directory.
......
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