README.md 7.32 KB
Newer Older
Dion Haefner's avatar
Dion Haefner committed
1 2 3 4 5
# Welcome to DORiE!
(__D__UNE-__O__perated __Ri__chards equation solving __E__nvironment)

[![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)

6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
## 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
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

Run a new container from the v2.4 image by calling

    docker run -i -t dorie/dune-env:2.4 /bin/bash

Additionally, use the `-v` option of the `run` command to mount a local directory into the container:

    -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.

Next, `git clone` the DORiE repository into the shared folder. Enter the container, and execute

    dunecontrol --only=dorie all

to build DORiE.

#### Update DUNE
The DUNE modules in the repository might be outdated. You can update to the newest versions by calling

    dunecontrol update

Then compile all modules again by executing

    dunecontrol all

Dion Haefner's avatar
Dion Haefner committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
## 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.
    
    *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.

* [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`.

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

It can then be found in the `doc/` directory of your repository.

## 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.

### 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).

### 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).

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

    doriecontrol install PACKAGES

e.g.,

    doriecontrol install openmpi dune dorie

to rebuild OpenMPI, DUNE, and DORiE.

### 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:

    doriecontrol test

You will be informed whether each test has been passed or failed, and you may find additional output in the DORiE build directory.

### Further help
Open an issue, or write to the [DORiE developer mailing list](mailto:dorieteam@iup.uni-heidelberg.de).