The openCARP ecosystem comprises the openCARP simulator, carputils, meshtool, meshalyzer, carputilsGUI and a number of examples as detailed here. Here, we provide instructions for:
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.
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.
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
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
.
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.
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.
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}
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.
If you expect to change the openCARP source code, we suggest you follow the build instructions (docs/BUILD.md) to install from source.
First, install Docker for your platform.
There are 2 options for the openCARP installation using Docker.
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.
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.
After making sure the prerequisites are installed, you can build openCARP using CMake (recommended) or the shipped Makefile.
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.
igbdft
)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.
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.
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
.
Spack is a package manager for supercomputers, Linux and MacOS. It is designed to make the installation of scientific software easier.
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.
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]
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.
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:
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.~/.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.
A quick way to get started is pulling the openCARP docker image.
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
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.
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
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
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
Meshalyzer is regularly used on Linux and Mac machines, and runs under Windows as well.
We provide binary packages on the release page.
Currently, it includes AppImage
, which works on any recent enough Linux-based operating system.
.AppImage
file of the latest versionchmod +x Meshalyzer-3.2-x86_64.AppImage
./Meshalyzer-3.2-x86_64.AppImage
If you want to build meshalyzer yourself, please check the following sections.
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
FLTK 1.3.x or higher.
cmake version 3.12 or higher, if you want to make compiling easier.
To make the "windowless" rendering version, OSMesa
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.
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.
VTK_INC
and VTK_DIR
variables to point to the directories containing the VTK header files and libraries, respectively. Comment them out otherwise.make -j
make mesalyzer
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.
If VTK is installed, type cmake -S. -B_build
. Otherwise type cmake -S. -B_build -DUSE_VTK=OFF
Compile the code via cmake --build _build
In the main meshalyzer directory, you will find a link to the compiled executalbe.
For those who are familiar with ccmake:
ccmake .
configure, edit and generate
make -j
To compile the manual (LaTeX required)
cd manual
pdflatex manual
pdflatex manual
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.
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.
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.
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.
meshalyzer
can be compiled to use the native windowing system under Cygwin.
First, install Cygwin and include the gcc compiler suite along with it. You will need to install at least the following packages:
Make sure libuuid-devel is NOT installed. Remove it if need be and be warned, it can be persistent.
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
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