models ¶

Bases: BaseModel

Configuration for 2D boundary mode (waveguide cross-section) simulation.

Attributes:

• freq (float) –

  Operating frequency in Hz.

• num_modes (int) –

  Number of propagation modes to compute.

• save (int) –

  Number of modes to save as ParaView fields (0 = disabled).

• target (float) –

  Target effective index for shift-and-invert (0 = auto).

• tolerance (float) –

  Relative convergence tolerance for the eigensolver.

• max_size (int) –

  Maximum eigensolver subspace size (0 = default).

• solver_type (str) –

  Palace eigensolver type.

Methods:

• to_palace_config –

  Convert to Palace JSON config format.

to_palace_config() -> dict

Bases: SolverConfig

Common and cross-section mode settings for BoundaryModeSim.

Bases: BaseModel

Configuration for a coplanar waveguide (CPW) port.

CPW ports consist of two elements (upper and lower gaps) that are excited with opposite E-field directions to create the CPW mode.

The port is placed at the center of the signal conductor. The two gap element surfaces are computed from s_width and gap_width.

Attributes:

• name (str) –

  Port name (must match a single component port at the signal center)

• layer (str) –

  Target conductor layer

• s_width (float) –

  Width of the signal (center) conductor (um)

• gap_width (float) –

  Width of each gap between signal and ground (um)

• length (float) –

  Port extent along direction (um)

• offset (float | None) –

  Shift the port along the waveguide direction (um). Positive moves in the port orientation direction.

• impedance (float) –

  Port impedance (Ohms)

• excited (bool) –

  Whether this port is excited

Bases: _LayerPairSpec

Named contact between two layers on the native-2D cross-section mesh.

The shared interface curves between the two layers' meshed regions are tagged as a dim-1 physical group named name, so charge-transport solvers (DEVSIM add_gmsh_contact) can bind boundary conditions to it by name.

Attributes:

• name (str) –

  Physical-group name of the contact (e.g. "anode").

• layer_a (str) –

  First layer of the interface (e.g. the electrode layer).

• layer_b (str) –

  Second layer of the interface (e.g. the doped semiconductor).

Bases: BaseModel

Axis-aligned cross-section plane for 2D mode extraction.

An optional window clips the meshed 2D domain to a sub-region of the component cross-section instead of the full bounding box plus margins. This lets one component feed differently sized per-solver domains (full extent for RF, a small box around the rib for optics, the doped slab for charge transport).

Attributes:

• axis (Literal['x', 'y', 'z']) –

  Plane normal axis ("x", "y", or "z").

• value (float) –

  Plane coordinate in microns.

• window (AscendingInterval | None) –

  Optional in-plane interval (min, max) in um clipping the transverse extent (y for an x-plane, x for a y-plane).

• window_z (AscendingInterval | None) –

  Optional z interval (min, max) in um clipping the vertical extent.

Methods:

• from_spec –

  Parse a string specification like x=0 or y=100.

• validate_value –

  Ensure the plane coordinate is finite.

spec: str

from_spec(spec: str) -> Self

validate_value() -> Self

Bases: BaseModel

Configuration for driven (frequency sweep) simulation.

Used for S-parameter extraction and frequency response analysis. Palace solves Maxwell's equations at each frequency point (or uses an adaptive reduced-order model to interpolate from fewer full solves).

Attributes:

• fmin (float) –

  Minimum frequency in Hz.

• fmax (float) –

  Maximum frequency in Hz.

• num_points (int) –

  Number of frequency points in the output. With adaptive sweep enabled, this controls the output resolution — Palace builds a reduced-order model from a few full solves and interpolates the rest, so you can request many points (e.g. 200+) cheaply.

• scale (Literal['linear', 'log']) –

  Frequency spacing — "linear" for uniform steps, "log" for logarithmic spacing (useful for broadband sweeps).

• adaptive_tol (float) –

  Relative error tolerance for the adaptive frequency sweep (PROM). Palace solves the full model at a few automatically chosen frequencies, builds a surrogate, and checks if the interpolation error is within this tolerance. Set to 0 to disable adaptive sweep (every point gets a full solve). Typical values: 0.02 (2%, fast), 1e-3 (0.1%, accurate), 1e-4 (publication quality).

• adaptive_max_samples (int) –

  Maximum number of full-fidelity solves for the adaptive algorithm. If the tolerance isn't met after this many samples, it stops. Default 20 is usually sufficient.

• compute_s_params (bool) –

  Whether to compute S-parameters.

• reference_impedance (float) –

  Reference impedance for S-parameter normalization in Ohms. Standard is 50 Ohm.

• excitation_port (str | None) –

  Name of port to excite. None = first port.

• waveport_boundary (Literal['pec', 'inherit']) –

  "pec" replaces Robin boundaries by PEC in the numeric port eigenproblem (default). "inherit" retains their physical conductivity, impedance and absorbing conditions.

Methods:

• to_palace_config –

  Convert to Palace JSON config format.

• validate_frequency_range –

  Validate that fmin <= fmax and snap save_fields_at to the sample grid.

center_frequency: float

to_palace_config() -> dict

validate_frequency_range() -> Self

Bases: SolverConfig

Common and frequency sweep settings for DrivenSim.

Bases: BaseModel

Configuration for eigenmode (resonance) simulation.

Finds resonant frequencies, quality factors, and mode shapes of the structure. Useful for resonator design and cavity characterization.

Attributes:

• num_modes (int) –

  Number of eigenvalues (resonant modes) to compute.

• target (float | None) –

  Target frequency in Hz — Palace searches for eigenvalues above this frequency. Required before meshing or exporting. Set this near your expected resonance to speed up convergence.

• tolerance (float) –

  Relative convergence tolerance for the eigenvalue solver. Tighter tolerance (e.g. 1e-8) gives more accurate frequencies and Q-factors at higher cost.

Methods:

• compute_floquet_wave_vector –

  Compute Palace Floquet wave vector [kx, ky, kz] in rad / mesh-unit.

• to_palace_config –

  Convert to Palace JSON config format.

• validate_floquet –

  Validate Floquet dependencies for eigenmode setup.

compute_floquet_wave_vector(
    *, periodic_axis: Literal["x", "y", "z"], periodic_length: float | None = None
) -> list[float]

to_palace_config() -> dict

validate_floquet() -> Self

Bases: SolverConfig

Common and eigenvalue settings for EigenmodeSim.

Methods:

• default_eigenmode_linear_tolerance –

  Use the eigenmode tolerance unless the caller supplies an override.

default_eigenmode_linear_tolerance(values: Any) -> Any

Bases: BaseModel

Configuration for electrostatic (capacitance matrix) simulation.

Attributes:

• save_fields (int) –

  Number of field solutions to save

Methods:

• to_palace_config –

  Convert to Palace JSON config format.

to_palace_config() -> dict

Bases: SolverConfig

Common and electrostatic settings for ElectrostaticSim.

Bases: BaseModel

Configuration for geometry settings.

This model stores metadata about the component being simulated. The actual Component object is stored separately on simulation classes.

Attributes:

• component_name (str | None) –

  Name of the component being simulated

• bounds (tuple[float, float, float, float] | None) –

  Bounding box as (xmin, ymin, xmax, ymax)

Bases: BaseModel

Configuration for an Impedance boundary on a dielectric-dielectric interface.

Specifies a surface impedance boundary condition (Rs, Ls, Cs) applied to the shared boundary curve between two dielectric layers. Capacitance, resistance, and inductance values are given as absolute quantities and are divided by the interface curve length internally to obtain the per-unit-length values (Rs, Ls, Cs) expected by Palace.

Alternatively, attributes can be specified directly (with Rs/Ls/Cs already in per-unit-length form) for cases where the user already knows the Palace boundary attribute numbers.

Attributes:

• layer_a (str | None) –

  Name of the first dielectric layer.

• layer_b (str | None) –

  Name of the second dielectric layer.

• capacitance (float | None) –

  Absolute capacitance [F] (divided by curve length).

• resistance (float | None) –

  Absolute resistance [Ohm] (divided by curve length).

• inductance (float | None) –

  Absolute inductance [H] (divided by curve length).

• attributes (list[int] | None) –

  Direct Palace boundary attribute list (bypasses layer lookup). When set, Rs/Ls/Cs must be in per-unit-length values.

• name (str | None) –

  Optional display name.

Bases: _LayerPairSpec

Named interface between two semiconductor layers on the native-2D mesh.

The shared curves between the two layers' meshed regions are tagged as a dim-1 physical group named name, so a charge-transport solver can bind continuity across it (DEVSIM add_gmsh_interface) by name. An Interface carries no terminal voltage — that is what separates it from a :class:ContactSpec, and why the two are declared apart.

Attributes:

• name (str) –

  Physical-group name of the interface (e.g. "junction").

• layer_a (str) –

  First semiconductor layer.

• layer_b (str) –

  Second semiconductor layer.

Bases: BaseModel

Linear solve controls, shared by all Palace simulation types.

tolerance is the relative residual tolerance of each linear solve. Eigenvalue convergence is configured separately under solver.eigenmode. Direct backends are more robust but can use more memory than iterative solves.

Methods:

• to_palace_config –

  Convert to Palace's Solver.Linear block.

to_palace_config() -> dict[str, Any]

Bases: BaseModel

Configuration for magnetostatic (inductance matrix) simulation.

Attributes:

• save_fields (int) –

  Number of field solutions to save

Methods:

• to_palace_config –

  Convert to Palace JSON config format.

to_palace_config() -> dict

Bases: BaseModel

EM properties for a material.

Used for material property overrides in simulation classes.

Attributes:

• type (Literal['conductor', 'dielectric', 'semiconductor']) –

  Material type (conductor, dielectric, or semiconductor)

• conductivity (float | None) –

  Conductivity in S/m (for conductors)

• permittivity (float | None) –

  Relative permittivity (for dielectrics)

• loss_tangent (float | None) –

  Dielectric loss tangent

Methods:

• conductor –

  Create a conductor material.

• dielectric –

  Create a dielectric material.

• to_dict –

  Convert to dictionary for YAML output.

conductor(conductivity: float = 58000000.0) -> Self

dielectric(permittivity: float, loss_tangent: float = 0.0) -> Self

to_dict() -> dict[str, object]

Bases: BaseModel

Configuration for mesh generation with quality presets.

Attributes:

• refined_mesh_size (float) –

  Mesh size near conductors (um)

• max_mesh_size (float) –

  Maximum mesh size in air/dielectric (um)

• cells_per_wavelength (int) –

  Number of mesh cells per wavelength

• margin (float) –

  XY margin around design (um)

• margin_x (float | None) –

  X-axis margin override (um). Falls back to margin.

• margin_y (float | None) –

  Y-axis margin override (um). Falls back to margin.

• airbox_margin (float) –

  Extra airbox around stack (um); 0 = disabled

• fmax (float) –

  Maximum frequency for mesh sizing (Hz)

• boundary_conditions (list[str] | None) –

  List of boundary conditions for each face

• planar_conductors (bool) –

  Treat conductors as 2D PEC surfaces instead of volumes

• refinement_boxes (list[tuple[float, float, float, float, float]]) –

  Boxes of a native-2D cross-section mesh held to an element size, each (h_min, h_max, z_min, z_max, size) in um. Refinement lines size the elements on them only, and the size grows at once with the distance; a box holds it over an area

• algorithm_3d (Literal['delaunay', 'hxt']) –

  Gmsh 3D meshing algorithm, "delaunay" or "hxt". In the 800 um CPW tests behind gsim#283 HXT gave a different mesh and was slower than Delaunay at every thread count.

• threads (int) –

  Threads for 3D meshing. With Delaunay and surface_threads=1 the mesh does not depend on it, and it did not speed meshing up in those tests either. With HXT the mesh depends on the thread count.

• surface_threads (int) –

  Threads for 1D and 2D (surface) meshing. Values above 1 are faster but gave a different mesh on every run, so keep 1 when the mesh must be reproducible.

• show_gui (bool) –

  Show gmsh GUI during meshing

• preview_only (bool) –

  Generate preview only, don't save mesh

Methods:

• coarse –

  Fast mesh for quick iteration (~2.5 elements per wavelength).

• default –

  Balanced mesh (~5 elements per wavelength).

• fine –

  High accuracy mesh (~10 elements per wavelength).

• set_default_boundary_conditions –

  Set default boundary conditions if not provided.

• validate_refinement_boxes –

  Every box spans an area and has a size to hold it to.

effective_margin_x: float

effective_margin_y: float

coarse(**kwargs: Any) -> Self

default(**kwargs: Any) -> Self

fine(**kwargs: Any) -> Self

set_default_boundary_conditions() -> Self

validate_refinement_boxes(
    boxes: list[tuple[float, float, float, float, float]],
) -> list[tuple[float, float, float, float, float]]

Bases: BaseModel

Deprecated numerical settings; use SolverConfig with a linear group.

Legacy flat constructor arguments, properties and serialization are retained.

Methods:

• flatten_grouped_linear_settings –

  Retain numerical values when copying a grouped solver dump.

• to_linear_solver_config –

  Convert to the legacy Palace Solver.Linear block.

• to_palace_config –

  Convert to the legacy Palace Solver block.

• to_solver_config –

  Convert to the legacy Palace Solver block.

flatten_grouped_linear_settings(values: Any) -> Any

to_linear_solver_config() -> dict[str, object]

to_palace_config() -> dict[str, object]

to_solver_config() -> dict[str, object]

Bases: BaseModel

Configuration for a PEC (Perfect Electric Conductor) block.

A PEC block is a user-drawn polygon on a GDS layer that gets extruded between two stack layers and treated as a PEC boundary. This is a common practice in commercial EM solvers for connecting ground planes across metal layers at port boundaries in terminal-driven simulations.

Attributes:

• gds_layer (tuple[int, int]) –

  GDS layer tuple where the PEC polygon is drawn.

• from_layer (str) –

  Stack layer name — extrusion starts at this layer's zmin.

• to_layer (str) –

  Stack layer name — extrusion ends at this layer's zmax.

Bases: BaseModel

Configuration for a single-element lumped port.

Lumped ports can be inplane, gap, or interlayer. CPW ports use :class:CPWPortConfig because they require two gap elements.

Attributes:

• name (str) –

  Port name (must match component port name)

• layer (str | None) –

  Target layer for inplane ports

• from_layer (str | None) –

  First conductor layer for interlayer ports

• to_layer (str | None) –

  Second conductor layer for interlayer ports

• length (float | None) –

  Port extent along direction (um)

• offset (float) –

  Shift port inward along the waveguide (um). Positive = away from boundary, into conductor.

• impedance (float) –

  Port impedance (Ohms)

• excited (bool) –

  Whether this port is excited

• geometry (Literal['inplane', 'gap', 'interlayer', 'via']) –

  Lumped-port surface geometry. "via" remains as a deprecated alias for "interlayer".

Methods:

• normalize_legacy_geometry –

  Normalize deprecated geometry names before field validation.

• validate_layer_config –

  Validate layer configuration based on geometry type.

normalize_legacy_geometry(data: Any) -> Any

validate_layer_config() -> Self

Bases: BaseModel

Adaptive mesh refinement (AMR) controls for Palace.

Maps onto config["Model"]["Refinement"]. Palace refines the elements that carry most of its estimated error and re-solves, until the error norm falls below tol, max_its passes have run, or the problem reaches max_dofs degrees of freedom. The defaults leave AMR off, as before.

In a frequency sweep, Palace refines on the error indicator averaged over the sampled frequencies, so a narrow resonance can end up under-refined.

Attributes:

• tol (float) –

  Stop refining when the norm of the estimated error falls below this value.

• max_its (int) –

  Maximum number of AMR passes. 0 disables AMR.

• uniform_levels (int) –

  Levels of uniform refinement applied to the input mesh before solving. Each level splits every tetrahedron into eight, so a coarse mesh file can stand in for a much finer mesh.

• max_dofs (int | None) –

  Maximum number of degrees of freedom AMR may reach (Palace's MaxSize). None leaves Palace's default, no limit.

• update_fraction (float | None) –

  Dörfler marking fraction, the share of the estimated error carried by the elements refined in each pass.

• nonconformal (bool | None) –

  Refine with hanging nodes instead of conformally.

• max_nc_levels (int | None) –

  Maximum number of nonconformal refinement levels. 0 means no limit.

• save_adapt_iterations (bool | None) –

  Keep the postprocessing output of every pass in an iterationX subdirectory.

• save_adapt_mesh (bool | None) –

  Save the final adapted mesh.

Fields left as None are not written, so Palace applies its own defaults.

Methods:

• to_palace_config –

  Convert to the Palace Model.Refinement block.

to_palace_config() -> dict

Bases: BaseModel

Result from running a Palace simulation.

Attributes:

• mesh_path (Path) –

  Path to the generated mesh file

• output_dir (Path) –

  Output directory path

• config_path (Path | None) –

  Path to the Palace config file

• results (dict[str, Path]) –

  Dictionary mapping result filenames to paths

• conductor_groups (dict) –

  Physical group info for conductors

• dielectric_groups (dict) –

  Physical group info for dielectrics

• port_groups (dict) –

  Physical group info for ports

• boundary_groups (dict) –

  Physical group info for boundaries

• port_info (list) –

  Port metadata

• metadata (dict) –

  Versioned JSON-compatible mesh measurements and sizing hints

Bases: BaseModel

Common Palace solver settings.

order is the finite element field order, independent of mesh geometry order. Order 2 is the default; higher orders increase the solve size. Simulation-specific subclasses add the applicable problem configuration. Legacy flat linear keywords and properties remain supported.

Methods:

• group_legacy_linear_settings –

  Accept the former NumericalConfig flat linear settings.

• to_linear_solver_config –

  Convert common settings to Palace's Solver.Linear block.

• to_palace_config –

  Convert all configured solver groups to Palace's Solver block.

• to_solver_config –

  Convert common settings to Palace's Solver block.

Attributes:

• max_iterations (int) –

  Compatibility alias for linear.max_iterations.

• preconditioner (Literal['Default', 'AMS', 'BoomerAMG']) –

  Compatibility alias for linear.preconditioner.

• solver_type (Literal['Default', 'SuperLU', 'STRUMPACK', 'MUMPS']) –

  Compatibility alias for linear.solver_type.

• tolerance (float) –

  Compatibility alias for linear.tolerance.

max_iterations: int

preconditioner: Literal['Default', 'AMS', 'BoomerAMG']

solver_type: Literal['Default', 'SuperLU', 'STRUMPACK', 'MUMPS']

tolerance: float

group_legacy_linear_settings(values: Any) -> Any

to_linear_solver_config() -> dict[str, object]

to_palace_config() -> dict[str, Any]

to_solver_config() -> dict[str, object]

Bases: BaseModel

A PEC or PMC symmetry plane that cuts the model in half.

Attributes:

• axis (Literal['x', 'y']) –

  Axis normal to the plane ("x" or "y").

• position (float) –

  Plane position along axis in um. Alignment to the owning layout's database grid is checked during geometry extraction.

• kind (Literal['pec', 'pmc']) –

  "pmc" (even/common mode) or "pec" (odd/differential mode).

• keep (Literal['positive', 'negative']) –

  Which side of the plane is simulated.

• verify_symmetry (bool) –

  Check that the layout is mirror-symmetric.

Bases: BaseModel

Configuration for a terminal (for electrostatic capacitance extraction).

Terminals define conductor surfaces for capacitance matrix extraction in electrostatic simulations. A terminal selects conductors in one of three ways, and at least one of layer, net and region is needed:

• layer alone: every conductor shape on that layer (the layer mode; two separate electrodes on one layer are then one terminal).
• net: the connected conductor with that name, metal and vias on every layer it spans (see ElectrostaticSim.nets()).
• region: every connected conductor with a shape inside the region, optionally only on layer.

net cannot be combined with region or layer.

Attributes:

• name (str) –

  Terminal name

• layer (str | None) –

  Target conductor layer. With region it limits the shapes that are tested against the region.

• net (str | None) –

  Name of a net (the names of its ports joined by +, or net<k>), or the name of a port on it.

• region (tuple[float, float, float, float] | list[tuple[float, float]] | None) –

  Box (xmin, ymin, xmax, ymax) or list of at least three (x, y) points of a polygon, in um.

• floating (bool) –

  The conductor is not driven: it is solved as a terminal and eliminated from the capacitance matrix afterwards.

Methods:

• region_polygon –

  The region as a shapely polygon (um), or None when there is none.

region_polygon() -> Polygon | None

Bases: BaseModel

Configuration for transient (time-domain) simulation.

Attributes:

• max_time (float) –

  Maximum simulation time in ns

• excitation (Literal['sinusoidal', 'gaussian', 'ramp', 'smoothstep']) –

  Excitation waveform type

• excitation_freq (float | None) –

  Excitation frequency in Hz (for sinusoidal)

• excitation_width (float | None) –

  Pulse width in ns (for gaussian)

• time_step (float) –

  Required positive time step in ns.

Methods:

• to_palace_config –

  Convert to Palace JSON config format.

to_palace_config() -> dict

Bases: BaseModel

Configuration for a two-terminal lumped port (single Palace port, two elements).

Both terminals are combined into one Palace LumpedPort with two EDGE-geometry elements (vertical surfaces spanning the conductor thickness), collapsing the simulation to a true 1-port S11 measurement on a coplanar device.

Attributes:

• plus_port (str) –

  GDS port name for the + (excitation) terminal

• minus_port (str) –

  GDS port name for the - (reference) terminal

• layer (str) –

  Conductor layer containing both terminals (e.g., "metal1")

• impedance (float) –

  Port impedance in Ohms

• excited (bool) –

  Whether this port is excited

Bases: BaseModel

Result of simulation configuration validation.

Attributes:

• valid (bool) –

  Whether the configuration is valid

• errors (list[str]) –

  List of error messages

• warnings (list[str]) –

  List of warning messages

Bases: BaseModel

Configuration for a wave port (domain boundary with mode solving).

Wave ports are used for domain-boundary ports where mode solving is needed. This is an alternative to lumped ports for more accurate S-parameter extraction.

Attributes:

• name (str) –

  Port name (must match component port name)

• layer (str | None) –

  Target conductor layer

• z_margin (float) –

  Margin to extend port geometry in z-direction (um)

• max_size (bool) –

  If True, set z_margin and lateral_margin to

• mode (int) –

  Mode number to excite

• offset (float) –

  De-embedding distance in um

• excited (bool) –

  Whether this port is excited

• eigensolver_type (Literal['Default', 'SLEPc', 'ARPACK'] | None) –

  Palace SolverType for this port's 2D mode eigenproblem ("Default", "SLEPc" or "ARPACK"). None uses Palace's own default.

• eigensolver_tol (float | None) –

  Palace EigenTol (eigenvalue solver relative tolerance) for this port's mode solve. None uses Palace's own default.

• eigensolver_ksp_tol (float | None) –

  Palace KSPTol (linear solver tolerance used inside the eigenvalue iteration) for this port's mode solve. None uses Palace's own default.

• eigensolver_max_size (int | None) –

  Palace MaxSize (eigensolver subspace dimension) for this port's mode solve - unrelated to the max_size domain-filling flag above. None lets Palace pick its own default (max(2 x Mode, Mode + 15)).

• eigensolver_verbose (int | None) –

  Palace Verbose level for this port's mode solve. None uses Palace's own default.