Installing openCARP

The openCARP ecosystem comprises the openCARP simulator, carputils, meshtool, meshalyzer, LimpetGUI, carputilsGUI and a number of examples as detailed here.

In the next section, we provide instructions for installing openCARP, optionally with carputils and meshtool.

Additionally, you can install the openCARP visualization tools:

• meshalyzer
• LimpetGUI (Instructions available in the code repository)

How to install openCARP, carputils and meshtool

In this section, we provide instructions for installing the openCARP simulator, the carputils framework and meshtool.

Note for Windows users: On Windows 11, you can use openCARP via the Windows Subsystem for Linux (WSL), and follow the Linux installation instructions. Alternatively, you can use the openCARP Docker containers

If you do not wish to develop in openCARP, we advise you to install openCARP, carputils and meshtool together, using the Precompiled installation packages for Linux and macOS.

Alternatively, you can use one of the following installation methods:

• Building from sources
• Docker containers
• Spack package

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

Installation of openCARP using precompiled packages

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 have to run these commands before installing your python3-pip.

add-apt-repository universe
apt-get update

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

Linux

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

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

cd <path-to-your-downloaded-rpm-file>
dnf install ./opencarp-vXX.X.rpm

After installation, you can find the examples installed to /usr/local/lib/opencarp/share/examples. If you want to later run the examples, you should first copy them in your user space, for instance with:

cp -r /usr/local/lib/opencarp/share/examples ~/opencarp-examples

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 by running the command: export PATH=/usr/local/lib/opencarp/lib/petsc/bin:${PATH}.

To finish the installation, you should now set up carputils

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.

After installation, you can find the examples installed to /usr/local/lib/opencarp/share/examples. If you want to later run the examples, you should first copy them in your user space, for instance with:

cp -r /usr/local/lib/opencarp/share/examples ~/opencarp-examples

To finish the installation, you should now set up 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}

2. Set up carputils

If you want to use openCARP with carputils, you should also set up carputils. With the command install_carputils.sh, you can create a virtual environment containing carputils in the current directory:

install_carputils.sh

You can then activate this environment and start using carputils:

. ./venv_carputils/bin/activate

To check that carputils has been set up correctly, you can run the command cusummary, which will give you some information about the carputils settings.

You can deactivate carputils environment at any time with the command deactivate.

Note: carputils' environment will only be activated for your current session. In particular, it must be activated again if you want to use carputils in a new terminal window.

Note: alternative ways for installing carputils are available in the carputils installation section.

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

Alternative installation methods

Installation from Source

If you expect to change the openCARP source code, or want to use features that are not available within the precompiled packages, we suggest you follow the build instructions to install from source.

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 installation instructions for detailed instructions on how to install and use (docker/README.md) the openCARP docker containers.

Spack package

If you want to install openCARP on a High-Performance Computing system, you may want to install openCARP using Spack

Install openCARP visualization tools

In addition to openCARP, carputils and meshtool, we advise you to install the openCARP visualization tools Meshalyzer and LimpetGUI:

• Install Meshalyzer
• Install LimpetGUI (instructions available in the code repository)