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 pip. 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 these 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 and Debian, please download the .deb package.

Note: the packages of versions <= 9.0 are compatible with Ubuntu 18.04 and 20.04, and Debian 10. The packages of openCARP versions > 9.0 are compatible with Ubuntu 20.04 and 22.04, and Debian 11. If the latest .deb package is not compatible with your OS version, we invite you to use the AppImage 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-vXX.X.deb

with XX.X the version that you downloaded.

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-vXX.X.rpm

with XX.X the version that you downloaded.

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 don't work for you for some reason (no support of the operating system, no superuser permissions, etc.), please use the openCARP AppImage, which is a package for any recent enough Linux-based operating system. The documentation for using the AppImage is available inside the README.md file of the AppImage package or here.

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

macOS

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

Note: For versions of openCARP >11.0, please use the .pkg installer coresponding to the architecture of your computer: use the arm64 installer for an Apple Silicon computer, and the x86_64 installer for systems with an Intel chip. If you don't know which one to choose, click on the Apple logo on the top left of the screen, then click on "About This Mac". If your processor's name contains "Intel", then use the x86_64 installer ; if it contains "Apple", use the arm64 installer.

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.

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}

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: v10.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)"

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. To get started, go to the directory containing the tutorials:

cd /openCARP/examples

and head over to the examples section.

NOTE: You can share a directory between your host machine and the docker container by running the container with the following command:

docker run -it -v /path/in/your/machine:/path/in/container docker.opencarp.org/opencarp/opencarp

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

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.

Visualization

For visualization, please 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 (or equivalent if you don't use the bash shell).

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

To have a more stable environment, we recommend using the latest release version instead of the bleeding edge commit on the master branch:

git checkout latest

If you want to develop and push your changes back to the openCARP repository, then staying on a branch is the better option and you should skip the command above.

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

Building using CMake

Use CMake to create the _build build folder, optionally add -DDLOPEN=ON to enable ionic shared library loading, and -DCMAKE_BUILD_TYPE=Release to optimize compilation.

By default, the OpenMP parallelization is activated for igbutils and meshtool. This is equivalent to setting the option -DUSE_OPENMP=UTILS and requires that OpenMP is installed on your system. You can use -DUSE_OPENMP=ON to activate OpenMP parallelization globally. If you want to deactivate OpenMP parallelization completely, set -DUSE_OPENMP=OFF.

If you also want to build the additional tools (meshtool, carputils, and examples) locally, use in addition the option -DBUILD_EXTERNAL=ON:

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

If you do not want to install the additional tools, you can use:

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

Compile the codebase, and all built executables will be 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.

Please note that in this case, carputils was downloaded, but you will still have to set it up in order to be able to run the examples. Check the installation instructions for carputils in order to do so.

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

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

This section explains how to build carputils and install it using pip. This is recommended if you do not expect to develop carputils.

In the carputils directory, to install carputils in the Python user-space, run

python3 -m pip install . --user

If the Python user-space bin folder is not in your PATH, you should add this line to your .bashrc.

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

You can then generate the carputils settings file settings.yaml if it does not exist:

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

This file contains the carputils settings, including the paths to openCARP binary files. It contains default values adapted to your local setup, but can be modified manually.

Note: if the directory containing the openCARP binary files is not in your PATH (most likely if you compiled openCARP from sources), you will have to change the default value of CARP_EXE_DIR in the settings file. For example, if your openCARP executables are located at /home/openCARP/_build/bin, you will have to edit the file and set CARP_EXE_DIR to

CARP_EXE_DIR:
   CPU: /home/openCARP/_build/bin

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

Development Installation

Enter the carputils directory and follow the instructions to do a development installation of carputils.

Install the dependencies using pip - preferably into user-space:

python3 -m pip install --user -r requirements.txt

Add carputils/bin to your PATH, and carputils to your PYTHONPATH. For example, if carputils is located at $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 and a .zip file with a Windows executable.

AppImage (Linux)

  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

Windows

  1. Download the .zip file of the latest version
  2. Extract it into a folder
  3. Run meshalyzer.exe. To access the files on your drive C:\, use the path /cygdrive/c in meshalyzer's file browser.

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. freetype to render fonts.

  6. glut or glfw for Linux and Windows only.

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

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

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

  10. HDF5 if you want to optionally use HDF5 data containers

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. Edit make.conf, to set the following:

    1. If VTK is installed, 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, make sure that HAVE_RETINA is correct.

    3. If rendering is really slow and you have an AMD graphics card, uncomment AMD_VIDEO.

    4. To use glfw instead of glut, set GLUT_ON to 0.

    5. If you want to use the HDF5 data format, uncomment HDF5=1

  2. Type make -j

  3. For the windowless version, type make mesalyzer

  4. The compiled executables will be found in the directory.

  5. 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 freetype
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 \
    libfreetype6 \
    libfreetype-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 \
freetype \
freetype-devel \
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++
  • make
  • colorgcc
  • libgcc1
  • libfreetype
  • libfreetype-devel
  • libuuid1
  • libjpeg8
  • libjpeg-devel
  • libpng-devel
  • libglut3
  • libglut-devel
  • libGL-devel
  • libGL1
  • libGLU1
  • libGLU-devel
  • zlib
  • zlib-devel

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

To pre-select the packages during installation just run setup-x86_64.exe -P gcc-core gcc-g++ make libgcc1 colorgcc libuuid1 libjpeg8 libjpeg-devel libpng-devel libglut3 libglut-devel zlib zlib-devel libGL-devel libGL1 libGLU1 libGLU-devel from the Windows commandline.

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

If there is an error compiling fluid, change all ocurrences of_snprintf to snprintf in fluid/ExternalCodeEditor_WIN32.cxx

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

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