Install From Source

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:

fixed commits

Many of these dependencies need to be installed from an specific git commit. Do not try to install DuneCopasi with unsupported commits!

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)	61b2893f4940e3bb5881bf32faee14524efb4184
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	1b79c9e4fe055ffa79e30b5b76989c4ebe30c606
dune-geometry	d45c81e18d940b4a0f755e64b9f3b67638508ada
dune-grid	70cd26d527b30ca2961e53b00f113f295f021f22
dune-uggrid	dec73a978754c6959dc9b8c34278979e9f6ba5bc
dune-istl	64f5f5184143f7a401b5e68a2ba76d9d3dd22570
dune-localfunctions	920cc8544401adde20b2fd6603a2050b810a4e31
dune-functions	664f68c63444ffd31537a57c5b12a6c40ed03da9
dune-multidomaingrid	7d04696469d62b36239d3d1101d9ac71ff247137
dune-typetree	962308509de2e67732afe5fe7e9c816ee16eec30
dune-pdelab	73f4c866b55f02c7b4bd0319bf304c5b01956bf3

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

Some of the dependencies can be obtained by package managers, e.g.,

Debian/Ubuntu (apt)

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

macOS/Linux (brew)

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

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.

This file can be executed to show the current configuration:

./dune-copasi.opts

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

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

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

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

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

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.

Build and Install

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
mkdir ~/dune-modules && cd ~/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 https://gitlab.dune-project.org/pdelab/dune-pdelab
git clone https://gitlab.dune-project.org/copasi/dune-copasi

# checkout commits necessary for DuneCopasi v2.0.0
git -C dune-common            checkout 1b79c9e4fe055ffa79e30b5b76989c4ebe30c606
git -C dune-geometry          checkout d45c81e18d940b4a0f755e64b9f3b67638508ada
git -C dune-grid              checkout 70cd26d527b30ca2961e53b00f113f295f021f22
git -C dune-uggrid            checkout dec73a978754c6959dc9b8c34278979e9f6ba5bc
git -C dune-istl              checkout 64f5f5184143f7a401b5e68a2ba76d9d3dd22570
git -C dune-localfunctions    checkout 920cc8544401adde20b2fd6603a2050b810a4e31
git -C dune-functions         checkout 664f68c63444ffd31537a57c5b12a6c40ed03da9
git -C dune-multidomaingrid   checkout 7d04696469d62b36239d3d1101d9ac71ff247137
git -C dune-typetree          checkout 962308509de2e67732afe5fe7e9c816ee16eec30
git -C dune-pdelab            checkout 73f4c866b55f02c7b4bd0319bf304c5b01956bf3

Then, build and install the DUNE modules with the dunecontrol script from dune-common:

# 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

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

# remove source and build files
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.

...
~$