Clone, Build and Install

This section describes how to install CSXCAD and openEMS from source and build everything automatically via ./update_openEMS.sh.

For FreeBSD and Windows users, the easiest option is to install ready-made packages instead, please refer to Installing Ready-Made Packages - although they may not be up-to-date and can contain known problems.

Quick Start

Clone

Clone this repository, build openEMS and install e.g. to ~/opt/openEMS:

git clone --recursive https://github.com/thliebig/openEMS-Project.git
cd openEMS-Project

Build and Install

To build and install openEMS automatically, run (assuming that we want to install openEMS into ~/opt/openEMS):

./update_openEMS.sh ~/opt/openEMS

Extra features can be controlled by additional command-line arguments. For example, to build openEMS with CTB and Python:

./update_openEMS.sh ~/opt/openEMS --with-CTB --python

openEMS search path

After the build is complete, add ~/opt/openEMS/bin into your search path:

export PATH="$HOME/opt/openEMS/bin:$PATH"

You need to write this line into your shell’s profile, such as ~/.bashrc or ~/.zshrc to make this change persistent.

Setup the Octave/Matlab or Python Interfaces

Optional: Setup the Matlab or Octave environment, see Octave Interface Install
Optional: Install the Python extensions, see Python Interface Install

Check Installation

After completing installation, now it’s a good test to verify that the installation is functional according to Check Installation.

Advanced Install

Optional Arguments

Passing these arguments to enable, disable, or adjust extra features:

--verbose: Print build outputs to the console, in addition to the log file.

--njobs <JOBS>: Use <JOBS> threads to compile the project. By default, it’s set to the number of logical CPUs. If Out-Of-Memory errors occur, You may need to reduce its value.

--python: Build Python extensions, recommended.

See also

The --python argument accepts additional options for greater control over the installation process, see Install Python Extensions Automatically for details.

--with-CTB: Enable Circuit Toolbox, an optional Matlab/Octave library for processing RF circuit data, recommended for Matlab/Octave programmers.

--with-hyp2mat: Enable hyp2mat for converting HyperLynx PCB layouts to simulation geometry. It still compiles, but is now unmaintained, not recommended.

--with-MPI: Build MPI engine version, the regular multi-thread engine is disabled. Only needed for cluster, not recommended.

--disable-GUI: Disable AppCSXCAD GUI for viewing simulation models, useful for servers.

--with-tinyxml: Download and build a custom installation of TinyXML from source, need network access to SourceForge and GitHub. Enabled by default on macOS, as TinyXML is desupported by Homebrew.

Build TinyXML Without Network Access on macOS

On macOS, TinyXML has been desupported by Homebrew. By default, ./update_openEMS.sh automatically downloads and builds a local copy of TinyXML from SourceForge and GitHub. In most cases, this step is performed transparently without user intervention.

However, this can be a problem if network access is restricted or unavailable. Ordinary users can overcome the problem using the following solution.

Tip

For packagers, sysadmins and developers who needs to understand inner working of the custom TinyXML build, read the source code of scripts/build_tinyxml.sh. Additional technical information is also available in Manual C++ Build and Install.

Pre-download TinyXML Files via a Proxy

Internally, ./update_openEMS.sh calls scripts/build_tinyxml.sh, which uses curl for fetching files from HTTPS URLs. If network access is restricted, it’s possible to set a global proxy using the standard environment variable https_proxy with the format [protocol://]<host>[:port].

# HTTP proxy server for HTTPS URLs
export https_proxy="http://proxy.example.com:8080"

# SOCKS5 proxy server (with remote DNS) for HTTPS URLs
export https_proxy="socks5h://proxy.example.com:8080"

mkdir -p downloads
scripts/build_tinyxml.sh --download

Important

If a SOCKS proxy is used, one must disable this proxy before running ./update_openEMS.sh. By default, pip3 is not compatible with a proxy, due to a missing optional dependency pysocks with the error ERROR: Could not install packages due to an OSError: Missing dependencies for SOCKS support. For more information, see Q: I have Internet access, but behind a proxy.

unset https_proxy

Pre-download TinyXML Files Externally

If all files in downloads have correct SHA-256 digests, all network accesses and downloads are skipped, the existing files are reused. Thus, it’s also possible to manually download them from another machine or using other tools, then copying them into downloads later to the target machine.

Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/tinyxml-2.6.2.tar.gz
Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/tinyxml-2.6.2-defineSTL.patch
Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/tinyxml-2.6.1-entity.patch
Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/CVE-2021-42260.patch
Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/CVE-2023-34194.patch
Skip download (file exists, hash valid): /home/fdtd/openEMS-Project/downloads/tinyxml_CMakeLists.patch

Build Python Extensions Without Network Access

If Python is also needed for an offline installation, use:

./openEMS_Project.sh --python --python-use-network disable

Before running this script, all Python packages marked as optional in the Requirements page should be installed, such as cython. See Requirements for the full list.

Update Instruction

Perform an update in case of a new release.

cd openEMS-Project
git pull --recurse-submodules
./update_openEMS.sh ~/opt/openEMS --python

Warning

Changes you may have made (e.g. to the tutorials or examples) may be overwritten.