CircuitTimeStepper

class photonforge.CircuitTimeStepper(mesh_refinement=None, max_iterations=100, abs_tolerance=1e-8, rel_tolerance=1e-5, max_threads=8, verbose=True, require_native=False)

Circuit-level time stepper.

Constructs time steppers for individual circuit elements and handles connections between them. Each time stepper initialization is preceded by an update to the component’s technology, the component itself, and its active model by calling Reference.update. They are reset to their original state afterwards. Reference updates must preserve the parent-visible interface, connectivity, and port-model or terminal-model representation, as described by CircuitModel.

More information on the handling of references and connections can be found CircuitModel.

Parameters:

• mesh_refinement (PositiveFloat | None) – Minimum number of mesh elements per wavelength used for mode solving.

• max_iterations (PositiveInt) – Maximum number of Newton updates per time step of a zero-delay loop, a group of instances whose declared signal paths (see TimeStepper.path_delays) close within the step. Loops closed through built-in affine steppers are solved exactly with one update; everything outside loops is stepped once, in flow order. 1 steps every instance exactly once and lets loop signals carry the previous time step’s value instead of converging.

• abs_tolerance (PositiveFloat) – The absolute tolerance for the convergence check.

• rel_tolerance (PositiveFloat) – The relative tolerance for the convergence check.

• max_threads (PositiveInt) – Unused.

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

• require_native (bool) – If set, setup fails when any instance steps through Python (see python_instances), and without a PhotonForge Photonic Canvas license.

Setup compiles the circuit into one numba function per circuit structure when config.compile_circuit_time_steppers is set, numba is installed (pip install photonforge[numba]) and native time stepping is licensed (PhotonForge Photonic Canvas); otherwise, or when the circuit is not supported, it is stepped by the built-in C++ kernel with the same results (see compilation). Without the license, the kernel calls every instance through TimeStepper.step_single().

Methods

bind_native(step, keys[, state, cstate, context])	Bind a compiled step function.
reset()	Reset the state of the circuit variables.
setup(component, time_step, *[, ...])	Initialize the time stepper.
setup_state(*, component, time_step, ...[, ...])	Initialize internal circuit variables.
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

compilation	Whether setup compiled the circuit and, if not, why.
evaluations	Number of instance calls since the last reset.
keys	Tuple of input/output keys.
parametric_function	Function used to update the time stepper.
parametric_kwargs	Keyword arguments used to update the time stepper.
path_delays	Minimum delay in time steps from each external input to the outputs it reaches.
properties	Object properties.
python_instances	Instances stepped through Python, as name[index] (class).
random_variables	Random variables associated to the time stepper's parameters.
silent_outputs	External outputs that are always zero.
status

property compilation: dict[str, object] | None

Whether setup compiled the circuit and, if not, why.

reason is None when compiled, else "disabled" (config.compile_circuit_time_steppers is off), "license" (no PhotonForge Photonic Canvas license), "numba" (not installed: pip install photonforge[numba]), "python" (an instance steps through Python), "solver" (a Newton loop or a linear loop of more than 16 edges), "factor" (a zero or non-finite mode factor), "budget" (too much generated code) or "codegen" (a compile error, in detail). A compiled circuit also reports compile_seconds, lines and the inlined instances.

property evaluations: int

Number of instance calls since the last reset.

property keys: tuple[str, ...]

Tuple of input/output keys.

property path_delays: dict[tuple[str, str], int]

Minimum delay in time steps from each external input to the outputs it reaches.

property python_instances: tuple[str, ...]

Instances stepped through Python, as name[index] (class).

Instances of nested circuits are listed by path. Empty when every instance is native, in which case the circuit steps without the interpreter. Without a PhotonForge Photonic Canvas license, every instance is listed.

reset()

Reset the state of the circuit variables.

Return type:

None

setup_state(*, component, time_step, carrier_frequency, monitors=None, updates=None, chain_technology_updates=True, verbose=None, **kwargs)

Initialize internal circuit variables.

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.

• monitors (dict[str, Port | FiberPort | GaussianPort] | None) – Additional ports to include in the outputs as a dictionary with monitor names as keys. Subcomponent ports can be obtained with Reference.get_ports() for the 1st level of references or with Component.query() for more deeply-nested ports.

• updates (dict[Sequence[str | int | None], dict[str, dict[str, Any]]] | None) – Dictionary of parameter updates to be applied to components, technologies, and models for references within the main component. See CircuitModel.start() for examples.

• chain_technology_updates (bool) – if set, a technology update will trigger an update for all components using that technology.

• verbose (bool | None) – If set, overrides the model’s verbose attribute and is passed to reference models.

• kwargs (object) – Keyword arguments passed to reference models.

Returns:

Object with a status dictionary.

Return type:

CircuitTimeStepper

property silent_outputs: tuple[str, ...]

External outputs that are always zero.

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