RingTimeStepper

class photonforge.RingTimeStepper(*, kappa1, kappa2=None, n_eff, length, propagation_loss=0.0, n_group=None, reference_frequency=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=, effective_area=one, kerr_index=, tpa_coefficient=.0, fca_cross_section=.0, fcd_coefficient=0, confinement=1.0, carrier_lifetime=None, thermal_time_constant=None, thermal_capacity=None, absorbed_fraction=1.0, heater_resistance=None, carrier_samples=401, 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. Its magnitude must not exceed 1.

• kappa2 (complex | None) – Complex cross-coupling coefficient for the second bus coupler. Its magnitude must not exceed 1. 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.

• reference_frequency (Annotated[float, minimum=0, units='Hz'] | None) – Reference frequency for dispersion coefficients. If None, the carrier frequency 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.

• effective_area (Annotated[float, exclusiveMinimum=0, units='m²'] | None) – Nonlinear effective area \(A_{\rm eff}\), in m².

• kerr_index (Annotated[float, units='m²/W']) – Kerr coefficient \(n_2\), in m²/W. Positive values red-shift the resonance.

• tpa_coefficient (Annotated[float, minimum=0, units='m/W']) – Two-photon absorption \(\beta_{\rm TPA}\), in m/W.

• fca_cross_section (Annotated[float, minimum=0, units='m²']) – Free-carrier absorption cross-section, in m².

• fcd_coefficient (Annotated[float, units='m³']) – Free-carrier index change per unit density \(\sigma_{\rm FCD}\), in m³.

• confinement (Annotated[float, maximum=1, minimum=0]) – Fraction of the optical mode overlapping the two-photon material. It scales the TPA loss and the carriers it generates.

• carrier_lifetime (Annotated[float, exclusiveMinimum=0] | Interpolator | None) – Free-carrier lifetime, either a constant or an Interpolator over carrier density in 1/m³.

• thermal_time_constant (Annotated[float, exclusiveMinimum=0] | None) – Thermal relaxation \(\tau_{\rm th}\).

• thermal_capacity (Annotated[float, exclusiveMinimum=0, units='J/K'] | None) – \(C_{\rm th} = m c_p\). The steady-state thermal impedance is \(\tau_{\rm th}/C_{\rm th}\).

• absorbed_fraction (Annotated[float, maximum=1, minimum=0]) – Fraction of the linear loss that is absorption rather than scattering or radiation.

• heater_resistance (Annotated[float, exclusiveMinimum=0, units='Ω'] | None) – If set, the electrical port also acts as a resistive heater of this resistance, contributing \(V^2/R\) to the thermal source.

• carrier_samples (Annotated[int, minimum=2]) – Points used to resample an interpolator lifetime onto a dense grid at setup.

• 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}\]

See also

srh_lifetime() for the density-dependent form of carrier_lifetime, whose shortening at high injection sets the self-pulsing period.

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.
write_verilog_a(path, *[, backend, ...])	Write this configured time stepper as one Verilog-A module.

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