User guide

This page outlines a typical pyPalace workflow. Step-by-step notebooks and scripts live under Jupyter examples.

If you are not modeling qubits, the configure → simulate steps below are still the main path; qubit-oriented meshing and analysis steps are optional (see Beyond qubit applications on the home page).

Workflow at a glance

  1. Design & mesh — Lay out the device (for example in Qiskit Metal) and produce a Palace-ready mesh (.msh or .bdf). Example 00 uses mesh_Quantum_Metal_design(); other tutorials ship pre-built meshes.

  2. Configure — Build config["Problem"], Model, Domains, Boundaries, and Solver with pypalace.builder, assemble them in a Config, and save JSON.

  3. Simulate — Point Simulation at your Palace binary and call run() (local MPI or Slurm).

  4. Analyze — Read CSV / field outputs; apply LOM, EPR, or custom postprocessing (see the example notebooks).

Building a Palace configuration

Import the builder namespaces and create a config object:

from pypalace.builder import Model, Domains, Boundaries, Solver
from pypalace.config import Config

cfg = Config("my_simulation.json")
cfg.add_Problem(Type="Eigenmode", Output="./output")
cfg.add_Model(Mesh="device.msh", L0=1.0e-6)
# ... add_Domains, add_Boundaries, add_Solver ...
cfg.save_config()

Use get_mesh_attributes() to map mesh physical groups to materials and boundary conditions.

Palace field semantics are documented in the stable Palace configuration reference.

Running Palace

from pypalace.simulation import Simulation

palace = "/path/to/palace-x86_64.bin"
sim = Simulation(cfg, palace)
sim.run(n=8)  # local MPI ranks

For clusters, pass HPC_options from HPC_options() (partition, time limit, tasks per node, etc.). See the Examples README for a Slurm template.

Mesh generation (Quantum Metal)

For coplanar designs in Qiskit Metal, mesh_Quantum_Metal_design() writes a tagged Gmsh mesh and returns attribute metadata. Extra packages are required — see Install.

Analysis workflows (qubit-focused examples)

These tutorials are superconducting-qubit oriented; the Palace problem types are general:

  • Capacitance + LOM — ex02 (Electrostatic)

  • Eigenmodes + EPR — ex01 (Eigenmode)

  • Driven \(S_{21}\) — ex03 (Driven)

  • Quantum Metal mesh → sim — ex00 (Eigenmode)

API details for config, simulation, and mesh modules are in API reference.