Version: Next

Install From Source

development

These are the instruction for the development branch of DuneCopasi!

docker build

This mode of installation is recommended only for API usage, immersive developemt, or cases where upstream dependencies need to be modified. In other cases, you can easily modify the source code, build it, and use it through a docker installation without needing to install the dependencies.

Operating Systems and Compilers

The installation from source is known to compile and run under Debian/Ubuntu, macOS, and Windows. In all three cases with Clang and GCC based compilers. It is known to be not compatible with Microsoft Visual Studio.

Dependencies

Locally building and installing DuneCopasi requires a variety of dependencies:

development branches

Many of these dependencies are in a development branch (e.g., master) because DuneCopasi is also under developemt or because the package does not offer other tagged release.

Software	Version/Branch
CMake	>= 3.16
C++ compiler	>= C++20
pkg-config	>= 1.8.1
{fmt}	>= 9.1.0
spdlog	>= 1.10.0
libTIFF	>= 3.6.1
muParser (optional)	>= 2.2.5
SymEngine (optional)	>= 0.8.0
ExprTk (optional, automatic)	>= 0.0.2
METIS (optional)	>= 5.1.0
parafields-core (optional, automatic)	`master`
MPI (optional)	>= 3.1
FFTW (optional)	>= 3.0.0
TBB (optional)	>= 2018.12
GTest (optional, automatic)	>= 1.12.1
function2 (automatic)	>= 4.2.3
nlohmann::json (automatic)	>= 3.11.3
SuiteSparse	>= 2.3.3
Perfetto	>= 32.1
dune-common	`master`
dune-geometry	`master`
dune-grid	`master`
dune-uggrid	`master`
dune-istl	`master`
dune-localfunctions	`master`
dune-functions	`master`
dune-multidomaingrid	`master`
dune-typetree	`master`
dune-pdelab	`feature/dune-assembler/main-multithreaded`

automatic: The requirement is automatically fetched from the internet by CMake. See the CMake configuration options on how to enable/disable this feature.
optional: The software package is not mandatory (but recommended) to build DuneCopasi.

MPI and FFTW requirements

The MPI and FFTW packages are only to fulfill the requirements of parafields-core. If these packages are present if your system, CMake can resolve parafields-core automatically by setting the option DUNE_COPASI_DISABLE_FETCH_PACKAGE_parafields to OFF in CMake.

Install Generic Dependencies

Many of the generic dependencies can be directly obtained by package managers, e.g.,

Debian/Ubuntu (apt)
macOS/Linux (brew)

apt update
apt install \
  cmake \
  g++ \
  gcc \
  git \
  libmuparser-dev \
  libfftw3-dev \
  libfftw3-mpi-dev \
  libgtest-dev \
  libscotchmetis-dev \
  libspdlog-dev \
  libtbb-dev \
  libtiff-dev \
  mpi-default-bin \
  mpi-default-dev \
  pkg-config

brew update
brew install \
  cmake \
  fftw \
  fmt \
  gcc \
  git \
  libtiff \
  metis \
  muparser \
  open-mpi \
  pkg-config \
  scotch \
  spdlog \
  suite-sparse \
  symengine \
  tbb

Download DuneCopasi and DUNE dependencies

DUNE Version incompatibility

Notice that this procedure assumes that you don't have previous installation of DUNE in your system. If that's the case, uninstall DUNE before continuing, otherwise, version conflicts may be difficult if not impossible to resolve!

The required DUNE modules (including DuneCopasi) can be obtained via internet by using git. For smooth installation, is better place all the dune modules within the same directory:

# prepare a folder to download and build dune modules (e.g. ~/dune-modules)
mkdir ~/dune-modules && cd ~/dune-modules

~/dune-modules
# fetch dependencies & dune-copasi in ~/dune-modules folder
git clone https://gitlab.dune-project.org/core/dune-common
git clone https://gitlab.dune-project.org/core/dune-geometry
git clone https://gitlab.dune-project.org/core/dune-grid
git clone https://gitlab.dune-project.org/staging/dune-uggrid
git clone https://gitlab.dune-project.org/core/dune-istl
git clone https://gitlab.dune-project.org/core/dune-localfunctions
git clone https://gitlab.dune-project.org/staging/dune-functions
git clone https://gitlab.dune-project.org/extensions/dune-multidomaingrid
git clone https://gitlab.dune-project.org/staging/dune-typetree
git clone -b feature/dune-assembler/main-multithreaded https://gitlab.dune-project.org/pdelab/dune-pdelab
git clone https://gitlab.dune-project.org/copasi/dune-copasi

Dune Options File

An important part of the installation procedure is to tune the build system flags to accommodate the build options to your system: this is done via the dune options file. In essence, is just a bash script that sets different flags (mainly the flags for CMake CMAKE_FLAGS). While the dune project usually leaves this open for the user, we provide a dune-copasi.opts file with sensible default options for the main operating systems. You can find this file in the root directory of the dune-copasi repository.

This file can be executed to show the current configuration:

# choose root dune-copasi directory
cd ~/dune-modules/dune-copasi
# show current build configuration options
./dune-copasi.opts

Executing the configuration options will display something similar to this:

Current build configuration options

~/dune-modules/dune-copasi$ ./dune-copasi.opts
Installation Prefix:
/opt/dune
OS Type:
linux
CMake flags:
-DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS='-fvisibility=hidden -fpic' -DCMAKE_CXX_FLAGS_DEBUG='-O0 -g' -DCMAKE_CXX_FLAGS_RELEASE='-O3 -DNDEBUG' -DCMAKE_CXX_FLAGS_RELWITHDEBINFO='-O2 -g3 -DNDEBUG -fno-omit-frame-pointer' -DCMAKE_CXX_STANDARD=17 -DCMAKE_DISABLE_FIND_PACKAGE_MPI=OFF -DCMAKE_GENERATOR='Unix Makefiles' -DCMAKE_INSTALL_PREFIX=/opt/dune -DCMAKE_PREFIX_PATH='/opt/dune' -DDUNE_PDELAB_ENABLE_TRACING=ON
Make flags:

~/dune-modules/dune-copasi$

There are two forms to add flags to the dune-copasi.opts file:

Setting environmental variables starging with CMAKE_ and DUNE_. These variables will be automatically included into the list of cmake flags.

~/dune-modules/dune-copasi/
export CMAKE_INSTALL_PREFIX="/path/to/install/prefix/"
export CMAKE_GENERATOR="'Ninja'"
./dune-copasi.opts

Appending new flags into the CMAKE_FLAGS variable in the dune-copasi.opts file (care must be taken to scape quotes):

~/dune-modules/dune-copasi/
echo 'CMAKE_FLAGS+=" -DCMAKE_INSTALL_PREFIX=/path/to/install/prefix/"' >> dune-copasi.opts
echo "CMAKE_FLAGS+=\" -DCMAKE_GENERATOR='Ninja'\"" >> dune-copasi.opts
./dune-copasi.opts

For more information about the possible options and the dune options file, check out the dune installation documentation and its build system documentation.

CMake configuration options

The following is the list of options to customize the build of DuneCopasi.

`CACHE:TYPE=DEFAULT`	Description
`DUNE_COPASI_WITH_EXECUTABLE:BOOL=ON`	Build dune-copasi executable
`DUNE_COPASI_CONCURRENT_ASSEMBLY:BOOL=ON`	Build with concurrent assembly. Turn off to reduce memory consumption
`DUNE_COPASI_PRECOMPILED_MODE:BOOL=ON`	Pre-build a fixed set of class instances
`DUNE_COPASI_GRID_DIMENSIONS:STRING="2"`	Semi-colon separated list of dimensions to build
`DUNE_COPASI_${dim}D_DIFFUSION_REACTION_FEM_ORDERS:STRING="1"`	Semi-colon separated list of finite element order to compile for dimension `${dim}`
`DUNE_COPASI_DISABLE_FETCH_PACKAGE_ExprTk:BOOL=OFF`	Disable automatic fetch of ExprTk package
`DUNE_COPASI_DISABLE_FETCH_PACKAGE_parafields:BOOL=OFF`	Disable automatic fetch of parafields-core package
`DUNE_COPASI_DISABLE_FMT_STYLE:BOOL=OFF`	Disable {fmt} styling
`DUNE_PDELAB_ENABLE_TRACING:BOOL=ON`	Enable automatic fetch of perfetto

Build and Install

Before starting the build process, make sure to have your terminal in the directory with all DUNE modules:

# choose root dune modules directory
cd ~/dune-modules

The, build and install the all of the DUNE modules with the dunecontrol script from dune-common:

Memory usage

The building stage is known to take substantial memory during compilation (varies depending on the compiler). If your system fails to build due to insufficient memory, try serializing the build process with the -j {cores} flag and disabling some of the features.

~/dune-modules
# choose an installation path          (this is read by the 'dune-copasi.opts' file)
export CMAKE_INSTALL_PREFIX=/opt/dune

# uncomment if you have MPI and FFTW
# export DUNE_COPASI_DISABLE_FETCH_PACKAGE_parafields=OFF

# configure and build dune modules                              (go grab a coffee ☕)
./dune-common/bin/dunecontrol --opts=dune-copasi/dune-copasi.opts all

# (optional) build tests
./dune-common/bin/dunecontrol --opts=dune-copasi/dune-copasi.opts --module=dune-copasi cmake -t build_tests

# (optional) run unit, system and tutorial tests on built binaries
./dune-common/bin/dunecontrol --opts=dune-copasi/dune-copasi.opts --module=dune-copasi bexec ctest

# install libraries and binaries                                (may require sudo 🔒)
./dune-common/bin/dunecontrol --opts=dune-copasi/dune-copasi.opts bexec make install

# remove source and build files from working directory
cd ~ && rm -r ~/dune-modules

# include dune binaries into your path (if you use bash)
echo "export PATH=${CMAKE_INSTALL_PREFIX}/bin:\$PATH" >> $HOME/.bashrc

Active development cycle

An active development cycle does not need you to install the packages. Instead, you can run the program directly in the build directory (i.e., bin/dune-copasi). In that case, we recommend using --builddir option from dunecontrol in order to keep all the DUNE build directorties out of the source code.

For further information on dune module installation process, check out the dune-project web page.

Run the program

Once installed, the program dune-copasi will be available on the command line and be ready for CLI usage:

Command Line Interface of DuneCopasi

~$ dune-copasi --help
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.

...
~$

Configuration Options

For more information on the possible options to successfully run a simulation, make sure to visit the Command Line Interface, the Configuration Options, and the Tutorials documentations!

Dependencies​

Install Generic Dependencies​

Download DuneCopasi and DUNE dependencies​

Dune Options File​

CMake configuration options​

Build and Install​

Run the program​