TimeStepper¶

class photonforge.TimeStepper(**kwargs)¶

Abstract time stepper class used to time step a component.

Time steppers must be derived from this class and implement the method step_single().

Time steppers may optionally override:

setup_state(), called with the Component, time step and index, and other arguments to initialize the time stepper.
reset(), used to reset any internal state the time stepper may hold.

Additionally, for time stepper parameterization to work correctly, the __init__ method must call super().__init__ with all parameters as keyword arguments (see example below).

Important

The following attributes and methods defined in the base class should never be redefined in the derived one: step(), setup(), update(), parametric_function, and parametric_kwargs.

Example

>>> class CustomTimeStepper(pf.TimeStepper):
...     def __init__(self, *, coeff=0.5):
...         super().__init__(coeff=coeff)
...
...     def setup_state(self, *, time_step, **kwargs):
...         self.coeff = self.parametric_kwargs["coeff"] ** time_step
...         self.state = {}
...
...     def reset(self):
...         self.state = {}
...
...     def step_single(self, inputs, time_index, update_state, shutdown):
...         outputs = {
...             port: self.state.get(port, 0) * self.coeff + value
...             for port, value in inputs.items()
...         }
...         if update_state:
...             self.state.update(outputs)
...         return outputs
...
>>> pf.register_time_stepper_class(CustomTimeStepper)
>>> time_stepper = CustomTimeStepper(coeff=0.2)

Methods

`reset`()	Reset any internal state of the time stepper.
`setup`(component, time_step, *[, ...])	Initialize the time stepper.
`setup_state`(*, component, time_step, ...)	Initialize any internal state in preparation for one or more runs.
`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.

parametric_function¶

Function used to update a parametric component.

Type:: str

parametric_kwargs¶

Keyword arguments used to update a parametric component.

Type:: dict[str, Any]

properties¶

Object properties.

Type:: Properties

random_variables¶

Random variables associated to this modles’s parameters.

Type:: list[RandomVariable]

reset()¶

Reset any internal state of the time stepper.

The default implementation performs no action. This method can be overridden in derived classes to reset any internal state the time stepper may have.

setup(component, time_step, *, carrier_frequency=0, show_progress=True, **kwargs)¶

Initialize the time stepper.

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.
show_progress (bool) – If True, show setup progress.
**kwargs – Keyword arguments forwarded to setup_state().

Returns:

This time stepper.

Return type:

TimeStepper

setup_state(*, component, time_step, carrier_frequency, show_progress, **kwargs)¶

Initialize any internal state in preparation for one or more runs.

The default implementation performs no action. This method can be overridden in derived classes to initialize any internal state the time stepper may have.

Long-running processes can immediately return an object with an status``attribute that provides a dictionary with keys ``"progress" (a number from 0 to 100 indicating the computation progress) and "message" (one of 'running', 'success', or 'error', indicating the current computation status).

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.
show_progress (bool) – If True, show setup progress.
**kwargs – Keyword arguments forwarded from setup().

Returns:

Optional object with a status dictionary.

Return type:

Any

step(inputs=None, steps=0, time_step=0, show_progress=True)¶

Compute the outputs of this time stepper, given inputs.

Parameters:

inputs (TimeSeries) – Inputs to the time stepper.
steps (int) – The number of time steps to execute. If inputs is defined, this value is not used.
time_step (float) – The interval between time steps (in seconds). If inputs is a defined, this value is not used.
show_progress (bool) – If True, show computation progress.

Returns:

Computed outputs.

Return type:

TimeSeries

step_single(inputs, time_index, update_state, shutdown)¶

Take a single time step on the given inputs.

Important

This is an abstract method that must be implemented by derived classes.

The method takes the inputs as a dictionary mapping port name to complex value. It advances a single time step, updating its internal state (if any) according to the update_state flag. It computes the outputs and returns them as a dictionary in the same form as the 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]

update(*args, **kwargs)¶

Update this time stepper.

All contents of the time stepper are updated with the contents from the updated version. Any contents or modifications introduced after the time stepper creation (outside of the original parametric function) are not propagated.

Parameters:

*args – Positional arguments to the parametric time stepper function.
**kwargs – Keyword arguments to the parametric time stepper function.

Returns:

This time stepper.

Return type:

TimeStepper

Note

The original keyword arguments used to generate the time stepper are stored and updated with the passed kwargs. This updated version is used in the function call and will be stored for future updates. Positional arguments are not stored.