Simulation Classes¶

DrivenSim ¶

Bases: PalaceSimMixin, BaseModel

Frequency-domain driven simulation for S-parameter extraction.

This class configures and runs driven simulations that sweep through frequencies to compute S-parameters. Uses composition (no inheritance) with shared Geometry and Stack components from gsim.common.

Example

from gsim.palace import DrivenSim
sim = DrivenSim()
sim.set_geometry(component)
sim.set_stack()
sim.set_airbox(margin_x=120.0, margin_above=120.0, margin_below=20.0)
sim.add_cpw_port("o1", layer="topmetal2", s_width=10, gap_width=6)
sim.add_cpw_port("o2", layer="topmetal2", s_width=10, gap_width=6)
sim.set_driven(fmin=1e9, fmax=100e9, num_points=40)
sim.set_output_dir("./sim")
sim.mesh(preset="default")
sp = sim.run()  # SParams
sp.s21.db  # dB magnitude of S21 vs frequency

Attributes:

geometry (Geometry | None) –

Wrapped gdsfactory Component (from common)
stack (LayerStack | None) –

Layer stack configuration (from common)
ports (list[PortConfig]) –

List of single-element port configurations
cpw_ports (list[CPWPortConfig]) –

List of CPW (two-element) port configurations
driven (DrivenConfig) –

Driven simulation configuration (frequencies, etc.)
mesh (SimulationResult) –

Mesh configuration
materials (dict[str, MaterialConfig]) –

Material property overrides
numerical (NumericalConfig) –

Numerical solver configuration

Methods:

set_driven –

Configure driven (frequency sweep) simulation.
run –

Run the driven sim on GDSFactory+ cloud.

set_driven ¶

set_driven(
    *,
    f: float | None = None,
    fmin: float | None = None,
    fmax: float | None = None,
    num_points: int = 40,
    scale: Literal["linear", "log"] = "linear",
    adaptive_tol: float = 0.02,
    adaptive_max_samples: int = 20,
    compute_s_params: bool = True,
    reference_impedance: float = 50.0,
    excitation_port: str | None = None,
    save_step: int = 0,
    save_fields_at: list[float] | None = None,
    save_freq: str | None = None,
) -> None

Configure driven (frequency sweep) simulation.

Parameters:

f (float | None, default: None ) –

Single frequency in Hz (convenience). Sets both fmin and fmax to this value with num_points=1. Ignored when both fmin and fmax are explicitly provided.
fmin (float | None, default: None ) –

Minimum frequency in Hz
fmax (float | None, default: None ) –

Maximum frequency in Hz
num_points (int, default: 40 ) –

Number of frequency points
scale (Literal['linear', 'log'], default: 'linear' ) –

"linear" or "log" frequency spacing
adaptive_tol (float, default: 0.02 ) –

Relative error tolerance (unitless fraction) for adaptive frequency sampling. Palace builds a reduced-order model from a few full solves and interpolates the rest. 0 = disabled (full solve at every point), 0.02 = 2% error (fast default), 1e-3 = 0.1% (accurate), 1e-4 = publication quality.
adaptive_max_samples (int, default: 20 ) –

Maximum number of additional frequency points that adaptive refinement may insert between the points defined by fmin, fmax, and num_points.
compute_s_params (bool, default: True ) –

Compute S-parameters
reference_impedance (float, default: 50.0 ) –

Reference impedance for S-params (Ohms)
excitation_port (str | None, default: None ) –

Port to excite (None = first port)
save_step (int, default: 0 ) –

Save fields every N frequency steps for ParaView (0 = disabled)
save_fields_at (list[float] | None, default: None ) –

Specific frequencies (Hz) at which to save fields for ParaView visualisation.
save_freq (str | None, default: None ) –

Convenience shorthand for saving fields at a named frequency. "center" saves at (fmin + fmax) / 2. Appended to save_fields_at if both are given.

Example

sim.set_driven(f=50e9)
sim.set_driven(fmin=1e9, fmax=100e9, num_points=40)
sim.set_driven(fmin=1e9, fmax=100e9, save_freq="center")

run ¶

run(
    parent_dir: str | Path | None = None,
    *,
    verbose: Literal["quiet", "status", "full"] = "status",
    wait: bool = True,
) -> SParams | str

Run the driven sim on GDSFactory+ cloud.

Thin wrapper over :meth:PalaceSimMixin.run that narrows the return type: the palace result parser always turns a completed driven run (which has port-S.csv) into an :class:~gsim.palace.results.SParams object.

Returns:

SParams | str –

class:SParams when wait=True (the default), or the
SParams | str –

job_id string when wait=False.

EigenmodeSim ¶

Bases: PalaceSimMixin, BaseModel

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.set_eigenmode(num_modes=10, target=50e9)
sim.set_output_dir("./sim")
sim.mesh(preset="default")
results = sim.run()  # dict[str, Path]
print(results["eig.csv"])

Attributes:

geometry (Geometry | None) –

Wrapped gdsfactory Component (from common)
stack (LayerStack | None) –

Layer stack configuration (from common)
ports (list[PortConfig]) –

List of single-element port configurations
cpw_ports (list[CPWPortConfig]) –

List of CPW (two-element) port configurations
eigenmode (EigenmodeConfig) –

Eigenmode simulation configuration
materials (dict[str, MaterialConfig]) –

Material property overrides
numerical (NumericalConfig) –

Numerical solver configuration

Methods:

set_eigenmode –

Configure eigenmode simulation.
run –

Run the eigenmode sim on GDSFactory+ cloud.

set_eigenmode ¶

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

Configure eigenmode simulation.

Parameters:

num_modes (int, default: 10 ) –

Number of modes to find
target (float | None, default: None ) –

Target frequency in Hz for mode search
tolerance (float, default: 1e-06 ) –

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 ) –

Bloch phase advance per cell in radians (Floquet only).
n_eff_guess (float, default: 2.0 ) –

Initial effective-index guess for Floquet k-vector setup.

Example

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

run ¶

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

Run the eigenmode sim on GDSFactory+ cloud.

Thin wrapper over :meth:PalaceSimMixin.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.

ElectrostaticSim ¶

Bases: PalaceSimMixin, BaseModel

Electrostatic simulation for capacitance matrix extraction.

This class configures and runs electrostatic simulations to extract the capacitance matrix between conductor terminals. Unlike driven and eigenmode simulations, this does not use ports.

Example

from gsim.palace import ElectrostaticSim
sim = ElectrostaticSim()
sim.set_geometry(component)
sim.set_stack()
sim.set_airbox(margin_x=120.0, margin_above=120.0, margin_below=20.0)
sim.add_terminal("T1", layer="topmetal2")
sim.add_terminal("T2", layer="topmetal2")
sim.set_electrostatic()
sim.set_output_dir("./sim")
sim.mesh(preset="default")
results = sim.run()  # dict[str, Path]
print(results["terminal-C.csv"])

Attributes:

geometry (Geometry | None) –

Wrapped gdsfactory Component (from common)
stack (LayerStack | None) –

Layer stack configuration (from common)
terminals (list[TerminalConfig]) –

List of terminal configurations
electrostatic (ElectrostaticConfig) –

Electrostatic simulation configuration
materials (dict[str, MaterialConfig]) –

Material property overrides
numerical (NumericalConfig) –

Numerical solver configuration

Methods:

set_electrostatic –

Configure electrostatic simulation.
add_terminal –

Add a terminal for capacitance extraction.

set_electrostatic ¶

set_electrostatic(*, save_fields: int = 0) -> None

Configure electrostatic simulation.

Parameters:

save_fields (int, default: 0 ) –

Number of field solutions to save

Example

sim.set_electrostatic(save_fields=1)

add_terminal ¶

add_terminal(name: str, *, layer: str) -> None

Add a terminal for capacitance extraction.

Terminals define conductor surfaces for capacitance matrix extraction.

Parameters:

name (str) –

Terminal name
layer (str) –

Target conductor layer

Example

sim.add_terminal("T1", layer="topmetal2")
sim.add_terminal("T2", layer="topmetal2")

Mesh¶

MeshConfig ¶

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

coarse `classmethod` ¶

coarse(**kwargs: Any) -> Self

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

This preset is suitable for initial debugging and quick checks. Not recommended for accurate results.

default `classmethod` ¶

default(**kwargs: Any) -> Self

Balanced mesh (~5 elements per wavelength).

This preset provides a good balance between accuracy and computation time. Suitable for most simulations.

fine `classmethod` ¶

fine(**kwargs: Any) -> Self

High accuracy mesh (~10 elements per wavelength).

This preset provides higher accuracy at the cost of increased computation time. Use for final production simulations.

generate_mesh ¶

generate_mesh(
    component,
    stack: LayerStack,
    ports: list[PalacePort],
    output_dir: str | Path,
    model_name: str = "palace",
    refined_mesh_size: float = 5.0,
    max_mesh_size: float = 300.0,
    margin_x: float = 50.0,
    margin_y: float = 50.0,
    air_margin: float = 50.0,
    airbox_margin_x: float | None = None,
    airbox_margin_y: float | None = None,
    airbox_z_above: float | None = None,
    airbox_z_below: float | None = None,
    fmax: float = 100000000000.0,
    show_gui: bool = False,
    simulation_type: str = "driven",
    driven_config: DrivenConfig | None = None,
    eigenmode_config: EigenmodeConfig | None = None,
    numerical_config: NumericalConfig | None = None,
    write_config: bool = True,
    planar_conductors: bool = False,
    pec_blocks: list[PECBlockConfig] | None = None,
    absorbing_boundary: bool = True,
    periodic_axis: str | None = None,
    merge_via_distance: float = 2.0,
    curve_fit_mode: Literal["line", "spline", "bspline"] = "line",
    curve_fit_layers: list[str] | None = None,
    curve_fit_tolerance_um: float = 0.0,
    curve_fit_min_points: int = 8,
    curve_fit_corner_angle_deg: float = 45.0,
    high_order_elements: bool = False,
    high_order_order: int = 2,
    high_order_optimize: bool = True,
    verbosity: int = 3,
    decimate_tolerance: float | None = None,
) -> MeshResult

Generate mesh for Palace EM simulation.

Parameters:

component –

gdsfactory Component
stack (LayerStack) –

LayerStack from palace-api
ports (list[PalacePort]) –

List of PalacePort objects (single and multi-element)
output_dir (str | Path) –

Directory for output files
model_name (str, default: 'palace' ) –

Base name for output files
refined_mesh_size (float, default: 5.0 ) –

Mesh size near conductors (um)
max_mesh_size (float, default: 300.0 ) –

Max mesh size in air/dielectric (um)
margin_x (float, default: 50.0 ) –

X-axis margin around design (um)
margin_y (float, default: 50.0 ) –

Y-axis margin around design (um)
air_margin (float, default: 50.0 ) –

Legacy isotropic airbox margin (um)
airbox_margin_x (float | None, default: None ) –

Extra x-margin for explicit airbox (um)
airbox_margin_y (float | None, default: None ) –

Extra y-margin for explicit airbox (um)
airbox_z_above (float | None, default: None ) –

Extra +z margin for explicit airbox (um)
airbox_z_below (float | None, default: None ) –

Extra -z margin for explicit airbox (um)
fmax (float, default: 100000000000.0 ) –

Max frequency for config (Hz)
show_gui (bool, default: False ) –

Show gmsh GUI during meshing
simulation_type (str, default: 'driven' ) –

Type of simulation (driven, eigenmode or electrostatics)
driven_config (DrivenConfig | None, default: None ) –

Optional DrivenConfig for frequency sweep settings
eigenmode_config (EigenmodeConfig | None, default: None ) –

Optional EigenmodeConfig for eigenmode problems
numerical_config (NumericalConfig | None, default: None ) –

Optional NumericalConfig for solver settings
write_config (bool, default: True ) –

Whether to write config.json (default True)
pec_blocks (list[PECBlockConfig] | None, default: None ) –

PEC configuration
planar_conductors (bool, default: False ) –

If True, treat conductors as 2D PEC surfaces
absorbing_boundary (bool, default: True ) –

If True, use absorbing boundary conditions on outer surfaces
periodic_axis (str | None, default: None ) –

("x" or "y") for meshing constraints on opposite domain sides
merge_via_distance (float, default: 2.0 ) –

Max gap between vias to merge (um)
curve_fit_mode (Literal['line', 'spline', 'bspline'], default: 'line' ) –

Patterned dielectric boundary mode: line/spline/bspline
curve_fit_layers (list[str] | None, default: None ) –

Layer names where curve fitting is applied
curve_fit_tolerance_um (float, default: 0.0 ) –

Point merge tolerance before curve fitting
curve_fit_min_points (int, default: 8 ) –

Min contour points required for curve fitting
curve_fit_corner_angle_deg (float, default: 45.0 ) –

Turn-angle threshold used to identify sharp corners during curve fitting segmentation
high_order_elements (bool, default: False ) –

Enable high-order geometric mesh elements
high_order_order (int, default: 2 ) –

Polynomial order for high-order elements
high_order_optimize (bool, default: True ) –

Run gmsh high-order optimization after meshing
decimate_tolerance (float | None, default: None ) –

Relative tolerance for polygon decimation (None = no decimation; typical 0.001-0.01)
verbosity (int, default: 3 ) –

Sets gmsh verbosity level

Returns:

MeshResult –

MeshResult with paths and metadata

Stack¶

LayerStack ¶

Bases: BaseModel

Complete layer stack for Palace simulation.

Layer ¶

Bases: BaseModel

Layer information for Palace simulation.

Palace

Simulation Classes¶

DrivenSim ¶

set_driven ¶

run ¶

EigenmodeSim ¶

set_eigenmode ¶

run ¶

ElectrostaticSim ¶

set_electrostatic ¶

add_terminal ¶

Mesh¶

MeshConfig ¶

coarse classmethod ¶

default classmethod ¶

fine classmethod ¶

generate_mesh ¶

Stack¶

LayerStack ¶

Layer ¶

coarse `classmethod` ¶

default `classmethod` ¶

fine `classmethod` ¶