Commit f4582f42 authored by Lukas Riedel's avatar Lukas Riedel

Update README.md

[ci skip]
parent eb9a1a4f
...@@ -18,26 +18,34 @@ directly to the the instructions on [how to execute DORiE](#run-dorie-run). ...@@ -18,26 +18,34 @@ 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 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 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`). docker build -f docker/dorie.dockerfile -t <img> .
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.
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 ## Manual Installation
Installing all packages manually can be quite an effort, but useful for developers who want to have easy access to the source files or users who prefer to run DORiE without the Docker overhead. Installing all packages manually can be quite an effort, but useful for developers who want to have easy access to the source files or users who prefer to run DORiE without the Docker overhead.
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! 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!
...@@ -177,49 +185,85 @@ or navigate to the `dorie/build-cmake` directory and call ...@@ -177,49 +185,85 @@ or navigate to the `dorie/build-cmake` directory and call
make doc 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! ## 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 ## 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`. 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`.
......
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