Unify the Gmsh → Palace pipeline: consolidate features from pyPalace & SQDMetal, add curved meshing

[mdmaas]

Summary

QGmshRenderer is the canonical geometry→Gmsh engine in qiskit-metal, yet the two major community Palace wrappers — pyPalace and SQDMetal — both re-implement the entire geometry→Gmsh→physical-groups pipeline from scratch, reading the QGeometry tables directly and emitting incompatible physical-group naming conventions. The result is heavy duplication and ecosystem divergence.

This issue proposes a consolidation path that merges the best features of pyPalace and SQDMetal into a shared layer inside qiskit-metal, with PalaceToolkit as decoupled infrastructure, and adds curved (second-order) tetrahedral meshing as a new capability.

---

Proposal

Adopt a two-layer architecture:

qiskit-metal (geometry + layer stack)
        │  QGeometry tables / QGmshRenderer primitives
        ▼
PalaceToolkit (topology + mesh + config + run)
   ├── Entity-based boolean pipeline (priority cuts + fragment)
   ├── pg_map naming contract (name → physical-group tag)
   ├── curved / high-order mesh generation
   ├── Palace config generator (single-pass, from pg_map + entity metadata)
   └── auto-installable Palace binary (CI-friendly)
        │
        ▼
   Palace solver (.msh + .json)

1. PalaceToolkit as base infrastructure

• Auto-installable Palace binary — already shipped by PalaceToolkit (palace_runtime.py), runnable in CI without manual Spack/build steps.
• Clean geometry-vs-topology split — the caller builds Entity dimtags (geometry); run_meshing_pipeline owns the boolean pipeline, auto interface naming (A__B / A__None), and returns a pg_map.
• Single-direction config generation — generate_palace_config_from_entities consumes pg_map + entity boundary_type metadata in one pass; no JSON rewriting.
• Validation and debugging tools -- verify_topology checks that the generated mesh will be accepted by Palace and produces graphical output that helps with geometry debugging duplicated/orphan tris.

2. Port SQDMetal's rich port vocabulary as Entity factories

SQDMetal has the most complete port/BC vocabulary in the ecosystem. Port these as PalaceToolkit Entity factories that emit properly-named 2D entities with boundary_type="lumped_port"/"waveport" and Direction/R/Mode metadata:

• create_port_CPW_on_Launcher → Entity(boundary_type="lumped_port", ...)
• create_port_CPW_on_Route
• create_port_2_conds
• create_port_JosephsonJunction (lumped L)
• create_waveport_on_boundary
• create_CPW_feed_Uclip_on_Launcher/Route (metallic U-clip + optional port)

Because PalaceToolkit's config generator already consumes entity metadata, ports flow end-to-end into the Palace JSON with no rewrite hazards (unlike SQDMetal's current set_port_impedance JSON-rewrite path).

3. Port pyPalace's curve/boundary processing and extend to curved meshes

• Boundary simplification — port pyPalace's BoundarySimplifySettings + _decompose_ring_to_chains (merges runs of short QM polygon edges into Gmsh splines/lines before imprinting) as an optional pre-mesh step.
• Curved / high-order meshing (headline feature) — add element_order (1 or 2) and curved flags to generate_3d_mesh / refine_near_surfaces. When element_order=2:
  • set Mesh.ElementOrder=2, Mesh.SecondOrderIncomplete=0, Mesh.HighOrderOptimize=1
  • Gmsh curves tet faces to the OCC geometry → eliminates flat-facet approximation
  • validate with verify_topology and a Palace round-trip smoke test
  • This is already proven in GSIM and works wonderfully; porting it here makes it available to the whole QM→Palace community.

4. EPR / kinetic inductance / farfield helpers (declarative)

Add Postprocessing builders (mirroring pyPalace's builder.Boundaries.Postprocessing_*) that append to the config dict. Covers:

• EPR dielectric interfaces (substrate-air, substrate-metal, metal-air)
• Kinetic inductance (Boundaries.Impedance with Ls)
• Farfield (Postprocessing.FarField)

5. Mesh↔config consistency validator

Add validate_config(pg_map, config) that asserts every physical group is referenced by exactly one boundary/material entry and vice versa — closing pyPalace's safety gap and preventing silent missing-BC bugs.

---

Phased rollout

• Add PalaceToolkit as optional dependency and test Palace runs on CI
• Merge SQDMetal port vocabulary as Entity factories
• Merge pyPalace curve pre-processing and extend into curved meshes
• Merge pyPalace's builder.Boundaries.Postprocessing
• Update SQDMetal and pyPalace to depend on the new upstream functionality so both can continue building simulation examples and other tools and avoid further divergence.

[zlatko-minev]

Thanks for putting this together, @mdmaas — this is a genuinely valuable proposal, and the timing is good. The "Open FEM stack" (Gmsh → Palace, HFSS-free validation) is exactly the arc we've flagged on the roadmap, and the duplication you're describing is the main thing slowing it down.

Framing / triage

The core problem you've identified — pyPalace, SQDMetal, and now PalaceToolkit each independently deriving the QGeometry → Gmsh → physical-groups pipeline with divergent physical-group naming conventions — is real, and it's the crux. Almost everything downstream (ports, config generation, EPR/farfield post-processing) forks off that one divergence. So the highest-leverage piece here isn't the mesher or the solver bindings; it's agreeing on one shared naming/topology contract (pg_map, the A__B / A__None interface convention) that everyone can target. Get that right and the rest can land incrementally.

Technical notes, section by section

• Two-layer split (QGmshRenderer = geometry; PalaceToolkit = topology/mesh/config). Sensible. QGmshRenderer is already the canonical geometry→Gmsh engine in-tree, so the design goal should be to build on it, not re-emit geometry beside it. Worth being explicit about the exact hand-off object (dimtags + entity metadata) so PalaceToolkit stays decoupled and qiskit-metal doesn't take on a hard Palace dependency.
• pg_map naming contract (§1). 👍 This is the piece I'd prototype first, in isolation, before any porting — it's small, it's the actual source of divergence, and it's what the other projects need to agree to. A short spec + a couple of round-trip examples would let SQDMetal / pyPalace comment concretely.
• Curved / high-order meshing (§3). High-value and relatively self-contained — element_order=2 + HighOrderOptimize can land as an opt-in QGmshRenderer flag early and benefit everyone, independent of the larger consolidation. I'd want a verify_topology + Palace round-trip smoke test gating it.
• Single-pass config generation (§1/§4). The declarative "append from entity metadata" flow is appealing here — it avoids a separate post-hoc JSON-rewrite step (e.g. SQDMetal's current set_port_impedance) and is easier to test and reason about.
• Port vocabulary as Entity factories (§2). The most valuable and the most coordination-heavy part — SQDMetal has the richest port/BC vocabulary, so the SQDMetal maintainers should really own/validate how those factories are shaped.
• Mesh↔config consistency validator (§5). Cheap, high-value safety net — could ship on its own regardless of the rest.

Open questions worth settling early

1. Where does the shared layer live? Inside qiskit-metal (one surface, but adds maintenance + a Palace-adjacent dependency to a lite-by-default library) vs. a standalone package that qiskit-metal / SQDMetal / pyPalace all depend on. Given our lite-by-default posture, my instinct is that the Palace runtime + binary auto-install must stay strictly opt-in (an extra), never pulled into the base install — but I'm open on the ownership/packaging shape.
2. Migration contract — a pg_map interface stable enough that SQDMetal and pyPalace can adopt it incrementally rather than big-bang.
3. Palace-in-CI — auto-installable Palace in CI is a real unlock well beyond this proposal: it's what would finally let us validate the qlibrary without an AEDT license.

This needs ecosystem coordination 🤝

This can't (and shouldn't) be decided unilaterally in qiskit-metal — it touches SQDMetal, pyPalace, and PalaceToolkit directly, and the naming contract only works if everyone signs off on it. So I'd like to get more eyes and voices here before we commit to a design:

• SQDMetal (@sqdlab team, @shanto268 , @abhishekchak52 ), pyPalace (@FirasAbouzahr), PalaceToolkit (@EpsilonForge) — does the two-layer split + pg_map contract match how you'd want to converge? What would you not want to give up?
• Anyone running the QM → Gmsh → Palace path today: what's your biggest current pain — the naming divergence, ports, curved meshes, config generation, or Palace-in-CI?
• If we picked one thing to prototype first, is the pg_map/topology contract the right starting point, or would a quick win like curved meshing be more motivating?

Please chime in below 🙏 — I'd much rather shape this together with the folks maintaining the surrounding tools than pick a design in a vacuum. Thanks again @mdmaas for the thoughtful write-up.