Installing OpenEMS on Linux

Guide to installing and using OpenEMS FDTD simulator on Ubuntu with Docker
(Updated: )
Categories:
Tags:

Post Source Files

OpenEMS is an open-source Finite-Difference Time-Domain (FDTD) simulator that has seen some significant adoption. As I go through the setup for the second time, I’m noting down all the steps, common pitfalls, and useful resources to help others get up and running quickly. In this guide, I’ll walk you through the installation process, highlight some useful tools, and share the sections that stumped me.

Interface Choice

There are three fully featured interfaces to openEMS:

  • C++: Using the source as a library
  • Python: Using the python bindings to the compiled C++. The openEMS executable is not called when using python as the XML generation is not fully supported yet.
  • XML: Generated by AppCSXCAD or the Octave/Matlab interface. The octave interface generates and XML and calls the openEMS executable with the file as an argument.

The C++/Python and XML interfaces are so different that I’m only going to focus on Python.

Project sections

The OpenEMS-Project has several sections:

  • fparser: Function Parser for C++
  • hyp2mat: Import Hyperlynx Boardsim files to openEMS
  • QCSXCAD: QT-GUI for CSXCAD
  • CTB: Circuit Toolbox for Matlab/Octave
  • CSXCAD: C++ library to describe geometrical objects
  • AppCSXCAD: Minimal GUI Application using the QCSXCAD library
  • openEMS: FDTD Engine

NOTE: If you are forking the project to make edits you will need to fork all of the subrepos as they have relative paths in the .gitmodules (link). That has been changed in my fork (here).

These compile into a set of tools and libraries:

  • openEMS: Command line tool for calling the FDTD engine. Takes an XML format whose generation is currently only supported from the Matlab/Octave interface.
  • AppCSXCAD: GUI for viewing the XML configurations. When using the python interface this is still useful for debugging your setup.
  • openEMS Python Bindings

To simply use the FDTD engine you will only need fparser and CSXCAD. My preference is to compile the python bindings and use an AppImage of AppCSXCAD. I have a pull request to make building that AppImage a CI/CD action here. Prebuilt appimages are available in releases on my fork as the pull request hasn’t been merged yet.

Installation

Package Manager

OpenEMS and AppCSXCAD are both available in Debian. As of writing (November 2024) version 0.0.35 is available on Ubuntu 22.04 but no version is available on 24.04.

sudo apt install openems appcsxcad

This method is quick and easy, but you may not get the latest version.

Edit: 2025-08-29: There isn’t a maintainer for any of the distros so it’s better to choose another method.

Source

Ubuntu 24.04

The AppCSXCAD build is currently broken due to changes in VTK9. To avoid that detail use the AppImage.

To setup just the python bindings:

FROM ubuntu:24.04

WORKDIR /home/root

RUN apt-get update && \
     apt-get upgrade -y && \
     apt-get install -y build-essential cmake git libhdf5-dev libvtk9-dev \
                     libboost-all-dev libcgal-dev libtinyxml-dev \
                     python3-numpy python3-matplotlib cython3 python3-h5py \
                     python3-venv

RUN git clone --recursive https://github.com/thliebig/openEMS-Project
RUN python3 -m venv venv && pip install numpy h5py matplotlib cython setuptools
RUN cd openEMS-Project && ./update_openEMS.sh ~/.local --python --disable-GUI
RUN ./build_python.sh ~/.local/ || cat *.log

You can just run these commands natively if preferred.

Ubuntu 22.04

AppCSXCAD will compile in 22.04 so you can leave off the –disable-GUI flag if desired. I still recommend using the AppImage and forgetting about it.

FROM ubuntu:22.04

WORKDIR /home/root
ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update && \
     apt-get upgrade -y && \
     apt-get install -y build-essential cmake git libhdf5-dev libvtk9-dev \
                     libboost-all-dev libcgal-dev libtinyxml-dev \
                     python3-numpy python3-matplotlib cython3 python3-h5py \
                     python3-venv

RUN git clone --recursive https://github.com/thliebig/openEMS-Project
RUN python3 -m venv venv && . venv/bin/activate && pip install numpy h5py matplotlib cython setuptools
RUN cd openEMS-Project && ./update_openEMS.sh ~/.local --python || cat *.log
RUN ./build_python.sh ~/.local/ || cat *.log

AppImage

AppCSXCAD is available as an AppImage. OpenEMS could also be packaged this way for the XML (Matlab) workflow. If you’d like to see that, leave a comment.

Python Wheels

There’s be talk about setting up a python build but I haven’t seen anything in that direction yet.

Use

After building you’ll need to set your PYTHONPATH and activate the virtual environment.

export PYTHONPATH=$PYTHONPATH:~/.local/lib
source /home/root/venv/bin/activate

python

Python 3.10.12 (main, Aug 15 2025, 14:32:43) [GCC 11.4.0] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import openEMS
>>> import CSXCAD

Next Steps

My current focus is on simulating Time Domain Reflectometry (TDR) measurements for soil moisture and conductivity analysis. I’m planning to put together a selection of tests that can be confirmed from analytic analysis and some field tests to get comfortable.

Alternatives

I should mention that there are other FDTD and EM simulator options available. I’m keeping a running Gist that includes various tools for electromagnetic field simulation.