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.

Some of the dependencies can be 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

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:

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

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 -b feature/dune-assembler/main-multithreaded https://gitlab.dune-project.org/pdelab/dune-pdelab
git clone https://gitlab.dune-project.org/copasi/dune-copasi

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.

...
~$

Dependencies​

Dune Options File​

CMake configuration options​

Build and Install​

Run the program​

Dependencies

Dune Options File

CMake configuration options

Build and Install

Run the program