models ¶

Bases: BaseModel

Controls MEEP subpixel averaging and polygon simplification.

eps_averaging toggles MEEP's subpixel smoothing (expensive for complex polygons). subpixel_maxeval / subpixel_tol tune the integration that implements it. simplify_tol applies Shapely polygon simplification before extrusion, dramatically reducing vertex counts on dense GDS curves.

Bases: BaseModel

One rectangular block in a 2D cross-section MEEP cell.

Bases: BaseModel

Pre-computed 2D cross-section cell geometry.

Serialised so the cloud runner can build the MEEP cell from simple blocks without needing gdsfactory or KLayout installed.

Bases: BaseModel

Controls diagnostic outputs from the MEEP runner.

Bases: BaseModel

One dielectric slab entry for the mode solver config.

Describes a uniform horizontal layer (infinite in x, y) with a material name and vertical extent.

Bases: BaseModel

Computational domain sizing: absolute bounds, PML, and symmetries.

x_bounds, y_bounds, and z_bounds control the PML-inner interval on each active axis. "auto" keeps automatic sizing; a numeric pair specifies the exact interval in absolute micrometers, with PML outside it.

Automatic X/Y sizing fits the component bounding box plus margin_x or margin_y. An explicit bound cannot be combined with an explicitly set margin on the same axis.

z_ref and margin_z remain temporarily as input-compatibility fields for existing code. They are deprecated and translated to concrete bounds by :meth:gsim.meep.Simulation.build_config.

Methods:

• legacy_z_fields_used –

  Return deprecated vertical fields explicitly set by the caller.

• resolved_margin_x –

  Return XY margin as (-x side, +x side).

• resolved_margin_y –

  Return XY margin as (-y side, +y side).

• resolved_margin_z –

  Return vertical margin as (below, above).

legacy_z_fields_used() -> tuple[str, ...]

resolved_margin_x() -> tuple[float, float]

resolved_margin_y() -> tuple[float, float]

resolved_margin_z() -> tuple[float, float]

Bases: BaseModel

Resolved simulation domain sizing and PML thickness.

Concrete *_bounds fields are authoritative PML-inner intervals. None retains legacy geometry-bbox plus margin sizing on that axis. The legacy margin_z_low / margin_z_high fields remain readable for old generated configs and are omitted when concrete bounds are serialized. Along automatic X/Y axes the margins are the per-side gaps between the geometry bounding box and the PML inner edge.

Explicit axes are centered on their interval midpoint. Automatic axes are shifted by (margin_high - margin_low)/2 so asymmetric margins place more room on the intended side.

Bases: BaseModel

Solver numerics: resolution, stopping, subpixel, diagnostics.

Methods:

• resolved_cut –

  Value of the active cut ('auto', a float, or None in 3D).

• resolved_is_3d –

  Whether this solves a full 3D simulation.

• resolved_plane –

  Internal 2D plane name implied by the active cut ('xz'|'xy'|None).

• stop_after_sources –

  Run for a fixed sim-time after sources turn off.

• stop_after_walltime –

  Set a wall-clock time limit (safety net).

• stop_when_dft_decayed –

  Stop when all DFT monitors converge.

• stop_when_energy_decayed –

  Stop when total field energy in the cell decays (recommended).

• stop_when_fields_decayed –

  Stop when a field component decays at a point (recommended).

resolved_cut() -> float | str | None

resolved_is_3d() -> bool

resolved_plane() -> Literal['xy', 'xz'] | None

stop_after_sources(time: float) -> FDTD

stop_after_walltime(seconds: float) -> FDTD

stop_when_dft_decayed(tol: float = 0.001, min_time: float = 100.0) -> FDTD

stop_when_energy_decayed(dt: float = 20.0, decay_by: float = 0.01) -> FDTD

stop_when_fields_decayed(
    dt: float = 50.0,
    component: str = "Ey",
    decay_by: float = 0.05,
    monitor_port: str | None = None,
) -> FDTD

Bases: BaseModel

Physical layout: component + layer stack.

The vertical crop reference lives on Domain.z_ref and the 2D cut plane lives on FDTD (solver.y_cut / z_cut).

Bases: BaseModel

One layer in the stack config sent to the cloud runner.

The cloud runner reads these entries alongside layout.gds to extract polygons per layer and extrude them to 3D prisms.

Bases: BaseModel

EM material properties for MEEP simulation overrides.

Initialize via exactly one of:

• refractive_index (+ optional extinction_coeff) — converted to permittivity internally.
• permittivity — used directly.

Use loss_tangent for dielectric loss (converted to conductivity at the simulation frequency).

Bases: BaseModel

Optical material data for config JSON.

Uses epsilon_diag as the primary permittivity representation. Supports anisotropic tensors and dispersive susceptibility poles for the MEEP runner.

Bases: BaseModel

Eigenmode solution from standalone mode solving.

Returned by :func:solve_slab_mode and :func:solve_cross_section_mode. Contains the effective index, field profiles over the cross-section, the dominant wavevector, and metadata about the mode.

Attributes:

• n_eff (float) –

  Effective index (real part of propagation constant / k0).

• wavelength (float) –

  Free-space wavelength in µm.

• frequency (float) –

  Frequency in MEEP units (1/µm = 1/wavelength).

• fields (dict[str, ndarray]) –

  Complex field arrays keyed by component name (e.g. {"Ex": array, "Ey": array, "Ez": array, ...}).

• kdom (list[float]) –

  Dominant wavevector [kx, ky, kz] in MPB k-units (k*a/(2*pi), equivalent to n_eff/lambda in 1/um). The true propagation constant is beta = 2*pi*|kdom| rad/um; n_eff = |kdom|*lambda.

• n_group (float | None) –

  Group index, if computable.

• band_num (int) –

  Mode band index (1 = fundamental).

• parity (str) –

  Parity of the mode ("NO_PARITY", "EVEN_Y", etc.).

• x_grid (ndarray | None) –

  X-axis grid coordinates in µm (absolute frame). Populated for XZ cross-section modes. None when unavailable.

• y_grid (ndarray | None) –

  Y-axis grid coordinates in µm (absolute frame). Populated for YZ cross-section modes. None when unavailable.

• z_grid (ndarray | None) –

  Z-axis grid coordinates in µm (absolute frame). Populated for both slab and cross-section modes. None when unavailable.

• stack (Any | None) –

  :class:LayerStack used for mode solving. Provides material boundary context for index profile reconstruction. None when unavailable.

• component (Any | None) –

  GDSFactory :class:Component for cross-section modes. None for slab modes.

• port_or_position (str | tuple[float, float] | None) –

  Port name (str) or position (x, y) used for cross-section mode extraction. None for slab modes.

• cross_section_plane (str | None) –

  "xz" or "yz" for cross-section modes. None for slab modes.

Methods:

• plot_index –

  Plot the refractive index profile from stored context.

• plot_mode –

  Plot eigenmode field profiles.

plot_index(
    *,
    ax: Any | None = None,
    figsize: tuple[float, float] = (7, 5),
    cmap: str = "RdYlBu",
    show: bool = True,
    **kwargs: Any,
) -> tuple[Any, Any]

plot_mode(
    components: str | list[str] = "auto",
    *,
    norm: str = "abs",
    index: bool = False,
    geometry: bool = False,
    geom_kwargs: dict[str, Any] | None = None,
    ax: Any | None = None,
    figsize: tuple[float, float] = (8, 6),
    cmap: str | None = None,
    aspect: str = "equal",
    title: str | None = "auto",
    suptitle: str | None = "auto",
    show: bool = True,
    shared_colorbar: bool = False,
    **kwargs: Any,
) -> tuple[Any, Any]

Bases: BaseModel

Eigenmode solver configuration for waveguide cross-section analysis.

Configure mode-solving parameters declaratively, then solve via sim.solve_modes().

Example::

sim.mode_solver(wavelengths=[1.55], num_bands=3)
sim.mode_solver.first(3).at_port("o1")
results = sim.solve_modes()

Methods:

• at_cross_section –

  Set solver mode to cross-section (2D transverse).

• at_port –

  Set the port name for cross-section mode solving.

• at_slab –

  Set solver mode to slab (1D vertical).

• first –

  Solve the first n bands (num_bands=n, band=None).

• fundamental –

  Solve only the fundamental mode (num_bands=1, band=None).

• sweep_wavelength –

  Populate wavelengths from a linear sweep (start, stop, num).

at_cross_section() -> ModeSolver

at_port(name: str) -> ModeSolver

at_slab() -> ModeSolver

first(n: int) -> ModeSolver

fundamental() -> ModeSolver

sweep_wavelength(start: float, stop: float, num: int) -> ModeSolver

Bases: BaseModel

Serializable config for cloud eigenmode solving.

Slab mode: the runner builds a 1D cell from layer_stack. Cross-section mode: cross_section_geometry is pre-computed by the client so the runner can build the 2D cell from blocks without GDS processing.

Methods:

• to_json –

  Write config to JSON file.

to_json(path: str | Path) -> Path

Bases: BaseModel

Mode source excitation and spectral measurement window.

Bases: BaseModel

Serializable port data for the config JSON.

Bases: BaseModel

Explicit vertical placement for one waveguide port.

Either field may be provided. Fields left unset continue to use automatic layer inference, so callers can override only an ambiguous center or span.

Bases: BaseModel

MEEP grid resolution configuration.

Methods:

• coarse –

  Coarse resolution (16 pixels/um) for quick tests.

• default –

  Default resolution (32 pixels/um).

• fine –

  Fine resolution (64 pixels/um) for production runs.

coarse() -> ResolutionConfig

default() -> ResolutionConfig

fine() -> ResolutionConfig

Bases: BaseModel

S-parameter results from MEEP simulation.

Parses CSV output from the cloud runner and provides visualization via matplotlib.

Methods:

• from_csv –

  Parse S-parameter results from CSV file.

• from_directory –

  Load from directory — handles preview-only with no CSV.

• plot –

  Plot S-parameters vs wavelength.

• plot_interactive –

  Plot S-parameters with interactive legend toggling.

• plot_plotly –

  Plot S-parameters with Plotly (interactive).

• show_animation –

  Display field animation MP4 in Jupyter.

• show_diagnostics –

  Display diagnostic images in Jupyter.

from_csv(path: str | Path) -> SParameterResult

from_directory(directory: str | Path) -> SParameterResult

plot(db: bool = True, keys: list[str] | None = None, **kwargs: Any) -> Any

plot_interactive(phase: bool = False) -> Any

plot_plotly(keys: list[str] | None = None) -> Any

show_animation() -> None

show_diagnostics() -> None

Bases: BaseModel

Complete serializable simulation config written as JSON.

This is the top-level config that the cloud MEEP runner reads. The geometry is NOT included here — it's in the GDS file. The layer_stack tells the runner how to extrude each GDS layer.

Methods:

• to_json –

  Write config to JSON file.

to_json(path: str | Path) -> Path

Bases: BaseModel

Source excitation configuration.

Controls the Gaussian source bandwidth and which port is excited. When bandwidth is None (auto), compute_fwidth returns a bandwidth ~3x wider than the monitor frequency span (matching gplugins' dfcen=0.2 convention) so edge frequencies receive adequate spectral power.

Methods:

• compute_fwidth –

  Compute Gaussian source fwidth in frequency units.

compute_fwidth(fcen: float, monitor_df: float) -> float

Bases: BaseModel

Controls when the MEEP simulation stops.

field_decay mode (recommended, matches MEEP tutorials) monitors a field component at a point and stops when |component|² decays by threshold from its peak, with max_time as a numeric time cap (whichever fires first).

energy_decay mode monitors total electromagnetic energy in the cell and stops when it decays by threshold from its peak.

dft_decay mode monitors convergence of all DFT monitors and stops when they stabilize. dft_min_run_time is an absolute sim time (not time-after-sources) — with a broadband source turning off at ~t=78, a min_run_time=100 starts checking at t=100, only ~22 time units after the source ends.

fixed mode runs for a fixed time after sources turn off.

Bases: BaseModel

Mirror symmetry plane.

Bases: BaseModel

One MEEP mirror symmetry plane.

Bases: BaseModel

Wavelength and frequency settings for MEEP FDTD simulation.

MEEP uses normalized units where c = 1 and lengths are in um. Frequency f = 1/wavelength (in 1/um).

Attributes:

• df (float) –

  Frequency width in MEEP units.

• fcen (float) –

  Center frequency in MEEP units (1/um, since c=1).

df: float

fcen: float