Install Docker Container
One of the easiest forms to use our executables for Command Line Interface (CLI) usage is by downloading and running a Docker Container. This way, the software is boundled in a Docker image such that no installation other than docker is required.
Install Docker
First, obtain and install Docker following the official Docker installation instructions.
Get the DuneCopasi Docker image
With Docker available in your command line, you can now obtain the DuneCopasi Docker image. This can simply be done by pulling it from the Docker registry:
docker pull registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.1.0
docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.1.0 dune-copasi
The first line downloads the image from the internet while second one creates a tagged alias named dune-copasi so that it is easier to recall.
If you want to work with different Docker images from DuneCopasi, make sure that your local aliases do not collide!
Once this is done, your terminal should look something similar to this:
v2.1.0: Pulling from copasi/dune-copasi/dune-copasi
09dd50cc7a64: Pull complete
820c3cdfe17d: Pull complete
c91c7d9f3fb1: Pull complete
4928c27b1e25: Pull complete
6fe40e7737d8: Pull complete
7b80474789e1: Pull complete
bd9ddc54bea9: Pull complete
Digest: sha256:56feba94d0acf8f392eb835a9c25fdbd2124a199ea55cee3ff9635a3871fd597
Status: Downloaded newer image for registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.1.0
registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.1.0
~$ docker tag registry.dune-project.org/copasi/dune-copasi/dune-copasi:v2.1.0 dune-copasi
~$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
dune-copasi v2.1.0 acb239d6253e 2 seconds ago 337MB
...
~$
You can check that the image is working properly by running the --help command:
docker run dune-copasi --help
An output similar to the following should be emitted:
USAGE: dune-copasi [options]
Numerical simulator for diffusion-reaction systems on single or multiple compartments
Website: <https://dune-copasi.netlify.app>
OPTIONS:
-h / --help - Display this help.
--help-full - Display this help with long descriptions.
--version - Display the version of this program.
--parser-default - Display the default parser.
--parser-list - Display the parsers available for this program.
--dimension-list - Display the grid dimensions available for this program.
--dump-config - Dumps configuration in the INI format to stdout.
--config=<string> - Specifies a config file in INI format. See Configuration Options.
--{key}={value} - Overrides key=value sections of the config file. See Configuration Options.
...
~$
Prepare a working directory
To be able to easily share data between your operating system and the Docker
container, prepare a working directory with read/write rights to other users
(e.g., a folder named workdir). We will save the simulation files on this working directory:
~$ cd workdir
~/workdir$
This working directory will be accessible to your local text editor, Paraview, as
well as to the dune-copasi executable within the Docker container. Now, you can
move or create your configuration files into it at will.
[grid]
dimension = 2
extensions = 2 2
origin = -1 -1
refinement_level = 5
[compartments.domain]
type = expression
expression = 1
[model.scalar_field.u]
compartment = domain
cross_diffusion.u.expression = 0.005
initial.expression = exp(-(position_x^2+position_y^2+position_z^2)/(4*0.005)) / (4*3.14159265359*0.005)
storage.expression = 1
[model.time_step_operator]
time_begin = 1
time_end = 4
For more information on the possible options to successfully run a simulation, make sure to visit the Configuration Options, and the Tutorials documentations!
Run the program
Once you have set up a valid configuration file (e.g. config.ini), you are ready to use the program through the CLI via docker.
To do so, create and run a Docker container with the configuration file:
docker run -v $PWD:/dunecopasi dune-copasi --config=config.ini
This mounts the Docker container working directory /dunecopasi in the current directory $PWD (e.g. ~/workdir) and
passes the rest of the arguments to the dune-copasi executable.
This is executed by default and is used in same way as with the CLI.
In this manner, the argument passed to the underlying executable is --config=config.ini and the results
of the computations will be written on current directory.
docker runFor more information about how to run Docker containers, execute docker run --help or
visit its online documentation.
When the simulation is finished, the last line of terminal should say whether the simulation was successful, for example:
[2024-03-21 12:38:32.479] [info] Reading configuration file '~/workdir/config.ini'
[2024-03-21 12:38:32.479] [info] Starting dune-copasi (version: 2.0.0)
[2024-03-21 12:38:32.580] [info] Axis names are set to: ["x", "y", "z"]
...
...
[2024-03-21 12:38:32.723] [info] dune-copasi successfully finished :)
~/workdir$
Build local Docker image
Advanced users, who may want to make modifications the DuneCopasi code but do not want to install all the dependencies may opt for a local Docker Build. For this, you must download the DuneCopasi source code, modify it as needed, and build a new local Docker image as follows:
# fetch source code from git
git clone https://gitlab.dune-project.org/copasi/dune-copasi
# enter dune-copasi directory
cd dune-copasi
# checkout the branch you want to modify (e.g. latest)
git checkout latest
# modify source code at will
# ...
# build a new docker image from modified code (tag: dune-copasi)
docker build -t dune-copasi .
# (optional) run unit, system and tutorial tests on the new docker image
docker build --target test-env -t dune-copasi-test .
This will build all dune dependencies as well as the new modified version of the dune-copasi executable within the Docker container.
Running the program works exactly as we discussed above.