Monitors

This page lists every monitor class in witwin.maxwell (import as import witwin.maxwell as mw). You add a monitor to a scene with scene.add_monitor(...), run the simulation, and read the recorded data with result.monitor(name). All monitor objects are frozen dataclasses: you cannot change their attributes after construction.

Lengths are in metres and frequencies in hertz. When a monitor takes frequencies=None, it records at the simulation frequencies passed to mw.Simulation.fdtd(...). Explicit monitor frequencies are added to the frequencies the FDTD run samples.

What result.monitor(name) returns for each monitor:

See Result for monitor, raw_monitor, and frequency selection, and Sources and monitors for background.

PointMonitor#

class PointMonitor(name, position, fields=('Ez',))

Records the frequency-domain value of field components at one point.

Raises ValueError when position does not have three values or fields is empty.

Result payload. result.monitor(name) returns a dict:

Each value is a complex scalar for one frequency, or has shape [F] for F frequencies.

scene.add_monitor(mw.PointMonitor("probe", (0.0, 0.0, 0.16), fields=("Ez",)))
result = sim.run()
ez = result.monitor("probe")["data"]

PlaneMonitor#

class PlaneMonitor(name, axis='z', position=0.0, fields=('Ez',), frequencies=None, compute_flux=False, normal_direction='+')

Records frequency-domain field components on a full axis-aligned plane of the grid.

Raises ValueError for an invalid axis or normal_direction, empty fields, or compute_flux=True without the tangential fields.

Result payload. result.monitor(name) returns a dict:

With one component, the dict also has component, data, plane_index, plane_sample_indices, plane_sample_weights, and plane_sample_positions. With several components, the top-level component arrays are collocated on a shared tangential grid; with compute_flux=True that grid is also cropped to the physical domain, so PML samples are excluded. Plane data has shape [Na, Nb] for one frequency or [F, Na, Nb] for several. The coordinate arrays are NumPy arrays; the field data are PyTorch tensors.

scene.add_monitor(
    mw.PlaneMonitor("plane", axis="z", position=0.0, fields=("Ex", "Ey", "Hx", "Hy"), compute_flux=True)
)

FinitePlaneMonitor#

class FinitePlaneMonitor(name, position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 0.0), fields=('Ez',), frequencies=None, compute_flux=False, normal_direction='+', *, face_label=None, surface_name=None)

Records field components on a finite rectangle. The axis with zero size sets the plane normal.

The monitor also exposes the derived attributes axis, plane_position, and tangential_bounds (a dict from each tangential axis to its (lower, upper) bounds).

Raises ValueError when size has a negative value or does not have exactly one zero axis.

Result payload. The run records a full plane; Result crops it to tangential_bounds and returns the PlaneMonitor dict with cropped coordinates and data, plus monitor_type="finite_plane", center, size, tangential_bounds, and, when set, face_label and surface_name. With compute_flux=True, flux and power are recomputed over the cropped area. Cropping raises ValueError when the bounds select fewer than two grid samples along an axis.

face = mw.FinitePlaneMonitor("aperture", position=(0.0, 0.0, 0.3), size=(0.2, 0.2, 0.0), fields=("Ex", "Ey", "Hx", "Hy"), compute_flux=True)

FluxMonitor#

class FluxMonitor(name, axis='z', position=0.0, frequencies=None, normal_direction='+')

A PlaneMonitor with compute_flux=True and fields set to the four tangential components of axis.

Result payload. The PlaneMonitor dict; read the integrated flux from flux.

scene.add_monitor(mw.FluxMonitor("transmission", axis="z", position=0.7))
result = sim.run()
power = result.monitor("transmission")["flux"]

IncidentPowerDensityMonitor#

class IncidentPowerDensityMonitor(name, axis='z', position=0.0, frequencies=None, normal_direction='+', spatial_average=None)

A flux plane for exposure incident power density, the time-averaged normal Poynting component in W/m^2.

The monitor sets spatial_average_version to 'spatial-average-v1' when spatial_average is set, otherwise None. It reports whatever field is present at its plane, so place it in the incident region, ahead of any scatterer.

Raises ValueError when spatial_average is not a positive finite number.

Result payload. result.monitor(name) returns the PlaneMonitor flux dict. Call result.incident_power_density(name) to get the typed incident power density; see Safety.

ClosedSurfaceMonitor#

class ClosedSurfaceMonitor(name, faces, frequencies=None)

Groups FinitePlaneMonitor faces into one closed surface, for Huygens-surface and far-field workflows.

The constructor rebuilds each face as FinitePlaneMonitor named "<surface>::<label>". The monitor also has bounds, the ((xmin, xmax), (ymin, ymax), (zmin, zmax)) box enclosing all faces.

Raises ValueError for no faces, duplicate labels, mismatched frequencies, or unbalanced face areas; TypeError when a face is not a FinitePlaneMonitor.

Result payload. result.monitor(name) returns:

You can also read one face with result.monitor("<surface>::<label>").

ClosedSurfaceMonitor.box#

ClosedSurfaceMonitor.box(name, *, position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 1.0), frequencies=None) -> ClosedSurfaceMonitor

Builds an axis-aligned box with six faces labelled x_neg, x_pos, y_neg, y_pos, z_neg, z_pos. Each face records the four tangential components and has an outward normal_direction.

Raises ValueError when a size value is not strictly positive.

scene.add_monitor(mw.ClosedSurfaceMonitor.box("huygens", position=(0.0, 0.0, 0.0), size=(0.4, 0.4, 0.4)))
result = sim.run()
top = result.monitor("huygens")["faces"]["z_pos"]

ClosedSurfaceMonitor.face_monitor_names#

ClosedSurfaceMonitor.face_monitor_names -> tuple[str, ...]

Property. Names of the face monitors, in face order.

ClosedSurfaceMonitor.resolved_monitors#

ClosedSurfaceMonitor.resolved_monitors() -> tuple[FinitePlaneMonitor, ...]

Returns the face monitors. Scene.resolved_monitors() uses this to expand the surface into its faces.

FieldTimeMonitor#

class FieldTimeMonitor(name, components=('Ez',), position=(0.0, 0.0, 0.0), size=(0.0, 0.0, 0.0), start=0, stop=None, interval=1)

Records raw time-domain Yee field values at a point, on a plane, or in a volume.

The derived attribute region_kind is 'point', 'plane', or 'volume'.

Raises ValueError for an invalid component, a negative size value, or invalid start, stop, interval.

Result payload. result.monitor(name) returns:

If the run stops early (auto-shutoff), t and the buffers hold only the recorded samples.

scene.add_monitor(mw.FieldTimeMonitor("pt_time", components=("Ez",), position=(0.0, 0.0, 0.16), interval=1))
result = sim.run()
trace = result.monitor("pt_time")
t, ez = trace["t"], trace["field"]

FluxTimeMonitor#

class FluxTimeMonitor(name, axis='z', position=0.0, start=0, stop=None, interval=1, normal_direction='+')

Records the instantaneous Poynting flux through a full axis-aligned plane over time.

The recorded fields are the four tangential components of axis. Recording is detached, also in differentiable runs. Runs with complex Bloch fields reject this monitor.

Result payload. result.monitor(name) returns a dict with kind="flux_time", differentiable=False, name, t (seconds, shape [T]), flux (shape [T]), axis, position, normal_direction, start, stop, and interval.

scene.add_monitor(mw.FluxTimeMonitor("port_flux_time", axis="z", position=0.16, interval=1))
result = sim.run()
series = result.monitor("port_flux_time")["flux"]

ModeMonitor#

class ModeMonitor(name, position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 0.0), mode_index=0, direction='+', polarization='auto', frequencies=None, normal_direction=None, bend_radius=None, bend_axis=None)

Decomposes the field on a port plane into a guided mode, indexed within the requested polarization family.

Derived attributes: axis and normal_axis (propagation axis), polarization_axis, polarization (unit vector), plane_position, and fields (the four tangential components).

Raises ValueError for an invalid size, polarization, direction, bend setting, or a negative mode_index.

Result payload. result.monitor(name) solves the reference mode and returns a dict with monitor, frequency, axis, position, direction, mode_index, polarization_axis, effective_index, beta, mode_power, total_power, amplitude_forward, amplitude_backward, power_forward, power_backward, power_fraction_forward, power_fraction_backward (None when the total power is near zero), coords, candidate_diagnostics, candidate_overlap_matrix, selected_candidate_index, plus kind="mode", fields, frequencies, normal_direction, and plane (the raw plane dict). The overlap uses the payload's frequency; for a multi-frequency monitor, pass frequency= or freq_index=. Pass resolve_modal=False, or call result.raw_monitor(name), to get only the plane dict.

scene.add_monitor(mw.ModeMonitor("mm", position=(0, 0, 0.5), size=(1.0, 1.0, 0.0), mode_index=1, frequencies=(3e14,)))
result = sim.run()
modal = result.monitor("mm", frequency=3e14)

ModeMonitor.mode_spec#

ModeMonitor.mode_spec() -> dict[str, object]

Returns the mode specification as a dict with name, position, size, mode_index, direction, polarization, polarization_axis, normal_axis, bend_radius, and bend_axis.

DiffractionMonitor#

class DiffractionMonitor(name, position=(0.0, 0.0, 0.0), size=(1.0, 1.0, 0.0), frequencies=None, normal_direction='+', orders=None)

Decomposes the field on a periodic unit-cell plane into grating diffraction orders.

Derived attributes: axis, plane_position, tangential_axes, periods (dict from tangential axis to the size along it), and fields.

Result payload. result.monitor(name) returns:

efficiency is normalised by propagating_power. The decomposition uses the payload's frequency; for a multi-frequency monitor, pass frequency= or freq_index=. It uses the transverse extent of the simulation domain as the period, together with the solver's Bloch wavevector. For another background index or an explicit incident power, use compute_diffraction_orders from Postprocess.

scene.add_monitor(mw.DiffractionMonitor("orders", position=(0.0, 0.0, 0.55), size=(0.6, 0.8, 0.0), orders=2))
result = sim.run()
for order in result.monitor("orders")["orders"]:
    print(order["m"], order["n"], order["power"])

DiffractionMonitor.diffraction_spec#

DiffractionMonitor.diffraction_spec() -> dict[str, object]

Returns a dict with name, position, size, normal_axis, tangential_axes, periods, orders, and normal_direction.

DipoleEmissionMonitor#

class DipoleEmissionMonitor(name, source_name, frequencies=None)

Measures the power a named PointDipole delivers to the field, P = -(1/2) Re(conj(J) . E), from the electric field at the dipole cell.

Result payload. result.monitor(name) returns a dict with kind="dipole_emission", monitor_type, power_delivered, current_spectrum, frequencies, frequency, polarization, position, source_name, and purcell_factor. purcell_factor is always None: compute it from a structured run and a vacuum run with purcell_factor in Postprocess.

scene.add_monitor(mw.DipoleEmissionMonitor("emit", source_name="d"))
result = sim.run()
power = result.monitor("emit")["power_delivered"]

PermittivityMonitor#

class PermittivityMonitor(name, position=(0.0, 0.0, 0.0), size=(0.0, 0.0, 0.0), frequencies=None)

Samples the compiled relative permittivity in a point, plane, or box region. It needs no time stepping and adds no DFT frequencies.

The attribute bounds holds the region as ((xmin, xmax), (ymin, ymax), (zmin, zmax)).

Result payload. result.monitor(name) returns a dict with kind, monitor_type (both "permittivity"), name, bounds, node coordinates x, y, z, the per-component permittivities eps_x, eps_y, eps_z, their mean eps, frequencies, and frequency when there is one frequency. Arrays have shape [nx, ny, nz] for one frequency or [F, nx, ny, nz] for several. The frequency used is, in order: frequency=, the result frequency at freq_index=, the monitor frequencies, then the result frequencies.

scene.add_monitor(mw.PermittivityMonitor("perm", position=(0.0, 0.0, 0.0), size=(0.6, 0.6, 0.6)))
result = sim.run()
eps = result.monitor("perm")["eps"]

MediumMonitor#

class MediumMonitor(name, position=(0.0, 0.0, 0.0), size=(0.0, 0.0, 0.0), frequencies=None)

Like PermittivityMonitor, and also samples permeability and electric conductivity.

Result payload. The PermittivityMonitor dict (with kind="medium"), plus mu_x, mu_y, mu_z, mu, and sigma_e_x, sigma_e_y, sigma_e_z, sigma_e (S/m). sigma_e is frequency-independent and repeated for each evaluated frequency. For a conductive material, eps is complex.

scene.add_monitor(mw.MediumMonitor("med", position=(0.0, 0.0, 0.0), size=(0.0, 0.0, 0.0)))
result = sim.run()
sigma = result.monitor("med")["sigma_e"]

PowerLossMonitor#

class PowerLossMonitor(name, position, size, frequencies=None, channels=('conduction',))

Selects a box region and the physical loss channels to report.

Only conduction (from static electric conductivity) is computed automatically. The other channels need explicit channel input to result.power_loss(...).

Raises ValueError for an empty name, non-positive size, invalid frequencies, or empty, duplicate, or unknown channels.

Result payload. result.monitor(name) returns result.power_loss(name), a PowerLossData object; frequency= and freq_index= raise ValueError here. Automatic conduction needs an FDTD run with full-field Ex, Ey, Ez (full_field_dft=True). See Safety for PowerLossData and SAR.

scene.add_monitor(mw.PowerLossMonitor("loss", position=(0.0, 0.0, 0.0), size=(0.2, 0.2, 0.2)))
result = sim.run()
total = result.monitor("loss").total

BreakdownMonitor#

class BreakdownMonitor(name, region=None, *, position=None, size=None, quantities=('electric_field', 'exposure', 'dissipated_energy'), critical_field=None, minimum_duration=0.0, damage_exponent=None)

Accumulates dielectric stress per cell during an FDTD run without changing the field solve. The result is a stress indicator only; it does not predict device failure.

Raises ValueError for a missing or invalid region, a missing critical_field, invalid thresholds, or invalid quantities; TypeError when region has neither bounds nor position/size.

Result payload. Read the record with result.breakdown(name), which returns BreakdownStressData; result.breakdown_names() lists the available names. result.monitor(name) does not handle this record type. See Safety.

scene.add_monitor(mw.BreakdownMonitor("stress", position=(0.0, 0.0, 0.0), size=(0.12, 0.12, 0.12), critical_field=1e-3))
result = sim.run()
peak = result.breakdown("stress").peak_field

ComponentStressMonitor#

class ComponentStressMonitor(name, *, port, rating, voltage_series, current_series)

Binds a ComponentRating to two recorded time series and reports the power, energy, and rating exceedance at a port. The result flags stress, not device failure.

Result payload. Read it with result.component_stress(name), which returns ComponentStressData. result.monitor(name) raises KeyError for this monitor. See Safety.

rating = mw.ComponentRating(voltage=50.0, current=1.0)
scene.add_monitor(mw.FieldTimeMonitor("vprobe", components=("Ez",), position=(0.0, 0.0, 0.0)))
scene.add_monitor(mw.FieldTimeMonitor("iprobe", components=("Ez",), position=(0.02, 0.0, 0.0)))
scene.add_monitor(mw.ComponentStressMonitor("part", port="feed", rating=rating, voltage_series="vprobe", current_series="iprobe"))
result = sim.run()
data = result.component_stress("part")

WireMonitor#

class WireMonitor(name, wire, frequencies, quantities=('current', 'charge', 'ohmic_loss'))

Samples frequency-domain current, charge, and ohmic loss on one declared thin wire.

Result payload. result.monitor(name) returns a WireData object. Current and ohmic loss have shape [F, S] (segments), charge has shape [F, N] (nodes), and unrequested quantities are None. Passing frequency= or freq_index= raises ValueError; select from the tensors yourself.

scene.add_monitor(mw.WireMonitor("state", wire="feed", frequencies=(1.0e9, 2.0e9), quantities=("charge", "current")))
result = sim.run()
current = result.monitor("state").current