SMatrixTimeStepper

class photonforge.SMatrixTimeStepper(pole_residue_matrix=None, s_matrix_kwargs={}, initial_poles=(), min_poles=0, max_poles=6, loss_factor=1e-3, rms_error_tolerance=1e-4, max_iterations=100, max_stale_iterations=3, passive=True, feedthrough=None, delays='auto')

Time stepper based on a time-domain model.

The TimeDomainModel can be calculated automatically using pole_residue_fit() and the component’s S matrix or from the provided PoleResidueMatrix.

Parameters:

• pole_residue_matrix (PoleResidueMatrix | None) – Pole-residue matrix for the underlying time-domain model. If provided, all other arguments are not used.

• s_matrix_kwargs (dict[str, Any]) – Keyword arguments for Component.s_matrix().

• initial_poles (Sequence[complex]) – Sequence of poles used as initial guess.

• min_poles (Annotated[int, minimum=0]) – Minimal number of poles to try. It has no effect when initial pole guesses are provided.

• max_poles (Annotated[int, minimum=0]) – Maximal number of poles to try. It has no effect when initial pole guesses are provided.

• loss_factor (Annotated[float, exclusiveMinimum=0]) – For complex initial pole guesses, ratio between their real and imaginary parts.

• rms_error_tolerance (Annotated[float, exclusiveMinimum=0]) – RMS error level to break the fitting loop.

• max_iterations (Annotated[int, exclusiveMinimum=0]) – Maximal number of fitting iterations.

• max_stale_iterations (Annotated[int, exclusiveMinimum=0]) – Maximal number of iterations without error progress.

• passive (bool) – Whether to attempt to enforce passivity.

• feedthrough (bool | None) – Whether to include a feedthrough (constant) term in the pole-residue model.

• delays (Literal['auto'] | ~typing.Annotated[float, minimum=0, units='s'] | dict[tuple[str, str], ~typing.Annotated[float, minimum=0, units='s']]) – Time delays (in seconds), one per matrix element. Missing elements have no time delay applied. If a single number is given, this is used as a global delay for all matrix elements. If "auto", the delays are estimated from the provided data.

Methods

reset()	Reset the state of the internal time domain model.
setup(component, time_step, *[, ...])	Initialize the time stepper.
setup_state(*, component, time_step, ...[, ...])	Initialize internal state, building a time domain model if necessary.
step([inputs, steps, time_step, show_progress])	Compute the outputs of this time stepper, given inputs.
step_single(inputs, 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 a parametric component.
parametric_kwargs	Keyword arguments used to update a parametric component.
properties	Object properties.
random_variables	Random variables associated to this modles's parameters.
status

reset()

Reset the state of the internal time domain model.

setup_state(*, component, time_step, carrier_frequency, frequencies=(), **kwargs)

Initialize internal state, building a time domain model if necessary.

Parameters:

• component (Component) – Component for the time stepper.

• time_step (float) – The interval between time steps (in seconds).

• carrier_frequency (float) – 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.

• frequencies (Sequence[Annotated[float, minimum=0, units='Hz']]) – Frequencies used to build the S matrix for component, if a pole_residue_matrix is not provided.

• kwargs – Unused.

step_single(inputs, time_index, update_state, shutdown)

Take a single time step on the given inputs.

Parameters:

• inputs (dict[str, complex]) – Dictionary containing inputs at the current time step, mapping port names to complex values.

• 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.

Returns:

Outputs at the current time step.

Return type:

dict[str, complex]