Installing openCARP

The openCARP ecosystem comprises the openCARP simulator, carputils, meshtool, meshalyzer, carputilsGUI and a number of examples as detailed here. Here, we provide instructions for:

How to install openCARP

In this section, we provide instructions for installing the openCARP simulator, the carputils framework and meshtool. If you do not wish to develop in openCARP, we advise you to install all three together, using one of the methods provided below:

If you don't know which method to choose, you can refer to the following decision tree.

openCARP installation decision tree

If you installed openCARP without carputils, you can also find the instructions for installing carputils alone.

Note for Windows users: you can try openCARP on Windows by using the Docker containers. If you use Windows 10 or Windows 11, you can also consider using the Windows Subsystem for Linux (WSL) and following the Linux installation instructions. An example of procedure for such an installation is detailed on this page.

Installation of Precompiled openCARP

Before installing openCARP, install Python3 and pip3. Using your package manager would be preferable for most users.

Make sure they work by running the following commands.

python3 --version
python3 -m pip --version

For Ubuntu users: you might require to run the commands before installing your python3-pip.

add-apt-repository universe
apt-get update

Installation Packages

We provide openCARP installation packages on our release page. Currently, they will install openCARP, carputils, meshtool, and the examples. Meshalyzer is not yet included, please install it separately.

After installation, you can find the examples installed to /usr/local/lib/opencarp/share/tutorials.

Linux

For Ubuntu (18.04 or 20.04) and Debian (10 or later), please download the .deb package. Installing the package can require to install the following packages as a prerequisite:

apt-get install git python3 python3-testresources python-is-python3

We recommand to install the package via apt-get like

cd <path-to-your-downloaded-deb-file>
apt-get update
apt-get install ./opencarp-v9.0.deb

For CentOS (8 or later) and Fedora (31 or later), please download the .rpm package.

We recommand to install the package via dnf like

cd <path-to-your-downloaded-rpm-file>
dnf install ./opencarp-v9.0.rpm

Note: If you are not using carputils, and want to run simulations with MPI using a command such as mpiexec -n 4 openCARP ..., you will in addition have to add the location of the MPI executables to your path: export PATH=/usr/local/lib/opencarp/lib/petsc/bin:${PATH}.

If the above packages doesn't work for you for some reasons (no support operating system, no superuser permissions, etc), please try the openCARP AppImage, which is a standalone file for any recent enough Linux-based operating system.

Make the .AppImage file executable and run it like

chmod +x openCARP-9.0-x86_64.AppImage
./openCARP-9.0-x86_64.AppImage

To run other openCARP binaries (bench, igbapd, igbdft, igbextract, igbhead, igbops, mesher, cellml_converter.py, limpet_fe.py, make_dynamic_model.py, make_dynamic_mode.sh), create a symbolic link with the corresponding name, take bench for example,

ln -s openCARP-9.0-x86_64.AppImage bench
./bench

The AppImage only supports openCARP binaries, so please check other components (carputils, meshtool, examples, and Meshalyzer) according to your needs.

macOS

Our current recommendation is to use Python 3.8 as some dependencies seem not to work well with Python 3.9.

For macOS (10.14 or later), please download the .pkg installer. Before running the installer, call xcode-select --install on the command line (Programs -> Utilities -> Terminal).

You may need to open the installer using the context menu (right click on the item and then select Open) to confirm the security warning.

Confirm the Installation

To confirm if the package is successfully installed, open a terminal and try the following commands.

Run openCARP binary as follows. If it prints the building information (e.g. GITtag: v9.0, etc), your openCARP is successfully installed. Enjoy the simulator!

openCARP -buildinfo

Run carputils in Python as follows. If it prints the installation location, your carputils is successfully installed. Enjoy Python coding!

python3 -c "import carputils; print(carputils)"

Note: If you are not using carputils, and want to run simulations with MPI using a command such as mpiexec -n 4 openCARP ..., you will in addition have to add the location of the MPI executables to your path: export PATH=/usr/local/lib/opencarp/lib/openmpi/bin:${PATH}

Docker

If you want to keep your host system clean but still be able to run and change openCARP, our Docker container might be most suitable for you. Docker containers should also run on Windows. See docker/INSTALL.md for detailed instructions on how to install and use (docker/README.md) the openCARP docker container.

Installation from Source

If you expect to change the openCARP source code, we suggest you follow the build instructions (docs/BUILD.md) to install from source.

Installation of openCARP Docker containers

First, install Docker for your platform.

There are 2 options for the openCARP installation using Docker.

  1. After the Docker installation use docker commands to pull and use the docker images.
  2. Alternatively, install using our script which will take care of all installation steps for you.

Pull the docker image (Option 1)

Pull the latest openCARP docker image:

docker pull docker.opencarp.org/opencarp/opencarp:latest

Run the docker image using the following terminal command:

docker run -it docker.opencarp.org/opencarp/opencarp:latest

You can now use openCARP. Head over to the experiments section to get started.

Install our docker script (Option 2)

Docker provides a variety of commands to utilize docker images:

docker --help

To help you quick start, our script wraps the most commonly used docker commands. Tell the install script where to place the binary files (should be a diretory in your $PATH). Use sudo if admin permission is required to write there:

cd <path-to-your-codebase>/openCARP/docker
./install_script.sh <path-to-your-bin>

For example, to install to /usr/local/bin, run:

sudo ./install_script.sh /usr/local/bin

The script enables you to start with the keyword opencarp-docker followed by the appropriate command.

Make sure the script is installed correctly:

opencarp-docker help

Pull the docker image:

opencarp-docker pull

For usage examples and more information, please refer to our docker/README.

For visualization, please also refer to installation of meshalyzer and locally install meshalyzer because it is not included in the Docker container.

Building from Source

After making sure the prerequisites are installed, you can build openCARP using CMake (recommended) or the shipped Makefile.

Prerequisites

First install the following openCARP prerequisites using your package manager (e.g. apt or rpm on Linux, homebrew or macports on macOS) or from source.

Building PETSc from source would be a better practice, so you could configure it depending on your needs. If you are not experienced with its various configurations, please refer to the following suggestions. Set --prefix= to the location you would install PETSc. After installation, set the environment variable PETSC_DIR and PETSC_ARCH accordingly.

./configure \
    --prefix=/opt/petsc \
    --download-mpich \
    --download-fblaslapack \
    --download-metis \
    --download-parmetis \
    --download-hypre \
    --with-debugging=0 \
    COPTFLAGS='-O2' \
    CXXOPTFLAGS='-O2' \
    FOPTFLAGS='-O2'
make all
make install

In this case, to make mpirun available on your machine, add $PETSC_DIR/bin to your PATH. That is, add the following line to your .bashrc.

export PATH=$PATH:$PETSC_DIR/bin

If you have all the listed dependencies, a quick way to get openCARP up and running is the following:

Clone the repository and enter the codebase folder openCARP

git clone https://git.opencarp.org/openCARP/openCARP.git
cd openCARP

We provide CMake files and Makefiles for building the codebase, choose one fits your workflow.

Building using CMake

Run CMake to create the _build build folder, optional add -DDLOPEN=ON to enable ionic shared library loading, and optional add -DCMAKE_BUILD_TYPE=Release to optimize compilation. You can also optionally add -DUSE_OPENMP=ON in order to activate OpenMP parallelization (requires that OpenMP is installed on your system).

cmake -S. -B_build -DDLOPEN=ON -DCMAKE_BUILD_TYPE=Release

Alternatively, if you would like to also build the additional tools (meshtool, carputils, and examples) locally, run:

cmake -S. -B_build -DDLOPEN=ON -DBUILD_EXTERNAL=ON -DCMAKE_BUILD_TYPE=Release

Compile the codebase, and all built executables are located in the _build/bin folder.

cmake --build _build

If you built the additional tools, meshtool executable is also located in the _build/bin folder, carputils and experiments (contain examples) are cloned to the external folder. Check carputils main page for its installation guide.

Building using the Makefile

The codebase can be compiled using

make setup

This target includes updating the codebase (make update) and code compilation (make all).

Make sure to edit the my_switches.def file to match you requirements (e.g., to enable the use of shared libraries for ionic models).

Links to all compiled executables are located in the bin folder.

Please also refer to the carputils main page, the meshtool main page. Download the openCARP examples to the location of your choice using git clone https://git.opencarp.org/openCARP/experiments.git.

Installation with Spack

Spack is a package manager for supercomputers, Linux and MacOS. It is designed to make the installation of scientific software easier.

Setting up Spack

To get Spack, clone its repository by entering the following commands in your terminal:

git clone https://github.com/spack/spack.git
cd spack

Then set up your environment by sourcing the Spack setup script:

. ./share/spack/setup-env.sh

If you are using another shell as bash/zsh/sh, please refer to the Spack documentation to get the appropriate command

Please also note that Spack has some minimum system requirements, which are assumed to be present on the machine where Spack is run.

You can now use the Spack commands.

Install the openCARP Spack package

In order to install openCARP with carputils and meshtool, you can use the following command in the shell:

spack install opencarp +carputils +meshtool

If the compilers you wish to use are loaded from a module (typical situation on clusters), it is likely that you have to do a modification in the Spack configuration in order to be able to install packages: open the file located at $HOME/.spack/linux/compilers.yaml (if you are on Linux) and add the name of the module in the modules field of your compiler. Example of a resulting file:

compilers:
- compiler:
    spec: gcc@10.2.0
    paths:
        cc: /opt/bwhpc/common/compiler/gnu/10.2.0/bin/gcc
        cxx: /opt/bwhpc/common/compiler/gnu/10.2.0/bin/g++
        f77: /opt/bwhpc/common/compiler/gnu/10.2.0/bin/gfortran
        fc: /opt/bwhpc/common/compiler/gnu/10.2.0/bin/gfortran
    flags:  {}
    operating_system: rhel8
    target: x86_64
    modules: [compiler/gnu/10.2]

Using openCARP

Once openCARP is installed, you can load it as it would be done for a module:

spack load opencarp

openCARP is now installed and ready to be used.

Using external packages with Spack

By default, Spack installs all the openCARP dependencies, even if some of them are already installed on the user's system. In order to use external packages in Spack, you can use one of two ways:

  1. Rely on the spack external command, e.g., spack external find cmake. If cmake is found, it will be added to the list of external packages that can be used by Spack.
  2. Modify ~/.spack/packages.yaml or $SPACK/etc/spack/packages.yaml as in the following example: 
    packages:
openmpi:
externals:
- spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64"
  prefix: /opt/openmpi-1.4.3
- spec: "openmpi@1.4.3%gcc@4.4.7 arch=linux-debian7-x86_64+debug"
  prefix: /opt/openmpi-1.4.3-debug
cmake:
externals:
- spec: cmake@3.7.2
  modules:
  - CMake/3.7.2
buildable: False

For more information about Spack, see the documentation.

Installing carputils separately

Docker

A quick way to get started is pulling the openCARP docker image.

Linux / macOS

To locally run carputils, first install Python3, pip, and openCARP.

carputils has already been included to openCARP/external/carputils if you installed openCARP with additional tools. Otherwise, clone the carputils repository and enter the codebase folder carputils.

git clone https://git.opencarp.org/openCARP/carputils.git
cd carputils

Installation

Build the carputils and install it. This is recommended if you do not expect to develop the carputils.

python3 -m pip install --only-binary=:all . --user

In this case, the python user-space bin folder should be included to your PATH, add the line to your .bashrc.

export PATH="$PATH:`python3 -m site --user-base`/bin"

Generating the settings.yaml file if you could not find one.

python3 ./bin/cusettings $HOME/.config/carputils/settings.yaml

On the other hand, if you plan to develop carputils, manually configuring it as follows is recommended.

Development Installation

Install the required python packages using pip - preferably into user-space:

python3 -m pip install --only-binary=:all --user -r requirements.txt

Add carputils/bin to your PATH, and carputils to your PYTHONPATH. For example, if you clone carputils to $HOME/openCARP/external, add the following lines in your .bashrc:

export PATH=$PATH:$HOME/openCARP/external/carputils/bin
export PYTHONPATH=$PYTHONPATH:$HOME/openCARP/external/carputils

Create a settings.yaml file, which is a summary of paths and (default) parameters associated with your installation. To generate a default file, run the following command in the root folder of your carputils installation:

python3 ./bin/cusettings $HOME/.config/carputils/settings.yaml

Open the file and specify the proper directories for openCARP binary files. Notice using the 2 or 4 characters indentation before the keyword CPU.

CARP_EXE_DIR:
    CPU: $HOME/install/openCARP/bin

Set directories for other openCARP tools if you use them. For example,

MESHALYZER_DIR:     $HOME/install/meshalyzer

Compiling C extensions and auto-generate code

To compile the C extensions for reading and writing meshes, just call

make

in the root folder of your carputils installation. If carputils is not installed under openCARP/external/carputils, you will also have to provide the path to the openCARP sources root folder:

make OPENCARP_PATH=/path/to/openCARPsources

If you need to use a non-default compiler (e.g. under macOS for OpenMP support), provide it as a variable

CC=clang make

A plain make will also auto-generate the model.ionic, model.activetension and model.mechanics python modules. They can be re-generated manually by calling

make models

Troubleshooting

The installation of some dependencies of carputils can fail if pip and setuptools are not up-to-date. They can be upgraded with the following commands:

python3 -m pip install --upgrade pip
python3 -m pip install --upgrade setuptools

Installation of meshalyzer

Meshalyzer is regularly used on Linux and Mac machines, and runs under Windows as well.

Binary packages

We provide binary packages on the release page. Currently, it includes AppImage, which works on any recent enough Linux-based operating system.

  1. Download the .AppImage file of the latest version
  2. Make it executable, for example, chmod +x Meshalyzer-3.2-x86_64.AppImage
  3. Run it ./Meshalyzer-3.2-x86_64.AppImage

If you want to build meshalyzer yourself, please check the following sections.

Prerequisities

  1. libpng

  2. libjpeg

  3. OpenMP is recommended to improve certain operations. For all compilers, except clang supplied by Apple, it is standard. A simple way to include it on Apple machines is with homebrew: brew install libomp

  4. FLTK 1.3.x or higher.

  5. glut or glfw for Linux and Windows only.

  6. cmake version 3.12 or higher, if you want to make compiling easier.

  7. To make the "windowless" rendering version, OSMesa

  8. To read in VTK/VTU format meshes, install VTK development files

Using your package manager is recommended for installing these packages if possible. On MacOS, homebrew works for us.

Compiling

Clone the repository and enter the codebase folder meshalyzer.

git clone https://git.opencarp.org/openCARP/meshalyzer.git
cd meshalyzer

We recommend to always use the latest release version as the master branch is continuously under development and might not be as robust as the releases: git describe --tags --abbrev=0 returns the latest release version (e.g. '2.2'). Then you can check out this version: git checkout 2.2.

We provide Makefiles and CMake files for compiling the code, choose the one that fits your workflow.

Makefile

  1. If VTK is installed, edit the make.conf to set the VTK_INC and VTK_DIR variables to point to the directories containing the VTK header files and libraries, respectively. Comment them out otherwise.
  2. If you have an Apple machine, edit make.conf to make sure that HAVE_RETINA is correct.
  3. If rendering is really slow and you have an AMD graphics card, you may have to edit make.conf to uncomment AMD_VIDEO.
  4. In make.conf, to use glfw instead of glut, set GLUT_ON to 0.
  5. Type make -j
  6. For the windowless version, type make mesalyzer
  7. The compiled executables will be found in the directory.
  8. Copy the binaries to a suitable location

CMake

  1. We suggest to run CMake by out-of-source builds, which means all the compiled code goes into a _build directory separate from the source code.

  2. If VTK is installed, type cmake -S. -B_build. Otherwise type cmake -S. -B_build -DUSE_VTK=OFF

  3. Compile the code via cmake --build _build

  4. In the main meshalyzer directory, you will find a link to the compiled executalbe.

ccmake

For those who are familiar with ccmake:

  1. ccmake .

  2. configure, edit and generate

  3. make -j

Documentation

To compile the manual (LaTeX required)

  1. cd manual
  2. pdflatex manual
  3. pdflatex manual

MacOS

First of all, the command line tools or Xcode must be installed. Next, install the prerequisities using your package manager. We use homebrew as an example.

brew install libpng
brew install fltk
brew install git
brew install cmake

Follow the steps in the Compiling to build the code.

Linux

For installing meshalyzer first you need to install the "Prerequisites" using your package manager (e.g. apt, yum, or dnf). The Dockerfile provides an installation example based on CentOS7.

Ubuntu

On Ubuntu (tested with Ubuntu 20.04), you can use:

apt-get update && apt-get install -y \
    build-essential \
    git \
    ca-certificates \
    fluid \
    freeglut3-dev \
    libfltk1.3-dev \
    libglu1-mesa-dev \
    libpng-dev \
    libjpeg-dev \
    cmake

Follow the steps in Compiling to build the code.

CentOS

On CentOS (tested with CentOS 7), you can use:

yum update && yum install git \
gcc gcc-c++ \
libpng-devel \
libjpeg-devel \
fltk-devel \
fltk-fluid \
freeglut-devel

If you want to compile meshalyzer with cmake, you will also need cmake version 3.12 or higher. You can know which version is provided by the package manager with the command:

yum info cmake

If the version is higher than 3.12, then use:

yum install cmake

Otherwise you can get cmake3 from EPEL. On CentOS 7, you can use:

yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
yum install cmake3

Please note that you will then have to use the cmake3 command instead of the cmake command to compile meshalyzer.

You can now follow the steps in Compiling to build the code.

Windows

meshalyzer can be compiled to use the native windowing system under Cygwin.

Cygwin

First, install Cygwin and include the gcc compiler suite along with it. You will need to install at least the following packages:

  • gcc-core
  • gcc-g++
  • libgcc1
  • colorgcc
  • libuuid1
  • libjpeg8
  • libjpeg-devel
  • libpng12
  • libpng12-devel
  • libglut3
  • libglut-devel

Make sure libuuid-devel is NOT installed. Remove it if need be and be warned, it can be persistent.

FLTK

Do NOT use the Cygwin FLTK package. Download the source, and then open a Cygwin terminal. Unpack the source, cd to the top-level FLTK directory and execute

./configure --enable-cygwin
make -j
make install

To compile meshalyzer, unpack it, cd to the top-level source directory and

make -j

Post-compilation

You can execute meshalyzer by typing ./meshalyzer

See README.md for an example.

To make meshalyzer available from anywhere on your machine, you need to copy it to your bin directory, or add the meshalyzer directory to PATH by editing your .bashrc (or .bash_profile). Using the nano editor as an example, type the following command into the terminal:

nano ~/.bashrc

This will open an editor, scroll all the way down and add the following line, replacing '/home/somefolder/anotherfolder/meshalyzer' with the path of your meshalyzer folder:

export PATH=$PATH:/home/somefolder/anotherfolder/meshalyzer

press Control+X, then type Y and Enter to save the changes. Close all terminal instances!

open a terminal and type meshalyzer

© Copyright 2020 openCARP project    Supported by DFG and EuroHPC    Contact    Imprint and data protection