Installing OpenEMS on Linux

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

Docker Source Files are available here.

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. The XML generation is skipped entirely.
  • XML: Generated by AppCSXCAD or the Octave/Matlab interface. The octave interface generates an XML file 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

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.

Build from source in a container

After some work on the build system the main branch builds again! There hasn’t been a release in awhile however the main branch is relatively stable so I recommend compiling from source.

I have Docker files for Ubuntu and Debian here.

As of 2025-09-22 Debian 12.12 & 13.1 and Ubuntu 22.04 & 24.04 all build.

For Ubuntu 24.04 this is:

FROM ubuntu:24.04
ENV DEBIAN_FRONTEND=noninteractive
ENV INSTALL_DIR=/usr/local

# Install all required packages
RUN apt-get update && apt-get install -y --no-install-recommends \
    git wget build-essential cmake pkg-config \
    libx11-dev x11-apps paraview \
    libhdf5-dev \
    libboost-all-dev libcgal-dev libtinyxml-dev \
    qtbase5-dev \
    gengetopt help2man groff pod2pdf bison flex libhpdf-dev libtool \
    libvtk9-dev libvtk9-qt-dev \
    python3-pip python3-dev python3-venv cython3 python3-setuptools \
    && rm -rf /var/lib/apt/lists/*

# Clone OpenEMS project
WORKDIR /root/
ARG BRANCH=master
ARG REPO=https://github.com/thliebig/OpenEMS-Project.git

RUN git clone --recursive --branch ${BRANCH} ${REPO}
RUN cd OpenEMS-Project && bash update_openEMS.sh ${INSTALL_DIR} --python 

ARG UID=1000
ARG GID=1000
ARG USER=appuser
ARG GROUP=appuser

# Setup user

RUN userdel -r ubuntu && \
    groupadd -g ${GID} ${GROUP} \
    && useradd -m -u ${UID} -g ${GROUP} -s /bin/bash ${USER} \
    && chown -R ${UID}:${GID} ${INSTALL_DIR}
USER ${UID}:${GID}
WORKDIR /home/${USER}

CMD ["bash"]

Building

docker build --build-arg UID=$(id -u) --build-arg GID=$(id -g) --build-arg USER=$(whoami) -t [IMAGE TAG] -f Dockerfile .

Running

AppCSXCAD and paraview

To run a GUI you’ll need to connect the container to your window manager. On Debian/Ubuntu/Mint:

docker run -it --rm  -e DISPLAY=:0 \
  --device /dev/dri --group-add video \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v $(pwd):$(pwd) \
  --workdir "$(pwd)" \
  --name [CONTAINER TAG] [IMAGE TAG] AppCSXCAD  # or paraview
openEMS CLI

This is the XML interface and only useful with the Matlab/Octave interface:

docker run -it --rm \
  -v $(pwd):$(pwd) \
  --workdir "$(pwd)" \
  --name [CONTAINER TAG] [IMAGE TAG] openEMS
Python Bindings

You’ll need to use python in the container:

docker run -it --rm \
  -v $(pwd):$(pwd) \
  --workdir "$(pwd)" \
  --name [CONTAINER TAG] [IMAGE TAG] python3 [SCRIPT]

If you want to setup a virtual environment in the container then you’ll either need to enable --system-site-packages or manually set PYTHONPATH.

Python Wheels

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

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.