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(air_above=300.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(
    *,
    fmin: float = 1000000000.0,
    fmax: float = 100000000000.0,
    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:

fmin (float, default: 1000000000.0 ) –

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

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(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(air_above=300.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.

set_eigenmode ¶

set_eigenmode(
    *,
    num_modes: int = 10,
    target: float | None = None,
    tolerance: float = 1e-06,
    save: int = 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)

Example

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

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(air_above=300.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,
    fmax: float = 100000000000.0,
    show_gui: bool = False,
    simulation_type: str = "driven",
    driven_config: DrivenConfig | None = None,
    eigenmode_config: EigenmodeConfig | None = None,
    write_config: bool = True,
    planar_conductors: bool = False,
    pec_blocks: list[PECBlockConfig] | None = None,
    absorbing_boundary: bool = True,
    merge_via_distance: float = 2.0,
    verbosity: int = 3,
) -> 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 ) –

Air box margin (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
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
merge_via_distance (float, default: 2.0 ) –

Max gap between vias to merge (um)
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 ¶

ElectrostaticSim ¶

set_electrostatic ¶

add_terminal ¶

Mesh¶

MeshConfig ¶

coarse classmethod ¶

default classmethod ¶

fine classmethod ¶

generate_mesh ¶

Stack¶

LayerStack ¶

Layer ¶

coarse `classmethod` ¶

default `classmethod` ¶

fine `classmethod` ¶