Skip to content

staircase

Staircase route: carrier maps as piecewise-constant Palace domains.

Palace only accepts piecewise-constant materials per mesh domain, so a continuously varying carrier distribution is represented as N adjacent strips along the junction axis. Each strip becomes a patterned-dielectric region through the same Layer/MaterialProperties machinery the doped cross-section builder uses, so the result plugs straight into build_doped_cross_section(doping=...) and the native BoundaryMode solver.

Everything that turns a Carrier map into per-Strip averages lives here:

  • :func:staircase_profile averages a sampled one-dimensional profile over N equal-width Strips, each carrying the exact average of the piecewise-linear interpolant over it.
  • :func:strip_averages_from_nodes reduces a scattered two-dimensional node cloud (e.g. a :class:gsim.tcad.results.CarrierMap) to that one-dimensional profile first — the tested, reusable mesh-transfer step — and averages it over the Strips.
  • :func:build_staircase_cross_section does the whole job in one call: a Carrier map, a strip count and the Junction extent in, a meshable Staircase cross-section out — the strip Regions, their material response for both mode solves, optical and RF (:class:Strips), and the flanking electrodes. The drawing of the Strips and the material of each one are its own private steps.
  • :func:surroundings_from_section supplies what the Strips are not: every other Region of the drawn Cross-section, cut against the Strip footprint, so the Staircase is the drawn waveguide with its doped silicon replaced by Strips rather than a bare silicon wire in the background medium. A Staircase built without them answers for a different guide, and the difference does not shrink with strip count.

n_strips=1 recovers the uniform-strip model: one rectangle spanning the window carrying the profile average.

Classes:

Functions:

CarrierCoupling

Bases: Protocol

The one thing that turns concentrations into material response.

Any callable of this shape satisfies it: the TW-MZM notebook builds one from :mod:gsim.common.carriers, and a test hands in a linear stand-in.

CrossSectionOrientationError

Bases: ValueError

A drawn Cross-section was not cut on an x-normal plane.

ElectrodeSpec dataclass

ElectrodeSpec(
    width_um: float = 2.0,
    gap_um: float = 0.0,
    thickness_um: float = 0.5,
    conductor_model: ConductorModel = "volume",
    sigma_s_per_m: float = 38000000.0,
    optical_permittivity: complex | None = None,
    zmin: float | None = None,
    names: tuple[str, str] = ("electrode_low", "electrode_high"),
    gds_layer: tuple[int, int] = (42, 0),
)

The Traveling-wave electrodes flanking a Staircase.

Attributes:

  • width_um (float) –

    Width of each electrode along the junction axis (um).

  • gap_um (float) –

    Gap between the Junction extent and the electrode edge (um).

  • thickness_um (float) –

    Electrode thickness (um).

  • conductor_model (ConductorModel) –

    How the metal is expressed in the mesh (ADR 0003). "volume" meshes each electrode as a Region of lossy metal carrying :attr:sigma_s_per_m; "pec" leaves its interior out of the meshed domain and makes its outline a perfect conductor. Only "pec" is a Cross-section both first-class Routes express identically, and only "pec" keeps an eigenvalue search off the metal-dominated modes a |eps| ~ 1e7 Region carries.

  • sigma_s_per_m (float) –

    Electrode conductivity (S/m; aluminium by default), used for the RF target of the "volume" model. A "pec" electrode has no conductivity to carry.

  • optical_permittivity (complex | None) –

    Complex relative permittivity of the electrode metal at the optical wavelength, in the exp(+i omega t) convention (Im < 0 is lossy). The RF Drude conductivity above is meaningless at optical frequencies, so an optical "volume" Staircase that contains the electrodes needs this value; leave it unset when the optical Window excludes them, or when the electrodes are "pec" and so carry no permittivity at all.

  • zmin (float | None) –

    Bottom z of the electrodes (um); defaults to the strip zmin.

  • names (tuple[str, str]) –

    Region names of the low-side and high-side electrode.

  • gds_layer (tuple[int, int]) –

    (layer, datatype) of the low-side electrode; the high-side one uses datatype + 1.

MaterialResponseLike

Bases: Protocol

What a carrier coupling answers, sample by sample.

Anything carrying these three per-sample arrays answers, so the Staircase depends on the answer and not on how it was computed.

Attributes:

  • absorption_cm (NDArray[float64]) –

    Free-carrier absorption per sample (cm^-1).

  • conductivity_s_per_m (NDArray[float64]) –

    Drude conductivity per sample (S/m).

  • index_shift (NDArray[float64]) –

    Refractive-index shift per sample.

absorption_cm property

absorption_cm: NDArray[float64]

Free-carrier absorption per sample (cm^-1).

conductivity_s_per_m property

conductivity_s_per_m: NDArray[float64]

Drude conductivity per sample (S/m).

index_shift property

index_shift: NDArray[float64]

Refractive-index shift per sample.

OpticalStripMaterial dataclass

OpticalStripMaterial(wavelength_um: float, index: float = DEFAULT_SI_INDEX)

What the optical mode solve adds to a Strip's material.

Attributes:

  • wavelength_um (float) –

    Vacuum wavelength the mode is solved at (um). Each Strip's extinction kappa = dalpha lambda / 4 pi is built at it, so the Staircase and a continuous eps(x, y) carry the same loss.

  • index (float) –

    Unperturbed refractive index of the Strips, which the plasma dispersion perturbs.

RFStripMaterial dataclass

RFStripMaterial(permittivity: float = 11.9, fmax_hz: float = 200000000000.0)

What the RF mode solve adds to a Strip's material.

Attributes:

  • permittivity (float) –

    Relative permittivity of the Strip lattice, which the carrier conductivity loads.

  • fmax_hz (float) –

    Upper validity frequency (Hz) of the Drude material.

StaircaseCrossSection dataclass

StaircaseCrossSection(
    component: Component,
    strips: Strips,
    strip_names: list[str],
    electrode_names: tuple[str, ...],
    electrode_spans: tuple[tuple[float, float], ...],
    surroundings: tuple[SurroundingRegion, ...],
    layers: dict[str, Layer],
    _centres: dict[str, float],
    _electrodes: ElectrodeSpec | None,
    _material: StripMaterial,
    _drawing: StaircaseDrawing,
    _respond: Callable[[ArrayLike, ArrayLike], Strips],
    _stack: LayerStack | None = None,
)

A Carrier map reduced to Strips, ready to mesh.

The strip Regions and the electrodes are drawn once on :attr:component; :meth:stack resolves them to a LayerStack carrying the Strip materials of the solve the Staircase was built for — the RF solve's Drude conductivity or the optical solve's perturbed permittivity, chosen by the :data:StripMaterial handed to the builder.

Attributes:

  • component (Component) –

    The gdsfactory component carrying the strip and electrode rectangles.

  • strips (Strips) –

    The :class:Strips — edges, average concentrations, and the conductivity and permittivity each carries.

  • strip_names (list[str]) –

    Region names of the strips, low edge first.

  • electrode_names (tuple[str, ...]) –

    Region names of the electrodes (empty when the Staircase was built without them).

  • electrode_spans (tuple[tuple[float, float], ...]) –

    (min, max) extent of each electrode along the junction axis (um), in the same order as the names.

  • surroundings (tuple[SurroundingRegion, ...]) –

    The drawn device's own Regions redrawn around the Strips (empty on a Staircase built without them).

  • layers (dict[str, Layer]) –

    Every Region the Staircase drew — Strips, electrodes and surroundings — as the layer spec the mesher reads, by name.

Methods:

  • conductor –

    One electrode, named the way a current integral reads it.

  • electrode_extent –

    The rectangle one electrode occupies on the Cross-section.

  • stack –

    Resolve the Staircase into a meshable layer stack.

  • unloaded –

    The same Staircase with its carriers switched off.

conductor_model property

conductor_model: ConductorModel | None

How the electrodes are expressed in the mesh, or None.

Returns:

  • The ( ConductorModel | None ) –

    class:ElectrodeSpec's model, and None for a

  • ConductorModel | None –

    Staircase drawn without electrodes.

material property

material: StripMaterial

The per-solve strip input this Staircase was built with.

strip_span property

strip_span: tuple[float, float]

(min, max) extent the Strips actually tile (um).

conductor

conductor(name: str) -> Conductor

One electrode, named the way a current integral reads it.

Parameters:

  • name (str) –

    Region name of the electrode.

Returns:

  • The ( Conductor ) –

    class:~gsim.common.modes.Conductor: its Region, its

  • Conductor –

    extent and the model it reached the mesh under.

Raises:

  • ValueError –

    When the Staircase has no electrode of that name.

electrode_extent

electrode_extent(name: str) -> tuple[tuple[float, float], tuple[float, float]]

The rectangle one electrode occupies on the Cross-section.

A downstream integral over a conductor — the line current the characteristic impedance divides by — needs the conductor's outline, and under the "pec" model the mesh no longer carries it as a Region to look up.

Parameters:

  • name (str) –

    Region name of the electrode.

Returns:

Raises:

  • ValueError –

    When the Staircase has no electrode of that name.

stack

stack() -> LayerStack

Resolve the Staircase into a meshable layer stack.

Returns:

  • LayerStack –

    The LayerStack, built once and cached, carrying the Strip

  • LayerStack –

    materials of the solve this Staircase was built for.

unloaded

unloaded() -> StaircaseCrossSection

The same Staircase with its carriers switched off.

Same Strips, same electrodes, same surroundings and the same drawing — every Strip's electron and hole concentration set to zero, so it carries no Drude conductivity and no plasma dispersion, and a solve of it answers for the bare Traveling-wave electrode. The "EM solve of the bare electrode" half of the classic loaded-line workflow.

Returns:

StaircaseDrawing dataclass

StaircaseDrawing(
    length_um: float = STRIP_LENGTH_UM,
    base_layer: tuple[int, int] = DEFAULT_STRIP_LAYER,
    surround_layer: tuple[int, int] = DEFAULT_SURROUND_LAYER,
    name_prefix: str = "strip_",
    mesh_resolution: str | float = "fine",
    axis: Literal["x", "y", "z"] = "x",
    value: float = STRIP_LENGTH_UM / 2.0,
    substrate_thickness: float = 2.0,
    component: Component | None = None,
)

How a Staircase is drawn, apart from what it carries.

Attributes:

  • length_um (float) –

    Drawn length along the propagation direction (um).

  • base_layer (tuple[int, int]) –

    (layer, datatype) of Strip 0; Strip i takes datatype + i.

  • surround_layer (tuple[int, int]) –

    (layer, datatype) of the first surrounding Region, the next taking datatype + 1.

  • name_prefix (str) –

    Region-name prefix of the Strips.

  • mesh_resolution (str | float) –

    Mesh resolution assigned to the Strip layers.

  • axis (Literal['x', 'y', 'z']) –

    Cross-section normal axis of the resolved stack.

  • value (float) –

    Cross-section plane coordinate (um): the middle of the drawn length, so the plane cuts through the Strips.

  • substrate_thickness (float) –

    Substrate thickness of the resolved stack (um).

  • component (Component | None) –

    Component to draw on; a new one when None.

StripSegment dataclass

StripSegment(span: tuple[float, float], z: tuple[float, float], n_strips: int)

A run of equal Strips across one stretch of the drawn device.

A Staircase built from segments rather than from one extent follows the device: each segment is tiled with its own number of equal Strips, and every Strip in it is drawn at the segment's own height and averages the Carrier map over that height. A rib beside a thinner slab is then two segments, not a slab drawn as tall as the rib; a lightly doped stretch where the carriers move and a heavily doped one where they do not take as many Strips as each needs.

Attributes:

  • span (tuple[float, float]) –

    (min, max) extent along the junction axis (um).

  • z (tuple[float, float]) –

    (min, max) vertical extent of the silicon there (um).

  • n_strips (int) –

    Number of equal Strips tiling the span.

Strips dataclass

Strips(
    edges_um: NDArray[float64],
    zmin_um: NDArray[float64],
    zmax_um: NDArray[float64],
    electrons_cm3: NDArray[float64],
    holes_cm3: NDArray[float64],
    index_shift: NDArray[float64],
    absorption_cm: NDArray[float64],
    conductivity_s_per_m: NDArray[float64],
    permittivity: NDArray[complex128],
)

The Strips of a Staircase: what each carries, Strip by Strip.

One entry per Strip, low edge first. The concentrations are the Carrier map's averages over the Strip; the response is what those averages turn into — the Drude conductivity the RF solve meshes and the plasma-dispersion permittivity the optical solve meshes.

Attributes:

  • edges_um (NDArray[float64]) –

    Ascending Strip edges along the junction axis (um), one more than the Strip count.

  • zmin_um (NDArray[float64]) –

    Bottom of each Strip (um).

  • zmax_um (NDArray[float64]) –

    Top of each Strip (um): the height of the silicon the Strip stands for, which a Staircase built from segments varies along the junction axis.

  • electrons_cm3 (NDArray[float64]) –

    Average electron concentration per Strip (cm^-3).

  • holes_cm3 (NDArray[float64]) –

    Average hole concentration per Strip (cm^-3).

  • index_shift (NDArray[float64]) –

    Refractive-index shift per Strip.

  • absorption_cm (NDArray[float64]) –

    Free-carrier absorption per Strip (cm^-1).

  • conductivity_s_per_m (NDArray[float64]) –

    Drude conductivity per Strip (S/m).

  • permittivity (NDArray[complex128]) –

    Complex relative permittivity per Strip at the optical wavelength (exp(+i omega t): lossy means Im < 0).

count property

count: int

Number of Strips.

span property

span: tuple[float, float]

(min, max) extent the Strips tile (um).

SurroundingRegion dataclass

SurroundingRegion(
    name: str,
    h: tuple[float, float],
    z: tuple[float, float],
    material: str,
    layer_type: Literal["conductor", "via", "dielectric", "substrate"] = "dielectric",
    properties: Any | None = None,
    mesh_resolution: str | float = "fine",
)

A Region of the drawn device redrawn beside the Strips.

The Strips carry the Carrier map, and nothing else. Everything the drawn Cross-section has around them — the undoped silicon the guide slab is made of, the Traveling-wave metal landing on the pads, an implant the charge solve never covered — guides the Mode just as much, and a Staircase that omits it solves a different waveguide. Each such Region reaches the Staircase as one of these, cut against the Strip footprint so the two never overlap.

Attributes:

  • name (str) –

    Region name on the meshed Cross-section.

  • h (tuple[float, float]) –

    (min, max) extent along the junction axis (um).

  • z (tuple[float, float]) –

    (min, max) vertical extent (um).

  • material (str) –

    Material name, as the drawn stack names it.

  • layer_type (Literal['conductor', 'via', 'dielectric', 'substrate']) –

    How the mesher expresses it — "dielectric" for a meshed domain, "conductor" for metal meshed as an outline (ADR 0003).

  • properties (Any | None) –

    The material's own entry from the drawn stack, for a material the base materials database does not already carry (a doped-silicon material, say). None leaves the lookup to the database.

  • mesh_resolution (str | float) –

    Mesh resolution assigned to the Region.

build_staircase_cross_section

build_staircase_cross_section(
    carriers: Any,
    *,
    n_strips: int | None = None,
    junction: tuple[float, float] | None = None,
    zmin: float | None = None,
    zmax: float | None = None,
    segments: Sequence[StripSegment] = (),
    response: CarrierCoupling,
    material: StripMaterial,
    band: tuple[float, float] | None = None,
    electrodes: ElectrodeSpec | None = DEFAULT_ELECTRODES,
    surroundings: Sequence[SurroundingRegion] = (),
    drawing: StaircaseDrawing = DEFAULT_DRAWING,
) -> StaircaseCrossSection

Turn a Carrier map into a meshable Staircase cross-section.

The Carrier map is binned into n_strips piecewise-constant Strips across the Junction extent, the carrier coupling turns each Strip's averages into its material, and each Strip is drawn as its own Region beside the Traveling-wave electrodes and whatever of the drawn device is redrawn around them.

The Strips come either from one extent — n_strips equal Strips across junction, all between zmin and zmax — or from segments, each tiled with its own Strips at its own height, which is how a Staircase follows a rib standing beside a thinner slab.

Coordinates follow the Carrier map's own frame: carriers.x_um runs along the junction axis (the in-plane coordinate of the Cross-section) and carriers.y_um is the vertical one, which is how the charge-transport backend reports a Carrier map.

Parameters:

  • carriers (Any) –

    The Carrier map to staircase (anything exposing x_um, y_um, electrons_cm3 and holes_cm3).

  • n_strips (int | None, default: None ) –

    Number of Strips; 1 recovers the uniform model.

  • junction (tuple[float, float] | None, default: None ) –

    (min, max) Junction extent along the junction axis (um) the Strips tile.

  • zmin (float | None, default: None ) –

    Bottom z of the Strips (um).

  • zmax (float | None, default: None ) –

    Top z of the Strips (um).

  • segments (Sequence[StripSegment], default: () ) –

    The Strips as :class:StripSegment runs, low edge first, tiling one extent end to end — in place of n_strips, junction, zmin and zmax, which then stay unset.

  • response (CarrierCoupling) –

    The carrier coupling — the one thing that turns electron and hole concentrations into index shift, absorption and conductivity.

  • material (StripMaterial) –

    The per-solve strip input: an :class:OpticalStripMaterial (wavelength and unperturbed index) or an :class:RFStripMaterial (lattice permittivity and top frequency).

  • band (tuple[float, float] | None, default: None ) –

    (min, max) vertical band of Carrier-map samples averaged into the Strips; defaults to (zmin, zmax). Segments always average over their own height.

  • electrodes (ElectrodeSpec | None, default: DEFAULT_ELECTRODES ) –

    Flanking electrodes; None draws none.

  • surroundings (Sequence[SurroundingRegion], default: () ) –

    The drawn device's own Regions to redraw around the Strips — see :func:surroundings_from_section. Empty leaves the Staircase as Strips alone in the background medium, which is the right Cross-section only when the drawn device has nothing else inside the meshed Window.

  • drawing (StaircaseDrawing, default: DEFAULT_DRAWING ) –

    How the Staircase is drawn — layers, names, length, plane and substrate; :data:DEFAULT_DRAWING otherwise.

Returns:

Raises:

  • ValueError –

    When the extent reaches outside the Carrier map, the segments overlap or leave a gap, both ways of giving the Strips are used at once, or the strip count or geometry is not usable.

carrier_map_extent

carrier_map_extent(
    carriers: Any, band: tuple[float, float] | None = None
) -> tuple[float, float]

The extent a Carrier map covers along the junction axis (um).

Strips average the Carrier map, so they cannot reach past it: the extent here is the widest one :func:build_staircase_cross_section will accept.

Parameters:

  • carriers (Any) –

    The Carrier map (anything exposing x_um and y_um).

  • band (tuple[float, float] | None, default: None ) –

    (min, max) vertical band of samples to measure across; the whole map when omitted.

Returns:

Raises:

  • ValueError –

    When the band holds no sample of the map.

staircase_profile

staircase_profile(
    h: ArrayLike,
    values: ArrayLike,
    *,
    n_bins: int,
    h_min: float | None = None,
    h_max: float | None = None,
) -> tuple[NDArray[float64], NDArray[float64]]

Average a sampled 1D profile over N equal-width piecewise-constant Strips.

The samples are interpreted as a piecewise-linear function of h; each strip value is the exact average of that interpolant over the strip, so n_bins=1 recovers the exact mean of the profile and increasing n_bins converges to the continuous profile.

Parameters:

  • h (ArrayLike) –

    Sample coordinates along the Strip axis (um), any order.

  • values (ArrayLike) –

    Sample values (e.g. carrier concentration, sigma, Delta n).

  • n_bins (int) –

    Number of strips (>= 1).

  • h_min (float | None, default: None ) –

    Window start; defaults to min(h).

  • h_max (float | None, default: None ) –

    Window end; defaults to max(h).

Returns:

  • NDArray[float64] –

    (edges, means) — strip edges of length n_bins + 1 and the

  • NDArray[float64] –

    per-strip averages of length n_bins.

strip_averages_from_nodes

strip_averages_from_nodes(
    h_um: ArrayLike,
    values: ArrayLike,
    *,
    n_strips: int,
    h_min: float | None = None,
    h_max: float | None = None,
    v_um: ArrayLike | None = None,
    v_range: tuple[float, float] | None = None,
    column_tol_um: float | None = None,
) -> tuple[NDArray[float64], NDArray[float64]]

Average scattered node values into N strips along the junction axis.

Node values (e.g. carrier concentrations on the charge-solve mesh) are reduced to a 1D profile of h and binned with :func:staircase_profile, whose strip values are exact averages of the piecewise-linear interpolant — so n_strips=1 recovers the profile mean and increasing N converges to the continuous profile.

A band selected with v_range is averaged over its area: the profile at each h is the mean over the band's height of the linear interpolant of the node cloud — the field a linear transfer reads off the same nodes. Counting nodes instead would weight the field by the mesh's refinement: a charge-solve mesh puts a third of its nodes on the silicon's top and bottom lines, which have no area, and the carriers there are not the Strip's once they vary with depth. A band whose nodes span no height (a single row) has no area to weigh, and its nodes are the profile.

The band is taken as a rectangle of silicon, the height of its nodes. Where the silicon changes height along the axis — a rib beside a thinner slab — one band over both would average across the oxide above the slab, on values interpolated between slab and rib; give each height its own call and v_range, as a Staircase's segments do.

Parameters:

  • h_um (ArrayLike) –

    Node coordinates along the junction (binning) axis in um.

  • values (ArrayLike) –

    Node values (same length as h_um).

  • n_strips (int) –

    Number of strips (>= 1).

  • h_min (float | None, default: None ) –

    Window start along the axis; defaults to min(h_um).

  • h_max (float | None, default: None ) –

    Window end along the axis; defaults to max(h_um).

  • v_um (ArrayLike | None, default: None ) –

    Optional node coordinates transverse to the binning axis (e.g. z); used with v_range to select a band of a 2D node cloud before binning.

  • v_range (tuple[float, float] | None, default: None ) –

    Optional (min, max) band in the v_um coordinate.

  • column_tol_um (float | None, default: None ) –

    Nodes whose h agree to within this (um) are one column of the mesh and are averaged together; defaults to :data:COLUMN_TOL_FRACTION of the sampled extent.

Returns:

  • NDArray[float64] –

    (edges, means) — strip edges of length n_strips + 1 and

  • NDArray[float64] –

    per-strip averages of length n_strips.

surroundings_from_section

surroundings_from_section(
    section: Iterable[Any],
    *,
    strip_span: tuple[float, float],
    strip_z: tuple[float, float],
    stack: LayerStack | None = None,
) -> tuple[SurroundingRegion, ...]

Everything a drawn Cross-section has around the Strips.

Each rectangle of the drawn section is cut against the Strip footprint: the part the Strips replace is dropped, and the rest becomes a :class:SurroundingRegion carrying the drawn material. That is one rule for every Region. The doped silicon the Carrier map speaks for disappears wherever the Strips cover it and survives wherever they do not, so a Strip extent narrower than the doped slab leaves unperturbed silicon rather than a hole.

Parameters:

  • section (Iterable[Any]) –

    Rectangles of the drawn Cross-section, each exposing layer_name, material, y0, y1, zmin and zmax (the output of :func:gsim.common.cross_section.extract_plane_section on an x-normal plane).

  • strip_span (tuple[float, float]) –

    (min, max) extent the Strips tile (um).

  • strip_z (tuple[float, float]) –

    (min, max) vertical extent of the Strips (um).

  • stack (LayerStack | None, default: None ) –

    The drawn layer stack, read for two things the section rectangles do not carry: how each Region is meshed ("conductor" metal becomes an outline rather than a domain, ADR 0003), and the material entry of a material the base database does not know.

Returns:

  • SurroundingRegion –

    The surrounding Regions, in section order, each named after the

  • ... –

    Region it came from (suffixed when one rectangle cuts into

  • tuple[SurroundingRegion, ...] –

    several pieces).

Raises:

  • CrossSectionOrientationError –

    The Cross-section was not cut on an x-normal plane. No caller builds a y-normal Staircase, so the contract is enforced rather than generalised.