Update README.md

@@ -18,22 +18,30 @@ directly to the the instructions on [how to execute DORiE](#run-dorie-run).

The commands listed there are appended to the usual commands for running a

Docker container. See the description on Docker Hub for further details.

## Docker Installation - Simple Setup

## Download Docker image

This setup is intended for users who simply want to start computations with DORiE.

If you want to use any stable version of DORiE, or the most recent unstable

version, you can download the appropriate images from Docker Hub. To do so,

execute

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 pull dorie/dorie[:<tag>]

docker build -f docker/dorie.dockerfile -t dorie .

Omitting the tag information downloads the image with tag `latest` which

refers to the latest stable version. You can download any tag by specifying

`<tag>`. The list of available tags can be found on Docker Hub and matches

the release tags list of the Git repository. The latest unstable version is

tagged as `devel`.

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:

## Docker Installation

docker run -it -v <dir>:/sim dorie <command>

You can also compile any local version of DORiE into a new Docker image. To do

so, execute

The `-v` option tells docker to mount the directory into the container work directory (`sim`).

In the section 'Usage' you will find a list of possible commands. Note that input and output files can only be placed in the `<dir>` directory or subdirectories thereof. You must use relative paths in the DORiE configuration files.

docker build -f docker/dorie.dockerfile -t <img> .

from within the top-level DORiE source directory. Docker will use a prepared

image from Dockerhub and install DORiE into it. The created image will be called

`<img>`.

## Manual Installation

...

...

@@ -177,49 +185,85 @@ 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`.

You will then find the index page of the documentation at

`dorie/build-cmake/doc/html/index.html`.

## Run, DORiE, Run!

If you made the DORiE wrapper directory available through your `PATH` variable, you can call it by simply executing

DORiE provides a command line interface (CLI) for all its functions.

The required Python modules and all their dependencies are readily installed

into a virtual environment (`virtualenv`), which has to be activated within a

shell session. You can do so by activating it in your current session

(Manual Installation only) or by running the Docker application.

dorie <command>

### Run the `virtualenv` using the Docker application

If you did not install DORiE locally, you can use the Docker

application to boot up the virtual environment in a mounted directory of choice.

You can always find the wrapper in the `dorie/build-cmake/bin` folder of your installation and call it directly with

Start up the Docker application by calling

<path/to/>dorie/build-cmake/bin/dorie <command>

docker run -it -v <dir>:/mnt <img>

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

where you replace `<dir>` with a local directory for storing input and output

data, and `<img>` with `dorie/dorie[:<tag>]`.

If you built a local Docker image, replace `<img>` appropriately.

You can also insert `$PWD` as `<dir>` if you want to mount your

current working directory.

dorie create

The command boots up a (`bash`) shell inside a Docker container and mounts

the directory `<dir>` and all its subdirectories into the directory `/mnt`

inside the container. Your shell session starts in this directory with the

virtual environment activated.

DORiE encapsulates two routines, the Parameter Field Generator (PFG) and the main program routine. Each takes a single `.ini` configuration file as arguments.

Notice, that you can only use **local file paths** in all configuration settings

due to the directory mount.

Tweak the paramters to your liking and then call

### Activate the `virtualenv` locally

To activate the virtual environment within your current shell session, execute

dorie pfg <inifile>

source <path/to/>dorie/build-cmake/activate

to create a parameter field file. Make sure that you instruct the main routine to call the file you just created. Then call

where you replace `<path/to/>` with the path to the appropriate directory.

dorie run <inifile>

Your shell will now display the prefix `(dune-env)` to indicate that it is

configured appropriately. You can exit the environent at any time by simply

executing

to execute the main program.

deactivate

List all available commands and find further help by executing

Notice that any virtual environment only applies to, and lasts for your current

terminal session!

dorie --help

_With the virtual environment activated,_ you can now navigate to any directory

that you would like to contain your simulation input and/or output data.

or

### Execute the application

Any command to the DORiE application has the signature

dorie <command> --help

dorie <cmd> [<opts>] [<args>]

Using the `-h` or `--help` option, you can find all available commands and

further help.

## Start an interactive Docker session

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

dorie create

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:

DORiE encapsulates two main routines, the Parameter Field Generator (PFG) and

the main program routine. Each takes a single `.ini` configuration file as

argument.

docker run -i -t --entrypoint=/bin/bash -v <dir>:/sim dorie

Tweak the parameters of `parfield.ini` to your liking and then call

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

dorie pfg parfield.ini

to create a parameter field file. Do the same with the `config.ini`, while

ensuring that you use the parameter field file you just created. Then call

dorie run config.ini

to execute the main program.

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