RingTimeStepper

class photonforge.RingTimeStepper(*, kappa1, kappa2=None, n_eff, length, propagation_loss=0.0, n_group=None, dn_dT=0.0, dL_dT=.0, temperature=293.0, reference_temperature=293.0, dn_dv=0.0, dn_dv2=, dloss_dv=.0, dloss_dv2=, z0=None, f_3dB=0, ports=None, mesh_refinement=None, verbose=True)

Analytic ring resonator time-stepper with single or double bus.

This model implements a 2 or 4-port micro-ring or racetrack resonator. It simulates the time-domain behavior using one bus coupler per waveguide and a delay-line for the ring’s round-trip propagation. In the double-bus case the two couplers sit half a round trip apart, splitting the delay line into two arcs. The model includes both electro-optic and thermo-optic tuning of the ring’s effective index and loss. An optional first-order low-pass filter can be applied to the electrical tuning input.

Each bus coupler is the symmetric, lossless matrix

\[\begin{split}C = \begin{bmatrix} \tau & \kappa \\ \kappa & \tau \\ \end{bmatrix}\end{split}\]

with the (possibly complex) cross-coupling \(\kappa\) supplied directly and the through coefficient derived as \(\tau = -i \exp(i\arg\kappa) \sqrt{1 - |\kappa|^2}\). This is the same convention used by RingModel, so both models share resonance positions and line shapes.

Parameters:

• kappa1 (complex) – Complex cross-coupling coefficient for the first bus coupler.

• kappa2 (complex | None) – Complex cross-coupling coefficient for the second bus coupler. If None, models a single-bus ring.

• n_eff (complex) – Effective refractive index (loss can be included here by using complex values).

• length (Annotated[float, units='μm']) – Round-trip length of the ring.

• propagation_loss (Annotated[float, minimum=0, units='dB/μm']) – Propagation loss.

• n_group (float | None) – Group index of the optical mode, used to calculate delay. If None, the real part of ‘n_eff’ is used.

• dn_dT (Annotated[complex, units='1/K']) – Temperature sensitivity for n_eff.

• dL_dT (Annotated[float, units='dB/μm/K']) – Temperature sensitivity for propagation_loss.

• temperature (Annotated[float, minimum=0, units='K']) – Operating temperature.

• reference_temperature (Annotated[float, minimum=0, units='K']) – Reference temperature.

• dn_dv (Annotated[complex, units='1/V']) – Linear voltage-dependent effective index coefficient.

• dn_dv2 (Annotated[complex, units='1/V²']) – Quadratic voltage-dependent effective index coefficient.

• dloss_dv (Annotated[float, units='dB/μm/V']) – Linear voltage-dependent propagation loss coefficient.

• dloss_dv2 (Annotated[float, units='dB/μm/V²']) – Quadratic voltage-dependent propagation loss coefficient.

• z0 (Annotated[complex, units='Ω'] | Interpolator | None) – Characteristic impedance of the electrical port used to convert the input field amplitude to voltage. If None, derived from port impedance, calculated by mode-solving, or set to 50 Ω.

• f_3dB (Annotated[float, minimum=0, units='Hz']) – -3 dB frequency cutoff for bandwidth limiting. Only active for positive values.

• ports (Annotated[Sequence[str], maxItems=2, minItems=2] | Annotated[Sequence[str], maxItems=4, minItems=4] | None) – List of port names. If not set, the sorted list of port names from the component is used.

• mesh_refinement (Annotated[float, exclusiveMinimum=0] | None) – Minimal number of mesh elements per wavelength used for mode solving.

• verbose (bool) – Flag setting the verbosity of mode solver runs.

Notes

The group delay \(n_g \ell / c_0\) is implemented as a fixed multiple of the time step. For the double-bus ring the two couplers are placed half a round trip apart, so an even round-trip delay is recommended for a symmetric drop response.

Ports follow the same order as RingModel: the (sorted) port names or ports argument map to input, through, drop, and add. For a unit drive at the input, the steady-state responses are:

Port (index)	Role	Coupled to the input via
ports[0]	input	–
ports[1]	through	same bus, first coupler (\(t_1\))
ports[2]	drop	second bus, half round trip (\(d\))
ports[3]	add	second bus, isolated from input (0)

giving the per-mode S matrix (single bus keeps only the upper-left 2x2 block, with no drop/add ports):

\[\begin{split}S = \begin{bmatrix} 0 & t_1 & d & 0 \\ t_1 & 0 & 0 & d \\ d & 0 & 0 & t_2 \\ 0 & d & t_2 & 0 \\ \end{bmatrix}\end{split}\]

Methods

reset()	Reset internal state.
setup(component, time_step, *[, ...])	Initialize the time stepper.
setup_state(*, component, time_step, ...[, ...])	Initialize internal state.
step([inputs, steps, time_step, show_progress])	Compute the outputs of this time stepper, given inputs.
step_single(inputs, outputs, time_index, ...)	Take a single time step on the given inputs.
update(*args, **kwargs)	Update this time stepper.

Attributes

parametric_function	Function used to update the time stepper.
parametric_kwargs	Keyword arguments used to update the time stepper.
properties	Object properties.
random_variables	Random variables associated to the time stepper's parameters.
status

reset()

Reset internal state.

Return type:

None

setup_state(*, component, time_step, carrier_frequency, temperature=None, verbose=None, **kwargs)

Initialize internal state.

Parameters:

• component (Component) – Component representing the laser source.

• time_step (Annotated[float, minimum=0, units='s']) – The interval between time steps (in seconds).

• carrier_frequency (Annotated[float, minimum=0, units='Hz']) – The carrier frequency used to construct the time stepper. The carrier should be omitted from the input signals, as it is handled automatically by the time stepper.

• temperature (Annotated[float, minimum=0, units='K'] | None) – If set, overrides the time stepper’s temperature.

• verbose (bool | None) – If set, overrides the time stepper’s verbose attribute.

• kwargs (object) – Unused.

Return type:

object

step_single(inputs, outputs, time_index, update_state, shutdown)

Take a single time step on the given inputs.

Parameters:

• inputs (ndarray) – Input values at the current time step. Must be a 1D array of complex values ordered according to keys.

• outputs (ndarray) – Pre-allocated output array where results will be stored. Same size and type as inputs.

• time_index (int) – Time series index for the current input.

• update_state (bool) – Whether to update the internal stepper state.

• shutdown (bool) – Whether this is the last call to the single stepping function for the provided TimeSeries.

Return type:

None