PalaceToolkit

A Python toolkit for open-source electromagnetic simulation with Palace and Gmsh. PalaceToolkit provides a declarative pipeline that takes you from geometry definition to post-processed S-parameters and far-field plots — no commercial licence required.

Features

Module	Description
palacetoolkit.mesh	Priority-based boolean pipeline for multi-material Gmsh models with automatic size-field grading.
palacetoolkit.simulation	Run Palace via downloaded runtime or optional Apptainer/SIF and extract S-parameters and impedance.
palacetoolkit.verify_topology	Validate that a 3D tetrahedral mesh is topologically consistent for Palace/MFEM.
palacetoolkit.analytic	Closed-form transmission-line formulas (CPW impedance, effective index, …).
palacetoolkit.postpro	Quick matplotlib plots of Palace S-parameter CSV files.
palacetoolkit.viz	Interactive PyVista mesh viewer with per-group colouring.
palacetoolkit.utils	Headless-safe visualisation helpers that export standalone HTML for docs and notebooks.

Installation

Prerequisites

• Python ≥ 3.8
• Gmsh (the gmsh Python package is pulled automatically)

Install the package (recommended)

python -m venv .venv
source .venv/bin/activate
pip install palace-toolkit

This installs palace-toolkit and, on Linux x86_64, fetches the matching prebuilt Palace CPU runtime on first use.

Optional (Linux x86_64) prebuilt runtime install:

palace-toolkit-install-binary

Verify Palace runtime after install

palace-toolkit-check

Expected output includes:

• Palace runtime check: OK
• resolved runtime mode/path
• Palace version line from --version

WSL notes (Ubuntu on Windows)

If you run inside WSL, you may need extra system libraries for runtime and plotting:

sudo apt update
sudo apt install -y libglu1-mesa-dev libgomp1 libxft2 openmpi-bin libopenmpi-dev libopenblas0

Matplotlib may default to a non-interactive backend (FigureCanvasAgg). If you want interactive plot windows:

sudo apt install -y python3-tk

Then set a GUI backend in ~/.config/matplotlib/matplotlibrc:

backend: TkAgg

Compatibility Policy

• Stable releases of palace-toolkit are validated against a matching stable release of palacetoolkit-palace-cpu.
• The default user install path is pip install palace-toolkit.
• A local clone/editable workflow is still supported for contributors.
• Nightly Palace builds are supported for power users through opt-in source builds and are treated as best-effort (no stability guarantee across commits).
• If API/runtime behavior differs between stable and nightly Palace, palace-toolkit stable behavior is defined by the stable palacetoolkit-palace-cpu line.

See docs/getting-started/compatibility-policy.md for the full policy and release cadence.

Release Tags and CI Publishing

• palace-cpu-vX.Y.Z triggers binary build/publish workflow for palacetoolkit-palace-cpu.
• vX.Y.Z triggers main package build/publish workflow for palace-toolkit.
• Both workflows also support manual dispatch from GitHub Actions.

Quick start

See docs/examples/ notebooks for worked examples covering waveguides, dipole antennas, horn antennas, and planar microwave circuits.

Building the docs

The documentation site is built with PyData Sphinx Theme. A justfile automates the full pipeline.

# Install docs dependencies (if not already)
pip install -e ".[docs]"

# Register the virtualenv as a Jupyter kernel
just ipykernel

# Full build: execute notebooks → build site
just docs-full

# Run documentation doctests (executes notebooks and fails on errors)
just doctest

# Or run each step individually:
just nbrun      # execute docs example notebooks with papermill
just nbdocs     # no-op (Sphinx renders .ipynb directly)
just docs       # build the Sphinx static site (strict mode)

# Serve locally for development
just serve      # starts a dev server on http://localhost:8080

Deploying docs to GitHub Pages

The documentation site is deployed to GitHub Pages. On every push to main, the .github/workflows/docs.yml workflow builds the Sphinx site and publishes it automatically.

One-time setup

1. In the GitHub repository settings: Settings → Pages → Build and deployment → Source: GitHub Actions.
2. The docs site will be available at https://<owner>.github.io/<repository>/.

Manual deploy

1. Build the site locally:

   pip install -e ".[docs]"
   just ipykernel
   just docs-full

2. Push the built site/ contents (or just push to main — the workflow rebuilds and deploys from the source).

You can also trigger a deploy manually from the Actions tab using the PalaceToolkit Docs workflow (workflow_dispatch).

The previous EpsilonForge.com deploy setup (SST + AWS CloudFront Router) has been removed from this repository. See DEPLOYING-DOCS.md if you need to reproduce that setup in another package.

Other useful recipes

Recipe	Description
just nbclean	Strip cell outputs from docs example notebooks for clean commits.

Roadmap

• Interactive 3D viewer for docs — Currently, mesh visualisations in the documentation are static PNG screenshots. A future enhancement will embed an interactive VTK.js viewer powered by trame or PyVista's export_html, giving readers the ability to rotate, pan, and inspect 3D meshes directly in the browser without leaving the documentation page.