![]() |
![]() |
| 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 ProgressVisualopenEMS 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.
- Features
- Screenshots
- Gallery
- Architecture
- Requirements
- Installation
- Quick Start
- Workflow
- AI Assistance
- GUI Reference
- Meshing Rules
- Project File Format
- Script Editor
- Examples
- Tests
- Documentation
- Changelog
- External Sources & Dependencies
- License
- FreeCAD native
.FCStdfiles — 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.cstcontainer is not parsed. A ready-to-run export macro is included atapp/freecad_io/cst_export_macro.bas(see CST import). openems_export.jsonmanifest 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 = 10in Geometry → Variables… and typeL/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 assqrt,sinand constants such aspiare reserved. Variable values may themselves be equations that reference other variables, including variables defined later in the table (for examplePCB_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>_stoppoints) are carried through from FCStd
- 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.
- 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 immutableruns/<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
- 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.vtrfiles 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
- 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 asPORT_<name>_start/PORT_<name>_stopplus 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.jsontemplate. 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 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.
Antenna tab: polar cut with dBi rings, the NF2FF results found in the work directory and the details block (Dmax, Gmax, η).
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 gain pattern with the spatial axes labelled x/y/z; the radius follows the "dBi min" window, the colour bar carries the absolute values.
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 through a multi-layer board. The mesh lines, material regions, ports and NF2FF/domain boxes are shown together.
Mesh and port editing: place a port directly on the geometry and inspect the port box plus the surrounding mesh cells.
Field distribution over the dual-feed SDARS patch, focused on the radiating patch area.
Field Viewer: 3D field distribution over a dual-feed SDARS patch antenna, with the openEMS field magnitude and colour bar.
Field Viewer: Vivaldi field slice with the antenna structure and field magnitude together.
Field Viewer: Vivaldi field view with an additional geometry/plane overlay.
Field Viewer: vector glyphs on a field slice — direction and strength of the field are visible at a glance.
Antenna tab: 2D E/H-plane pattern of a GNSS patch with polar grid, markers and pattern details.
Antenna tab: 3D gain pattern of the dual-feed SDARS patch, with the dBi colour bar and spatial orientation.
Axial ratio versus frequency for the dual-feed SDARS patch.
Axial ratio versus frequency for the single-feed GNSS patch, including the 3 dB circular-polarization band.
Radiated efficiency and gain versus frequency from the loaded NF2FF result.
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.
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)
| 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.
git clone --recurse-submodules https://github.com/istra711/VisualOpenEMS.git
cd VisualOpenEMSpip install -r requirements.txtDownload 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.whlpip install .\third_party\easyMesh4openEMSpython tests\verify_imports.pyThe 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 --versionIf it is not on PATH, set the full executable path in AI → AI settings….
python app\main.py| 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 |
- File → Import Geometry… — select
.step,.fcstd,.stl,.obj, or a folder - Geometry → Add → Port… — define lumped/waveguide ports
- Geometry → Add → Assignment… — assign materials to objects
- Build Mesh (Ctrl+M) — generate the FDTD mesh
- Run Simulation (Ctrl+R) — execute the FDTD solver into a staging folder
- Simulation → Commit staged results — publish the run as the active result
- View results in the S-Params, Antenna, and Fields tabs; old committed runs remain available under Simulation → Run history…
- Set up geometry, materials, variables, ports, mesh and solver settings.
- Presets → Save current project as template… — give it a name and a short description. Results, markers and the S-parameter reference are not stored.
- 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.
- 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.
- Open What AI sees… to review the exact redacted prompt before sending.
- Optional: apply one of the proposed safe fixes, then use AI → Undo AI change to compare the previous state.
- 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.
┌─────────────┐ 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) │
└────────────┘ └────────────┘ └────────────┘
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.
| 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. |
The dock has two layers:
- 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. - Optional OpenCode explanation receives the compact project digest, the
run report, filtered log lines and an optional
project_run.pyexcerpt. 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).
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.
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.
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.
- 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.
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 --versionIf 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.
- 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….
┌────────────────────────────────────────────────────────────────┐
│ 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.
| 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 |
- Open — load
.s1p/.s2pTouchstone or appsparams.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 → 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.
- 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 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.
- 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
fieldvector 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)
|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.
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.
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 |
This fork includes local modifications to easyMesh4openEMS:
- Cylinder-end densification — pre-pass adds 5 mesh lines at both end-caps of every
CYLINDERprimitive (fixes interleaved edge gaps for Yagi antennas) - Bounds checks — prevents
IndexErrorinsmooth_and_process_mesh_linesfor STL polyhedron projects
See docs/EASYMESH_CHANGES_EN.md for details.
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….
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.pyAfter Commit staged results, the script is kept in
work/<project>/runs/<run-id>/project_run.py for reproducibility.
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.pyStep-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).
python -m pytest tests -qThe 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.
python tests\verify_imports.py # All imports OK?
python tests\test_models.py # Dataclass serialization round-trip$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.pypython 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| 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).
VisualopenEMS builds on the following open-source projects:
| 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) |
| 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. |
| Project | License | Source | Usage |
|---|---|---|---|
| FreeCAD | LGPLv2.1 | freecad.org · github.com/FreeCAD/FreeCAD | 3D parametric CAD modeler; geometry source for STEP/FCStd import |
| 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 |
| 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 |
| 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.
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Commit changes:
git commit -am 'Add my feature' - Push to the branch:
git push origin feature/my-feature - Create a Pull Request
- 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





















