Problems

problems

Problem types beyond single-object scattering.

Every problem is a pydantic model with a kind discriminator, so any of them can be passed as JSON to solve/estimate/the CLI/MCP. Shared conventions: lengths in nm, vacuum wavelengths, exp(-i omega t) (Im(eps) > 0 is loss).

Coordinate conventions: - layer_stack / periodic: layers are stacked along z and listed from the superstrate side to the substrate side; light is incident from the semi-infinite superstrate and travels towards the semi-infinite substrate (+z). R is measured in the superstrate, T in the substrate. - mode: the waveguide cross-section lies in the xy plane; propagation is along +z. - device: structures live in 3D (or the xy plane when dimension == 2); ports are planes whose normal is the axis where size_nm is zero.

Wavelengths module-attribute

Wavelengths = list[float] | WavelengthRange

Profile module-attribute

Profile = Annotated[Union[Rectangle, Circle, Ellipse, Polygon], Field(discriminator='kind')]

Geometry module-attribute

Geometry = Annotated[Union[Prism, Box, Ball], Field(discriminator='kind')]

Problem module-attribute

Problem = Annotated[Union[Simulation, LayerStackProblem, PeriodicProblem, ModeProblem, DeviceProblem, BandProblem, CircuitProblem, OptimizationProblem], Field(discriminator='kind')]

PROBLEM_KINDS module-attribute

PROBLEM_KINDS = ('scattering', 'layer_stack', 'periodic', 'mode', 'device', 'bands', 'circuit', 'optimization')

Rectangle

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['rectangle'] = 'rectangle'

center_nm class-attribute instance-attribute

center_nm: tuple[float, float] = (0.0, 0.0)

size_nm instance-attribute

size_nm: tuple[float, float]

Circle

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['circle'] = 'circle'

center_nm class-attribute instance-attribute

center_nm: tuple[float, float] = (0.0, 0.0)

radius_nm class-attribute instance-attribute

radius_nm: float = Field(gt=0)

Ellipse

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['ellipse'] = 'ellipse'

center_nm class-attribute instance-attribute

center_nm: tuple[float, float] = (0.0, 0.0)

semi_axes_nm instance-attribute

semi_axes_nm: tuple[float, float]

angle_deg class-attribute instance-attribute

angle_deg: float = 0.0

Polygon

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['polygon'] = 'polygon'

vertices_nm class-attribute instance-attribute

vertices_nm: list[tuple[float, float]] = Field(min_length=3)

Prism

Bases: _Model

A 2D profile in the xy plane extruded from z_min to z_max (with optional sidewall angle).

kind class-attribute instance-attribute

kind: Literal['prism'] = 'prism'

profile instance-attribute

profile: Profile

z_min_nm instance-attribute

z_min_nm: float

z_max_nm instance-attribute

z_max_nm: float

sidewall_angle_deg class-attribute instance-attribute

sidewall_angle_deg: float = Field(0.0, description='0 = vertical; positive = narrower at the top.')

Box

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['box'] = 'box'

center_nm class-attribute instance-attribute

center_nm: tuple[float, float, float] = (0.0, 0.0, 0.0)

size_nm instance-attribute

size_nm: tuple[float, float, float]

Ball

Bases: _Model

kind class-attribute instance-attribute

kind: Literal['ball'] = 'ball'

center_nm class-attribute instance-attribute

center_nm: tuple[float, float, float] = (0.0, 0.0, 0.0)

radius_nm class-attribute instance-attribute

radius_nm: float = Field(gt=0)

Structure

Bases: _Model

A material region. Later structures override earlier ones where they overlap.

name class-attribute instance-attribute

name: str | None = None

geometry instance-attribute

geometry: Geometry

material instance-attribute

material: Material

Structure2D

Bases: _Model

name class-attribute instance-attribute

name: str | None = None

profile instance-attribute

profile: Profile

material instance-attribute

material: Material

Layer

Bases: _Model

thickness_nm class-attribute instance-attribute

thickness_nm: float = Field(ge=0)

material instance-attribute

material: Material

coherent class-attribute instance-attribute

coherent: bool = Field(True, description='False for thick incoherent layers (e.g. a 1 mm substrate slab).')

LayerStackProblem

Bases: _Model

Planar multilayer: reflection/transmission/absorption vs wavelength and angle.

kind class-attribute instance-attribute

kind: Literal['layer_stack'] = 'layer_stack'

superstrate instance-attribute

superstrate: Material

layers class-attribute instance-attribute

layers: list[Layer] = Field(default_factory=list, description='From the superstrate side to the substrate side.')

substrate instance-attribute

substrate: Material

wavelengths instance-attribute

wavelengths: Wavelengths

angles_deg class-attribute instance-attribute

angles_deg: list[float] = Field([0.0], description='Angles of incidence in the superstrate.')

polarizations class-attribute instance-attribute

polarizations: list[Literal['s', 'p']] = ['s', 'p']

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

PatternedLayer

Bases: _Model

thickness_nm class-attribute instance-attribute

thickness_nm: float = Field(gt=0)

background instance-attribute

background: Material

shapes class-attribute instance-attribute

shapes: list[Structure2D] = Field(default_factory=list, description='Inclusions in one unit cell (xy).')

Incidence

Bases: _Model

theta_deg class-attribute instance-attribute

theta_deg: float = 0.0

phi_deg class-attribute instance-attribute

phi_deg: float = 0.0

polarizations class-attribute instance-attribute

polarizations: list[Literal['s', 'p']] = ['s', 'p']

PeriodicProblem

Bases: _Model

A 1D/2D-periodic stack of patterned layers under plane-wave illumination.

kind class-attribute instance-attribute

kind: Literal['periodic'] = 'periodic'

lattice_a1_nm instance-attribute

lattice_a1_nm: tuple[float, float]

lattice_a2_nm class-attribute instance-attribute

lattice_a2_nm: tuple[float, float] | None = Field(None, description='None for 1D gratings: periodic along a1, invariant perpendicular to it; shapes are sampled along the line through the origin in the a1 direction.')

superstrate instance-attribute

superstrate: Material

layers class-attribute instance-attribute

layers: list[PatternedLayer] = Field(min_length=1, description='From the superstrate side to the substrate side.')

substrate instance-attribute

substrate: Material

wavelengths instance-attribute

wavelengths: Wavelengths

incidence class-attribute instance-attribute

incidence: Incidence = Incidence()

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

ModeProblem

Bases: _Model

Eigenmodes of a waveguide cross-section (xy plane), propagation along +z.

kind class-attribute instance-attribute

kind: Literal['mode'] = 'mode'

structures class-attribute instance-attribute

structures: list[Structure2D] = Field(min_length=1)

background instance-attribute

background: Material

window_center_nm class-attribute instance-attribute

window_center_nm: tuple[float, float] = (0.0, 0.0)

window_size_nm instance-attribute

window_size_nm: tuple[float, float]

wavelengths instance-attribute

wavelengths: Wavelengths

num_modes class-attribute instance-attribute

num_modes: int = Field(2, ge=1)

target_neff class-attribute instance-attribute

target_neff: float | None = Field(None, description='Search near this effective index (default: highest index).')

bend_radius_nm class-attribute instance-attribute

bend_radius_nm: float | None = Field(None, description='Bend about the y axis; None = straight.')

include_fields class-attribute instance-attribute

include_fields: bool = False

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

Port

Bases: _Model

name instance-attribute

name: str

center_nm instance-attribute

center_nm: tuple[float, float, float]

size_nm class-attribute instance-attribute

size_nm: tuple[float, float, float] = Field(description='Zero along the port normal. In 2D devices z may also be zero, e.g. (0, w, 0) for an x-normal port.')

direction class-attribute instance-attribute

direction: Literal['+', '-'] = Field(description='Direction of propagation *into* the device along the normal.')

num_modes class-attribute instance-attribute

num_modes: int = Field(1, ge=1)

normal_axis property

normal_axis: int

GdsLayout

Bases: _Model

Import geometry from a GDS file: each layer/datatype is extruded with a material.

path instance-attribute

path: str

cell class-attribute instance-attribute

cell: str | None = None

layer_map class-attribute instance-attribute

layer_map: dict[str, dict[str, Any]] = Field(description="'layer/datatype' -> {'material': Material JSON, 'z_min_nm': .., 'z_max_nm': ..}")

DeviceProblem

Bases: _Model

A photonic device (waveguides, couplers, gratings, ...) characterised by its S-matrix.

kind class-attribute instance-attribute

kind: Literal['device'] = 'device'

dimension class-attribute instance-attribute

dimension: Literal[2, 3] = 3

structures class-attribute instance-attribute

structures: list[Structure] = Field(default_factory=list)

layout class-attribute instance-attribute

layout: GdsLayout | None = None

background instance-attribute

background: Material

domain_center_nm class-attribute instance-attribute

domain_center_nm: tuple[float, float, float] = (0.0, 0.0, 0.0)

domain_size_nm instance-attribute

domain_size_nm: tuple[float, float, float]

ports class-attribute instance-attribute

ports: list[Port] = Field(min_length=1)

wavelengths instance-attribute

wavelengths: Wavelengths

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

KPoint

Bases: _Model

label instance-attribute

label: str

reduced class-attribute instance-attribute

reduced: tuple[float, float, float] = Field(description='Coordinates in units of the reciprocal lattice vectors.')

BandProblem

Bases: _Model

Band structure of a photonic crystal along a k-path.

kind class-attribute instance-attribute

kind: Literal['bands'] = 'bands'

dimension class-attribute instance-attribute

dimension: Literal[2, 3] = 2

lattice_vectors_nm class-attribute instance-attribute

lattice_vectors_nm: list[tuple[float, float, float]] = Field(min_length=2, max_length=3)

background instance-attribute

background: Material

structures_2d class-attribute instance-attribute

structures_2d: list[Structure2D] = Field(default_factory=list, description='Unit-cell inclusions for 2D crystals.')

structures class-attribute instance-attribute

structures: list[Structure] = Field(default_factory=list, description='Unit-cell inclusions for 3D crystals.')

k_path class-attribute instance-attribute

k_path: list[KPoint] = Field(min_length=2)

points_per_segment class-attribute instance-attribute

points_per_segment: int = Field(16, ge=1)

num_bands class-attribute instance-attribute

num_bands: int = Field(8, ge=1)

polarization class-attribute instance-attribute

polarization: Literal['te', 'tm', 'both'] = Field('both', description='2D only: TE = E in plane, TM = E along z.')

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

Instance

Bases: _Model

component class-attribute instance-attribute

component: str = Field(description="Registered compact model name, e.g. 'waveguide', 'mmi1x2', or 'sparams:<file>'.")

settings class-attribute instance-attribute

settings: dict[str, Any] = Field(default_factory=dict)

CircuitProblem

Bases: _Model

A netlist of components with S-parameter models; solves the circuit S-matrix.

kind class-attribute instance-attribute

kind: Literal['circuit'] = 'circuit'

instances instance-attribute

instances: dict[str, Instance]

connections class-attribute instance-attribute

connections: list[tuple[str, str]] = Field(default_factory=list, description="Pairs of 'instance,port'.")

ports class-attribute instance-attribute

ports: dict[str, str] = Field(description="External port name -> 'instance,port'.")

wavelengths instance-attribute

wavelengths: Wavelengths

options class-attribute instance-attribute

options: dict[str, dict[str, Any]] = Field(default_factory=dict)

wavelength_array

wavelength_array(w: Wavelengths) -> ndarray

parse_problem

parse_problem(obj: Any) -> BaseModel

Parse a problem from a model, dict or JSON string. Missing kind means scattering (v0.1 specs).

problem_json_schema

problem_json_schema() -> dict

JSON Schema covering every problem kind.

options_for

options_for(problem: BaseModel, backend_name: str, method: str) -> dict[str, Any]