Installing carputils

To locally run carputils on Linux or macOS, first install Python3, pip, and openCARP.

Standard installation

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

In order to avoid conflicts in Python dependencies, we recommend to install carputils within a virtual environment. A virtual environment can be created in the current directory with the following command:

python3 -m venv carputils_env

This environment should then be activated each time you want to use carputils with:

. ./carputils_env/bin/activate

Once the environment is activated, install carputils with pip:

python -m pip install <PATH_TO_CARPUTILS>

where <PATH_TO_CARPUTILS> should be replaced with the path to carputils:

• if you have installed openCARP using the precompiled packages, replace it with /usr/local/lib/opencarp/share/carputils
• if you have built openCARP with external tools using CMake, then carputils is available in your_openCARP_folder/external/carputils (replace your_openCARP_folder with the location of the openCARP codebase on your system)
• if you don't have carputils locally or want to get the most recent version, replace it with git+https://git.opencarp.org/openCARP/carputils.git

Note: Some carputils scripts require specific dependencies that are not needed in standard workflows, and are not installed by default. You can install carputils with these optional dependencies using python -m pip install "<PATH_TO_CARPUTILS>[full]"

You can now generate the carputils settings file settings.yaml:

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

You can now start using carputils.

Alternative: development installation

If you wish to develop in carputils, we advise you to use the development installation. carputils will be install in such a way that the project appears to be installed, but yet is still editable from its source directory.

First, download carputils:

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

We advise you to create a virtual environment for your carputils installation:

python3 -m venv carputils_env

This environment should then be activated each time you want to use carputils with:

. ./carputils_env/bin/activate

Then install carputils in development mode with:

pip install -e .

You can now generate the carputils settings file settings.yaml:

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.

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