Skip to content

D
dorie
Commit 8deb59e4 authored by Lukas Riedel's avatar Lukas Riedel
Browse files
Options

revamped readme: 

* updated requirement list
* added optional package list
* reworked manual installation
* warning not to call 'make install' #16
* notes on parallel setup requirements #24
parent c28e2847
Hide whitespace changes
Inline Side-by-side
Showing with 49 additions and 26 deletions
README.md
View file @ 8deb59e4
......@@ -34,18 +34,13 @@ In the section 'Usage' you will find a list of possible commands. Note that inpu
## Docker Installation - Interactive Setup
This setup is intended for advanced users. You will gain access to the DORiE module outside the container, and be able to make changes to the source code.
We have prepared a [DORiE DUNE Environment Image on Dockerhub](https://hub.docker.com/r/dorie/dune-env/), which is a modified image of the Ubuntu OS that has all dependencies readily installed. The current version is 2.5 (referencing the DUNE module version 2.5).
Run a new container from this image by calling
We have prepared a [DORiE DUNE Environment Image on Dockerhub](https://hub.docker.com/r/dorie/dune-env/), which is a modified image of the Ubuntu OS that has all dependencies readily installed. The current version is 2.5 (referencing the DUNE module version 2.5). We will run a new container from this image and mount some local directory `<hostdir>/dorie` into it by calling
docker run -i -t dorie/dune-env:2.5 /bin/bash
docker run -v <hostdir>/dorie:/opt/dune/dorie -i -t dorie/dune-env:2.5 /bin/bash
Docker will automatically download the image if necessary. Use the `-v` option of the `run` command to mount a local directory into the container:
Docker will automatically download the image if necessary. Now you can access the content of the (still empty) folder of the virtual machine from your local `<hostdir>/dorie` directory. *Mounting directories is not possible after your container has been started!*
-v <hostdir/dorie>:/opt/dune/dorie
This way, you can access the content of the (still empty) folder of the virtual machine from your local `<hostdir>/dorie` directory. *Mounting directories is not possible after your container has been started!*
Next, use `git clone` to download the DORiE repository into the shared folder. Enter the container, and execute
Next, use `git clone` to download the DORiE repository into the shared (mounted) folder. Enter the container, and execute
dunecontrol --only=dorie all
......@@ -58,7 +53,7 @@ to build in parallel on `N` processes. Lastly, install the DORiE binaries by cal
dunecontrol --only=dorie make install
### Update DUNE
The DUNE modules in the repository might be outdated. You can update to the newest versions by calling
The DUNE modules (as well as DORiE itself) in the repository might be outdated. You can update to the newest versions by calling
dunecontrol update
......@@ -87,7 +82,7 @@ Depending on your system configuration, there will be more packages necessary to
| pip | 2.7 or 3.x |
| MPI | | Tested with OpenMPI
| SuperLU | 4.3 or 5.x |
| VirtualEnv | | Install via `pip` |
| VirtualEnv | | For Python 2 only. Install via `pip` |
| [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
......@@ -97,10 +92,18 @@ Depending on your system configuration, there will be more packages necessary to
| [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
| [dune-python](https://gitlab.dune-project.org/quality/dune-python) | releases/2.5
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | releases/2.5
| [dune-testtools](https://gitlab.dune-project.org/quality/dune-testtools) | master
### Optional Packages
| Software | Version/Branch | Comments |
| ---------| -------------- | -------- |
| [doxygen](http://www.stack.nl/~dimitri/doxygen/) | | Builds documentation
| [Sphinx](http://www.sphinx-doc.org/en/stable/) | | Builds documentation
| [Breathe](https://github.com/michaeljones/breathe) | | 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
If you also want to build the documentation, you will additionally need to install Doxygen, Sphinx and Breathe.
### 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.
......@@ -119,11 +122,23 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
**Mac OS X:**
brew update
brew install automake cmake doxygen gcc libtool libpng open-mpi \
brew install cmake doxygen gcc libpng open-mpi \
pkg-config python3 superlu
brew install hdf5 --with-mpi
brew install fftw --with-mpi
1. The parallel linear solver of DORiE can make use of the ParMETIS package. If you want to run DORiE in parallel on multiple processes, additionally install METIS and ParMETIS:
**Ubuntu:**
TBD
**Mac OS X:**
brew install metis parmetis
**Parallel runs without these two packages are possible but not supported!**
2. Install the necessary Python packages using `pip`:
**Ubuntu:**
......@@ -132,13 +147,13 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
**Mac OS X:**
sudo -H python3 -m pip install virtualenv sphinx breathe
pip3 install sphinx breathe
3. **Mac OS X** only:
The Apple Clang compiler shipped with CMake is not suitable for compiling DUNE and UG. Before proceeding, call
The Apple Clang compiler shipped with CMake is not suitable for compiling DORiE. Before proceeding, call
export CC=gcc-6
export CXX=g++-6
export CC=gcc-7
export CXX=g++-7
to enfore the Homebrew'd GCC compiler. Note that this variable export only lasts for your current terminal session. Always make sure that the configuration tool actually finds GCC instead of the Apple Clang.
......@@ -146,19 +161,21 @@ These instructions are suitable for a clean **Ubuntu** or **Mac OS X** setup. Th
**Ubuntu:**
MAKE_FLAGS="-j <N>" ./dune-common/bin/dunecontrol all
CMAKE_FLAGS="-DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" MAKE_FLAGS="-j <N>" ./dune-common/bin/dunecontrol all
**Mac OS X:**
CMAKE_FLAGS="-DDUNE_FORCE_PYTHON3=True" MAKE_FLAGS="-j <N>" ./dune-common/bin/dunecontrol all
CMAKE_FLAGS="-DDUNE_PYTHON_VIRTUALENV_SETUP=True -DDUNE_PYTHON_ALLOW_GET_PIP=True" MAKE_FLAGS="-j <N>" ./dune-common/bin/dunecontrol all
to build all DUNE modules in parallel on `N` processes. If you installed software into paths not appended to your `PATH` variable, you will have to add `CMAKE_FLAGS` to the call to make sure that CMake finds all packages. Alternatively, you can add a custom options file. See the [DUNE Installation Instructions](https://dune-project.org/doc/installation/) for details. CMake will throw an error if required packages are not found.
5. To install all DUNE packages into system locations (so you can call `dunecontrol` and `dorie` from anywhere), you can run
5. After a successful build you can call the `dorie` wrapper located in `dorie/build-cmake/bin` from anywhere on your machine, but it is more handy to add this location to your search path. You can add the directory to your `PATH` variable by calling
./dune-common/bin/dunecontrol make install
PATH=<path/to/>dorie/build-cmake/bin:$PATH
which may require `sudo` rights on your machine. This action is **optional and not required to run DORiE**. If you choose not to install DORiE, make sure to append the location of `dunecontrol` (`dune-common/bin`) and `dorie` (`dorie/build-cmake/bin`) to your search path.
However, this will only last for your current terminal session. Another option is to add this path permanently in your shell configuration file.
**Installing DUNE and DORiE via `make install` into your usual work environment is strongly discouraged!**
## Recommended Third-Party Software
......@@ -186,14 +203,20 @@ The documentation can be built after DORiE has been properly configured (i.e., b
dunecontrol --only=dorie make doc
or navigate to the `dorie/build-cmake` directory and call
make doc
The documentation files can now be found in the subfolder `dorie/build-cmake/doc`.
## Run, DORiE, Run!
During `make install`, DORiE installs a wrapper to access the functions and executables of DORiE from any location on your device. After a successful installation, you can call the wrapper by simply executing
If you made the DORiE wrapper directory available through your `PATH` variable, you can call it by simply executing
dorie <command>
If you did not run `dunecontrol make install`, you can find the wrapper in the `dorie/build-cmake/bin` folder of your installation.
You can always find the wrapper in the `dorie/build-cmake/bin` folder of your installation and call it directly with
<path/to/>dorie/build-cmake/bin/dorie <command>
To start your first simulation run, create a new directory and enter it. Place some exemplary configuration and boundary condition data files in there by calling
......
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