palace-toolkit 0.1.0__tar.gz

palace_toolkit-0.1.0/MANIFEST.in

@@ -0,0 +1 @@
+include tools/build_palace.py

palace_toolkit-0.1.0/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: palace-toolkit
+Version: 0.1.0
+Summary: PALACE electromagnetic simulation course materials
+Requires-Python: >=3.8
+Requires-Dist: gmsh
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: meshio
+Requires-Dist: mfem
+Requires-Dist: pyvista
+Requires-Dist: enlighten
+Requires-Dist: pint
+Provides-Extra: plot
+Requires-Dist: pandas; extra == "plot"
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: palace-cpu
+Requires-Dist: palacetoolkit-palace-cpu>=0.1.0; extra == "palace-cpu"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Requires-Dist: pyvista[jupyter]; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: papermill; extra == "docs"
+Requires-Dist: pytest; extra == "docs"
+Requires-Dist: nb-clean; extra == "docs"
+Requires-Dist: pre-commit; extra == "docs"

palace_toolkit-0.1.0/README.md

@@ -0,0 +1,176 @@
+# PalaceToolkit
+
+A Python toolkit for open-source electromagnetic simulation with
+[Palace](https://awslabs.github.io/palace/) and [Gmsh](https://gmsh.info/).
+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 |
+|--------|-------------|
+| `palace.mesh` | Priority-based boolean pipeline for multi-material Gmsh models with automatic size-field grading. |
+| `palace.simulation` | Run Palace via Apptainer/MPI and extract S-parameters and impedance. |
+| `palace.verify_topology` | Validate that a 3D tetrahedral mesh is topologically consistent for Palace/MFEM. |
+| `palace.analytic` | Closed-form transmission-line formulas (CPW impedance, effective index, …). |
+| `palace.s_plot` | Quick matplotlib plots of Palace S-parameter CSV files. |
+| `palace.view_mesh` | Interactive PyVista viewer with per-group colouring. |
+| `palace.viz` | Headless-safe visualisation helpers that export standalone HTML for docs and notebooks. |
+
+## Installation
+
+### Prerequisites
+
+* Python ≥ 3.8
+* [Gmsh](https://gmsh.info/) (the `gmsh` Python package is pulled automatically)
+
+### Install the package
+
+```bash
+# Clone the repository
+git clone https://github.com/EpsilonForge/PalaceToolkit.git
+cd PalaceToolkit
+
+# Create a virtual environment and install in editable mode
+python -m venv .venv
+source .venv/bin/activate
+
+# Local clone install (recommended for now)
+./tools/install_local_editable.sh
+
+# Or equivalent manual commands:
+pip install https://github.com/EpsilonForge/PalaceToolkit/releases/download/palace-cpu-vX.Y.Z/<wheel-file>.whl
+pip install -e ".[plot,docs]"
+```
+
+Default runtime is binary-first when `palacetoolkit-palace-cpu` is installed.
+
+By default, `./tools/install_local_editable.sh` fetches the latest
+GA-built binary wheel from GitHub Releases.
+
+To force local binary package mode from the checkout:
+
+```bash
+PALACETOOLKIT_BINARY_SOURCE=local ./tools/install_local_editable.sh
+```
+
+### Compatibility Policy
+
+- Stable releases of `palace-toolkit` are validated against a matching stable release of `palacetoolkit-palace-cpu`.
+- The default local clone path (`./tools/install_local_editable.sh`) installs both packages from the same repository checkout and is the reference development workflow.
+- 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.
+
+### Optional: Power-user source build (nightly/custom)
+
+Source builds are opt-in and disabled by default.
+Use this only if you need custom flags (CUDA/HIP/MAGMA/etc.) or nightly Palace.
+
+```bash
+PALACETOOLKIT_BUILD_PALACE=1 \
+PALACETOOLKIT_CLONE_NIGHTLY=1 \
+PALACETOOLKIT_PALACE_WITH_CUDA=0 \
+PALACETOOLKIT_PALACE_WITH_HIP=0 \
+PALACETOOLKIT_PALACE_WITH_MAGMA=0 \
+pip install -e .
+```
+
+Source builds are cached at:
+
+`~/.cache/palacetoolkit/palace/<source-key>-<platform>-<options-hash>/build/bin/palace`
+
+On subsequent installs, the cached build is reused automatically. Useful controls:
+
+```bash
+# Force rebuild even when cache exists
+PALACETOOLKIT_FORCE_PALACE_REBUILD=1 pip install -e .
+
+# Use a local Palace source tree instead of cloning nightly
+PALACETOOLKIT_PALACE_SOURCE=/path/to/palace PALACETOOLKIT_BUILD_PALACE=1 pip install -e .
+
+# Override parallel build jobs
+PALACETOOLKIT_PALACE_JOBS=8 pip install -e .
+
+# Extra custom CMake args
+PALACETOOLKIT_PALACE_EXTRA_CMAKE_ARGS="-DCMAKE_BUILD_TYPE=Release" pip install -e .
+```
+
+The core install pulls `gmsh`, `numpy`, `meshio`, `pyvista`,
+`enlighten`, and `pint`. The optional dependency groups are:
+
+| Group | Extra packages |
+|-------|---------------|
+| `plot` | `pandas`, `matplotlib` |
+| `docs` | `mkdocs`, `mkdocs-material`, `pyvista[jupyter]`, `nbconvert`, `ipykernel`, `papermill`, `nb-clean`, `pre-commit` |
+
+## Quick start
+
+Below is a minimal example that creates a coaxial geometry, meshes it, runs
+Palace, and plots the S-parameters:
+
+```python
+import palacetoolkit as ptk
+from ptk.mesh import Entity, run_meshing_pipeline
+from ptk.simulation import run_palace
+from ptk.s_plot import plot_s_params
+
+# 1. Define entities with names, priorities and materials
+inner  = Entity(name="inner_conductor", ...)
+dielectric = Entity(name="dielectric", ...)
+outer  = Entity(name="outer_conductor", ...)
+
+# 2. Run the boolean pipeline — cuts, fragments, and meshes
+run_meshing_pipeline([inner, dielectric, outer], output="coax.msh")
+
+# 3. Run Palace with a JSON config
+run_palace("coax.json", np=4)
+
+# 4. Plot results
+plot_s_params("postpro/coax")
+```
+
+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
+[MkDocs Material](https://squidfunk.github.io/mkdocs-material/).
+A [justfile](https://github.com/casey/just) automates the full pipeline.
+
+```bash
+# 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 (MkDocs renders .ipynb directly)
+just docs       # build the MkDocs static site
+
+# Serve locally for development
+just serve      # starts a dev server on http://localhost:8080
+```
+
+### Other useful recipes
+
+| Recipe | Description |
+|--------|-------------|
+| `just nbclean` | Strip cell outputs from docs example notebooks for clean commits. |

palace_toolkit-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "palace-toolkit"
+version = "0.1.0"
+description = "PALACE electromagnetic simulation course materials"
+requires-python = ">=3.8"
+dependencies = [
+    "gmsh",
+    "numpy",
+    "scipy",
+    "meshio",
+    "mfem",
+    "pyvista",
+    "enlighten",
+    "pint",
+]
+
+[project.optional-dependencies]
+plot = ["pandas", "matplotlib"]
+palace-cpu = ["palacetoolkit-palace-cpu>=0.1.0"]
+docs = [
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocs-jupyter",
+    "pyvista[jupyter]",
+    "nbconvert",
+    "ipykernel",
+    "papermill",
+    "pytest",
+    "nb-clean",
+    "pre-commit",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = [
+    "docs: execute documentation notebooks",
+]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["palacetoolkit", "palacetoolkit.*"]
+
+[build-system]
+requires = ["setuptools>=45", "wheel"]
+build-backend = "setuptools.build_meta"

palace_toolkit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

palace_toolkit-0.1.0/setup.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from setuptools import setup
+from setuptools.command.build_py import build_py as _build_py
+
+
+def _wants_palace_build() -> bool:
+    raw = os.environ.get("PALACETOOLKIT_BUILD_PALACE", "0").strip().lower()
+    return raw not in {"0", "false", "no", "off"}
+
+
+def _run_palace_build() -> None:
+    tools_dir = Path(__file__).parent / "tools"
+    script = tools_dir / "build_palace.py"
+    ns: dict[str, object] = {}
+    with script.open("r", encoding="utf-8") as f:
+        code = compile(f.read(), str(script), "exec")
+    exec(code, ns)
+    ns["ensure_palace_cached_build"]()
+
+
+class build_py(_build_py):
+    def run(self) -> None:
+        if _wants_palace_build():
+            self.announce("PalaceToolkit: opt-in Palace source build requested", level=3)
+            _run_palace_build()
+        else:
+            self.announce("PalaceToolkit: skipping Palace source build (default)", level=3)
+        super().run()
+
+
+cmdclass: dict[str, type] = {"build_py": build_py}
+
+try:
+    from setuptools.command.editable_wheel import editable_wheel as _editable_wheel
+
+    class editable_wheel(_editable_wheel):
+        def run(self) -> None:
+            if _wants_palace_build():
+                self.announce("PalaceToolkit: opt-in Palace source build requested", level=3)
+                _run_palace_build()
+            else:
+                self.announce("PalaceToolkit: skipping Palace source build (default)", level=3)
+            super().run()
+
+    cmdclass["editable_wheel"] = editable_wheel
+except Exception:
+    # Older setuptools versions may not expose editable_wheel.
+    pass
+
+setup(cmdclass=cmdclass)

palace_toolkit-0.1.0/src/palace_toolkit.egg-info/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: palace-toolkit
+Version: 0.1.0
+Summary: PALACE electromagnetic simulation course materials
+Requires-Python: >=3.8
+Requires-Dist: gmsh
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: meshio
+Requires-Dist: mfem
+Requires-Dist: pyvista
+Requires-Dist: enlighten
+Requires-Dist: pint
+Provides-Extra: plot
+Requires-Dist: pandas; extra == "plot"
+Requires-Dist: matplotlib; extra == "plot"
+Provides-Extra: palace-cpu
+Requires-Dist: palacetoolkit-palace-cpu>=0.1.0; extra == "palace-cpu"
+Provides-Extra: docs
+Requires-Dist: mkdocs; extra == "docs"
+Requires-Dist: mkdocs-material; extra == "docs"
+Requires-Dist: mkdocs-jupyter; extra == "docs"
+Requires-Dist: pyvista[jupyter]; extra == "docs"
+Requires-Dist: nbconvert; extra == "docs"
+Requires-Dist: ipykernel; extra == "docs"
+Requires-Dist: papermill; extra == "docs"
+Requires-Dist: pytest; extra == "docs"
+Requires-Dist: nb-clean; extra == "docs"
+Requires-Dist: pre-commit; extra == "docs"

palace_toolkit-0.1.0/src/palace_toolkit.egg-info/SOURCES.txt

@@ -0,0 +1,23 @@
+MANIFEST.in
+README.md
+pyproject.toml
+setup.py
+src/palace_toolkit.egg-info/PKG-INFO
+src/palace_toolkit.egg-info/SOURCES.txt
+src/palace_toolkit.egg-info/dependency_links.txt
+src/palace_toolkit.egg-info/requires.txt
+src/palace_toolkit.egg-info/top_level.txt
+src/palacetoolkit/__init__.py
+src/palacetoolkit/analytic.py
+src/palacetoolkit/geometry.py
+src/palacetoolkit/mesh.py
+src/palacetoolkit/mode_solver.py
+src/palacetoolkit/palace_runtime.py
+src/palacetoolkit/plot_farfield.py
+src/palacetoolkit/s_plot.py
+src/palacetoolkit/simulation.py
+src/palacetoolkit/utils.py
+src/palacetoolkit/verify_topology.py
+src/palacetoolkit/viz.py
+tests/test_docs_notebooks.py
+tools/build_palace.py

palace_toolkit-0.1.0/src/palace_toolkit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

palace_toolkit-0.1.0/src/palace_toolkit.egg-info/requires.txt

@@ -0,0 +1,27 @@
+gmsh
+numpy
+scipy
+meshio
+mfem
+pyvista
+enlighten
+pint
+
+[docs]
+mkdocs
+mkdocs-material
+mkdocs-jupyter
+pyvista[jupyter]
+nbconvert
+ipykernel
+papermill
+pytest
+nb-clean
+pre-commit
+
+[palace-cpu]
+palacetoolkit-palace-cpu>=0.1.0
+
+[plot]
+pandas
+matplotlib

palace_toolkit-0.1.0/src/palace_toolkit.egg-info/top_level.txt

@@ -0,0 +1 @@
+palacetoolkit

palace_toolkit-0.1.0/src/palacetoolkit/__init__.py

@@ -0,0 +1,31 @@
+"""PalaceToolkit — utilities for Palace electromagnetic simulations.
+
+Import as::
+
+    from palacetoolkit.analytic import cpw_impedance
+    from palacetoolkit.mesh import Entity, run_meshing_pipeline
+    from palacetoolkit.simulation import run_palace, generate_palace_config
+    from palacetoolkit.viz import view_mesh
+    from palacetoolkit.verify_topology import analyse_mesh
+"""
+
+from palacetoolkit.analytic import *          # noqa: F401,F403
+from palacetoolkit.mesh import *              # noqa: F401,F403
+from palacetoolkit.simulation import *         # noqa: F401,F403
+from palacetoolkit.verify_topology import *   # noqa: F401,F403
+
+# Optional submodules — silently skip when extra deps are missing
+try:
+    from palacetoolkit.s_plot import *        # noqa: F401,F403
+except ImportError:
+    pass
+
+try:
+    from palacetoolkit.viz import *           # noqa: F401,F403
+except ImportError:
+    pass
+
+try:
+    from palacetoolkit.utils import *         # noqa: F401,F403
+except ImportError:
+    pass

palace_toolkit-0.1.0/src/palacetoolkit/analytic.py

@@ -0,0 +1,60 @@
+"""Analytic closed-form expressions for transmission line parameters."""
+
+import numpy as np
+
+def _K_over_Kp(k: float, kp: float) -> float:
+    """Approximate ratio K(k)/K(k') using the Hilberg formula."""
+    def _s(x: float) -> float:
+        return np.log(
+            2 * (np.sqrt(1 + x) + (4 * x) ** 0.25)
+            / (np.sqrt(1 + x) - (4 * x) ** 0.25)
+        )
+
+    if k >= 1.0 / np.sqrt(2):
+        return _s(k) / (2 * np.pi)
+    else:
+        return 2 * np.pi / _s(kp)
+
+def cpw_impedance(w: float, s: float, h: float, eps_r: float) -> float:
+    """Compute the characteristic impedance of a CPW line.
+
+    Uses the conformal mapping approach with elliptic integral ratios K(k)/K(k').
+
+    Args:
+        w:     Centre conductor width.
+        s:     Gap between centre conductor and ground.
+        h:     Substrate thickness.
+        eps_r: Relative permittivity of the substrate.
+
+    Returns:
+        Z0: Characteristic impedance in Ohms.
+    """
+    k  = w / (w + 2 * s)
+    k1 = np.sinh(np.pi * w / (4 * h)) / np.sinh(np.pi * (w + 2 * s) / (4 * h))
+
+    kp  = np.sqrt(1 - k ** 2)
+    k1p = np.sqrt(1 - k1 ** 2)
+
+    kok  = _K_over_Kp(k,  kp)
+    k1ok = _K_over_Kp(k1, k1p)
+
+    eps_eff = 1 + ((eps_r - 1) / 2) * k1ok / kok
+    Z0 = 30 * np.pi / (kok * np.sqrt(eps_eff))
+    return Z0
+
+
+def cpw_effective_index(w: float, s: float, h: float, eps_r: float) -> float:
+    """Return the effective refractive index of a CPW line.
+
+    Uses the same conformal-mapping model as :func:`cpw_impedance`.
+    """
+    k  = w / (w + 2 * s)
+    k1 = np.sinh(np.pi * w / (4 * h)) / np.sinh(np.pi * (w + 2 * s) / (4 * h))
+
+    kp  = np.sqrt(1 - k ** 2)
+    k1p = np.sqrt(1 - k1 ** 2)
+    kok  = _K_over_Kp(k,  kp)
+    k1ok = _K_over_Kp(k1, k1p)
+
+    eps_eff = 1 + ((eps_r - 1) / 2) * k1ok / kok
+    return np.sqrt(eps_eff)

palace_toolkit-0.1.0/src/palacetoolkit/geometry.py

@@ -0,0 +1,48 @@
+import gmsh
+
+def extract_tag(obj):
+    """
+    Extract the Gmsh tag from an object.
+
+    If object contains only one tag, return it as an integer, otherwise, preserve its
+    container.
+
+    Most gmsh functions return list of tuples like [(2, 5), (2, 8), (2, 10), ...], where the
+    first number is dimensionality and the second is the integer tag associated to that object.
+
+    Examples
+    --------
+    >>> extract_tag((3, 6))
+    6
+
+    >>> entities = [(2, 5), (2, 8), (2, 10)]
+    >>> [extract_tag(e) for e in entities]
+    [5, 8, 10]
+    """
+
+    if isinstance(obj, list) and len(obj) == 1:
+        return extract_tag(obj[0])
+    elif isinstance(obj, tuple):
+        return obj[1]
+    else:
+        raise ValueError("Expected a tuple or single-element list")
+
+
+# Convenience functions to extract extrema of the bounding box of an entity
+def xmin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[0]
+
+def ymin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[1]
+
+def zmin(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[2]
+
+def xmax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[3]
+
+def ymax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[4]
+
+def zmax(dimtag):
+    return gmsh.model.occ.getBoundingBox(dimtag[0], dimtag[1])[5]