README.md 5.85 KB
Newer Older
Dion Haefner's avatar
Dion Haefner committed
1 2 3 4 5 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 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
# 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)

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