📘 EMStudio – User Guide & Developer Documentation

<p align="center"> <img src="icons/logo.png" alt="EMStudio Logo" width="180"/> </p> <h1 align="center">EMStudio</h1> <p align="center"> Qt-based GUI for electromagnetic (EM) simulations Developed at IHP Microelectronics </p>

Overview

EMStudio is a Qt-based desktop application for preparing, visualizing, and managing electromagnetic simulations.

It provides an integrated workflow for:

Loading GDS layout data
Choosing substrate stacks (dielectrics, metals, layers)
Visualizing a 2.5D cross-section
Configuring simulation parameters
Generating configuration files for EM solvers (OpenEMS, Palace)
Editing Python driver scripts with syntax highlighting
Running simulations and streaming log output

Features

Cross-platform Qt GUI (Linux & Windows)
GDS reader (gdsreader.cpp)
Substrate & material model
2.5D stack visualization (substrateview)
Python script editor with syntax highlighting & autocompletion
Python/Palace parser with JSON configuration
QtPropertyBrowser-based parameter editor
Preferences dialog (paths, solver settings, Python interpreter)
Command-line interface for automation

Installation

Pre-built Installer (Windows)

You can download a pre-built Windows installation if you are logged into your GitHub account. Without login, downloading the installer is not possible!

Go to Actions (In the Bar next to Code, Issues, Pull requests, etc.)
Click on the latest run with a green checkmark
Scroll to the bottom of the page
Press the download button on the right next to emstudio-windows-installer

Build from source (Linux)

Linux users typically build EMStudio from source:

cd /path/to/EMStudio
qmake EMStudio.pro
make -j$(nproc)
./EMStudio

Build from source (Windows / MSVC)

cd \path\to\EMStudio
qmake EMStudio.pro
nmake 
.\release\EMStudio.exe

External solvers (required for full functionality)

EMStudio integrates with external electromagnetic solvers.
For full functionality, these tools must be installed separately by the user.

Please ensure the solvers are available in your PATH, or configure their locations explicitly in the EMStudio settings.

openEMS

EC-FDTD electromagnetic solver.

Project page: https://www.openems.de/
Documentation: https://docs.openems.de/
Source code & build instructions: https://github.com/thliebig/openEMS-Project

Palace

Parallel finite-element electromagnetic solver.

Project page & documentation: https://awslabs.github.io/palace/
Source code: https://github.com/awslabs/palace

Running EMStudio (Standalone)

You can launch EMStudio.exe directly or via terminal:

EMStudio.exe [options] [run_file.json]

Command-line options

-gdsfile <path>
Path to GDS file
-topcell <name>
Top-level GDS cell

Example

EMStudio.exe -gdsfile "C:/Work/design.gds" -topcell "top"

KLayout Integration (method 1)

EMStudio can be launched directly from KLayout through the helper script:

scripts/klEmsDriver.py

Usage on Linux

Save klEmsDriver.py inside your EMStudio installation directory.
(Optional) Add EMStudio directory to your system PATH.
Launch KLayout with:

"<path>\klayout_app.exe" -e -rm "<path>\EMStudio\scripts\klEmsDriver.py"

Desktop Shortcut (Windows)

Right-click → New → Shortcut
Set target:

"<Path to KLayout>\klayout_app.exe" -e -rm "<Path to EMStudio>\scripts\klEmsDriver.py"

Name it e.g. EMStudio via KLayout
(Optional) Change the icon: icons/logo.ico

KLayout Integration (method 2)

EMStudio can be launched directly from KLayout if you start KLayout using one of the scripts provided in the EMStudio scripts directory:

KLayout.bat for Windows
KLayout.sh for Linux

This will find your KLayout installation by searching the PATH, and then start KLayout with EMStudio integration.

What happens when executed?

EMStudio receives the currently opened GDS layout
The top cell name is passed automatically
If you had already created a simulation model for this layout, you can load it from the history list in File menu

Workflow overview

EMStudio is a Qt-based desktop application for preparing, visualizing, and managing electromagnetic simulations.

EMStudio can be started stand-alone, or from the klayout layout editor.

After simulation settings and port configuration are configured, EMStudio can save a simulation model to disk, and also start simulation. The simulation model requires the solver workflow folder ('modules' for openEMS, 'gds2palace' for Palace) and the stackup file (*.XML) to be present in your target directory. This means you usually want to have one folder for each solver type (openEMS or Palace) where simulation model scripts are located together with the solver modules folder and the substrate files.

Note that the solver workflow folders are only the "bridge" to openEMS and Palace EM solvers, and you need to have these EM solvers installed, as described in the solver documentation. This is no different from using the normal Python script based IHP EM workflows.

Note for advanced users: If you want to create simulation models in different directories, and don't want to copy & paste the "modules" or "gds2palace" to each of these folders, you can also include these folders in your PYTHONPATH environment variable. For gds2palace, you can also install that using "pip install gds2palace" and update using "pip install gds2palace --upgrade".

User Interface

When you start EMStudio, you first need to configure some path settings using Setup > Preferences from the main menu.

Configuration

The screenshot shows the configuration of EMStudio on a Windows machine, with openEMS installed on Windows and Palace installed in Windows Subsystem for Linux (WSL).

MODEL_TEMPLATES_DIR EMStudio provides templates for openEMS and Palace workflows, so that you can start from scratch with no existing Python model code. The path configured here points to the template directory where openems_model.py and palace_model.pyare located.
OpenEMS Python Path
Path to the Python interpreter used for the openEMS workflow. If you installed openEMS and the IHP workflow files into a venv named "openEMS" located in your home directory "home/venv/openEMS", the python interpreter would be "home/venv/openEMS/bin/python"
PALACE_PYTHON
Path to the Python interpreter used for the Palace workflow. If you installed the gds2palace workflow files into a venv named "palace" located in "home/venv/palace", the python interpreter would be "home/venv/palace/bin/python". If you don't want to use Palace, you can leave this empty.

IMPORTANT: There is no native Palace version for Windows. When running Palace from EMStudio on Windows, you need to have gds2palace installed in a WSL virtual machine, and PALACE_PYTHON points to the venv for gds2palace in your WSL subsystem! In that case, gds2palace and the Palace solver will all run in the WSL subsystem.
PALACE_RUN_MODE
This setting is used to define how Palace is started after creating the model files (config.json and *.msh). "Executable" is used if Palace is installed into the "normal" file system, e.g. using spack installation. "Script" is used if you want/need more control over starting Palace, e.g. because you installed it in an apptainer container, or if you want to send jobs to remote machines. An example run script is shown in the gds2palace repository here.
PALACE_INSTALL_PATH
This is where you have installed Palace when using the "Executable" run mode. When using EMStudio on Windows, this points to Palace in your WSL virtual machine.

If you don't want to use Palace, or start Palace using script, you can leave this empty.
<img src="./doc/png/path_executable1.png" alt="exepath" width="700">
In this case, Palace will be started with the maximum number of cores available on your system.
PALACE_RUN_SCRIPT
This is the script used to start Palace when using the "Script" run mode. When using EMStudio on Windows, this points to Palace in your WSL virtual machine. If you don't want to use Palace, or start Palace using the "Executable" run mode, you can leave this empty.

Main

The main tab is where you configure the layout input file (*.gds) and the main simulation settings.

When you start from scratch, the settings grid is almost empty. You can now load a project template using File > Load Python Model ... or you can go to the Python tab, choose the simulator that you want to use and then press Generate Default. Before leaving the tab, save your changes using File > Save or Ctrl+S

When a valid model is loaded or created from the template, the main tab will look as shown below. Scripts parameters defined using the settings[]=value syntax will be shown in the settings grid and can be modified, with bi-directional synchronization to the built-in Python script editor. If the script line provides additional information in a comment, this will be shown as "flyout help" when moving the mouse over that item in the settings grid.

Not all possible settings are included in the template. Adding an additional setting is possible using the script editor

EMStudio

Install / Use

README