Command Line Interface

DORiE consists of two main executables and multiple utility scripts. This wrapper script supplies input files, and manages the execution of these routines. The CLI is available from within the virtual environment (venv).

The Virtual Environment

A virtual environment is a specially configured shell session, where only a certain Python installation with specific modules is available. It is installed separately from the system’s Python installation to avoid compatibility issues. DUNE and DORiE automatically create such a virtual environment upon configuration and install the necessary modules into it. You then just need to activate it.

Whenever using DORiE, you need to activate the virtual environment. You can do so by running the Docker application, or by activating it from your local installation. After following either of the subsequent instructions, you are set up to execute DORiE.

Boot up the Docker application

The Docker application starts an interactive Docker container with its own file system. To interchange files between the container and your local file system, you need to mount a directory into it. Mounting a directory will include all its subdirectories and preserve their relative file paths.

Start up the Docker application by calling

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

Replace <img> with dorie/dorie[:<tag>] and optionally insert the tag of the version you want to run. Omitting tag information will default to the latest tag which points to the latest stable version of DORiE.

Replace <dir> with the directory you would like to mount into the container. The mount endpoint is the directory /mnt inside the container. One easy way of working with the directories is creating a new directory for input and output data, navigating to it, and replacing <dir> with $PWD, which mounts your current working directory.

Executing the above command will start an interactive (bash) shell session inside the container’s file system. You will be placed inside the /mnt directory.

Activate the venv locally

After installing DORiE manually, you can activate the virtual environment in your local shell. Simply execute

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

to activate it. The prefix (dune-env) will indicate that activation was successful. You can deactivate the venv at any time by executing

deactivate

You are now ready to use the DORiE Command Line Interface!

CLI Commands

The Command Line Interface has the following signature:

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

The entire wrapper and every command of it support the -h or --help option for information about how to use the command, and on its possible arguments.

Installation Support

The command line interface supports execution of an installation directory tree anywhere on the file system. If you installed DORiE into a specific directory, export this directory as DORIE_INSTALL_DIR environment variable inside the virtual environment. The command line interface will then use the install tree instead of the default build tree:

# Uses the default build tree
dorie run config.ini

# Will execute DORiE from installed location '/some/dir'
export DORIE_INSTALL_DIR=/some/dir
dorie run config.ini

Argument Parser Documentation

The following is a documentation of the link ArgumentParser instance used for the CLI.

DORiE Command Line Interface For more information check out our online documentation: https://hermes.iup.uni-heidelberg.de/dorie_doc/master/html/

usage: dorie [-h] {create,pfg,run,plot} ...

Commands

command

Possible choices: create, pfg, run, plot

Sub-commands:

create

Copy example configuration to current folder.

dorie create [-h] [-f]
Named Arguments
-f, --force

Override existing files.

Default: False

pfg

This starts a lightweight wrapper around the dune-randomfield generator, along with a field converter.

dorie pfg [-h] [-p [N]] [-m MPI_FLAGS] config
Positional Arguments
config

Configuration file for the parameter field generator. A default version can be created with ‘dorie create’.

Named Arguments
-p, --parallel

Run in parallel on N processes. If N is not specified, run on all available CPU threads.

Default: 1

-m, --mpi-flags

Additional flags that are passed to mpirun when run in parallel. May be specified multiple times.

run

Run the DORiE main routine.

dorie run [-h] [-p [N]] [-m MPI_FLAGS] config
Positional Arguments
config

DORiE configuration file. A default version can be created with ‘dorie create’.

Named Arguments
-p, --parallel

Run in parallel on N processes. If N is not specified, run on all available CPU threads.

Default: 1

-m, --mpi-flags

Additional flags that are passed to mpirun when run in parallel. May be specified multiple times.

plot

Plot a preview of a VTK file created by DORiE.

dorie plot [-h] [-v [VAR [VAR ...]]] vtk
Positional Arguments
vtk

Input VTK file.

Named Arguments
-v, --var

Plot only given variables. If not specified, all variables are plotted.

DORiE Copyright (C) 2019 DORiE Developers This program comes with ABSOLUTELY NO WARRANTY. This is free software, and you are welcome to redistribute it under certain conditions; refer to the files LICENSE and COPYING.md in the source code repository for details.