Requirements

The following section describes the dependency requirements of building CSXCAD and openEMS on many systems. It’s used for both the semi-automatic and manual installation, as described in Clone, Build and Install, Manual C++ Build and Install. and Manual Documentation Build respectively. The former is recommended for general use, while the latter is recommended for development, troubleshooting, or usage on non-standard systems.

Tip

The following instructions are working at the time of writing, but it can become outdated. If you have difficulties building the project from source, refer to these official CI/CD test scripts in the source code. They contain all commands necessary for building openEMS on 10+ different systems.

Hardware Requirements

All CPU architectures are supported on Unix-like operating systems, such as ARM, POWER, x86_64, RISC-V. In addition, x86 and x86_64 CPUs are supported on Windows via MSVC.

In the past, a “supported CPU check” was used , but it has been removed. There’s no hardcoded “CPU checks” to artificially limit the project to a particular CPU.

The main simulation engine is known as the SSE engine, but it’s misnomer. The SSE engine uses GCC’s vector extension with 64-bit vectors, which compiles to SSE on x86 CPUs, AltiVec on IBM POWER, NEON on ARM, and scalar code on a generic CPU with vectorization disabled.

Tip

64-bit CPUs and operating systems are not required, but strongly recommended. 32-bit systems impose severe limitations on the simulation problem size.
If you have a CPU-specific build failure (such as RISC-V), it’s considered a bug. Please report the problem to the project’s bug tracker.

Minimum Dependency Versions

The following list shows the minimum dependency versions supported by openEMS

CMake 3.0
GCC 4.8
Boost 1.55
VTK 6.0
CGAL 4.0
- CGAL 4.14.3 is the last version supported by GCC 4.8.
Qt 4
- VTK’s Qt must be linked to the same Qt version as QCSXCAD/AppCSXCAD.

Install From Package Manager

Alpine

openEMS depends on the following packages for minimum functionality:

doas apk add bash \
             build-base gmp-dev mpfr-dev git cmake \
             boost-dev tinyxml-dev hdf5-dev cgal-dev vtk-dev

AppCSXCAD is used to visualize 3D models (recommended, but optional):
```
# To build a custom VTK, first remove the system package's
# development files
doas apk del vtk-dev

# Install VTK build-time dependencies, prepare to build it from source!
doas apk add qt6-qtbase-dev qt6-qtdeclarative-dev qt6-qtdeclarative-private-dev \
             qt6-qt5compat-dev
```
Warning

VTK with Qt does not exist on Alpine, installing it via the package manager is not possible. If you’re using Alpine, please report a bug to Alpine developers. After installing the build-time dependencies above, use the workaround below: Build From Source. Alternatively, disable the GUI while building openEMS with ./update_openEMS.sh --disable-GUI.
To use Octave scripting (recommended):
```
doas apk add octave
```
To use Python scripting (recommended):
```
doas apk add python3-dev py3-pip
```
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
doas apk add py3-setuptools py3-setuptools_scm cython \
             py3-numpy py3-h5py py3-matplotlib
```
To use ParaView to visualize simulation results (recommended):

Warning

ParaView does not exist on Alpine, installing it via the package manager is not possible. If you’re using Alpine, please open a feature request to Alpine developers. In the meantime, you can download a pre-compiled binary version of ParaView as a tarball at the official website: https://www.paraview.org/download/.
Skip to Clone, Build and Install and continue installation.

AlmaLinux

openEMS requires additional packages not included in the standard repository, which can be enabled by the following command:

sudo dnf install -y epel-release

# use "crb" for AlmaLinux 8 and later, use "powertools" for AlmaLinux 7
sudo dnf config-manager --set-enabled crb
sudo dnf config-manager --set-enabled powertools

openEMS depends on the following packages for minimum functionality:

# install git first to avoid dependency graph conflicts
sudo dnf install git

sudo dnf install git gcc gcc-c++ cmake \
                 boost-devel tinyxml-devel hdf5-devel vtk-devel CGAL-devel

To use AppCSXCAD to visualize 3D models (recommended):
```
sudo dnf install vtk-qt
```
To use Octave scripting (recommended):
```
sudo dnf install octave
```
To use Python scripting (recommended):
```
sudo dnf install python3-pip
```
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
sudo dnf install python3-setuptools python3-setuptools_scm \
                 python3-Cython python3-numpy python3-h5py \
                 python3-matplotlib
```
To use ParaView to visualize simulation results (recommended):
```
sudo dnf install paraview
```
Skip to Clone, Build and Install and continue installation.

CentOS 7

openEMS continues to support legacy systems when it’s practical, including CentOS 7, but additional steps are required.

CentOS repos are EOL and desupported. For a fresh installation, the following steps are required to bring the package manager back into a functional state:

Warning

CentOS 7 no longer receives security updates. Use at your own risk.
```
# change all mentions of mirror.centos.org to vault.centos.org
sed -i 's|^mirrorlist|#mirrorlist|g; s|^#baseurl|baseurl|g; s|mirror.centos.org|vault.centos.org|g' \
    /etc/yum.repos.d/CentOS-Base.repo
```

openEMS requires additional packages not included in the standard repository, which can be enabled by the following command:

yum install centos-release-scl

# change all mentions of mirror.centos.org to vault.centos.org
sed -i 's|^mirrorlist|#mirrorlist|g; s|^#baseurl|baseurl|g;
        s|^# baseurl|baseurl|g; s|mirror.centos.org|vault.centos.org|g' \
    /etc/yum.repos.d/CentOS-SCLo-scl.repo \
    /etc/yum.repos.d/CentOS-SCLo-scl-rh.repo

yum install epel-release

openEMS depends on the following packages for minimum functionality:

# install git first to avoid dependency graph conflicts
yum install git

yum install gcc gcc-c++ gmp-devel mpfr-devel \
            git tinyxml-devel hdf5-devel

CentOS 7 has CMake 2 by default, but we require CMake 3:

# use cmake3 instead of default cmake2
yum install cmake3
alternatives --install /usr/local/bin/cmake cmake /usr/bin/cmake3 99

boost-predef is only available on Boost 1.55 and later. Without it, the error “fatal error: boost/predef.h: No such file or directory” occurs. We can build the latest version of Boost from source. But as CentOS 7 is already a frozen platform, we can try some non-standard tricks here and get away from it. Here, we borrow a copy of Boost 1.58 from rh repo’s mariadb backport package.
```
yum install -y rh-mariadb101-boost-devel

# copy it into /usr/local, so it can be found in the standard system
# search path
ln -s /opt/rh/rh-mariadb101/root/usr/include/boost /usr/local/include/boost
mkdir /usr/local/lib64 && cd /usr/local/lib64
for i in /opt/rh/rh-mariadb101/root/usr/lib64/libboost*; do
    ln -s $i /usr/local/lib64/
done
```
CentOS 7 uses GCC 4.8, which has only partial C++11 support, but it’s currently sufficient to build CSXCAD or openEMS.

Warning

Manual -std= options are no longer needed in CXXFLAGS. Before building CSXCAD or openEMS, one should remove all -std= options from CXXFLAGS. This flag is now managed by CMake. See Remove C++11 from CXXFLAGS for details.
Install CGAL:

Important

CGAL v4.14.3 must be built from source, see Build From Source.
To use AppCSXCAD to visualize 3D models (recommended):
```
yum install vtk-qt
```
To use Octave scripting (recommended):
```
yum install octave
```
To use Python scripting (recommended):
```
yum install python3-devel python3-pip
```
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies manually:
```
yum install python3-Cython

# system packages are incompatible, must be manually
# installed via pip
pip3 install numpy h5py matplotlib --user
```
Skip to Clone, Build and Install and continue installation.

Debian/Ubuntu

openEMS depends on the following packages for minimum functionality:

sudo apt-get install build-essential cmake git libhdf5-dev libvtk9-dev \
                     libboost-all-dev libcgal-dev libtinyxml-dev

To use AppCSXCAD to visualize 3D models (recommended):
```
sudo apt-get install qtbase5-dev libvtk9-qt-dev
```

To use Octave scripting (recommended):

sudo apt-get install octave liboctave-dev

To use Python scripting (recommended):

sudo apt-get install python3-pip python3-venv

By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
sudo apt-get install python3-setuptools python3-setuptools-scm \
                     python3-numpy python3-matplotlib python3-h5py
```
To use ParaView to visualize simulation results (recommended):
```
sudo apt-get install paraview
```

For the package hyp2mat you need additional dependencies (optional):

sudo apt-get install gengetopt help2man groff pod2pdf bison flex \
                     libhpdf-dev libtool

Skip to Clone, Build and Install and continue installation.

Legacy Debian/Ubuntu

openEMS continues to support legacy systems when it’s practical, including Debian oldoldstable and Ubuntu 14.04. These additional steps are required.

Debian/Ubuntu

Instead of libvtk9-dev, on earlier versions of Debian/Ubuntu, you need to choose an older version of vtk. Both libvtk7-dev and libvtk6-dev are still supported.

# you can use VTK9
sudo apt-get install libvtk9-dev libvtk9-qt-dev

# or VTK7
sudo apt-get install libvtk7-dev libvtk7-qt-dev

# or VTK6
# note: libvtk6-qt-dev is not used on Ubuntu 14.04, only libvtk6-dev is required
sudo apt-get install libvtk6-dev

Ubuntu 14.04 only

Ubuntu 14.04 has CMake 2 by default, but we require CMake 3:
```
sudo apt-get install cmake3
```
Ubuntu 14.04 ships Boost 1.54 and is required by libcgal-dev, but we need Boost 1.55, so we install Boost 1.55 first, then install CGAL from source.
```
sudo apt-get install boost1.55 boost1.55-dev
```
Ubuntu 14.04 uses GCC 4.8, which has only partial C++11 support, but it’s currently sufficient to build CSXCAD or openEMS.

Warning

Manual -std= options are no longer needed in CXXFLAGS. Before building CSXCAD or openEMS, one should remove all -std= options from CXXFLAGS. This flag is now managed by CMake. See Remove C++11 from CXXFLAGS for details.
Install CGAL:

Important

CGAL v4.14.3 must be built from source, see Build From Source.
Ubuntu 14.04’s Python packages are ancient. Python 3.4 frequently encounters SyntaxError. For a minimum viable setup, suggested to install Python 3.5 from apt-get, and installing other packages via pip into an isolated virtual environment (venv) instead. Here, we use $HOME/opt/openEMS as an example. This directory must match the directory later used to install openEMS.
```
apt-get install -y curl python3.5-dev

# create an isolated virtual environment, without pip
# (because Python 3.5 pip is broken on Ubuntu 14.04)
python3.5 -m venv $HOME/opt/openEMS --without-pip

# activate the venv, and manually bootstrap pip ourselves
curl -O https://bootstrap.pypa.io/pip/3.5/get-pip.py
source ~/venv/bin/activate
python3.5 get-pip.py
```
Warning

Python 3.5 is not fully supported, use at your own risk. This setup is intended for testing purposes. From limited testing, one can run a trivial openEMS script, but SyntaxError may still be encountered in some APIs. If possible, it’s strongly recommended to install a custom Python interpreter, either from a third-party repository (PPA), or building from source.

Fedora

openEMS depends on the following packages for minimum functionality:

sudo dnf install gcc gcc-c++ cmake git \
                 boost-devel tinyxml-devel vtk-devel hdf5-devel \
                 CGAL-devel

To use AppCSXCAD to visualize 3D models (recommended):
```
sudo dnf install vtk-qt
```
To use Octave scripting (recommended):
```
sudo dnf install octave
```
To use Python scripting (recommended):
```
sudo dnf install python3-pip
```
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
sudo dnf install python3-setuptools python3-setuptools_scm \
                 python3-Cython python3-numpy python3-h5py python3-matplotlib
```
To use ParaView to visualize simulation results (recommended):
```
sudo dnf install paraview
```

For the package hyp2mat you need additional dependencies (optional):

sudo dnf install gengetopt help2man groff perl-pod2pdf bison flex \
                 libharu-devel

Skip to Clone, Build and Install and continue installation.

Void Linux

openEMS depends on the following packages for minimum functionality:

sudo xbps-install -S base-devel cmake git hdf5-devel boost-devel \
                     cgal-devel tinyxml-devel vtk-devel

To use AppCSXCAD to visualize 3D models (recommended, but optional):
```
# To build a custom VTK, first remove the system package's
# development files
sudo xkps-remove vtk-dev

# Install VTK build-time dependencies, prepare to build it from source!
sudo xbps-install -S qt6-base-devel qt6-declarative-devel qt6-qt5compat-devel
```
Warning

VTK with Qt does not exist on Void Linux, installing it via the package manager is not possible. If you’re using Void Linux, please report a bug to Void Linux developers. After installing the build-time dependencies above, use the workaround below: Build From Source. Alternatively, disable the GUI while building openEMS with ./update_openEMS.sh --disable-GUI.
To use Octave scripting (recommended):
```
sudo xbps-install -S octave
```

To use Python scripting (recommended):

sudo xbps-install -S python3 python3-pip

By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
sudo xbps-install -S python3-setuptools python3-setuptools_scm \
                     python3-Cython python3-matplotlib python3-h5py
```
To use ParaView to visualize simulation results (recommended):

Warning

ParaView does not exist on Void Linux, installing it via the package manager is not possible. If you’re using Void Linux, please open a feature request to Void Linux developers. In the meantime, you can download a pre-compiled binary version of ParaView as a tarball at the official website: https://www.paraview.org/download/.
Skip to Clone, Build and Install and continue installation.

FreeBSD

openEMS can be installed directly via FreeBSD Ports. For first-time users who are just getting started, there’s no need to install dependencies manually. Please skip to Install Ready-Made Package on FreeBSD for more information.

However, the FreeBSD package may not be up-to-date and can contain known problems. Often it’s necessary to build your own development version, if so, follow this guide.

openEMS depends on the following packages for minimum functionality:

sudo pkg install bash cmake git boost-libs tinyxml \
                 vtk9 hdf5 cgal

To use AppCSXCAD to visualize 3D models (recommended):
```
sudo pkg install qt5
```
For Octave scripting (recommended):
```
sudo pkg install octave
```
For Python scripting (recommended):
```
sudo pkg install python3

# DO NOT copy and paste this command, pause and check,
# see the note below.
sudo pkg install py311-pip
```
Important

After installing python3, check the default Python version on your FreeBSD system python3 --version. If a newer Python is used on FreeBSD, replace the py311 package prefix with your Python version, such as py314-pip.
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
sudo pkg install py311-setuptools py311-wheel py311-setuptools-scm \
                 py311-cython3 py311-numpy py311-h5py py311-matplotlib
```
To use ParaView to visualize simulation results (recommended):
```
sudo pkg install paraview
```
Skip to Clone, Build and Install and continue installation.

macOS

Warning

In the past, a Homebrew formula for macOS was provided. However, at the time of writing, the formula is broken and unmaintained, manual installation is required!

openEMS depends on the following packages for minimum functionality:
```
brew install cmake boost hdf5 cgal vtk
```
openEMS also depends on TinyXML, which is unmaintained since 2011 and has been removed from Homebrew (TinyXML2 is not API-compatible). As a workaround, update_openEMS.sh will automatically download TinyXML and patches online, building it from source. It’s even possible to do so on a system without network access, explained later in the next section.

For packagers, sysadmins and developers who needs to understand inner working of the custom TinyXML build, technical information is available in Manual C++ Build and Install. For regular users, no manual intervention is needed anymore.
To use ParaView to visualize simulation results (recommended):
```
brew install paraview
```
To use Octave scripting (recommended):
```
brew install octave
```
To use Python scripting (recommended):
```
brew install python3
```
By default, one doesn’t need to install other Python packages here. The update_openEMS.sh script installs them automatically via pip into an isolated virtual environment (venv). However, if one wants to manage Python dependencies externally outside pip, use the system’s package manager (optional):
```
brew install python-setuptools cython numpy python-matplotlib
```
To use ParaView to visualize simulation results (recommended):
```
brew install paraview
```
Skip to Clone, Build and Install and continue installation.

Windows

openEMS can be installed directly as a pre-built binary package, there is no need to install dependencies (or build openEMS from source) manually. Please skip to Install Ready-Made Package on Windows for more information.

The follow instructions are given for developers only, one should follow these instructions only if a manual install is needed during development.

One can build openEMS on Windows using two different methods. The first method is using MSVC, this is how the official pre-built package is prepared, but it has a long and complicated procedure, and is currently undocumented.

Alternatively, MinGW-w64 and MSYS2 can be used.

Build From Source

Important

The following examples install third-party packages to a custom user directory $HOME/opt/openEMS. If you use this directory, CSXCAD and openEMS must also be installed to the same location, for example:

./update_openEMS.sh ~/opt/openEMS

VTK with Qt

Important

For Alpine and Void Linux only.
AppCSXCAD can always be disabled via ./update_openEMS.sh --disable-GUI, making the following step optional if visualization is not needed.

Alpine and Void Linux doesn’t provide Qt support for VTK applications. If one want to use AppCSXCAD for visualization, building a custom VTK version from source is required.

git clone https://gitlab.kitware.com/vtk/vtk.git --depth=1
cd vtk && mkdir build && cd build
cmake ../ -DCMAKE_BUILD_TYPE=Release -DVTK_GROUP_ENABLE_Qt=YES -DVTK_QT_VERSION=6 \
         -DCMAKE_INSTALL_PREFIX=$HOME/opt/openEMS
make -j$(nproc)
make install

CGAL v4.14.3

Important

For Ubuntu 14.04 and CentOS 7 only.

On legacy systems such as Ubuntu 14.04 and CentOS 7, CGAL relies on an obsolete Boost version which is in conflict with openEMS’s requirements. To use openEMS, CGAL must be built from source.

git clone https://github.com/CGAL/cgal.git --depth=1 --branch=v4.14.3
cd cgal && mkdir build && cd build

cmake ../ -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=$HOME/opt/openEMS
make && make install

CGAL v4.14.3 is the last version compatible with GCC 4.8. In newer CGAL versions, the following errors occur: The compiler feature "cxx_decltype_auto" is not known to CXX compiler "GNU" version 4.8.5.