Meep API¶

Simulation¶

Simulation ¶

Bases: BaseModel

Declarative MEEP FDTD simulation container.

Assigns typed physics objects, then calls write_config() to produce the JSON + GDS + runner consumed by the cloud engine.

Example::

from gsim import meep

sim = meep.Simulation()
sim.geometry.component = ybranch
sim.geometry.stack = stack
sim.materials = {"si": Material(permittivity=12.0)}
sim.source.port = "o1"
sim.monitors = ["o1", "o2"]
sim.solver.stopping = "dft_decay"
sim.solver.max_time = 200
result = sim.run()  # creates sim-data-{job_name}/ in CWD

Methods:

validate_config –

Validate the simulation configuration.
write_config –

Serialize simulation config to output directory.
plot_2d –

Plot 2D cross-sections of the geometry.
plot_3d –

Plot 3D visualization of the geometry.
run –

Run MEEP simulation on the cloud.
start –

Start cloud execution for this sim's uploaded job.
upload –

Write config and upload to the cloud. Does NOT start execution.
get_status –

Get the current status of this sim's cloud job.
wait_for_results –

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

Attributes:

geometry (Geometry) –
source (ModeSource) –
domain (Domain) –
solver (FDTD) –

geometry `class-attribute` `instance-attribute` ¶

geometry: Geometry = Field(default_factory=Geometry)

source `class-attribute` `instance-attribute` ¶

source: ModeSource = Field(default_factory=ModeSource)

domain `class-attribute` `instance-attribute` ¶

domain: Domain = Field(default_factory=Domain)

solver `class-attribute` `instance-attribute` ¶

solver: FDTD = Field(default_factory=FDTD)

validate_config ¶

validate_config() -> Any

Validate the simulation configuration.

Returns:

Any –

ValidationResult with errors/warnings.

write_config ¶

write_config(output_dir: str | Path) -> Path

Serialize simulation config to output directory.

Thin wrapper around :meth:build_config — writes GDS, JSON, and the runner script.

Parameters:

output_dir (str | Path) –

Directory to write layout.gds, sim_config.json, run_meep.py.

Returns:

Path –

Path to the output directory.

Raises:

ValueError –

If config is invalid.

plot_2d ¶

plot_2d(**kwargs: Any) -> Any

Plot 2D cross-sections of the geometry.

Uses :meth:build_config so the plot shows exactly what meep processes — including extended ports and PML boundaries.

In XZ 2D mode (solver.mode='2d' with y_cut set), slices defaults to "y" and y defaults to the resolved y_cut.

The default kind="index" colors resolved material geometry by refractive index at the simulation center wavelength and shows PML, source, and monitor annotations. Pass kind="layers" for the categorical legacy view.

Accepts the same keyword arguments as :func:gsim.meep.viz.plot_2d.

plot_3d ¶

plot_3d(**kwargs: Any) -> Any

Plot 3D visualization of the geometry.

Uses :meth:build_config so the plot shows exactly what meep processes — including extended ports.

Accepts the same keyword arguments as :func:gsim.meep.viz.plot_3d.

run ¶

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

Run MEEP simulation on the cloud.

Parameters:

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

Where to create the sim directory. Defaults to the current working directory.
verbose (Literal['quiet', 'status', 'full'], default: 'status' ) –

"quiet" no output, "status" status line, "full" stream solver logs.
wait (bool, default: True ) –

If True (default), block until results are ready. If False, upload + start and return the job_id.
check_cache (bool, default: False ) –

If True, look for a completed cloud job with byte-identical inputs and reuse its results instead of submitting. A lookup failure degrades to a normal submit.

Returns:

Any –

SParameterResult when wait=True, or job_id string
Any –

when wait=False.

start ¶

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

Start cloud execution for this sim's uploaded job.

Raises:

ValueError –

If :meth:upload has not been called.

upload ¶

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

Write config and upload to the cloud. 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.

get_status ¶

get_status() -> str

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

Returns:

str –

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

"completed", "failed").

Raises:

ValueError –

If no job has been submitted yet.

wait_for_results ¶

wait_for_results(
    *,
    verbose: Literal["quiet", "status", "full"] = "status",
    parent_dir: str | Path | None = None,
) -> Any

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

Parameters:

verbose (Literal['quiet', 'status', 'full'], 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.

Returns:

Any –

Parsed result (typically SParameterResult).

Raises:

ValueError –

If no job has been submitted yet.

Configuration¶

Geometry ¶

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

Domain ¶

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.

x_bounds, y_bounds, and z_bounds set exact PML-inner intervals in absolute micrometers; PML is added outside them. Leave an axis as "auto" to size it from the component bounding box and that axis's margin:

sim.domain(
    pml=1.0,
    margin_x=1.0,
    y_bounds=(-4.0, 4.0),
    z_bounds=(0.0, 3.0),
)

Do not combine an explicit bound with margin_x or margin_y on the same axis. In XZ 2D simulations Y is collapsed, so y_bounds is not active.

ModeSource ¶

Bases: BaseModel

Mode source excitation and spectral measurement window.

3D port placement¶

Meep automatically places each waveguide source and monitor at the vertical center of its port's fabrication layer. Its vertical span is that layer's thickness plus domain.port_margin on both sides. Resolution happens before simulation layers are remapped, so mixed-layer components can use independent Si and SiN port planes.

Use port_overrides for ambiguous fabrication tuples, virtual ports, or intentional custom mode-plane placement:

sim.domain(z_bounds=(0, 3))
sim.port_overrides = {
    "o1": 1.535,  # shorthand for {"z": 1.535}
    "o2": {"z": 1.535, "z_span": 1.39},
}

Override fields take precedence individually; omitted fields remain inferred. Every inferred or overridden mode plane must fit inside domain.z_bounds. Overrides do not restore a physically drawn layer excluded by those bounds. They are supported in 3D and XZ simulations, but not in top-down XY 2D where Z is collapsed. For mixed-height devices, set explicit bounds that contain every port layer; automatic Z cropping currently follows one optical reference layer.

PortVerticalOverride ¶

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.

Results¶

SParameterResult ¶

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.
show_animation –

Display field animation MP4 in Jupyter.
show_diagnostics –

Display diagnostic images in Jupyter.

from_csv `classmethod` ¶

from_csv(path: str | Path) -> SParameterResult

Parse S-parameter results from CSV file.

Expected CSV format

wavelength,S11_mag,S11_phase,S21_mag,S21_phase,... 1.5, 0.1, -30.0, 0.9, 45.0, ...

Automatically loads meep_debug.json from the same directory if it exists, populating the debug_info field.

Parameters:

path (str | Path) –

Path to CSV file

Returns:

SParameterResult –

SParameterResult instance

from_directory `classmethod` ¶

from_directory(directory: str | Path) -> SParameterResult

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

If s_parameters.csv exists, delegates to from_csv(). Otherwise loads only debug info and diagnostic images (preview mode).

Parameters:

directory (str | Path) –

Path to results directory

Returns:

SParameterResult –

SParameterResult instance

plot ¶

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

Plot S-parameters vs wavelength.

Parameters:

db (bool, default: True ) –

If True, plot in dB scale
keys (list[str] | None, default: None ) –

S-parameter names to plot (e.g. ["s21", "s31"]). Plots all if None.
**kwargs (Any, default: {} ) –

Passed to matplotlib plot()

Returns:

Any –

matplotlib Figure

show_animation ¶

show_animation() -> None

Display field animation MP4 in Jupyter.

show_diagnostics ¶

show_diagnostics() -> None

Display diagnostic images in Jupyter.

Meep API¶

Simulation¶

Simulation ¶

geometry class-attribute instance-attribute ¶

source class-attribute instance-attribute ¶

domain class-attribute instance-attribute ¶

solver class-attribute instance-attribute ¶

validate_config ¶

write_config ¶

plot_2d ¶

plot_3d ¶

run ¶

start ¶

upload ¶

get_status ¶

wait_for_results ¶

Configuration¶

Geometry ¶

Domain ¶

ModeSource ¶

3D port placement¶

PortVerticalOverride ¶

Results¶

SParameterResult ¶

from_csv classmethod ¶

from_directory classmethod ¶

plot ¶

show_animation ¶

show_diagnostics ¶

geometry `class-attribute` `instance-attribute` ¶

source `class-attribute` `instance-attribute` ¶

domain `class-attribute` `instance-attribute` ¶

solver `class-attribute` `instance-attribute` ¶

from_csv `classmethod` ¶

from_directory `classmethod` ¶