Skip to content

About

GUI for 3D-EM-Simulator openEMS: Meshing, FDTD, S-parameters and antenna patterns, field viewer (MP4 export). FreeCAD import, parametric presets, STEP export.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Repository files navigation

VisualopenEMS

Vivaldi antenna field visualization Beam steering animation
Animated 3D field visualization of a Vivaldi antenna in the Field Viewer (Et field playback). Beam steering at 77 GHz: animated 3D gain pattern and E-plane cut while the beam is steered.

⚠️ Pre-Alpha — Work in Progress

VisualopenEMS is currently in pre-alpha development. The code is a work in progress and not suitable for production use. APIs, project file formats, and GUI layouts may change without notice. Simulation results should be independently verified.

Found a bug? Please open an issue with a description of the problem, steps to reproduce, and — if possible — a suggested fix or pull request. Contributions are welcome!


A standalone desktop GUI that takes 3D structures from FreeCAD, builds an openEMS/CSXCAD simulation model, runs FDTD simulations via Python bindings, and post-processes S-parameters, field dumps, and NF2FF far-field patterns.

An optional AI assistant diagnoses failed runs, proposes validated fixes, generates projects from templates and applies structured project patches — always under explicit user review, without autonomous file writes or solver runs.

Built with Python 3.11, PySide6 (Qt 6), and the openEMS/CSXCAD Python APIs.


Table of Contents


Features

Geometry Import

  • FreeCAD native .FCStd files — tessellated via FreeCADCmd into per-object triangle meshes
  • STEP (.step / .stp) — axis-aligned boxes are emitted as exact openEMS boxes; everything else as STL polyhedra
  • STL (.stl) — single file or folder of per-object STLs
  • OBJ (.obj)
  • CST Studio export package - folder or ZIP with manifest.json + one STL per solid. Imports geometry, materials (relative permittivity/permeability/ conductivity), ports, frequency range and boundary conditions; the proprietary .cst container is not parsed. A ready-to-run export macro is included at app/freecad_io/cst_export_macro.bas (see CST import).
  • openems_export.json manifest from the FreeCAD export tools
  • CSX primitives — generic box, cylinder, polygon, and STL entries for non-FreeCAD workflows
  • Named geometry variables — define L = 20, W = 10 in Geometry → Variables… and type L/2, sqrt(L*L + W*W) or plain numbers in every geometry field (Start/Stop, Center, Radius, waveguide a/b, dump and NF2FF boxes, polygon/wire point lists). The table has Name/Value/Result/Comment columns; Result shows the resolved numeric value live, shows how many fields use each variable, re-evaluates all geometry on change/rename, and refuses unresolved expressions. Variable-name completion while typing is optional in Settings → Geometry variables. Names are case-insensitive; functions such as sqrt, sin and constants such as pi are reserved. Variable values may themselves be equations that reference other variables, including variables defined later in the table (for example PCB_x = trace_l + 2*offset_y); circular references and unknown names are rejected. Expressions are stored next to the resolved numeric values, so existing meshing, CSX and script code keep seeing numbers.
  • Port markings (PORT_<name>_start / PORT_<name>_stop points) are carried through from FCStd

Mesh Generation

  • easyMesh automated meshing with three checkmarked profiles (Default / Antenna / PCB), frequency-aware cell-size overrides and critical-cell reporting
  • Enforces openEMS rules of thumb: max cell ≤ λ/10, smooth grading, 1/3–2/3 metal edge rule
  • Metal-edge densification for cylindrical structures (custom fix — see easyMesh Changes)
  • Separate min cell size for Z-axis (useful for flat PCB structures)
  • Axis-restricted meshing (xy, xz, xyz, …)
  • Arc detection and graded mesh refinement at metal interfaces (fine next to PEC, coarsening into the air/dielectric by the max grading ratio)
  • Interactive mesh viewer with 3D scene and per-axis slice inspection (per-object colour, transparency and visibility, set in the object dialogs)
  • Mesh Editor — add / edit / delete manual grid lines per axis directly in the slice (click to add, click a line to select, Shift+click to add several, snap to geometry edges, multi-select with Del, right-click menu). Edits apply to the existing mesh instantly (no easyMesh re-run, view kept) and to every rebuild; removals snap to the nearest line and are reported if the mesh moved. New Scene (no mesh) shows geometry + domain + NF2FF box on an empty grid so the mesh can be built by hand; Rebuild from scratch and Delete Mesh round it out.
  • Two status-bar progress bars (side by side): timesteps and residual-energy convergence toward the end criterion (0 % = energy at start, 100 % = converged). New Project, Open and geometry imports clear the previous run's bars/labels.

Simulation

  • FDTD via openEMS Python bindings (FDTD / CSXCAD)
  • Configurable frequency range, excitation (Gaussian pulse f0/fc), boundary conditions (PML / Mur / periodic / PEC / PMC), air margin, and timestep limits
  • Boundary “all sides equal”: set all six faces to PEC, PMC, MUR or PML in one action; individual faces stay editable
  • Transactional runs: a run is written to a project-local staging/ folder, then explicitly committed to an immutable runs/<id>/ folder; older runs are retained and the project JSON is only written by Save/Commit. Save offers to commit a staged run; the close dialog offers Commit / Keep staged / Discard / Cancel. On reopening, leftover staging is detected and can be loaded for inspection or committed.
  • Multi-threaded solver control (auto or manual thread count)
  • Field dumps (Et/Hz time-domain, Ef/Hf frequency-domain) on configurable grids
  • NF2FF (Near-Field to Far-Field) box with automatic positioning

Post-Processing

  • S-Parameter Viewer — Touchstone/JSON import, Smith chart, |S| dB, phase, VSWR; interactive markers with right-click smart functions (trace min/max, nearest peak/valley, -3 dB points, band center, delta marker from the selected reference); the marker list shows the value for every ticked trace at each marker frequency and updates when traces are ticked/unticked; marker list selection highlights the plot, markers are saved in the project JSON, and marker rows can copy their value/frequency; closing the GUI with unsaved marker/settings changes asks Save/Discard/Cancel; auto-opens after simulation. Export… writes Touchstone (.sNp), CSV (frequency + every Sij as dB/phase/real/imaginary) and ASCII tables; the suggested file name follows the currently loaded file.
  • Antenna Viewer — 3D gain pattern (axes labelled x/y/z), E/H cuts (Az/El), directivity, gain, radiation efficiency; HPBW and front-to-back analysis; axial ratio and phase center from the stored E_theta/E_phi (no re-run), including an AR-vs-θ cut at a selectable azimuth; pop-out plot windows
  • NF2FF Summary — gain/directivity/efficiency plot per frequency
  • 3D Design — embedded read-only VTK view of the current project geometry (including imported STL), ports, NF2FF box and domain; per-object colours, global opacity, standard views, fit and pop-out; selecting a primitive or port in the Project / Geometry list outlines it in 3D. The right-click menu toggles X/Y/Z axes, labels and a numeric coordinate ruler (size, anchor, label size, ruler placement and tick side selectable; ruler, triad and camera fit follow the visible geometry when the domain box is hidden), can show a small fixed-size corner triad in the lower-left, can put an optional tick tape directly on the axis arrows, and starts a two-click distance tape in project units. The scene API is prepared for further measurement, clipping/picking and mesh overlays.
  • Field Viewer — 3D field slices with per-axis navigation
  • VTK Viewer — convert the HDF5 field dumps to VTK rectilinear grids (.vtr) and inspect them in an embedded 3D view (iso-surface of |field|, outline, configurable axes: View → Axes for corner marker, labels/font, size and a numeric coordinate ruler; ParaView-style vector glyphs: small arrows on the slice/surface/iso-surface that make the field motion visible during playback; export the sequence as an MP4 video or animated GIF with an options dialog for format, resolution, fps/duration and start/end frame range); the .vtr files open in ParaView too. A per-step export also writes a ParaView collection (<dump>.pvd) with the physical time (TD) or frequency (FD) of every step, so ParaView plays the whole series from one file
  • All viewers support export to PNG
  • Project context — every viewer header and pop-out title (Mesh Viewer, 3D Design, S-Params, Antenna, Field Viewer) shows the name of the current project and follows New / Open / Save As automatically

Workflow Automation

  • Preset generators: Patch Antenna, GPS L1 patch (CP), Dipole, PCB Filter, Yagi Antenna, WR62 waveguide
  • FreeCAD CAD export dialog (STEP or per-object STL)
  • STEP export for CAD / CST (File → Export STEP…): writes the effective geometry (analytic boxes/cylinders/spheres/polygons + imported meshes) as an AP214 STEP file in mm. Object names are preserved as STEP product names, so the solids arrive in CST Studio Suite under the same names as in the Mesh Viewer. Zero-thickness metal sheets (e.g. the patch preset) become planar faces, and meshes become shells (solids when watertight).
  • Mesh2FreeCAD (Mesh → Mesh2FreeCAD): opens the built mesh in FreeCAD as discretised geometry — one mesh-cell solid per object (cell-centre rule), optional STEP and OpenEMS voxel-grid overlay. Files are written to a temporary folder and deleted when FreeCAD (or VisualopenEMS) closes. The Mesh2FreeCAD Parameters… window selects STEP, Part/Mesh features, the voxel grid scope, zero-thickness sheets, port points and (for debugging) temporary-file keeping; these options are stored in the project file (.fcsim.json). Port points are written as PORT_<name>_start / PORT_<name>_stop plus a connecting line.
  • Grid export (JSON) (Mesh → Export grid (JSON)…): writes the built mesh lines per axis in mm (plus cell counts, min/max cell size and the FDTD domain) so another FDTD solver — e.g. CST — can run on identical cell boundaries.
  • User project templates — Presets → Save current project as template… stores the current geometry, materials, variables, ports, mesh/solver settings and notes as a reusable .fcsim.json template. Presets → New project from template… (also File → New from Template…) lists all templates with a preview/metadata, creates a fresh unsaved project and offers folder change, delete and open folder. Results, markers and the S-parameter reference are not stored.
  • Simulation script editor with regenerate/revert workflow
  • Project save/load (.fcsim.json) with backward-compatible deserialization

AI Assistance

  • AI error assistant — the AI dock (Ctrl+Shift+A) diagnoses the last run without network access: exit code, missing S-parameters, convergence, passivity, port and NF2FF settings, timestep budget and target-frequency checks. An optional explanation uses the local OpenCode CLI and its existing login/subscription; no API key is stored.
  • Local OpenEMS/CSXCAD knowledge — the assistant retrieves cited excerpts from the installed openEMS/CSXCAD packages, openEMS tutorials/docs/include, VisualopenEMS docs/examples/help and easyMesh. Indexing and ranking run locally; only the selected [K1]…[Kn] excerpts are added to the prompt. Sources… shows the exact files, line ranges and versions. Extra folders and the character budget are configurable; Check sources builds a sample index without sending anything.
  • Review-first fixes — only a small allow-list of solver, mesh and port fields can be changed. Every proposal shows an exact field diff, is validated on a deep copy (JSON round-trip plus variable/port resolution) and is applied only on an explicit click. AI → Undo AI change restores one level.
  • Project generation — AI → Generate project… builds a new project from seven validated templates (patch, Yagi, microstrip notch, open-stub band-pass, hairpin band-pass, GPS L1 patch, WR62 waveguide), with a parameter form, optional OpenCode JSON suggestion and structural preflight.
  • Structured project edits — AI → Edit project with AI… asks for a declarative patch (variables, ports, materials, primitives, mesh/solver fields), rejects unknown operations and fields, applies it to a copy and shows a diff plus preflight before Apply. No free-form Python and no arbitrary file paths.
  • Structural preflight — checks JSON round-trip, expressions, names, domain bounds, ports, mesh/solver settings, boundaries and NF2FF before a generated project or patch can be applied.
  • Offline by default — diagnosis, fixes, templates, patch validation, preflight and local knowledge retrieval work without OpenCode. Data is sent only when you press Explain last run, Send, AI suggest or Ask AI for proposal; What AI sees… shows the exact redacted prompt.

Screenshots

Antenna tab

Antenna tab: polar cut with dBi rings, the NF2FF results found in the work directory and the details block (Dmax, Gmax, η).

Mesh viewer

Mesh viewer: XY slice at the patch plane — the grid refines over the patch and coarsens towards the λ/10 limit; grid, geometry, ports and the NF2FF box toggle separately, a right click on a marked cell opens the repair actions.

3D pattern

3D gain pattern with the spatial axes labelled x/y/z; the radius follows the "dBi min" window, the colour bar carries the absolute values.


Gallery

Geometry, mesh and port placement

3D geometry viewer

3D Design: rotatable geometry with coordinate ruler, board outline and per-object display; useful as a quick visual check before meshing.

Mesh Viewer YZ slice

Mesh Viewer: YZ slice through a multi-layer board. The mesh lines, material regions, ports and NF2FF/domain boxes are shown together.

Mesh and port editor

Mesh and port editing: place a port directly on the geometry and inspect the port box plus the surrounding mesh cells.

Field Viewer

Field distribution over SDARS patch

Field distribution over the dual-feed SDARS patch, focused on the radiating patch area.

Field Viewer dual-feed patch

Field Viewer: 3D field distribution over a dual-feed SDARS patch antenna, with the openEMS field magnitude and colour bar.

Vivaldi field 3

Field Viewer: Vivaldi field slice with the antenna structure and field magnitude together.

Vivaldi field 4

Field Viewer: Vivaldi field view with an additional geometry/plane overlay.

Field vectors

Field Viewer: vector glyphs on a field slice — direction and strength of the field are visible at a glance.

Antenna patterns and polarization

2D antenna pattern GNSS

Antenna tab: 2D E/H-plane pattern of a GNSS patch with polar grid, markers and pattern details.

3D antenna pattern SDARS

Antenna tab: 3D gain pattern of the dual-feed SDARS patch, with the dBi colour bar and spatial orientation.

Axial ratio dual-feed

Axial ratio versus frequency for the dual-feed SDARS patch.

Axial ratio single-feed

Axial ratio versus frequency for the single-feed GNSS patch, including the 3 dB circular-polarization band.

Radiated efficiency

Radiated efficiency and gain versus frequency from the loaded NF2FF result.

S-parameters

S-parameter Re/Im/phase

S-Params Viewer: real/imaginary and phase traces over frequency with markers; the touchstone/JSON import and CSV/ASCII/Touchstone export use the same data.


Architecture

VisualopenEMS/
├── app/
│   ├── main.py                    # GUI entry point (PySide6)
│   ├── paths.py                   # App root resolution
│   ├── settings.py                # Persistent app settings
│   ├── project_templates.py       # User template storage, metadata and loading
│   ├── models/
│   │   └── project.py             # Project, MeshSpec, SimSpec, NF2FFDef, BoundarySpec, PortDef …
│   ├── ai/
│   │   ├── types.py               # Shared diagnosis/fix/context dataclasses
│   │   ├── diagnosis.py           # Deterministic run-report diagnosis
│   │   ├── fixes.py               # Allow-list, validation, safe apply
│   │   ├── context.py             # Project digest, log/script excerpts, redaction
│   │   ├── knowledge.py           # Read-only local OpenEMS/CSXCAD knowledge index
│   │   ├── backend.py             # AiBackend, OpenCode CLI adapter, MockBackend
│   │   ├── worker.py              # QThread with streaming and cancellation
│   │   ├── templates.py           # Seven validated project templates
│   │   ├── project_patch.py       # Structured project patch operations
│   │   ├── preflight.py           # Structural preflight checks
│   │   └── generation.py          # JSON extraction and prompt builders
│   ├── csxcad_builder/
│   │   ├── builder.py             # CSXCAD model construction
│   │   ├── primitives.py          # Parametric antenna generators (patch, dipole, Yagi)
│   │   ├── quantize.py            # Coordinate quantization
│   │   └── triangle_mesh.py       # Triangle mesh → CSX.AddMesh
│   ├── freecad_io/
│   │   ├── freecad_launcher.py    # FreeCADCmd subprocess management
│   │   ├── freecad_mesh.py        # FCStd → per-object STL tessellation
│   │   ├── freecad_step_runner.py # Builds STEP shapes inside FreeCADCmd
│   │   ├── importer.py            # Unified geometry import (STEP/STL/OBJ/FCStd)
│   │   ├── port_marks.py          # PORT_* point → PortDef extraction
│   │   ├── step_export.py         # Geometry → STEP (mm, named products) for CST
│   │   └── stl_import.py          # STL file parsing and bounds
│   ├── meshing/
│   │   ├── easy_wrapper.py        # easyMesh Python integration
│   │   ├── grid_export.py         # Mesh lines → JSON (mm) for external solvers
│   │   ├── preview.py             # Mesh preview generation
│   │   ├── rules.py               # Mesh validation rules
│   │   └── validators.py          # Mesh quality checks
│   ├── simulation/
│   │   ├── runner.py              # Simulation process management
│   │   └── script_gen.py          # Project → project_run.py code generation
│   ├── storage/
│   │   └── run_store.py           # Staging, immutable runs, atomic commit
│   ├── postproc/
│   │   ├── fields.py              # Field dump post-processing
│   │   ├── nf2ff.py               # NF2FF far-field computation
│   │   └── sparams.py             # S-parameter extraction
│   └── ui/
│       ├── main_window.py         # Main window, menus, tabs
│       ├── ai_panel.py            # AI assistant dock (diagnosis, chat, preview)
│       ├── ai_settings_dialog.py  # Provider, model, timeout and context settings
│       ├── project_generator.py   # Template generator and AI suggestion dialog
│       ├── project_patch_dialog.py # Structured project edit dialog
│       ├── project_template_dialogs.py # User template save/browse dialogs
│       ├── mesh_params.py         # Mesh parameter dialog
│       ├── sim_params.py          # Simulation parameter dialog
│       ├── ports_dumps.py         # Ports & dumps dialog
│       ├── geometry_editors.py    # Port, material, primitive editors
│       ├── mesh_viewer.py         # 3D mesh visualization
│       ├── sparam_viewer.py       # S-parameter plots (scikit-rf)
│       ├── antenna_viewer.py      # Antenna pattern viewer
│       ├── script_editor.py       # Simulation script editor
│       ├── freecad_tools.py       # FreeCAD CAD export dialog
│       ├── tab_help.py            # Per-tab help system
│       └── freq_units.py          # Hz/kHz/MHz/GHz unit conversion
├── third_party/
│   └── easyMesh4openEMS/          # Git submodule — automated meshing engine
├── examples/                      # Runnable example scripts
├── tests/                         # Smoke tests and unit tests
├── docs/                          # Detailed documentation (EN/DE)
└── work/                          # Runtime output (git-ignored)

Requirements

Component Version / Path Source
Python 3.11.5 WinPython
openEMS (Python) 0.0.36 openems.de
CSXCAD (Python) 0.6.3 openems.de
FreeCAD 1.1.4 freecad.org
PySide6 ≥ 6.5 pyside.org
NumPy ≥ 1.26 numpy.org
SciPy ≥ 1.11 scipy.org
Matplotlib ≥ 3.8 matplotlib.org
h5py ≥ 3.7 h5py.org
scikit-rf ≥ 0.29 scikit-rf.org
easyMesh4openEMS fork (this repo) github.com/istra711/easyMesh4openEMS
OpenCode CLI (optional) latest opencode.ai — only for AI explanations, template suggestions and project patches; offline diagnosis needs no provider

Linux: the Python/Qt/VTK GUI is cross-platform. Native openEMS/CSXCAD, a Linux-built easyMesh and—for FCStd/STEP—FreeCAD must be installed separately. See Running on Linux for prerequisites, Settings paths, environment variables and the build_linux.sh packaging script.


Installation

1. Clone the repository

git clone --recurse-submodules https://github.com/istra711/VisualOpenEMS.git
cd VisualOpenEMS

2. Install Python dependencies

pip install -r requirements.txt

3. Install openEMS / CSXCAD Python wheels

Download from openems.de or use local wheels:

pip install C:\openEMS\python\CSXCAD-0.6.3-cp311-cp311-win_amd64.whl
pip install C:\openEMS\python\openEMS-0.0.36-cp311-cp311-win_amd64.whl

4. Install easyMesh4openEMS

pip install .\third_party\easyMesh4openEMS

5. Verify installation

python tests\verify_imports.py

6. Optional: install OpenCode for AI features

The deterministic AI diagnosis, safe fixes, templates, patch validation, preflight and local knowledge retrieval work without any provider. For natural-language explanations and AI proposals, install the OpenCode CLI using its official instructions and sign in once. Check that the command resolves:

opencode --version

If it is not on PATH, set the full executable path in AI → AI settings….


Quick Start

Launch the GUI

python app\main.py

Load a preset

Menu Preset Description
Presets → Patch Antenna… 2.45 GHz microstrip patch on FR4 2-port S-parameter sweep
Presets → Dipole… Half-wave dipole Basic antenna validation
Presets → PCB Filter… Microstrip notch filter 2-port, dual-excitation
Presets → PCB Bandpass (5.6 GHz)… 5-pole Chebyshev stub band-pass on PTFE 2-port, no vias
Presets → PCB Hairpin Bandpass (2.4 GHz)… Compact 5-pole hairpin band-pass on RT/duroid 6010 2-port, no vias
Presets → Yagi Antenna… 3-element Yagi Directional antenna
Presets → WR62 Waveguide (10 GHz)… Straight WR62, 100 mm, TE10 2-port, E/H/J field dumps

Import your own geometry

  1. File → Import Geometry… — select .step, .fcstd, .stl, .obj, or a folder
  2. Geometry → Add → Port… — define lumped/waveguide ports
  3. Geometry → Add → Assignment… — assign materials to objects
  4. Build Mesh (Ctrl+M) — generate the FDTD mesh
  5. Run Simulation (Ctrl+R) — execute the FDTD solver into a staging folder
  6. Simulation → Commit staged results — publish the run as the active result
  7. View results in the S-Params, Antenna, and Fields tabs; old committed runs remain available under Simulation → Run history…

Save your own project template

  1. Set up geometry, materials, variables, ports, mesh and solver settings.
  2. Presets → Save current project as template… — give it a name and a short description. Results, markers and the S-parameter reference are not stored.
  3. Later use Presets → New project from template… to browse the template with preview/metadata and create a fresh unsaved project. The manager can also open/change the template folder or delete a template.

Try the AI features

  1. Open AI → AI Assistant (Ctrl+Shift+A) and press Explain last run after a run, or use Explain with AI in a failure message box.
  2. Open What AI sees… to review the exact redacted prompt before sending.
  3. Optional: apply one of the proposed safe fixes, then use AI → Undo AI change to compare the previous state.
  4. AI → Generate project… creates a new design from a validated template; AI → Edit project with AI… proposes a structured patch for the current project. Both show a preflight and a diff before anything is applied.

Workflow

┌─────────────┐    STEP/FCStd    ┌──────────────────┐
│   FreeCAD   │ ──────────────▶  │  Import Geometry  │
│  (draw 3D)  │   (or STL/OBJ)   │  (tessellation)   │
└─────────────┘                  └────────┬─────────┘
                                          │
                                          ▼
                                 ┌──────────────────┐
                                 │ Assign Materials  │
                                 │ Define Ports      │
                                 └────────┬─────────┘
                                          │
                                          ▼
                                 ┌──────────────────┐
                                 │   Build Mesh      │◀── easyMesh automation
                                 │   (FDTD grid)     │    (presets + rules)
                                 └────────┬─────────┘
                                          │
                                          ▼
                                 ┌──────────────────┐
                                 │  Run Simulation   │◀── openEMS FDTD solver
                                 │  (project_run.py) │    (Python bindings)
                                 └────────┬─────────┘
                                          │
                          ┌───────────────┼───────────────┐
                          ▼               ▼               ▼
                   ┌────────────┐  ┌────────────┐  ┌────────────┐
                   │ S-Params   │  │  Antenna   │  │  Fields    │
                   │ Viewer     │  │  Viewer    │  │  Viewer    │
                   │ (S11/S21)  │  │  (gain)    │  │  (E/H)     │
                   └────────────┘  └────────────┘  └────────────┘

AI Assistance

The AI features follow one rule: the model may propose, but only you apply. No AI action writes a project file, builds a mesh, starts a solver run, commits a staged result or generates free-form Python.

Three workflows

Workflow Entry point What it does
Error analysis AI → AI Assistant (Ctrl+Shift+A), AI → Explain last run…, failure boxes Deterministic diagnosis of the last run plus an optional OpenCode explanation and a small set of validated fixes.
Project generation AI → Generate project… Builds a new project from a validated template or an AI JSON suggestion, runs the structural preflight and installs it as unsaved editor content.
Project editing AI → Edit project with AI… Asks OpenCode for a declarative project patch, validates it on a copy, preflights it and shows a diff before Apply.

Error assistant

The dock has two layers:

  1. Deterministic diagnosis works offline and is authoritative for known findings: solver exit code, missing S-parameters, max_timesteps, energy/end-criterion convergence, passivity, inactive/unexcited ports, target frequency outside the sweep and NF2FF flag mismatches.
  2. Optional OpenCode explanation receives the compact project digest, the run report, filtered log lines and an optional project_run.py excerpt. It explains and prioritizes the findings; it does not replace them.

Safe fixes are limited to numeric solver/mesh knobs, PML size, NF2FF switches and port active/excite/resistance/phase fields. Each proposal is validated on a deep copy and shown as an exact field diff. Apply fix does not rebuild the mesh or start a simulation. AI → Undo AI change restores the previous project and primitive snapshot (one level).

Project generation

Seven templates are registered: probe-fed patch, Yagi-Uda, microstrip notch filter, open-stub band-pass, hairpin band-pass, GPS L1 CP patch and WR62 waveguide. Each exposes only its relevant parameters and produces a normal, editable project with variables, materials, ports, dumps, mesh and solver settings.

AI suggest sends the template catalogue and parameter schema. The model must return exactly one JSON object with a template ID, parameters and assumptions; unknown templates or parameters are rejected. The form is filled only for a valid answer, and Preview / preflight stays a separate action. Create project is enabled only when the preflight has no errors; the result is unsaved editor content, so use File → Save As to keep it.

Structured project edits

Edit project with AI accepts only declarative operations: set, set_variable/remove_variable, set_port/add_port/remove_port, add_primitive/update_primitive/remove_primitive, add_material/update_material, set_mesh, set_sim, set_nf2ff and set_boundary. Port, primitive and material fields use fixed allow-lists; set_* accepts existing dataclass fields only, and *_file, path and source are refused. Unknown operations or fields abort the whole proposal before it reaches the project. Apply stores a one-level undo snapshot and clears results that no longer match the edited model.

Structural preflight

Both generation and editing run preflight() before anything is applied. It checks the project JSON round-trip, variable/expression resolution, names, primitive/port bounds against the estimated FDTD domain, port geometry and metal contact, active/excited ports, frequency and mesh settings, solver timesteps/end criterion, boundary faces and dump/NF2FF expressions. Errors block Apply/Create; warnings are informational. It is not a mesh build and not an EM simulation.

Safety and privacy

  • No autonomous actions. The assistant cannot save a project, write files, build a mesh, start a solver, commit results or execute generated code.
  • Explicit approval. Every change is a proposal with a diff and a separate Apply/Create button; one-level undo is always available.
  • Strict code gates. Operation/field allow-lists, type/range checks, JSON round-trip, variable resolution and preflight are enforced in code, not only in prompts.
  • Redaction. Home directory, C:\Users\<name>, common token formats and Bearer/API-key values are redacted. What AI sees… shows the exact prompt before sending. Absolute paths outside the profile, hostnames, material names or comments may still be visible.
  • Local knowledge stays local. The knowledge index scans a focused set of text files and ranks them in memory. It does not download anything, does not execute source files and does not write an index. Only the selected excerpts are inserted into the prompt; Sources… shows their paths and line ranges.
  • Neutral process. OpenCode runs in a temporary directory with stdin disabled, hidden console and a timeout, using its own login/subscription. VisualopenEMS stores no API key.
  • Offline mode. Without OpenCode, diagnosis, safe fixes, templates, patch validation, preflight and local knowledge retrieval remain fully available.

OpenCode's own permissions and sandbox are outside VisualopenEMS's control. For sensitive environments use offline mode, restrict the OpenCode configuration or run the application in an isolated account/VM.

Optional OpenCode setup

OpenCode is only needed for natural-language explanations, AI template suggestions and AI project patches. Install the CLI using the official instructions at opencode.ai, sign in once, and check the command:

opencode --version

If the command is not on PATH, set the full executable path in AI → AI settings…. The same dialog selects offline/OpenCode mode, model, timeout, answer language, log-line limit and whether the generated script is included. Test OpenCode only checks that the command resolves; it sends no prompt.

Documentation and implementation

  • AI implementation (EN) — architecture, data flow, module map, backend protocol, context/redaction, allow-lists, patch schema, preflight, privacy, tests and extension guide.
  • KI-Implementierung (DE) — German version.
  • In the application: Help → AI assistant (error analysis)…, Help → AI project generation and edits… and Help → AI implementation details….

GUI Reference

Main Window Layout

┌────────────────────────────────────────────────────────────────┐
│  File  Presets  FreeCAD  Mesh  Simulation  AI  View  Help       │
├────────────────────────────────────────────────────────────────┤
│ [Geometry] [Mesh] [S-Params] [Antenna] [Fields] [Log] [Help]  │
├────────────────────────────┬───────────────────────────────────┤
│                            │  Project Tree                     │
│   Tab Content              │  ├─ Geometry Files                │
│   (viewers, mesh info,     │  ├─ Materials                     │
│    computed values)        │  ├─ Ports                         │
│                            │  └─ Dumps                         │
│                            │                                   │
│                            │  [Import…] [Add Port…] [Add Mat…] │
├────────────────────────────┴───────────────────────────────────┤
│  Log / Mesh Report / Scene Info                                │
└────────────────────────────────────────────────────────────────┘

Window state is remembered across sessions: geometry (including maximised state), splitter sizes, Project/Geometry and log-panel visibility, the last active tab, and the size/position of the main Settings, Viewer settings and Display dialogs.

Keyboard Shortcuts

Shortcut Action
Ctrl+O Open project
Ctrl+S Save project
Ctrl+Shift+S Save As
Ctrl+M Open Mesh Parameters
Ctrl+R Run Simulation
Ctrl+Shift+R Run All Ports (full S-matrix)
Ctrl+Shift+A Open the AI Assistant dock

S-Parameter Viewer

  • Open — load .s1p/.s2p Touchstone or app sparams.json
  • Plot types — Smith chart, |S| dB, |S| magnitude, Phase, VSWR, Re/Im
  • Markers — click on plot; table shows f, |S|, dB, phase, VSWR
  • Go to S-min — jump to the resonance dip
  • Pop out — detach plot into a separate window
  • Auto-opens after a simulation completes

AI Assistant

  • AI → AI Assistant (Ctrl+Shift+A) opens the right-hand dock.
  • Explain last run shows the deterministic diagnosis: verdict, checked rules, ranked issues with evidence, and an optional fix selector.
  • Apply fix validates the selected allow-listed changes on a copy and applies them only after the click; Undo restores the previous snapshot.
  • Chat asks free-form questions about the current project and run. The answer is streamed; Stop cancels. What AI sees… shows the exact redacted prompt before anything is sent.
  • Settings selects offline/OpenCode mode, command, model, timeout, answer language, log-line limit and script inclusion.
  • The dock never writes files, builds a mesh, starts a run or commits results.

Antenna Viewer

  • 3D gain — spherical surface coloured by gain (dBi), spatial axes labelled x/y/z; the radius is normalised to the dBi window set by the slider, the colour bar carries the absolute values
  • E/H cuts — Az/El plane cuts with polar plots
  • Axial-ratio cut — AR against θ at a selectable azimuth (0…315°), with the 3 dB band shaded and the widest angle that still meets it labelled
  • Polarization… — axial ratio, CP sense, ellipse tilt and phase center per frequency, derived from the stored complex E_theta/E_phi (no re-run); copy as TSV
  • HPBW / VRV — half-power beamwidth and front-to-back ratio of the current cut
  • Gain / efficiency vs frequency — Dmax, gain, η and Prad over the NF2FF list
  • Pop out — detach any plot into a separate window

Axial-ratio cut

Axial ratio against θ for the GPS L1 preset at 1.57542 GHz (φ = 0°): 1.70 dB at boresight, ≤ 3 dB out to θ = 62°. The selector in the plot toolbar chooses the azimuth; the data comes from the nf2ff.json of the last run.

Field Viewer

  • Display panel on the left with collapsible Data, Slice / Iso, Colour and Vectors sections; a compact action bar on top and the playback bar at the bottom. Slice/iso controls appear only for those representations.
  • Field indicator in the page header, e.g. Field Viewer (J_tee [A/m²])
  • Layout modes in Viewer settings: B = docked display panel, C = minimal UI with a Display… popup, leaving the full width to the viewer
  • Export ▾ menu with per-step series and step-stride options
  • Slices and iso-surfaces of the field dumps, per-axis navigation
  • Vector glyphs ("Vectors") that replace the coloured surface, so the arrows stay visible; "field underneath" brings the overlay back
  • Three planes at once ("3 planes") — the X, Y and Z slice in one view; the selected axis follows the slider, the other two cut through the centre
  • Contour lines ("Contours") — 2…24 iso-lines of the selected array drawn on the slices
  • Streamlines — field lines traced through the volume and drawn as tubes, coloured from a seed plane through the centre; enabled when the dump carries the field vector array
  • Viewer settings (three tabs: Viewer, Colour, Colour bar) — layout (B/C), playback (fps, Loop, Auto-play), standard view, vector-arrow default, the colour scale (map, reverse, colour steps), the colour bar (position, width, height, font, label size) and its title (left/right, x/y, text size, rotation) with live preview under Settings → Viewer settings…; a Preview button applies changes without saving, Cancel restores them; remembered across sessions
  • Series playback over the time or frequency steps, with an arrow-motion readout per step
  • Export — VTK rectilinear grids (.vtr) plus a ParaView collection (<dump>.pvd), or MP4 / animated GIF via the export-options dialog (format, resolution, fps/duration, start/end frame range)

E field

|Et| in the substrate of the 2.45 GHz example, sliced from the field dump. The post-processing writes such slices as PNG next to the dump; the interactive 3D view with the vector glyphs lives in the Field Viewer tab.

Magic tee field

3 planes, contour lines and streamlines in a WR-90 magic tee at 10 GHz (0.75 mm mesh, 149 000 dump points, logarithmic colour scale). The bright band is the junction where the wave splits into the two arms.


Meshing Rules

The application enforces these openEMS meshing rules automatically:

Rule Description
λ/10 limit Maximum cell size ≤ λ_min / 10 (openEMS rule of thumb)
Preset targets low ≈ λ/10, medium ≈ λ/12, high ≈ λ/16
Grading ratio Neighbor cell ratio ≤ max_grading_ratio (default 2.0)
Metal edge 1/3–2/3 Additional mesh lines at metal edges (easyMesh)
Cylinder ends Densification at both end-caps of cylinder primitives
Port alignment 1D ports → one mesh line; 2D ports → one cell
PML placement PML cells after air margin
Drawing unit Consistent mm/µm/m throughout the model

Custom easyMesh Fixes

This fork includes local modifications to easyMesh4openEMS:

  • Cylinder-end densification — pre-pass adds 5 mesh lines at both end-caps of every CYLINDER primitive (fixes interleaved edge gaps for Yagi antennas)
  • Bounds checks — prevents IndexError in smooth_and_process_mesh_lines for STL polyhedron projects

See docs/EASYMESH_CHANGES_EN.md for details.


Project File Format

Projects are stored as .fcsim.json — a human-readable JSON file:

{
  "name": "my_antenna",
  "version": 1,
  "geometry_files": [...],
  "variables": [
    {"name": "L", "value": 20.0, "comment": "board length"},
    {"name": "W", "value": 10.0, "comment": "board width"}
  ],
  "materials": [...],
  "assignments": [...],
  "ports": [...],
  "dumps": [...],
  "nf2ff": {...},
  "mesh": {
    "preset": "high",
    "drawing_unit": "mm",
    "start_frequency": 2.2e9,
    "stop_frequency": 2.7e9,
    "target_frequency": 2.45e9,
    "refined_cellsize": null,
    "min_cellsize": null,
    "min_cellsize_z": null,
    "max_cellsize": null,
    "smooth_metal_edge": "one_third_two_thirds",
    "use_circle_detection": false,
    "use_arc_detection": false,
    "handle_closely_placed_edges": true,
    "max_grading_ratio": 2.0,
    "num_lines": 5,
    "dirs": "xyz",
    "add_graded_mesh_lines_at_material_transitions": true
  },
  "boundary": {...},
  "sim": {...},
  "primitives": [...],
  "project_id": "…",
  "storage_layout": 2,
  "results": {
    "active_run": "MyProject/runs/20261109-…",
    "status": "complete"
  }
}

Backward compatibility: unknown keys in older project files are silently ignored; missing keys fall back to defaults. Old flat result layouts are still read. On save, the file is rewritten atomically (temporary file + replace).

Expressions: primitives, ports, dumps and the NF2FF box can carry an expressions object alongside their numeric values, for example "expressions": {"start.0": "L/2", "stop.1": "W + 2"}. Primitive keys use start.<axis>, stop.<axis>, center.<axis>, radius, coord, length or points.<point>.<axis>; ports add wg_a/wg_b. A scaled field is stored as {"expr": "phi", "scale": 0.017453292519943295}. The numeric fields are the resolved drawing-unit values; the expressions are re-evaluated on load and whenever the variable table changes.

Run storage: a data folder contains staging/ (uncommitted runs), runs/<run-id>/ (immutable committed runs with manifest.json) and optional meshes/. The project JSON only points at the active run; older runs remain on disk and can be selected from Simulation → Run history….


Script Editor

Every simulation generates a standalone, reproducible project_run.py in its staging folder (work/<project>/staging/run-…/). The Script… editor edits the project-level template work/<project>/project_run.py; starting a run copies or regenerates it into staging.

Simulation → Script… opens a modeless editor with:

  • Save — write changes back
  • Revert — restore last saved state
  • Regenerate from project — rebuild from GUI state (backs up your edits to project_run_edited.py)

Run a generated script directly:

python work\my_antenna\staging\run-…\project_run.py

After Commit staged results, the script is kept in work/<project>/runs/<run-id>/project_run.py for reproducibility.


Examples

All examples are in examples/ and runnable standalone:

Script Description
freecad_yagi_model_param.py Parametric Yagi antenna (editable Part::Cylinder objects)
freecad_pcb_filter_model.py PCB notch filter (FreeCAD model)
freecad_dipole_ports.py Dipole with port markings
freecad_export_for_openems.py FreeCAD → openEMS export utility
run_patch_example.py Patch antenna end-to-end
run_pcb_filter_example.py PCB filter with dual excitation
run_pcb_bandpass_example.py 5.6 GHz stub band-pass (PTFE)
run_pcb_hairpin_example.py 2.4 GHz hairpin band-pass (RT/duroid 6010)
run_pcb_hairpin_3pol_example.py 2.44 GHz 3rd-order hairpin band-pass on FR4 (article rebuild, doc)
run_wr62_waveguide_example.py Straight WR62 waveguide, 100 mm, TE10 at 10 GHz
run_stl_import_example.py Headless STL import
run_yagi_example.py Yagi antenna simulation

Run an example:

python examples\run_yagi_example.py

Step-by-step video tutorial: Inverted-F antenna on a PCB at 5.8 GHz builds the geometry, meshes it, runs openEMS and explains the S-parameter, antenna-pattern and E-field viewers (MP4 + twelve annotated slides).


Tests

Unit and regression tests

python -m pytest tests -q

The suite covers the project model, simulation helpers, S-parameter comparison, variable sweeps, AI diagnosis/fixes/context/backend parsing, project templates, structured patches and the structural preflight. Current result: 531 passed.

Quick verification

python tests\verify_imports.py    # All imports OK?
python tests\test_models.py       # Dataclass serialization round-trip

Smoke tests (headless)

$env:QT_QPA_PLATFORM="offscreen"
python tests\menu_smoke.py
python tests\sim_params_smoke.py
python tests\mesh_viewer_smoke.py
python tests\sparam_viewer_smoke.py
python tests\antenna_viewer_smoke.py
python tests\script_editor_smoke.py
python tests\tab_help_smoke.py
python tests\tree_edit_smoke.py
python tests\ai_assistant_smoke.py
python tests\project_generator_smoke.py
python tests\project_template_smoke.py

Physics tests

python tests\smoke_patch.py       # Patch antenna S11
python tests\stl_import_smoke.py  # STL import + mesh
python tests\yagi_mesh_ends.py    # Yagi cylinder-end densification

Documentation

Document Description
docs/ANLEITUNG_EN.md Full guide: FreeCAD antenna → simulation (EN)
docs/ANLEITUNG_DE.md Full guide (DE)
docs/AI_IMPLEMENTATION_EN.md AI implementation: architecture, data flow, safety gates, backend, patches, preflight, tests, extension guide (EN)
docs/AI_IMPLEMENTATION_DE.md KI-Implementierung: Architektur, Datenfluss, Sicherheitsschranken, Backend, Patches, Preflight, Tests, Erweiterungen (DE)
docs/LINUX.md Linux prerequisites, path configuration and native build
docs/FREECAD_WORKFLOW_EN.md Step-by-step workflow checklist (EN)
docs/FREECAD_PORTS_EN.md Port marking in FreeCAD (EN)
docs/EASYMESH_CHANGES_EN.md Local easyMesh modifications (EN)
docs/DIAGNOSTICS_CHANGES_EN.md Mesh diagnostics: timing, run status, critical cells, fine-cell sources, coordinate quantization, cell repair (V1–V4) (EN)
docs/DIAGNOSTICS_CHANGES_DE.md Same, German — with the measurements over the real projects (DE)
docs/HAIRPIN_3POL_FR4_DE.md 3rd-order hairpin band-pass 2.44 GHz on FR4: article rebuild, synthesis, layout, mesh, validation status (DE)
CHANGELOG.md Full change history per release

Both guides are also available as Word and LibreOffice documents: ANLEITUNG_DE.docx · ANLEITUNG_DE.odt · ANLEITUNG_EN.docx · ANLEITUNG_EN.odt. All four are generated from the Markdown sources with python examples/build_anleitung_docx.py --all --odt (the ODT step uses a headless LibreOffice and is skipped when none is installed; --md / --docx build a single file).


External Sources & Dependencies

VisualopenEMS builds on the following open-source projects:

Core Simulation Engine

Project License Source Usage
openEMS GPLv3 openems.de · github.com/thliebig/openEMS FDTD time-domain electromagnetic solver
CSXCAD LGPLv3 openems.de · github.com/thliebig/CSXCAD Continuous Structure library for openEMS (geometry, materials, ports)

Mesh Generation

Project License Source Usage
easyMesh4openEMS GPL-3.0 github.com/MustafaAlchalabi/easyMesh4openEMS Automated FDTD mesh generation with metal-edge densification, grading, and arc detection. This repo uses a fork with local fixes.

CAD / Geometry

Project License Source Usage
FreeCAD LGPLv2.1 freecad.org · github.com/FreeCAD/FreeCAD 3D parametric CAD modeler; geometry source for STEP/FCStd import

Python Libraries

Library License Source Usage
NumPy BSD-3-Clause numpy.org · github.com/numpy/numpy Array operations, mesh data
SciPy BSD-3-Clause scipy.org · github.com/scipy/scipy Signal processing, interpolation
Matplotlib PSF-based matplotlib.org · github.com/matplotlib/matplotlib Plotting (S-params, fields, patterns)
h5py BSD-3-Clause h5py.org · github.com/h5py/h5py HDF5 field dump reading
PySide6 LGPL-3.0 pyside.org · github.com/pyside/PySide6 Qt 6 GUI bindings
scikit-rf BSD-3-Clause scikit-rf.org · github.com/scikit-rf/scikit-rf Touchstone file parsing, network analysis
Qt (PySide6) LGPL-3.0 qt.io · github.com/qt/qtbase Cross-platform GUI framework

Data Formats

Format Specification Usage
Touchstone IBIS Open S-parameter file exchange (.s1p, .s2p, …)
HDF5 hdfgroup.org openEMS field dump storage
STEP ISO 10303 CAD geometry exchange
STL wikipedia.org/wiki/STL_(file_format) Triangle mesh interchange

License

Component License
VisualopenEMS (this code) See repository license
openEMS GPLv3
CSXCAD LGPLv3
easyMesh4openEMS GPL-3.0
FreeCAD LGPLv2.1

Note: openEMS and easyMesh4openEMS are GPL-3.0 licensed. If you distribute a combined work, the GPL-3.0 terms apply to the whole. Consult a lawyer for commercial distribution.


Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Commit changes: git commit -am 'Add my feature'
  4. Push to the branch: git push origin feature/my-feature
  5. Create a Pull Request

Acknowledgements

  • openEMS by Thorsten Liebig and contributors — the FDTD engine that makes this project possible
  • CSXCAD by Thorsten Liebig — the continuous structure library
  • easyMesh4openEMS by Mustafa Alchalabi — automated mesh generation
  • FreeCAD community — the parametric CAD platform
  • scikit-rf — Touchstone and network analysis toolkit

About

GUI for 3D-EM-Simulator openEMS: Meshing, FDTD, S-parameters and antenna patterns, field viewer (MP4 export). FreeCAD import, parametric presets, STEP export.

Topics

Resources

Stars

0 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages