GDSFactory FDTD guide¶
gsim.fdtd separates simulation setup into geometry, materials, source,
monitors, domain, and solver concerns. It generates the transfer mesh and
validated config.json, submits one source to one cloud job, and returns typed
results.
Use Simulation to configure a run and
FDTDResult to inspect its output.
Configure and run¶
from gsim import fdtd
sim = fdtd.Simulation(pdk=gpdk)
sim.materials(background="SiO2")
sim.geometry(component=mmi, geometry_tolerance_nm=10)
sim.source(
port="o1",
wavelength_um=1.55,
wavelength_span_um=0.1,
num_wavelengths=101,
)
sim.domain(padding=0.75, pml_cells=16)
sim.solver(
cell_size_nm=40,
energy_decay_fraction=1e-6,
max_wall_seconds=3600,
)
result = sim.run(check_cache=True)
result.plot()
result.plot_plotly()
The transfer mesh preserves the resolved CAD boundaries exactly and uses coarse
tetrahedra in volume interiors. Its default maximum target size is 1 µm;
mesh_size_nm remains available as an advanced override. Gmsh conforms to every
explicit component, hole, gap, tooth, and port edge even when it is smaller than
that target. geometry_tolerance_nm is a geometry-error bound, not a mesh edge
size.
Transfer meshing is independent of cell_size_nm, which requests the actual Yee
grid used by the FDTD solver and defaults to 60 nm. Source sweeps default to 101
wavelengths. Guided-port monitors are implicit; one port source returns one
S-matrix column.
Virtual port layers¶
When a guided port uses a virtual routing marker, gsim can find its physical
core through the PDK cross-section. Pass a cross-section to add_port() to
retain its complete section description on the port:
import gdsfactory as gf
routing = gf.cross_section.cross_section(
width=0.5,
layer=(100, 0), # Virtual port marker.
sections=(gf.cross_section.Section(width=0.5, layer=(1, 0)),),
)
waveguide.add_port(
name="o1", center=(0, 0), orientation=180, cross_section=routing
)
sim.geometry(component=waveguide)
Here the physical core is drawn on (1, 0) and must already have a
material-bearing entry in the PDK LayerStack. The marker is not extruded.
gsim reads gdsfactory's saved cross-section snapshot or the port's named
cross_section metadata. Without either, it checks default-instantiable
factories in PDK.cross_sections. Only visible sections with the same width
and offset as the primary marker section identify the core; wider cladding
and offset sections do not. The actual resolved geometry at each port decides
which vertical bands are present, so a local etch can give two ports different
heights. Material identity is supplied by the LayerStack.
An inferred core must form one abutting, non-overlapping group of a single
material. Equivalent registry aliases are accepted; multiple different cores
or incompatible bands raise UnsupportedPortError instead of selecting one.
Unmapped vertical optical ports retain their free-space semantics.
Use port_layer_map when a cross-section does not describe an unambiguous core,
or to select particular physical bands explicitly:
The marker layer is not added to the mesh. The mapped physical entry supplies
the port's material and vertical position, and must contain the port location.
Explicit maps take precedence, followed by existing direct physical-layer
matches. Cross-section inference is a fallback when direct matching fails.
When an unmapped port matches abutting vertical bands of the same material, its
mesh surface includes those bands and its center uses their combined height.
Overlapping entries are not joined; candidates are considered in mesh-priority
order. The saved port layer is the primary material and priority reference;
the port's mesh physical group defines its complete cross-section.
An explicit single-entry mapping keeps the port limited to that entry.
For a core represented by several physical bands, select their LayerStack keys as a tuple:
All selected bands must have resolved geometry at the port location, use the
same material, and abut without overlaps or gaps. Empty selections, duplicate
keys, and incompatible bands raise UnsupportedPortError. The first key stays
the primary material/priority reference; the mesh covers the complete selected
height. Existing string mappings retain their single-band behavior.
Bounded PDK stacks¶
Keep the PDK's LayerStack unchanged and specify the physical window directly.
Opt in to trimming material geometry with clip_geometry=True:
sim = fdtd.Simulation(pdk=pdk)
sim.domain(z_bounds=(-0.5, 1.0), clip_geometry=True)
sim.geometry(component=waveguide)
Set the bounds before resolving geometry. Films wholly outside the vertical
window and footprints outside the XY window are omitted before their materials
are required. Sidewall overhangs are retained conservatively. This includes
films with negative thickness; boundary-only contact has no material volume.
Intersecting layers keep their original sidewall profiles and are clipped by
the mesher; the PDK object is not modified. Missing materials inside the window
still raise an error. GeometryClippingWarning identifies layers and axes
where explicit bounds trim or wholly omit material, including truncated
blanket films. Repeated resolution of the same component/window does not
repeat this warning. Empty masks and bounds containing all material do not
warn. Source containment and guided-port face checks still apply.
Migration for 0.10.0¶
clip_geometry is deprecated starting with 0.10.0, but remains functional
through that release. Its default remains False: explicit bounds must
contain the geometry unless clip_geometry=True is supplied. Both values
remain supported in saved domain settings and the JSON schema. Explicit domain
configuration and assignments emit a DeprecationWarning attributed to the
calling code. Dumps omit an unspecified switch, so ordinary model round trips,
writes, and previews do not warn about a switch the user never set.
The removal target is 0.12.0 or later, and only after at least two feature releases and 12 months since the first released warning in 0.10.0. If those conditions are not met in 0.12.0, removal and automatic clipping move to a later incompatible release. Until then, keep the flag wherever clipping is required. Cloud cache lookup uses generated input files; changing the physical window can change the mesh, configuration, and cache identity.
Levels marked background=True fill the physical simulation domain in XY,
including lateral padding, without requiring a drawn source polygon. Their
background_exclude_layers masks still remove material. Patterned levels follow
their masks. Every blanket film intersecting the chosen z interval is retained
and clipped to that interval; films wholly outside it are omitted. Preview and
written Gmsh geometry use the same domain. Automatic padding is applied once,
and neither the component nor the PDK stack is modified.
Display metadata such as info.visible=False only changes initial viewer
visibility. Hidden films remain in the simulation and can be enabled for
inspection.
Port centers and diagnostic windows follow the clipped active bands. Automatic diagnostic planes, including their cladding margins, are intersected with the physical domain when previewed or written. The requested monitor windows remain available if the domain is enlarged; the original LayerStack extrusion and sidewall fields are retained.
Linear PDK sidewall angles are represented as continuous ruled solids between
their exact bottom and top contours. If polygon offsetting changes component,
hole, or edge topology, meshing safely falls back to vertical slices bounded by
geometry_tolerance_nm instead of constructing an invalid loft.
Use write(path) to generate mesh.msh and config.json without submitting.
The original flat constructor keywords remain accepted for compatibility.
Material dispersion¶
MaterialCards attached to the PDK object or exported by its module are discovered
automatically and take precedence over built-in cards. Schema Lorentz and Drude
models are evaluated using their angular frequencies in rad/s and the passive
n+ik convention. Their loss and wavelength dependence follow the same solver
rules as other cards below.
By default, each material reaches the solver as its index at the source
wavelength. A broadband run therefore uses that one index at every wavelength.
write() and run() emit one warning that names every material whose card
varies over the source band, and by how much.
sim.materials(dispersion=True) sends those cards as dispersive models instead.
The deployed GDSFactory FDTD solver does not accept them yet, so a run with
dispersion=True currently fails on the cloud.
| Material card | config.json material entry with dispersion=True |
|---|---|
| Constant, lossless | refractive_index |
| Sellmeier, lossless | dispersion.sellmeier, with wavelength_range_nm |
| Anything else (tables, equations, loss) | dispersion.table of n and k |
Tables are sampled at 21 evenly spaced wavelengths, plus the knots of a
tabulated card inside the band, so that narrow features are kept. The sampled
range is the source band plus a 10 % margin on each side; a side keeps its
margin only if the card is still valid there. A card that does not cover the
band itself raises FDTDConfigError.
A continuous-wave or zero-span source needs only the index at its wavelength,
so every material is written as a constant there. The solver encodes loss only
in a dispersion table, so a lossy card raises unless the source is pulsed and
dispersion=True. sim.materials(overrides={"si": 3.47}) always gives a
constant material.
Domain padding is specified in micrometers, using padding as a shared fallback
and padding_x, padding_y, or padding_z to override individual axes. Each
accepts a nonnegative scalar (equal padding on both sides) or a
(negative_side, positive_side) pair. Zero padding is allowed.
sim.domain(
padding=1,
padding_x=(0, 2), # -x, +x
padding_y=0.5, # both y sides
padding_z=(1, 2), # below, above
)
Explicit axis padding is measured from the resolved geometry bounds. Without
padding_z, automatic Z sizing uses the PDK background stack when present,
otherwise the shared padding. The shared fallback retains automatic guided-port
alignment. Explicit axis padding must be zero on a side containing a guided
port: waveguide extensions into padding are not currently supported, and a
nonzero value on that side raises an error. For a bend with an input on the
negative X face and an output on the positive Y face, use
padding_x=(0, 1) and padding_y=(1, 0) to pad its other sides.
The old padding_um domain argument and background_padding_um constructor
argument have been removed; configure sim.domain(padding=...) instead.
Optional x_bounds, y_bounds, and z_bounds tuples set the non-PML physical
domain in micrometers. Omitted axes remain automatically sized from the
component, PDK stack, and padding. With clip_geometry=True, explicit bounds
trim material geometry and must contain sources; guided ports must remain on
a domain face. Plane monitor
windows are intersected with the domain and warn if cropped. The backend
adds PML outside these bounds. The resulting box is written to config.json as
grid.non_pml_bounds, in nanometers.
Do not combine explicit bounds and explicit per-axis padding on the same axis;
the shared padding fallback can still be used for other axes.
sim.domain(
x_bounds=(0.0, 35.0),
y_bounds=(-12.0, 12.0),
z_bounds=(-1.0, 1.55),
clip_geometry=True,
)
Background default in 0.10.0¶
The 0.10.0 feature release changes the default simulation background from
"SiO2" to "Air", an ideal lossless, nondispersive material with refractive
index 1. This intentional change does not target a 0.9.x patch release.
Stack regions continue to use their own material cards and take priority over the background. The background fills space not occupied by those regions; it does not replace BOX, substrate, cladding, or patterned materials. A domain fully filled by stack regions retains those physical material assignments.
Existing calls that omit a background can change behavior in uncovered space.
Source and receiver references that inherit the background can also change.
Automatic Z sizing can differ because it follows matching background stack
levels when available. Unused Air declarations (such as an undrawn undercut)
do not enlarge the automatic domain. Air and its built-in air alias use
the same bounds. Explicit domain bounds remain in force.
For example, a bare gpdk silicon component with no drawn oxide simulates silicon
in air when the background is omitted, once its material names resolve.
GDSFactory 9.x uses the lowercase si name; with those releases, supply
sim.materials(overrides={"si": 3.47}) when the PDK has no card for it.
Declaring oxide in the LayerStack does
not create oxide geometry. Select background="SiO2" to fill otherwise
unoccupied space with oxide.
To preserve the former environment, add sim.materials(background="SiO2"),
or retain background_material="SiO2" in the historical constructor API.
Saved settings with an explicit background are unchanged; settings omitting it
use the new default when loaded. Set z_bounds or padding_z explicitly if
preserving an automatically chosen vertical extent matters. Re-exporting
updates inputs and cache keys; previously generated inputs and results are
unchanged. The existing FDTD notebooks already choose their backgrounds
explicitly.
Setup visualization¶
plot_2d() produces a static Matplotlib cross-section, like the Meep setup view.
plot_2d_static() remains available with the same behavior and arguments.
Materials are colored by their real refractive index at the source center
wavelength, with a colorbar, physical-domain boundary, hatched PML regions, and source
and monitor annotations where they intersect the slice. The plot uses the FDTD
transfer mesh, including sidewalls and material priorities. All physical groups
are shown by default; show_groups and hide_groups select physical group names.
ax = sim.plot_2d() # XY at geometry midpoint
ax = sim.plot_2d(axis="z", position_um=0.11) # XY at z = 0.11 µm
ax = sim.plot_2d(axis="x", position_um=0, show_mesh=True) # YZ with mesh edges
ax.figure.savefig("cross_section.png", dpi=200, bbox_inches="tight")
To overlay material boundaries on a field plot, pass its Matplotlib axes with
outline_only=True. Boundaries follow the selected slice and material priority,
including holes. Touching regions of the same material share one outline.
This mode preserves existing axes limits, labels, aspect and colorbars, and adds
no fills, setup annotations, legend or refractive-index colorbar.
The same option is available on plot_2d(). Group filters remain available;
outline_only=True cannot be combined with show_mesh=True.
The method returns a Matplotlib Axes. Pass ax to draw into an existing
subplot, cmap to change the index colormap, legend=False to hide the legend,
aspect="auto" to fill the axes, or figsize=(8, 4) to set the figure size.
An omitted position_um uses the geometry midpoint along the requested axis.
If explicit bounds clip material on that axis, it uses the bounded domain
midpoint instead; bounds containing the geometry keep the geometry midpoint.
The current geometry and material settings are resolved for every call. A
temporary mesh is generated; the plot does not require selecting a source port
or writing run artifacts. A selected source port must exist, and sources and
monitors must fit any explicit domain bounds, as required by write(). The PML
thickness uses the same per-axis alignment as the metadata estimate: z PML is
rounded up to a multiple of 16 cells (for example, 20 becomes 32). Guard cells
are not drawn as PML. Mesh edges describe the tetrahedral transfer mesh,
rather than the solver's Yee grid.
Without mesh edges, adjacent cells are merged into material regions with
antialiased boundaries. Consecutive equally colored physical groups share a
fill to avoid seams at overlapping edges; their legend entries remain separate.
SVG and PDF exports retain vector material outlines;
show_mesh=True retains the individual mesh cells and rasterizes the overlay.
The interactive setup views use the GDSFactory FDTD Three.js viewer and do not depend on PyVista. Smaller material groups are listed first, followed by the largest volumetric group and then the ports.
sim.plot_3d() # solid interactive geometry
sim.plot_3d(show_mesh=True) # add Gmsh surface edges
sim.plot_3d(zoom_to_cursor=False) # zoom toward the view center
sim.plot_2d_interactive(axis="z", position_um=0.11) # movable cross-section
viewer = sim.plot_2d_interactive(show_mesh=True) # add transfer-mesh edges
viewer.save("mesh.html")
The interactive 2D viewer includes a slider that moves the plane through the
mesh. plot_2d_interactive() and plot_3d() return a standalone MeshViewer.
Each call resolves the current settings and generates a temporary mesh, so edits
to geometry, meshing, background material, and domain settings appear immediately.
Previously written simulation artifacts are preserved.
The 3D viewer uses PDK layer-view fill colors, falling back to frame colors when
the fill is absent. Stack info["color"] overrides the layer-view color. Colors
can be CSS color strings; their alpha channel does not change surface opacity.
An exactly named layer view matching the stack key, or its declared name,
is preferred over a physical-layer lookup. Otherwise the derived layer view
is preferred, with the source layer view as a fallback. A drawing layer reused
by background films of distinct materials does not supply an individual film
color: those films use explicit stack/named colors or the fallback palette.
Visibility and opacity still follow their existing PDK defaults.
For duplicate colored views of a GDS layer, the first effectively visible view
is preferred, then the first colored view. Missing colors retain the viewer's
fallback palette, including its port and largest-group colors. These display
choices do not change the mesh or solver configuration.
The viewer also uses each PDK stack entry's info["opacity"] and layer-view
visibility by default, including hidden parent groups. If several layer views
refer to the same GDS layer, it is initially visible when any of those views
and its enclosing groups are visible, regardless of view order. Stack info["visible"]
overrides layer-view visibility. Only stack entries with resolved geometry have
their display metadata applied and validated. A zero opacity starts a layer hidden;
enabling it in the viewer's layer list makes it fully opaque (opacity=1.0),
which can obscure enclosed layers. Explicit show_groups
and hide_groups override these initial visibility defaults; hide_groups
takes precedence. Entries without display metadata retain the viewer defaults.
Zooming moves toward the pointer by default; set zoom_to_cursor=False to zoom
toward the view center instead. The same choice is available in the viewer's
Zoom toward controls.
The viewer also summarizes the physical domain, estimated Yee-grid dimensions
and total cell count (including PML). Grid counts use the same Python calculation
as metadata.json, preserving its rounding and per-axis alignment. These values are estimates; the solver
backend is authoritative when it constructs the final grid.
2D plotting migration (0.10.0)¶
The next feature release, 0.10.0, intentionally changes plot_2d() from the
interactive HTML MeshViewer to a static Matplotlib Axes, making the standard
2D setup method produce the static preview. Static calls do not emit a deprecation
warning. plot_2d_static() remains a supported equivalent.
To make setup examples easier to use, inspect and export, this default changes in
0.10.0 rather than following the normal two-feature-release, three-month transition.
Callers using .html or .save() should change
their call to plot_2d_interactive() to retain the previous interactive behavior.
Legacy plot_2d(height=...) or plot_2d(zoom_to_cursor=...) calls continue returning
the HTML viewer with a DeprecationWarning. Removal targets 0.12.0 or later,
after two feature releases and at least three months since the first released
warning in 0.10.0. If those conditions are not met, removal moves to a later feature
release. These viewer keywords cannot be mixed with static-only options
such as ax or outline_only. The explicit interactive method remains supported.
For static exports, use
ax.figure.savefig(...); ax, cmap, legend, aspect, and figsize configure
the static view. This default change is intended for 0.10.0, not a 0.9.x patch.
Sources¶
PortSource requires an explicit sim.source(port="...") selection before
artifacts can be written or a job can run. A guided PDK port maps to an
eigenmode source. Selecting a vertical_te or vertical_tm PDK port instead
derives a Gaussian beam and fiber monitor from the port metadata.
To excite a specific guided mode, set its one-based mode_order:
The selector is also available as fdtd.ModeSelection. te_like and tm_like
select the first candidate with the requested polarization; those selectors
require a transverse te_axis and can set num_candidate_modes and
min_polarization_fraction. With no selector, the fundamental mode is used.
The implicit guided-port monitors use the same selection as the source.
te_axis is a global coordinate axis and must be transverse to every guided
port. Components with both x-normal and y-normal ports, such as a 90-degree
bend, require te_axis="z". Vertical fiber monitors do not use this selector.
Replace sim.source to use another physical source:
sim.source = fdtd.DipoleSource(
position_um=(0, 0, 0.11),
current_axis="z",
wavelength_um=1.55,
)
sim.source = fdtd.LineCurrentSource(
position_um=(0, -0.5, 0.11),
line_axis="y",
current_axis="z",
length_um=1,
)
GaussianBeamSource exposes the aperture center and size, propagation and
polarization vectors, focal point, waist, and optional background index. Only
PortSource on a guided port produces normalized S-parameters. Other source
types return outgoing port amplitudes and powers.
Plane monitors¶
FDTD input exports include a versioned monitor-memory estimate in
metadata.json under memory.estimated_monitor_memory_bytes. The estimate
covers explicit plane monitors, automatic guided-port monitors, spectral field
accumulators, reference profiles, retained port-mode data, and sample buffers.
It uses conservative pixel bounds and excludes the main grid, material/PML
state, and temporary eigensolver workspace. More wavelength points increase
spectral storage even when no extra monitor is added.
Cloud preparation sends this byte estimate alongside the unchanged Yee-cell
count as sizing_requirements.fdtd.estimated_monitor_memory_bytes. Resource
selection remains server-owned. Older input directories without the estimate
retain their cell-count-only sizing request. Diagnostic metadata remains
excluded from the simulation input hash.
For notebook diagnostics, add center-wavelength field intensity images with one call after configuring geometry, source and solver:
sim.add_monitors(xy_name="field_xy") # Optical port images and an XY field image.
sim.add_monitors(xy=False) # Alternative: optical port images only.
sim.add_monitors(xy_name="field_xy", z_um=0.11) # Alternative: set the XY height in micrometers.
sim.add_monitors(xy_name="field_xy", margin_um=1.0) # Alternative: more cladding around each port.
These are alternative calls, not a sequence: monitor names must be unique.
xy=True is the default; z_um=None chooses the resolved geometry's vertical
midpoint within any opted-in crop and is ignored when xy=False. Each optical
port's plane follows its
own width and its selected physical bands' active vertical bounds, including
negative layer thickness and any opted-in geometry crop. margin_um=0.75 adds
that much cladding on each side of the cross section; set it to zero for only
the active region or increase it for wider field
tails. This is a geometric window, not an automatically mode-converged aperture.
The plane is three grid cells inward along its normal. Port images are named
port_<port_name> (for example, port_o1); the field_xy image spans the component's
bounding box at a constant Z height. All these planes use the source center wavelength, record intensity
without flux, and leave implicit guided-port responses unchanged. They show the
driven field, not independent source eigenmode profiles. Existing custom monitors
are preserved, and name collisions fail before adding any of these planes.
Changing geometry/source/solver later requires recreating the diagnostic planes.
This helper only configures monitors; it does not mesh or submit a job. Dimensional suffixes
follow the existing center_um/position_um conventions; the domain's padding
rename is specific to its directional-padding API.
During write() or run(), every explicitly configured plane monitor is
intersected with the physical, non-PML domain, whether the domain is automatic
or explicitly bounded. This applies to XY, YZ, and XZ planes, including port
images and custom heatmap, flux, and fiber-overlap monitors. Each cropped
monitor emits one UserWarning identifying its name and the original and cropped
extent on every changed axis, in micrometers. Flux and fiber-overlap warnings
also note that the measurement aperture changes. The physical domain and the
requested sim.monitors settings remain unchanged; the submitted config.json
contains the cropped bounds, and results report the actual sampled extents.
plot_2d_static() shows the same cropped monitor windows and warnings.
A plane whose normal position is outside the physical domain, whose window is
disjoint from it, or whose cropping collapses a requested nonzero extent raises
FDTDConfigError before meshing or submission. Planes on the domain boundary
and already contained zero-width line or point probes retain their existing
behavior. Sources are never cropped.
Field-monitor migration (0.9.0 onward)¶
Starting in 0.9.0, use sim.add_monitors(xy_name="field_xy") to choose the clearer
name for the device-wide intensity image. Existing sim.add_monitors() calls
still generate overview_xy, preserving monitor iteration, serialized settings,
config.json, raw result keys, and cache inputs for contained planes. Omitting
xy_name when xy=True emits a DeprecationWarning announcing the new name.
The default will remain overview_xy for at least two feature releases and
roughly 12 months after the first released warning. The default change targets
0.11.0 or a later feature release, whichever first satisfies both conditions. Set
xy_name="overview_xy" explicitly to retain the old generated name indefinitely.
xy_name is ignored when xy=False, which does not issue a naming warning.
When opting into field_xy, update monitor-name comparisons and code reading
raw configuration or solver JSON to use that name. Existing
sim.monitors["overview_xy"], sim.monitors.remove("overview_xy"), and
result.monitors["overview_xy"] lookups remain supported as compatibility aliases;
field_xy lookups also work on saved results using overview_xy. Exact names
take precedence if both names were explicitly configured. Iteration and
serialization retain the stored name without duplicate images. The old lookup
name remains supported, with no removal planned.
Earlier versions checked monitor containment only on explicitly bounded axes: partially outside monitors either failed locally or reached the solver and could fail there. The 0.9.0 behavior crops overlapping windows with a warning and rejects unusable planes locally, avoiding wasted cloud setup. To retain a requested measurement aperture, enlarge the physical domain where allowed by guided-port constraints; otherwise reduce the window or move the plane into the domain. Rewriting artifacts applies these checks to existing configurations.
Additional plane monitors can independently record flux, scalar heatmaps, and Gaussian fiber overlap:
sim.monitors.add_plane(
name="top",
center_um=(0, 0, 1),
size_um=(10, 6, 0),
normal="+z",
flux=True,
heatmap=fdtd.Heatmap(
quantity="intensity",
wavelengths_um=[1.55],
),
)
For a vertical PortSource, request a field image from its implicit port plane:
sim.source(
port="o2",
vertical_monitor_heatmap=fdtd.Heatmap(
quantity="abs_e",
wavelengths_um=[1.55],
),
)
Monitor names are unique. Use add(), remove(), and clear() to manage the
collection. A plane's size must be zero along its normal.
Fiber reference medium¶
When FiberMode.refractive_index is omitted, the exporter determines the real
index at the source center wavelength from the material covering the receiver's
cropped aperture. It checks the exported tetrahedral mesh, including sidewalls,
holes, overlapping material priorities, and both sides of the plane. A receiver
outside stack volumes uses the simulation background. Different materials with
the same real index can share a reference medium.
Set FiberMode(refractive_index=...) to choose the reference medium explicitly.
For an implicit receiver derived from a vertical port, use
sim.source(vertical_refractive_index=...). The selected vertical port's Gaussian
beam and its receiver use the same index. Explicit GaussianBeamSource settings
retain their existing behavior.
An aperture spanning different indices, lying on an interface, or lacking a usable area cannot determine one homogeneous Gaussian reference. The exporter warns and retains the background index for compatibility; set the relevant explicit index to define the intended reference.
This numerical correctness fix targets the next patch release after 0.9.0.
Previously, an omitted fiber index always used the global background, even for
a receiver embedded in a different stack material. Such setups can produce
different coupling values after this fix, while their material assignments stay
unchanged. To preserve the previous reference, supply the background's index
explicitly through FiberMode.refractive_index or
PortSource.vertical_refractive_index. Re-exporting updates solver inputs and
their cache keys; existing downloaded results are unchanged. The simulation
background default is unchanged by this fix.
Complex-field export¶
Request complex plane fields with Fields. Omit fields to retain the
existing output, or pass Fields() to save all six E/H components at the
monitor's wavelengths. Components are case-insensitive; explicit selections
must be nonempty and unique. The field request can select its own wavelengths
in micrometers and can be used without flux, heatmaps, or a fiber mode.
sim.monitors.add_plane(
name="capture",
center_um=(5, 0, 1),
size_um=(10, 8, 0),
normal="+z",
flux=False,
fields=fdtd.Fields(
components=["ex", "ey", "hx", "hy"],
wavelengths_um=[1.54, 1.55, 1.56],
),
)
result = sim.run(check_cache=True)
monitor = result.monitors["capture"]
sample = monitor.field("ey", wavelength_um=1.55)
ey = sample.load() # Complex NumPy array, shape (v, u).
u_um = sample.coordinates.u_um
v_um = sample.coordinates.v_um
sample.metadata["normalization"] # "raw_dft" for GDSFactory FDTD output.
monitor.fields contains the exported component/frequency records. field()
selects the closest exported wavelength for the requested component; inspect
the returned wavelength_um. Real and imaginary sidecars are loaded lazily,
with shape, dtype, and finite-value checks. A missing file raises an error
when loaded. Actual sample coordinates and the snapped normal position are
available through monitor.field_coordinates or sample.coordinates, in
micrometers. They can differ from the requested monitor bounds and position.
The plane's monitor.shape is (n_u, n_v). Complex-field and heatmap arrays
are (n_v, n_u): rows follow v_um, columns follow u_um. For example, a
plane with three U samples and two V samples reports (3, 2) and loads
arrays of shape (2, 3).
Loading preserves the exported complex values without source normalization,
noise masking, or phase corrections. sample.metadata retains the backend's
normalization, DFT convention, phase reference, colocation, field-unit system,
solver time unit, and boundary-interpolation metadata. Raw DFT fields are not
incident-power-normalized fields or fiber coupling efficiencies. Quantitative
overlap postprocessing requires consistent normalization and sampling.
dft_convention="exp(-i*omega*t)" describes the Fourier integration kernel:
the solver accumulates sum(field(t) * exp(-i*omega*t) * sample_dt).
The corresponding phasor has time dependence exp(+iωt), so a forward
wave's phase decreases along its propagation direction. This agrees with
result.s_parameters; the loader does not conjugate either result. Electric
and magnetic fields use their actual Yee sample times before spatial colocation.
Missing or unsupported DFT conventions are rejected; legacy results without
complex-field entries remain supported.
A recorded straight-waveguide run
checks both conventions on real output. Its (25, 32) arrays retain the forward
phase decrease, and the independent 0.5 * Re(E × conj(H)) integral agrees with
the native plane flux within 1.2%. Exact equality is not expected because the
exported fields are colocated while the native flux retains transverse Yee
staggering. The sample includes the result JSON and paired arrays.
Selecting fewer components or wavelengths reduces the saved field payload. Existing result files without complex fields continue to load normally.
The grating-coupler example uses a small notebook helper to calculate Gaussian fiber overlap from saved fields.
Results¶
result.s_parameters.plot()
result.s_parameters.plot_plotly()
s_parameter_table = result.s_parameters.to_dataframe()
result.port_outputs.plot(quantity="modal_power")
port_table = result.port_outputs.to_dataframe()
# Net monitor flux can be useful as a diagnostic normalization.
result.plot_plotly(normalize_to="top")
# For a Gaussian source, use its analytic incident power and mask weak tails.
coupling = fdtd.gaussian_coupling_efficiency(
result, sim.source, port="o1"
)
coupling.plot_plotly()
# An eigenmode-normalized fiber overlap is an amplitude; plot its power.
fiber = fdtd.fiber_coupling_efficiency(result.monitors["fiber"])
fiber.plot_plotly()
top = result.monitors["top"]
top.plot_flux()
top.plot_heatmap(wavelength_um=1.55)
Heatmap arrays are loaded lazily from their .npy sidecars. S-parameter plots
gap samples flagged below the source noise floor by default. Convergence, grid,
timing, and resolved runtime settings remain available on the result object.
Simulation setup views remain separate from these result plots: sim.plot_*()
inspects the submitted geometry and mesh, while result.plot*() displays solver
output.
Export to SAX and Touchstone¶
One run excites one port, so it measures one column of the S-matrix. Run a source at each port and combine the results
with s_matrix. SAX is not a gsim dependency and is installed separately with pip install sax;
s_matrix and write_touchstone do not need it.
import sax
result_o1 = sim.run(check_cache=True)
sim.source(port="o2", wavelength_um=1.55, wavelength_span_um=0.1, num_wavelengths=101)
result_o2 = sim.run(check_cache=True)
matrix = fdtd.s_matrix([result_o1, result_o2])
model = matrix.sax_model()
circuit, _ = sax.circuit(
netlist={
"instances": {"arm": "dut", "delay": "straight"},
"connections": {"arm,o2": "delay,in0"},
"ports": {"in": "arm,o1", "out": "delay,out0"},
},
models={"dut": model, "straight": sax.models.straight},
)
transmission = circuit(wl=1.55)["in", "out"]
matrix.write_touchstone("device") # device.s2p
With fewer runs than ports, s_matrix raises and lists the entries no run measured. SAX reads an
absent entry as zero, so you state each assumption explicitly:
matrix = fdtd.s_matrix(
result_o1,
assume_reciprocal=True, # S(o1,o2) copied from the measured S(o2,o1)
assume_unmeasured_zero=True, # what is left, here S(o2,o2), set to zero
)
matrix.measured # False for every assumed entry
Runs must share their ports and wavelengths. Samples below the source noise floor are dropped, with a warning. This often affects a band-edge sample, which narrows the band the model accepts.
The model takes wl in micrometers and covers the simulated band only: a wavelength outside it raises. It interpolates
magnitude and unwrapped phase, and unwrapping needs phase to change by less than pi between wavelengths, which means a
wavelength step below λ²/(2·n_g·L). Stay below ¾ of that step, about 2.6 nm for 100 µm at n_g = 3.4 and 1.55 µm:
s_matrix warns from ¾ pi, for each measured entry with at least a tenth of the strongest peak.
It cannot catch every undersampled grid, because a delay can alias to a smaller one with small steps, so choose the step
from the longest path in your device. The model computes with numpy, so it works in sax.circuit but cannot be traced by jax.jit.
The two exports use different conventions:
| Where | Entry for transmission from o1 to o2 |
Time convention |
|---|---|---|
result.s_parameters, matrix.s, Touchstone |
S(o2,o1) (receive, source) |
exp(+jωt), phase falls with length |
sax_model() |
("o1", "o2") (in, out) |
exp(-iωt), phase rises with length, as sax.models.straight |
sax.parsers.parse_touchstone keeps the phase sign of the file and reads s[i, j] as (in, out), so a file written here
does not compose correctly with SAX's photonic models that way. Use sax_model() to reach SAX.
Time convention of the solver. gsim takes the solver's values as exp(+jωt). The solver does not state this, so it was
checked on a real run of a 10 µm silicon straight waveguide: phase falls with frequency at every sample, with a delay of
139 fs against 137 fs from the group index of a separate mode solver. That is one device, so
s_matrix still warns if the strongest transmission has a
negative group delay. Real anomalous dispersion, such as inside a ring notch, can also trigger this warning. A
transmission whose phase does not move across the band gives no sign to judge. On a grid too
coarse to unwrap phase, this check can stay silent even when the sign is wrong, so silence is not proof.
Phases are referenced where the solver's port monitors sit, and gsim does not de-embed them. The z0 argument of
write_touchstone only fills the file header, because the S-parameters are normalized per mode.