Skip to content

eigenmode

Eigenmode simulation class for resonance/mode finding.

This module provides the EigenmodeSim class for finding resonant frequencies and mode shapes.

Classes:

  • EigenmodeSim –

    Eigenmode simulation for finding resonant frequencies.

EigenmodeSim

Bases: _PalaceSimBase

Eigenmode simulation for finding resonant frequencies.

This class configures and runs eigenmode simulations to find resonant frequencies and mode shapes of structures.

Example

from gsim.palace import EigenmodeSim

sim = EigenmodeSim() sim.set_geometry(component) sim.set_stack() sim.set_airbox(margin_x=120.0, margin_above=120.0, margin_below=20.0) sim.add_port("o1", layer="topmetal2", length=5.0) sim.solver.eigenmode.target = 50e9 sim.set_output_dir("./sim") sim.mesh(preset="default") results = sim.run() # dict[str, Path] print(results["eig.csv"])

Attributes:

Methods:

  • add_cpw_port –

    Add a coplanar waveguide (CPW) port.

  • add_impedance_boundary –

    Add an Impedance boundary on the interface between two dielectric layers.

  • add_multimode_wave_port –

    Add a wave port that follows several modes on one port face.

  • add_pec –

    Add a PEC block between two stack layers.

  • add_port –

    Add a single-element lumped port.

  • add_symmetry_plane –

    Simulate half of a mirror-symmetric structure.

  • add_two_terminal_port –

    Add a two-terminal lumped port for true 1-port S11 simulation.

  • add_wave_port –

    Add a single element wave port.

  • get_status –

    Get the current status of this simulation's cloud job.

  • group_legacy_solver_settings –

    Move legacy constructor arguments into their solver groups.

  • mesh –

    Generate the mesh for Palace simulation.

  • nets –

    Find the electrically connected conductor shapes of the geometry.

  • plot_mesh –

    Plot the mesh using PyVista.

  • plot_stack –

    Plot the layer stack visualization.

  • preview –

    Preview the mesh without running simulation.

  • print_mesh_stats –

    Print mesh statistics from the last mesh generation.

  • reuse_mesh –

    Take the mesh of another meshed simulation instead of meshing.

  • run –

    Run the eigenmode sim on GDSFactory+ cloud.

  • run_local –

    Run simulation locally using Palace.

  • set_airbox –

    Configure an explicit weak-priority airbox for meshing.

  • set_eigenmode –

    Configure eigenmode simulation.

  • set_geometry –

    Set the gdsfactory component for simulation.

  • set_material –

    Override or add material properties.

  • set_numerical –

    Deprecated alias for set_solver, with the same order-2 defaults.

  • set_output_dir –

    Set the output directory for mesh and config files.

  • set_pn_junction –

    Apply the depletion capacitance of a PN junction between two layers.

  • set_refinement –

    Configure Palace's adaptive mesh refinement (AMR).

  • set_solver –

    Set common solver controls, preserving problem-specific settings.

  • set_stack –

    Configure the layer stack.

  • show_stack –

    Print the layer stack table.

  • start –

    Start cloud execution for this simulation's uploaded job.

  • upload –

    Write the inputs and upload them. Does NOT start execution.

  • validate_config –

    Validate the simulation configuration.

  • validate_mesh –

    Validate the generated mesh and config before cloud submission.

  • wait_for_results –

    Wait for this simulation's cloud job, then download and parse results.

  • write_config –

    Write Palace config.json after mesh generation.

boundary_mode property writable

boundary_mode: BoundaryModeConfig | None

Compatibility alias for solver.boundary_mode (None for other modes).

component property

component: Component | None

Get the current component (for backward compatibility).

driven property writable

driven: DrivenConfig | None

Compatibility alias for solver.driven (None for other modes).

eigenmode property writable

eigenmode: EigenmodeConfig

Deprecated alias for solver.eigenmode, retaining the original type.

electrostatic property writable

electrostatic: ElectrostaticConfig | None

Compatibility alias for solver.electrostatic (None for other modes).

has_mesh property

has_mesh: bool

Whether mesh() has run and left a mesh to read.

mesh_groups property

mesh_groups: dict[str, Any]

Physical groups of the generated mesh, once meshed.

Raises:

mesh_path property

mesh_path: Path

Path of the generated mesh (um), once meshed.

Raises:

numerical property writable

numerical: SolverConfig

Compatibility alias for the common controls in solver.

output_dir property

output_dir: Path | None

Get the current output directory.

add_cpw_port

add_cpw_port(
    name: str,
    *,
    layer: str,
    s_width: float,
    gap_width: float,
    length: float = 2.0,
    offset: float | None = None,
    impedance: float = 50.0,
    excited: bool = True,
) -> None

Add 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.

Place a single gdsfactory port at the center of the signal conductor. The two gap element surfaces are computed from s_width and gap_width.

Parameters:

  • name (str) –

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

  • layer (str) –

    Target conductor layer (e.g., "topmetal2")

  • s_width (float) –

    Width of the signal (center) conductor (um)

  • gap_width (float) –

    Width of each gap between signal and ground (um)

  • length (float, default: 2.0 ) –

    Port extent along direction (um)

  • offset (float | None, default: None ) –

    Shift the port inward along the waveguide (um). Positive moves away from the boundary, into the conductor. Defaults to length/2 (port flush with conductor edge).

  • impedance (float, default: 50.0 ) –

    Port impedance (Ohms)

  • excited (bool, default: True ) –

    Whether this port is excited

Example

sim.add_cpw_port( ... "left", layer="topmetal2", s_width=20, gap_width=15, length=5.0 ... )

add_impedance_boundary

add_impedance_boundary(
    layer_a: str,
    layer_b: str,
    *,
    capacitance: float | None = None,
    resistance: float | None = None,
    inductance: float | None = None,
    name: str | None = None,
) -> None

Add an Impedance boundary on the interface between two dielectric layers.

The capacitance, resistance, and inductance values are absolute and are divided by the interface curve length internally to produce the per-unit-length Cs, Rs, Ls values expected by Palace.

Parameters:

  • layer_a (str) –

    First dielectric layer name.

  • layer_b (str) –

    Second dielectric layer name.

  • capacitance (float | None, default: None ) –

    Absolute capacitance [F].

  • resistance (float | None, default: None ) –

    Absolute resistance [Ohm].

  • inductance (float | None, default: None ) –

    Absolute inductance [H].

  • name (str | None, default: None ) –

    Optional display name.

add_multimode_wave_port

add_multimode_wave_port(
    name: str,
    *,
    modes: Sequence[int],
    layer: str | None = None,
    active_mode: int = 1,
    excite: Literal["active", "all"] = "active",
    pilot_paths: Mapping[int, Sequence[Sequence[float]]] | None = None,
    z_margin: float = 0.0,
    lateral_margin: float = 0.0,
    max_size: bool = False,
    excited: bool = True,
    offset: float = 0.0,
    eigensolver_type: Literal["Default", "SLEPc", "ARPACK"] | None = None,
    eigensolver_tol: float | None = None,
    eigensolver_ksp_tol: float | None = None,
    eigensolver_max_size: int | None = None,
    eigensolver_verbose: int | None = None,
) -> None

Add a wave port that follows several modes on one port face.

The port keeps one boundary surface. Palace gets one WavePort entry per mode on that surface: the entry of active_mode keeps the port's own index and terminates the face, and every other mode is an observation-only entry ("Active": false) with an index after all the ports, so the active entry always has the lowest index of its face, which Palace requires. Every entry solves its own 2D port mode, and every entry is measured, so port-S.csv gets a column per entry and excitation. The map from Palace index to (port, mode, active) is written next to config.json as port_modes.json.

Only the active entry loads the face. A wave that arrives in another mode is not matched there, so the S-parameters of the observed modes carry a reflection error of the order of the relative difference of the wave numbers. The error is zero for the active mode. To get every mode with the active-mode accuracy, run once per mode with that mode as active_mode and use only the columns of the active entries.

Parameters:

  • name (str) –

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

  • modes (Sequence[int]) –

    The Palace mode numbers (1-based) to follow on this face, for example (1, 2, 3). Must contain active_mode.

  • layer (str | None, default: None ) –

    Target conductor layer.

  • active_mode (int, default: 1 ) –

    The mode that terminates the face.

  • excite (Literal['active', 'all'], default: 'active' ) –

    "active" excites only the active entry (one excitation per port); "all" excites every entry, which gives a column per mode but excites the unmatched modes with an amplitude that is off by the same mismatch.

  • pilot_paths (Mapping[int, Sequence[Sequence[float]]] | None, default: None ) –

    Optional {mode: points}. Each path is an open polyline of (x, y, z) points in um across the face, from the signal (high-potential) conductor to the reference, and becomes that entry's VoltagePath: Palace flips the mode so the line integral of E along it is positive, which pins the sign of the mode, and writes the voltage to port-V.csv.

  • z_margin (float, default: 0.0 ) –

    Margin in z direction.

  • lateral_margin (float, default: 0.0 ) –

    Margin in x/y directions.

  • max_size (bool, default: False ) –

    Fill the full simulation domain boundary on that side.

  • excited (bool, default: True ) –

    Whether the port is excited at all.

  • offset (float, default: 0.0 ) –

    Offset distance used for scattering parameter de-embedding.

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

    Palace SolverType of the 2D mode eigenproblem.

  • eigensolver_tol (float | None, default: None ) –

    Palace EigenTol of the mode solve.

  • eigensolver_ksp_tol (float | None, default: None ) –

    Palace KSPTol of the mode solve.

  • eigensolver_max_size (int | None, default: None ) –

    Palace MaxSize of the mode solve.

  • eigensolver_verbose (int | None, default: None ) –

    Palace Verbose level of the mode solve.

Raises:

  • ValueError –

    If this is not a driven simulation, or the modes, active mode or pilot paths are inconsistent.

Example

sim.add_multimode_wave_port( ... "o1", ... layer="metal3", ... modes=(1, 2, 3), ... active_mode=1, ... max_size=True, ... )

add_pec

add_pec(*, gds_layer: tuple[int, int], from_layer: str, to_layer: str) -> None

Add a PEC block between two stack layers.

The PEC block is a user-drawn polygon on a GDS layer that gets extruded between from_layer.zmin and to_layer.zmax 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.

Parameters:

  • 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.

Example

sim.add_pec( ... gds_layer=(65000, 0), from_layer="metal1", to_layer="topmetal2" ... )

add_port

add_port(
    name: str,
    *,
    layer: str | None = None,
    from_layer: str | None = None,
    to_layer: str | None = None,
    length: float | None = None,
    offset: float = 0.0,
    impedance: float = 50.0,
    resistance: float | None = None,
    inductance: float | None = None,
    capacitance: float | None = None,
    excited: bool = True,
    geometry: Literal["inplane", "gap", "interlayer", "via"] = "inplane",
) -> None

Add a single-element lumped port.

Parameters:

  • name (str) –

    Port name (must match component port name)

  • layer (str | None, default: None ) –

    Target layer for inplane ports

  • from_layer (str | None, default: None ) –

    First conductor layer for interlayer ports

  • to_layer (str | None, default: None ) –

    Second conductor layer for interlayer ports

  • length (float | None, default: None ) –

    Port extent along direction (um)

  • offset (float, default: 0.0 ) –

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

  • impedance (float, default: 50.0 ) –

    Port impedance (Ohms)

  • resistance (float | None, default: None ) –

    Series resistance (Ohms)

  • inductance (float | None, default: None ) –

    Series inductance (H)

  • capacitance (float | None, default: None ) –

    Shunt capacitance (F)

  • excited (bool, default: True ) –

    Whether this port is excited

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

    "inplane", "gap", or "interlayer". Gap ports are vertical sheets with GDS width spanning the gap along orientation, centered in the gap and extending through the conductor layer thickness. Gap ports currently require cardinal orientations; omit length. "interlayer" creates a Z-directed sheet between two layers. "via" is a deprecated alias for "interlayer". Use :meth:add_cpw_port for the "cpw" lumped-port geometry.

Example

sim.add_port("o1", layer="topmetal2", length=5.0) sim.add_port( ... "feed", ... from_layer="metal1", ... to_layer="topmetal2", ... geometry="interlayer", ... )

add_symmetry_plane

add_symmetry_plane(
    axis: Literal["x", "y"] = "y",
    position: float = 0.0,
    kind: Literal["pec", "pmc"] = "pmc",
    keep: Literal["positive", "negative"] = "positive",
    *,
    verify_symmetry: bool = True,
) -> None

Simulate half of a mirror-symmetric structure.

A PMC plane selects the even (common) mode, a PEC plane the odd (differential) mode. Only one plane is supported, and only for driven and eigenmode simulations.

Parameters:

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

    Axis normal to the plane.

  • position (float, default: 0.0 ) –

    Plane position along axis in um, aligned to the owning layout's database grid. Checked during geometry extraction.

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

    "pmc" (even mode) or "pec" (odd mode).

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

    Side of the plane that is simulated.

  • verify_symmetry (bool, default: True ) –

    Check that the layout is mirror-symmetric.

Raises:

Example

sim.add_symmetry_plane(axis="y", position=0.0, kind="pec")

add_two_terminal_port

add_two_terminal_port(
    plus_port: str,
    minus_port: str,
    *,
    layer: str,
    impedance: float = 50.0,
    excited: bool = True,
) -> None

Add a two-terminal lumped port for true 1-port S11 simulation.

Combines two GDS ports into a single Palace LumpedPort with two EDGE-geometry elements (vertical surfaces spanning the conductor thickness). No artificial reference layer is needed — P1 is the excitation and P2 is the reference, both on the same metal layer.

Parameters:

  • 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, default: 50.0 ) –

    Port impedance in Ohms (default: 50)

  • excited (bool, default: True ) –

    Whether this port is excited (default: True)

Example

sim.add_two_terminal_port("P1", "P2", layer="metal1", excited=True)

add_wave_port

add_wave_port(
    name: str,
    *,
    layer: str | None = None,
    z_margin: float = 0.0,
    lateral_margin: float = 0.0,
    max_size: bool = False,
    mode: int = 1,
    excited: bool = True,
    offset: float = 0.0,
    eigensolver_type: Literal["Default", "SLEPc", "ARPACK"] | None = None,
    eigensolver_tol: float | None = None,
    eigensolver_ksp_tol: float | None = None,
    eigensolver_max_size: int | None = None,
    eigensolver_verbose: int | None = None,
) -> None

Add a single element wave port.

Parameters:

  • name (str) –

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

  • layer (str | None, default: None ) –

    Target conductor layer (e.g., "topmetal2")

  • z_margin (float, default: 0.0 ) –

    Margin in z direction

  • lateral_margin (float, default: 0.0 ) –

    Margin in x/y directions Ignores lateral margin and port_width.

  • max_size (bool, default: False ) –

    When True, automatically set z_margin and lateral_margin to fill the full simulation domain boundary on that side. Overrides z_margin and lateral_margin values.

  • mode (int, default: 1 ) –

    Mode number to excite.

  • excited (bool, default: True ) –

    Whether this port is excited

  • offset (float, default: 0.0 ) –

    Offset distance used for scattering parameter de-embedding.

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

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

  • eigensolver_tol (float | None, default: None ) –

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

  • eigensolver_ksp_tol (float | None, default: None ) –

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

  • eigensolver_max_size (int | None, default: None ) –

    Palace MaxSize (eigensolver subspace dimension) for this port's mode solve - unrelated to max_size above, which sizes geometry. None lets Palace pick its own default.

  • eigensolver_verbose (int | None, default: None ) –

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

Example

sim.add_wave_port( ... "w1", ... layer="topmetal2", ... max_size=True, ... mode=1, ... excited=True, ... offset=0.0, ... )

get_status

get_status() -> str

Get the current status of this simulation's cloud job.

Returns:

  • str –

    Status string ("created", "queued", "running",

  • str –

    "completed", "failed").

Raises:

  • ValueError –

    If no job has been submitted yet.

group_legacy_solver_settings classmethod

group_legacy_solver_settings(values: Any) -> Any

Move legacy constructor arguments into their solver groups.

mesh

mesh(
    *,
    preset: Literal["coarse", "default", "fine"] | None = None,
    refined_mesh_size: float | None = None,
    max_mesh_size: float | None = None,
    margin: float | None = None,
    margin_x: float | None = None,
    margin_y: float | None = None,
    z_above: float | None = None,
    z_below: float | None = None,
    airbox_margin: float | None = None,
    fmax: float | None = None,
    planar_conductors: bool | None = None,
    show_gui: bool = False,
    model_name: str = "palace",
    verbose: bool = True,
    verbosity: int = 0,
    auto_size: bool = False,
    cells_per_feature: int = 2,
    periodic_axis: str | None = None,
    decimate_tolerance: float | None = None,
    merge_via_distance: float | None = None,
    clip_merged_vias: bool | None = None,
    curve_fit_mode: Literal["line", "spline", "bspline"] | None = None,
    curve_fit_layers: list[str] | None = None,
    curve_fit_tolerance_um: float | None = None,
    curve_fit_min_points: int | None = None,
    curve_fit_corner_angle_deg: float | None = None,
    high_order_elements: bool | None = None,
    high_order_order: int | None = None,
    high_order_optimize: bool | None = None,
    refinement_boxes: list[tuple[float, float, float, float, float]] | None = None,
    mesh_grading: MeshGrading | None = None,
    algorithm_3d: Literal["delaunay", "hxt"] | None = None,
    threads: int | None = None,
    surface_threads: int | None = None,
) -> SimulationResult

Generate the mesh for Palace simulation.

Only generates the mesh file (palace.msh). Config is generated separately with write_config().

Requires set_output_dir() to be called first.

Parameters:

  • preset (Literal['coarse', 'default', 'fine'] | None, default: None ) –

    Mesh quality preset ("coarse", "default", "fine")

  • refined_mesh_size (float | None, default: None ) –

    Mesh size near conductors (um), overrides preset

  • max_mesh_size (float | None, default: None ) –

    Max mesh size in air/dielectric (um), overrides preset

  • margin (float | None, default: None ) –

    XY margin around design (um), overrides preset

  • margin_x (float | None, default: None ) –

    X-axis margin (um). Overrides margin for X.

  • margin_y (float | None, default: None ) –

    Y-axis margin (um). Overrides margin for Y.

  • z_above (float | None, default: None ) –

    Airbox extension above stack top (um).

  • z_below (float | None, default: None ) –

    Airbox extension below stack bottom (um).

  • airbox_margin (float | None, default: None ) –

    Deprecated. Use set_airbox().

  • fmax (float | None, default: None ) –

    Max frequency for mesh sizing (Hz), overrides preset

  • planar_conductors (bool | None, default: None ) –

    Treat conductors as 2D PEC surfaces

  • show_gui (bool, default: False ) –

    Show gmsh GUI during meshing

  • model_name (str, default: 'palace' ) –

    Base name for output files: <model_name>.msh and output/<model_name>. A plain name, without path separators

  • verbose (bool, default: True ) –

    Print progress messages

  • verbosity (int, default: 0 ) –

    Gmsh OCC verbosity level (0=silent, 1-99=increasing)

  • auto_size (bool, default: False ) –

    If True, scale refined_mesh_size down to the smallest conductor feature / cells_per_feature. Off by default so presets use their literal refined_mesh_size. Explicit refined_mesh_size overrides always bypass auto-sizing.

  • cells_per_feature (int, default: 2 ) –

    Target cells across the smallest conductor feature for auto-sizing and resolution warnings. Default 2.

  • periodic_axis (str | None, default: None ) –

    Optional periodic axis ("x" or "y") for periodic meshing constraints on opposite domain sides.

  • decimate_tolerance (float | None, default: None ) –

    Relative tolerance for polygon decimation (None = no decimation; typical 0.001-0.01). Reduces vertex count on curved geometry before meshing.

  • merge_via_distance (float | None, default: None ) –

    Max gap (um) between nearby via polygons to merge before extrusion. Pass 0 to disable merging (keep each via as a separate volume). Defaults to the preset's value (typically 2.0 um). Merging fills the gaps between the vias, so a dense via array can grow to several times its drawn area; a warning is logged when the area grows by more than 5%.

  • clip_merged_vias (bool | None, default: None ) –

    Clip each merged via polygon to the overlap of the conductor layers directly below and above its layer, so merging adds no via area outside the metal. The drawn cuts are always kept, and contacts on substrate or dielectric stay as drawn. Defaults to the value in sim.mesh_config (False). A slab that lies entirely between two continuous metals is left unchanged; merge_via_distance=0 keeps every cut there.

  • curve_fit_mode (Literal['line', 'spline', 'bspline'] | None, default: None ) –

    Patterned dielectric boundary mode (line/spline/bspline).

  • curve_fit_layers (list[str] | None, default: None ) –

    Layer names where spline fitting is applied.

  • curve_fit_tolerance_um (float | None, default: None ) –

    Point merge tolerance before fitting.

  • curve_fit_min_points (int | None, default: None ) –

    Min contour points required to fit curves.

  • curve_fit_corner_angle_deg (float | None, default: None ) –

    Turn-angle threshold used to split sharp corners from smooth curve-fit segments.

  • high_order_elements (bool | None, default: None ) –

    Enable high-order geometric mesh elements.

  • high_order_order (int | None, default: None ) –

    Polynomial order for high-order elements.

  • high_order_optimize (bool | None, default: None ) –

    Run gmsh high-order optimization after meshing.

  • refinement_boxes (list[tuple[float, float, float, float, float]] | None, default: None ) –

    Native-2D cross-section meshes only: boxes 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; a box holds the size over an area.

  • mesh_grading (MeshGrading | None, default: None ) –

    Native-2D cross-section meshes only: a :class:~gsim.palace.models.MeshGrading whose element size grows from chosen features at a set rate per um, in place of the fixed growth from every internal curve. Defaults to the value in sim.mesh_config (None, the fixed growth).

  • algorithm_3d (Literal['delaunay', 'hxt'] | None, default: None ) –

    Gmsh 3D meshing algorithm, "delaunay" or "hxt".

  • threads (int | None, default: None ) –

    Threads for 3D meshing (see MeshConfig).

  • surface_threads (int | None, default: None ) –

    Threads for 1D and 2D meshing. Above 1 the mesh differs from run to run.

Returns:

Raises:

  • ValueError –

    If output_dir not set, configuration is invalid, or model_name is not a plain file name

Example

sim.set_output_dir("./sim") result = sim.mesh(preset="fine", planar_conductors=True) print(f"Mesh saved to: {result.mesh_path}")

nets

nets() -> Nets

Find the electrically connected conductor shapes of the geometry.

Metal that touches on one layer, and metal on different layers that a via joins, is one net; disconnected electrodes stay separate even when they share a layer. Electrical ports name the nets they sit on.

Terminals select nets by these names: add_terminal(name, net=...) takes the name above or the name of one of its ports. A terminal given only layer= still takes every shape on its layer when no terminal uses nets, so two disconnected electrodes on one layer are then a single terminal. This shows how many electrodes each layer holds.

Returns:

  • Nets –

    The nets, in the order their first shape appears in the layout.

Raises:

Example

print(sim.nets())

plot_mesh

plot_mesh(
    output: str | Path | None = None,
    show_groups: list[str] | None = None,
    interactive: bool | None = None,
    style: Literal["wireframe", "solid"] = "wireframe",
    transparent_groups: list[str] | None = None,
) -> None

Plot the mesh using PyVista.

Requires mesh() to be called first.

Parameters:

  • output (str | Path | None, default: None ) –

    Output PNG path (only used for static rendering).

  • show_groups (list[str] | None, default: None ) –

    List of group name patterns to show (None = all). Example: ["metal", "P"] to show metal layers and ports.

  • interactive (bool | None, default: None ) –

    If True, force an interactive 3D viewer (a widget on the shared trame server in a notebook, or a blocking window otherwise). If False, save a static PNG. If None (default), follow the session flag from gsim.viz.set_interactive_mode — off by default, so plots render statically until enabled.

  • style (Literal['wireframe', 'solid'], default: 'wireframe' ) –

    "wireframe" (edges only) or "solid" (coloured surfaces per physical group).

  • transparent_groups (list[str] | None, default: None ) –

    Group names rendered at low opacity in solid mode. Ignored in wireframe mode.

Raises:

  • ValueError –

    If output_dir not set or mesh file doesn't exist

Example

sim.mesh(preset="default") sim.plot_mesh(show_groups=["metal", "P"]) sim.plot_mesh(style="solid", transparent_groups=["Absorbing_boundary"])

plot_stack

plot_stack() -> None

Plot the layer stack visualization.

Example

sim.plot_stack()

preview

preview(
    *,
    preset: Literal["coarse", "default", "fine"] | None = None,
    refined_mesh_size: float | None = None,
    max_mesh_size: float | None = None,
    margin: float | None = None,
    margin_x: float | None = None,
    margin_y: float | None = None,
    z_above: float | None = None,
    z_below: float | None = None,
    airbox_margin: float | None = None,
    fmax: float | None = None,
    planar_conductors: bool | None = None,
    show_gui: bool = True,
    auto_size: bool = False,
    cells_per_feature: int = 2,
    curve_fit_mode: Literal["line", "spline", "bspline"] | None = None,
    curve_fit_layers: list[str] | None = None,
    curve_fit_tolerance_um: float | None = None,
    curve_fit_min_points: int | None = None,
    curve_fit_corner_angle_deg: float | None = None,
    high_order_elements: bool | None = None,
    high_order_order: int | None = None,
    high_order_optimize: bool | None = None,
    algorithm_3d: Literal["delaunay", "hxt"] | None = None,
    threads: int | None = None,
    surface_threads: int | None = None,
    decimate_tolerance: float | None = None,
) -> None

Preview the mesh without running simulation.

Opens the gmsh GUI to visualize the mesh interactively.

Parameters:

  • preset (Literal['coarse', 'default', 'fine'] | None, default: None ) –

    Mesh quality preset ("coarse", "default", "fine")

  • refined_mesh_size (float | None, default: None ) –

    Mesh size near conductors (um)

  • max_mesh_size (float | None, default: None ) –

    Max mesh size in air/dielectric (um)

  • margin (float | None, default: None ) –

    XY margin around design (um)

  • margin_x (float | None, default: None ) –

    X-axis margin (um). Overrides margin for X.

  • margin_y (float | None, default: None ) –

    Y-axis margin (um). Overrides margin for Y.

  • z_above (float | None, default: None ) –

    Airbox extension above stack top (um).

  • z_below (float | None, default: None ) –

    Airbox extension below stack bottom (um).

  • airbox_margin (float | None, default: None ) –

    Deprecated. Use set_airbox().

  • fmax (float | None, default: None ) –

    Max frequency for mesh sizing (Hz)

  • planar_conductors (bool | None, default: None ) –

    Treat conductors as 2D PEC surfaces

  • show_gui (bool, default: True ) –

    Show gmsh GUI for interactive preview

  • auto_size (bool, default: False ) –

    If True, scale refined_mesh_size down to the smallest conductor feature / cells_per_feature. Off by default. Explicit refined_mesh_size overrides bypass auto-sizing.

  • cells_per_feature (int, default: 2 ) –

    Target cells across the smallest conductor feature for auto-sizing and resolution warnings. Default 2.

  • curve_fit_mode (Literal['line', 'spline', 'bspline'] | None, default: None ) –

    Patterned dielectric boundary mode (line/spline/bspline).

  • curve_fit_layers (list[str] | None, default: None ) –

    Layer names where spline fitting is applied.

  • curve_fit_tolerance_um (float | None, default: None ) –

    Point merge tolerance before fitting.

  • curve_fit_min_points (int | None, default: None ) –

    Min contour points required to fit curves.

  • curve_fit_corner_angle_deg (float | None, default: None ) –

    Turn-angle threshold used to split sharp corners from smooth curve-fit segments.

  • high_order_elements (bool | None, default: None ) –

    Enable high-order geometric mesh elements.

  • high_order_order (int | None, default: None ) –

    Polynomial order for high-order elements.

  • high_order_optimize (bool | None, default: None ) –

    Run gmsh high-order optimization after meshing.

  • algorithm_3d (Literal['delaunay', 'hxt'] | None, default: None ) –

    Gmsh 3D meshing algorithm, "delaunay" or "hxt".

  • threads (int | None, default: None ) –

    Threads for 3D meshing (see MeshConfig).

  • surface_threads (int | None, default: None ) –

    Threads for 1D and 2D meshing. Above 1 the mesh differs from run to run.

  • decimate_tolerance (float | None, default: None ) –

    Relative tolerance for polygon decimation (None = no decimation; typical 0.001-0.01).

Example

sim.preview(preset="fine", planar_conductors=True, show_gui=True)

print_mesh_stats

print_mesh_stats() -> None

Print mesh statistics from the last mesh generation.

Reports node/element counts and input-mesh Field DOF estimates at the configured field order, before Palace preprocessing and refinement.

reuse_mesh

reuse_mesh(source: PalaceSimMixin) -> SimulationResult

Take the mesh of another meshed simulation instead of meshing.

Driven and eigenmode simulations can share a mesh, in either direction, so an eigenmode solve and driven sweeps with different excitations run on one discretization. The call takes a snapshot of the source: it copies the source's .msh into this simulation's output directory, under the source's model name, and writes a new metadata.json there. It never meshes, never writes to the source, and keeps no link to it. To pick up a newer mesh of the source, call reuse_mesh again. A later mesh() or reuse_mesh on this simulation replaces the mesh.

Copied from the source, as independent copies that replace what this simulation had: the geometry, the stack and its settings, the material overrides, the airbox, the PEC blocks, the symmetry plane, the mesh settings the source's mesh was made with (as mesh_config, after presets and auto-sizing) and the port declarations. The geometry copy is flat: it has the source's polygons and ports but no instances, so it shares no cells with the source. Kept per simulation: the simulation type, the solver and problem settings, the absorbing boundary, refinement, impedance boundaries and the output directory.

Ports are matched by name. A port this simulation declared with the source's kind and geometry keeps its own Port settings: excitation, impedance, R/L/C and wave-port mode options. That is how a driven simulation chooses its excited ports: declare them with excited=True, before or after this call, or set excited on the copied port config. Every other source port is copied with the source's settings except excited, which is cleared, so this simulation excites only the ports it chooses. A declared port of another kind or geometry, or one the source does not declare, is refused.

On a simulation that already holds a reused mesh, its ports came from a source, so the call takes the Port geometry and kind back from the source for every port instead: a port the source declares keeps this simulation's Port settings, a port the source lacks is dropped.

Give each simulation its own output directory. The mesh fixes the layout and component ports, the stack layers and dielectric regions, which materials are air-like, the airbox, the PEC blocks, the symmetry plane and the port geometry. Each write_config() checks them first and raises ValueError naming what changed; call mesh() on this simulation to mesh its current state, or reuse_mesh(source) again to take the source's inputs back, Port geometry included. write_config() then re-applies the Port settings and validates the configuration; a driven simulation needs at least one port with excited=True. Mesh sizes, Port settings, solver settings and material values such as permittivity, loss tangent and conductor conductivity can change freely; check that the mesh still resolves the new values.

Parameters:

Returns:

Raises:

  • TypeError –

    If source is not a simulation, for example a mesh file or a MeshResult: a mesh file alone has no physical-group or port mappings.

  • ValueError –

    If this simulation or the source is not a driven or eigenmode simulation; if the source has no mesh, is this simulation, or changed after its mesh was made; if no output directory is set, or it is, contains or lies inside one of the source's; if this simulation does not hold a reused mesh and a declared port does not match the mesh; or if this is a driven simulation and the mesh has no port surfaces.

  • FileNotFoundError –

    If the source's mesh file is missing.

Example

eigen is an EigenmodeSim with lumped ports o1 and o2, each declared with layer="topmetal2", length=5.0. A driven sweep excites o1 on its mesh, with a reflecting outer wall; o2 is copied from eigen, not excited.

eigen.set_output_dir("./eigen") eigen.mesh(preset="default") driven = DrivenSim(absorbing_boundary=False) driven.set_output_dir("./driven") driven.add_port("o1", layer="topmetal2", length=5.0, excited=True) result = driven.reuse_mesh(eigen) driven.set_driven(fmin=7e9, fmax=10e9) driven.write_config()

run

run(
    parent_dir: str | Path | None = None,
    *,
    verbose: Literal["quiet", "status", "full"] = "status",
    wait: bool = True,
    check_cache: bool = False,
    poll_interval: float = 5.0,
) -> dict[str, Path] | str

Run the eigenmode sim on GDSFactory+ cloud.

Thin wrapper over :meth:~gsim.common.cloud.CloudJobMixin.run that narrows the return type: an eigenmode run returns a dict[str, Path] of output files keyed by name (e.g. "eig.csv"), or the job_id string when wait=False.

run_local

run_local(
    *,
    palace_sif_path: str | Path | None = None,
    palace_executable: str | Path | None = None,
    use_apptainer: bool = False,
    num_processes: int | None = None,
    num_threads: int | None = None,
    verbose: bool = True,
    remedy: str | None = None,
    log_path: str | Path | None = None,
) -> SParams | PalaceTextResults | dict[str, Path]

Run simulation locally using Palace.

Requires mesh() and write_config() to be called first. Supports both Apptainer and direct Palace installation.

Parameters:

  • palace_sif_path (str | Path | None, default: None ) –

    Path to Palace Apptainer SIF file. Only used when use_apptainer=True and no executable is selected. If None, tries PALACE_SIF, then local defaults: ./Palace.sif, ./palace.sif, ./bin/Palace.sif, ./bin/palace.sif.

  • palace_executable (str | Path | None, default: None ) –

    Path to Palace executable. If provided, runs Palace directly and overrides use_apptainer. If None, tries PALACE_EXECUTABLE, then ./bin/palace, then palace on PATH.

  • use_apptainer (bool, default: False ) –

    If True (default), run via Apptainer using SIF file. If False, run Palace executable directly. Ignored when palace_executable is explicitly provided.

  • num_processes (int | None, default: None ) –

    Number of MPI processes. If None (default), a problem-size-aware default is chosen: 2D mode-analysis runs use a single MPI rank (SuperLU_DIST's 2D processor grid does not scale on small 2D problems and can effectively hang at 8-16 ranks), while 3D runs are capped to a few ranks by the estimated unknown count. An explicit value is always respected.

  • num_threads (int | None, default: None ) –

    Number of OpenMP threads to use for OpenMP builds. When running with a single MPI rank and num_threads is omitted, defaults to the number of physical CPU cores so shared-memory parallelism is used.

  • verbose (bool, default: True ) –

    Print progress messages and stream Palace output in real time

  • log_path (str | Path | None, default: None ) –

    Optional file for combined solver output, retained on success and failure even when verbose is False. A relative path is resolved against the current working directory, not the run directory.

  • remedy (str | None, default: None ) –

    A second way out of a dead Palace runtime, named at the end of the abort report beyond pointing PALACE_BIN somewhere else. A caller with no other way out gives none.

Returns:

Raises:

  • ValueError –

    If output_dir not set or Palace not configured

  • FileNotFoundError –

    If mesh, config, or Palace not found

  • RuntimeError –

    If the simulation fails. A binary that died on a signal is reported through :func:gsim.palace.runtime.local_abort_report, which says whether the runtime or the model is at fault.

Example

Using Apptainer (default)

import os os.environ["PALACE_SIF"] = "/path/to/Palace.sif" results = sim.run_local()

Using Apptainer with explicit path

results = sim.run_local(palace_sif_path="/path/to/Palace.sif")

Auto-discovery with no options:

prefers local ./bin/palace if present,

otherwise falls back to local SIF or PATH executable

results = sim.run_local()

Using direct Palace with custom executable path

results = sim.run_local(palace_executable="/usr/local/bin/palace")

Using a locally built Palace binary

results = sim.run_local(palace_executable="./bin/palace")

For DrivenSim: results is SParams -> results.s21.db

For eigen / electrostatic: results is dict[str, Path]

set_airbox

set_airbox(
    *,
    margin_x: float | None = None,
    margin_y: float | None = None,
    z_above: float | None = None,
    z_below: float | None = None,
    material: str = "air",
) -> None

Configure an explicit weak-priority airbox for meshing.

This helper centralizes airbox controls that were previously split across mesh margin arguments and stack air thickness parameters. The resulting airbox is created as a dedicated dielectric volume with the weakest boolean-priority in mesh construction.

material sets the material name of the padded background region. It defaults to "air" (eps=1). For a photonic cross-section with a uniform cladding, pass e.g. "sio2" so the region around the device is filled with SiO2 instead of air. The material must be resolvable in the stack's materials (or the built-in database); its permittivity is evaluated at the simulation frequency (e.g. Sellmeier SiO2 at 1550 nm).

Note: the background material currently applies to the native-2D BoundaryMode domain (the region outside the stack/cladding); the 3D airbox region remains air.

Parameters:

  • margin_x (float | None, default: None ) –

    Airbox x-margin around the design (um). Defaults to 0.0 when omitted.

  • margin_y (float | None, default: None ) –

    Airbox y-margin around the design (um). Defaults to 0.0 when omitted.

  • z_above (float | None, default: None ) –

    Airbox extension above the stack top (um). Defaults to 0.0 when omitted.

  • z_below (float | None, default: None ) –

    Airbox extension below the stack bottom (um). Defaults to 0.0 when omitted. The stack bottom is the lowest dielectric region: the silicon substrate with set_stack(include_substrate=True), otherwise the oxide bottom at -substrate_thickness. With add_oxide_dielectric=False there is no such oxide, and the bottom comes from the PDK's remaining dielectric regions or layer extents (substrate_thickness is ignored). A substrate layer left out of the stack does not move it.

  • material (str, default: 'air' ) –

    Background material name for the padded region (default "air").

set_eigenmode

set_eigenmode(
    *,
    num_modes: int = 10,
    target: float | None = None,
    tolerance: float = 1e-09,
    save: int = 0,
    floquet: bool = False,
    phi_target: float = pi / 2,
    periodic_length: float | None = None,
    n_eff_guess: float | None = None,
) -> None

Configure eigenmode simulation.

Parameters:

  • num_modes (int, default: 10 ) –

    Number of modes to find

  • target (float | None, default: None ) –

    Positive target frequency in Hz for mode search. Required before meshing or exporting the configuration.

  • tolerance (float, default: 1e-09 ) –

    Eigenvalue solver tolerance

  • save (int, default: 0 ) –

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

  • floquet (bool, default: False ) –

    Enable Floquet periodic boundary setup in config generation (requires mesh(periodic_axis=...)).

  • phi_target (float, default: pi / 2 ) –

    Signed Bloch phase per cell in radians (Floquet only). Zero and ±pi are valid. The wave vector is phase / mesh period. Palace applies E(receiver) = exp(-i * phi_target) * E(donor).

  • periodic_length (float | None, default: None ) –

    Optional expected period in mesh units (um). Must match the measured mesh translation, including domain padding. Omit to use the measured period directly.

  • n_eff_guess (float | None, default: None ) –

    Deprecated compatibility argument, ignored with a warning. Target frequency controls the eigenvalue search, not the wave vector.

Example

sim.set_eigenmode(num_modes=10, target=50e9)

set_geometry

set_geometry(component: Component) -> None

Set the gdsfactory component for simulation.

Parameters:

  • component (Component) –

    gdsfactory Component to simulate

Example

sim.set_geometry(my_component)

set_material

set_material(
    name: str,
    *,
    material_type: Literal["conductor", "dielectric", "semiconductor"] | None = None,
    conductivity: float | None = None,
    permittivity: float | None = None,
    loss_tangent: float | None = None,
) -> None

Override or add material properties.

Parameters:

  • name (str) –

    Material name

  • material_type (Literal['conductor', 'dielectric', 'semiconductor'] | None, default: None ) –

    Material type (conductor, dielectric, semiconductor)

  • conductivity (float | None, default: None ) –

    Conductivity in S/m (for conductors)

  • permittivity (float | None, default: None ) –

    Relative permittivity (for dielectrics)

  • loss_tangent (float | None, default: None ) –

    Dielectric loss tangent

Example

sim.set_material( ... "aluminum", material_type="conductor", conductivity=3.8e7 ... ) sim.set_material("sio2", material_type="dielectric", permittivity=3.9)

set_numerical

set_numerical(
    *,
    order: int | _UnsetOrder = DEFAULT,
    tolerance: float | None = None,
    max_iterations: int = max_iterations,
    solver_type: Literal["Default", "SuperLU", "STRUMPACK", "MUMPS"] | None = None,
    preconditioner: Literal["Default", "AMS", "BoomerAMG"] | None = None,
    device: Literal["CPU", "GPU"] = device,
    mg_max_levels: int = mg_max_levels,
    pc_mat_real: bool = pc_mat_real,
    complex_coarse_solve: bool = complex_coarse_solve,
) -> None

Deprecated alias for set_solver, with the same order-2 defaults.

Omitting order emits a visible migration warning because this setter previously defaulted to order 1. Pass order=1 to retain that behavior.

set_output_dir

set_output_dir(path: str | Path) -> None

Set the output directory for mesh and config files.

Parameters:

  • path (str | Path) –

    Directory path for output files

Example

sim.set_output_dir("./palace-sim")

set_pn_junction

set_pn_junction(
    junction: Any,
    *,
    layer_p: str,
    layer_n: str,
    length_um: float,
    height_um: float,
    name: str | None = None,
) -> float

Apply the depletion capacitance of a PN junction between two layers.

Capacitance-mode modelling of a PN junction: the depletion width W is computed from the doping concentrations and bias point via :class:gsim.common.stack.pn_junction.PNJunctionConfig (Sze, Physics of Semiconductor Devices, ch. 2), converted to an absolute parallel-plate capacitance C = eps_s * A / W, and applied as a lumped Impedance boundary on the shared P/N interface.

Use this when the depletion strip is too thin to resolve on the mesh; for a well-resolved depletion region prefer drawing it as dielectric geometry of its own instead.

Parameters:

  • junction (Any) –

    PNJunctionConfig or its dict form (doping concentrations, bias, temperature, permittivity).

  • layer_p (str) –

    Name of the P-doped layer.

  • layer_n (str) –

    Name of the N-doped layer.

  • length_um (float) –

    Device length along the propagation direction (um).

  • height_um (float) –

    Junction z-extent (um), e.g. the rib height.

  • name (str | None, default: None ) –

    Optional display name for the boundary.

Returns:

  • float –

    The absolute capacitance applied [F].

Example

sim.set_pn_junction( ... {"na_cm3": 1e19, "nd_cm3": 1e19}, ... layer_p="p_rib", ... layer_n="n_rib", ... length_um=10.0, ... height_um=0.22, ... )

set_refinement

set_refinement(
    *,
    max_its: int = 0,
    tol: float = 0.01,
    uniform_levels: int = 0,
    max_dofs: int | None = None,
    update_fraction: float | None = None,
    nonconformal: bool | None = None,
    max_nc_levels: int | None = None,
    save_adapt_iterations: bool | None = None,
    save_adapt_mesh: bool | None = None,
) -> None

Configure Palace's adaptive mesh refinement (AMR).

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. See :class:~gsim.palace.models.RefinementConfig.

Parameters:

  • max_its (int, default: 0 ) –

    Maximum number of AMR passes. 0 disables AMR.

  • tol (float, default: 0.01 ) –

    Stop refining when the estimated error norm falls below this.

  • uniform_levels (int, default: 0 ) –

    Uniform refinement levels applied to the input mesh before solving.

  • max_dofs (int | None, default: None ) –

    Maximum degrees of freedom. None means no limit.

  • update_fraction (float | None, default: None ) –

    Dörfler marking fraction, between 0 and 1.

  • nonconformal (bool | None, default: None ) –

    Refine with hanging nodes instead of conformally.

  • max_nc_levels (int | None, default: None ) –

    Maximum nonconformal refinement levels; 0 means no limit.

  • save_adapt_iterations (bool | None, default: None ) –

    Keep the output of every pass in an iterationX subdirectory.

  • save_adapt_mesh (bool | None, default: None ) –

    Save the final adapted mesh.

Example

sim.set_refinement(max_its=5, tol=1e-3, max_dofs=2_000_000)

set_solver

set_solver(
    *,
    order: int = order,
    tolerance: float | None = None,
    max_iterations: int = max_iterations,
    solver_type: Literal["Default", "SuperLU", "STRUMPACK", "MUMPS"] | None = None,
    preconditioner: Literal["Default", "AMS", "BoomerAMG"] | None = None,
    device: Literal["CPU", "GPU"] = device,
    mg_max_levels: int = mg_max_levels,
    pc_mat_real: bool = pc_mat_real,
    complex_coarse_solve: bool = complex_coarse_solve,
    estimator_tolerance: float | None = None,
    estimator_max_iterations: int | None = None,
    estimator_mg: bool | None = None,
) -> None

Set common solver controls, preserving problem-specific settings.

Defaults match the simulation constructor: order 2, 400 iterations, and CPU. Tolerance, backend and preconditioner left as None take the simulation class's own linear defaults: complex MUMPS multigrid at 1e-6 (1e-9 for eigenmode), or AMS at 1e-8 for magnetostatic. Error estimator controls left as None are chosen by AMR state. Set individual controls directly through sim.solver to retain other common values.

Example

sim.set_solver(order=1, tolerance=1e-6) sim.solver.eigenmode.target = 4e9

set_stack

set_stack(
    stack: LayerStack | None = None,
    *,
    yaml_path: str | Path | None = None,
    air_above: float | None = None,
    air_below: float | None = None,
    substrate_thickness: float | None = None,
    include_substrate: bool = False,
    add_oxide_dielectric: bool = True,
    pdk_authoritative: bool = False,
    dielectrics: list[dict[str, Any]] | None = None,
    role_overrides: dict[str, str] | None = None,
    use_pdk_overlay: bool = True,
    **kwargs,
) -> None

Configure the layer stack.

Three modes of use:

  1. Active PDK (default — auto-detects IHP, QPDK, etc.)::

    sim.set_stack(substrate_thickness=2.0)

  2. YAML file::

    sim.set_stack(yaml_path="custom_stack.yaml")

  3. Custom stack (advanced — pass a hand-built LayerStack)::

    sim.set_stack(my_layer_stack)

Parameters:

  • stack (LayerStack | None, default: None ) –

    Custom gsim LayerStack (bypasses PDK extraction).

  • yaml_path (str | Path | None, default: None ) –

    Path to custom YAML stack file.

  • air_above (float | None, default: None ) –

    Deprecated and ignored. Use set_airbox().

  • air_below (float | None, default: None ) –

    Deprecated and ignored. Use set_airbox().

  • substrate_thickness (float | None, default: None ) –

    Depth below z=0 in um (2.0 when omitted). It only matters where something is built from it: the synthetic oxide fill (include_substrate=False with add_oxide_dielectric=True) or the silicon substrate (include_substrate=True; a stack with shaped (photonic) dielectrics keeps the PDK's own substrate depth if that is deeper). With include_substrate=False and add_oxide_dielectric=False nothing is built from it, it is ignored, and a warning is logged if it was given.

  • include_substrate (bool, default: False ) –

    Include lossy silicon substrate (default False). With False the PDK's substrate layer is left out of the simulation, so changing its thickness in the PDK stack changes neither the mesh nor the config. A warning is logged when the PDK substrate and these settings disagree.

  • add_oxide_dielectric (bool, default: True ) –

    Add the synthetic oxide background dielectric (default True). When the substrate is omitted this is the region whose bottom is -substrate_thickness. With False the stack bottom comes from the PDK's own dielectric regions, or from the lowest layer when there are none, not from substrate_thickness.

  • pdk_authoritative (bool, default: False ) –

    Build directly from the PDK LayerStack without synthetic oxide or substrate; unknown materials raise. Defaults to False to preserve legacy behavior.

  • dielectrics (list[dict[str, Any]] | None, default: None ) –

    Explicit bulk regions with name/material/zmin/zmax in authoritative mode.

  • role_overrides (dict[str, str] | None, default: None ) –

    Explicit {layer_key: role} declarations in authoritative mode.

  • use_pdk_overlay (bool, default: True ) –

    Apply the reviewed per-PDK overlay in authoritative mode. Defaults to True.

  • **kwargs –

    Additional args passed to extract_layer_stack.

The bottom of the Palace domain is the lowest non-air dielectric region of the resolved stack (the lowest layer when there is no such region) minus set_airbox(z_below=...). What sets that region:

  • include_substrate=True: the silicon, whose bottom is -substrate_thickness (or the PDK substrate bottom, if deeper, for stacks with shaped dielectrics).
  • include_substrate=False and add_oxide_dielectric=True (the default): the oxide fill, whose bottom is -substrate_thickness.
  • include_substrate=False and add_oxide_dielectric=False: not substrate_thickness; the PDK's dielectric layers and layer extents. Move the bottom with z_below or the PDK layers.

With a custom LayerStack the bottom is whatever its dielectrics say.

Example

sim.set_stack(substrate_thickness=2.0) sim.set_stack( ... pdk_authoritative=True, ... dielectrics=[ ... {"name": "ild", "material": "sio2", "zmin": -2.0, "zmax": 14.03} ... ], ... role_overrides={"via1": "via"}, ... ) # PDK-authoritative stack with explicit background/roles

show_stack

show_stack() -> None

Print the layer stack table.

Example

sim.show_stack()

start

start(*, verbose: bool = True) -> None

Start cloud execution for this simulation's uploaded job.

Raises:

  • ValueError –

    If :meth:upload has not been called.

upload

upload(*, verbose: bool = True) -> str

Write the inputs and upload them. Does NOT start execution.

Parameters:

  • verbose (bool, default: True ) –

    Print progress messages.

Returns:

  • str –

    job_id string for use with :meth:start, :meth:get_status,

  • or ( str ) –

    func:gsim.wait_for_results.

validate_config

validate_config() -> ValidationResult

Validate the simulation configuration.

Returns:

validate_mesh

validate_mesh() -> ValidationResult

Validate the generated mesh and config before cloud submission.

Checks that physical groups are correctly assigned after meshing: conductor surfaces, dielectric volumes, ports, and absorbing boundary. Also verifies the generated config.json structure.

Call after mesh() and before run().

Returns:

  • ValidationResult –

    ValidationResult with validation status and messages when valid.

Raises:

Example

sim.mesh(preset="coarse") result = sim.validate_mesh() print(result)

wait_for_results

wait_for_results(
    *,
    verbose: Verbosity = "status",
    parent_dir: str | Path | None = None,
    poll_interval: float = 5.0,
) -> Any

Wait for this simulation's cloud job, then download and parse results.

Parameters:

  • verbose (Verbosity, default: 'status' ) –

    "quiet" no output, "status" status line, "full" stream solver logs.

  • parent_dir (str | Path | None, default: None ) –

    Where to create the sim-data directory.

  • poll_interval (float, default: 5.0 ) –

    Seconds between status polls.

Returns:

  • Any –

    The solver's parsed results.

Raises:

  • ValueError –

    If no job has been submitted yet.

write_config

write_config(
    *,
    validate_mesh: bool = True,
    photonic: bool = False,
    photononic: bool | None = None,
) -> Path

Write Palace config.json after mesh generation.

By default this validates that the generated mesh/config include conductor boundaries required for EM conductor solves. For photonic simulations, pass photonic=True to skip this validation.

Parameters:

  • photonic (bool, default: False ) –

    Skip conductor-oriented mesh validation when True.

  • photononic (bool | None, default: None ) –

    Deprecated alias for photonic.

Returns:

  • Path –

    Path to the generated config.json

Raises:

  • ValueError –

    If mesh() hasn't been called yet. For a mesh taken with reuse_mesh(), also if a mesh input changed since, a periodic mesh is used with an absorbing wall and no Floquet solve, the configuration is invalid, or a driven simulation excites no port of the mesh.

Example

result = sim.mesh("./sim") config_path = sim.write_config()

Photonic workflow without conductor boundaries

config_path = sim.write_config(photonic=True)