Skip to content
PhotonForge

TerminatedModTimeStepper

TerminatedModTimeStepper(
    *,
    v_piL: Annotated[float, exclusiveMinimum=0, units='V·μm'],
    length: Annotated[float, units='μm'] | None = None,
    n_eff: complex
    | photonforge.Interpolator
    | photonforge.PortSpec
    | Literal['cross-section']
    | None = None,
    n_group: float | photonforge.Interpolator | None = None,
    reference_frequency: Annotated[float, minimum=0, units='Hz']
    | None = None,
    n_rf: complex
    | photonforge.Interpolator
    | photonforge.PortSpec
    | Literal['cross-section']
    | None = None,
    z0: Annotated[complex, units='Ω']
    | photonforge.Interpolator
    | None = None,
    z_load: Annotated[complex, units='Ω']
    | photonforge.Interpolator
    | Literal['z0'] = 'z0',
    z_source: Annotated[complex, units='Ω']
    | photonforge.Interpolator
    | Literal['z0']
    | None = None,
    propagation_loss: Annotated[float, minimum=0, units='dB/μm'] = 0,
    rf_propagation_loss: Annotated[float, minimum=0, units='dB/μm']
    | photonforge.Interpolator = 0,
    k2: Annotated[float, units='rad/μm/V²'] = 0,
    k3: Annotated[float, units='rad/μm/V³'] = 0,
    fir_taps: Annotated[int, exclusiveMinimum=0] = 4096,
    optical_input: str | None = None,
    mesh_refinement: Annotated[float, exclusiveMinimum=0] | None = None,
    verbose: bool = True,
) -> None

Time-stepper for a travelling-wave electro-optic phase modulator.

This model implements a two-port optical phase modulator with a single electrical drive. The forward optical path is phase-modulated, and the reverse path propagates passively (attenuation only). The model assumes that the transmission line is terminated, so a single electrical port is used.

Args

  • v_piL: Electro-optic phase coefficient VπLV_{\pi L}.
  • length: Physical length of the modulator. If not provided, the length is measured by route_length or ports distance.
  • n_eff: Effective index of the optical mode at the reference frequency. An Interpolator can be used to set frequency-dependent values. If None, automatic computation is performed by mode-solving the first optical port of the component. If desired, the port specification can be overridden by setting n_eff to "cross-section" (uses Component.slice_profile) or to a PortSpec object.
  • n_group: Group index of the optical mode. An Interpolator can be used to set frequency-dependent values. If None, it is calculated together with n_eff by mode-solving or set to the value of n_rf (perfect phase-matching).
  • reference_frequency: Reference frequency for the effective and group indices. If None, the carrier frequency is used. This argument is ignored when either index is interpolated or mode-solved.
  • n_rf: Effective index of the electrical (RF/microwave) mode. If None, automatic computation is performed by mode-solving the electrical port of the component. If desired, the port specification can be overridden by setting n_rf to "cross-section" (uses Component.slice_profile) or to a PortSpec object.
  • z0: Characteristic impedance of the transmission line. If None, derived from port impedance, calculated by mode-solving, or set to 50 Ω.
  • z_load: Load impedance. Use "z0" to match z0.
  • z_source: Source impedance. If None, derived from the connected port. Use "z0" to match z0.
  • propagation_loss: Optical propagation loss.
  • rf_propagation_loss: Electrical propagation loss.
  • k2: Quadratic nonlinear phase coefficient.
  • k3: Cubic nonlinear phase coefficient.
  • optical_input: Name of the optical port used as input. If None, the first one is used (sorted alphabetically).
  • mesh_refinement: Minimal number of mesh elements per wavelength used for mode solving.
  • verbose: Flag setting the verbosity of mode solver runs.

Important

The electrical input AA is converted to a voltage signal through the source impedance:

V=ℜ{A}ℜ{Zsource}V = \Re\{A\} \sqrt{\Re\{Z_\text{source}\}}

Note

Phase non-linearities are applied before the RF dynamics (Hammerstein form).

The group delay ngℓ/c0n_g \ell / c_0 is implemented as a fixed multiple of the time step.

In Verilog-A export, constant real RF parameters give a line model with continuous delays. Frequency-dependent or complex ones (interpolated or mode-solved) export the time stepper’s own FIR kernel, truncated once its step response settles within 0.1 %.

Methods

Section titled “Methods”
MethodDescription
bind_nativeBind a compiled step function.
resetReset internal state.
setupInitialize the time stepper.
setup_stateInitialize internal state.
stepCompute the outputs of this time stepper, given inputs.
step_singleTake a single time step on the given inputs.
updateUpdate this time stepper.
write_verilog_aWrite this configured time stepper as one Verilog-A module.

bind_native

Section titled “bind_native”
bind_native(self, step, keys, state=None, cstate=None, context=None)

Bind a compiled step function.

Instead of implementing step_single, a time stepper can hand the simulator the address of a C function with the signature:

int64 step(inputs, outputs, time_index, update_state, shutdown,
           context, state, cstate)

inputs and outputs are complex128 arrays with one entry per key, state and cstate are the float64 and complex128 arrays, and a nonzero return signals failure. The function must overwrite every element of outputs and only modify the state arrays when update_state is true. The arrays must not be reallocated after binding; reset restores them to the values given here, so a subclass overriding reset must call super().reset().

Calls with update_state false must give the same outputs: circuits may call the function several times in a time step, and setup checks this for steppers that declare path_delays. Random numbers must therefore come from a generator whose state lives in the arrays (e.g., a seed and a counter): output a draw kept there and draw the next one only when update_state is true, which also makes reset replay the stream. Do not use numpy.random in the function: numba draws it from a global stream that differs on every call and survives a reset.

The function can be compiled with numba (when available).

Args

  • step (int | object): Address of the step function, or an object with an address attribute such as a numba cfunc.
  • keys (Sequence[str]): Input/output keys.
  • state (ndarray | None): Contiguous float64 array the function may use.
  • cstate (ndarray | None): Contiguous complex128 array the function may use.
  • context (int | None): Opaque pointer passed to the function.

Example

A two-port element that leaks the field entering its first port out of its second one:

>>> from numba import cfunc
>>> from photonforge.time_steppers import STEP_SIGNATURE
>>>
>>> @cfunc(STEP_SIGNATURE, cache=True)  # doctest: +SKIP
... def leaky_step(inputs, outputs, time_index, update_state,
...                shutdown, context, state, cstate):
...     # state[0]: decay per step
...     # cstate[0]: field leaving the second port
...     outputs[0] = 0j
...     outputs[1] = cstate[0] * state[0] + inputs[0]
...     if update_state:
...         cstate[0] = outputs[1]
...     return 0
...
>>> class LeakyTimeStepper(pf.TimeStepper):
...     def __init__(self, *, k=0.5):
...         super().__init__(k=k)
...
...     def setup_state(self, *, component, time_step, **kwargs):
...         keys = tuple(f"{p}@0" for p in sorted(component.ports))
...         state = numpy.array([
...             self.parametric_kwargs["k"] ** time_step
...         ])
...         self.bind_native(
...             leaky_step, keys, state, numpy.zeros(1, complex)
...         )
...
>>> pf.register_time_stepper_class(LeakyTimeStepper)

reset

Section titled “reset”
reset(self) -> None

Reset internal state.

setup

Section titled “setup”
setup(
    self,
    component,
    time_step,
    *,
    carrier_frequency=0,
    show_progress=True,
    **kwargs,
)

Initialize the time stepper.

Args

  • 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 (object): Keyword args forwarded to setup_state.

Returns

TimeStepper: This time stepper.

setup_state

Section titled “setup_state”
setup_state(
    self,
    *,
    component: photonforge.Component,
    time_step: Annotated[float, minimum=0, units='s'],
    carrier_frequency: Annotated[float, minimum=0, units='Hz'],
    connections: dict[
        str, tuple[photonforge.Port, photonforge.Technology]
    ] = {},
    verbose: bool | None = None,
    **kwargs: object,
) -> object

Initialize internal state.

Args

  • component: Component representing the laser source.
  • time_step: The interval between time steps (in seconds).
  • carrier_frequency: 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.
  • connections: Mapping of the ports (and respective technologies) connected to each of ports in component.
  • verbose: If set, overrides the time stepper’s verbose attribute.
  • kwargs: Unused.

step

Section titled “step”
step(self, inputs=None, steps=0, time_step=0, show_progress=True)

Compute the outputs of this time stepper, given inputs.

Args

  • 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

TimeSeries: Computed outputs.

step_single

Section titled “step_single”
step_single(self, inputs, outputs, time_index, update_state, shutdown)

Take a single time step on the given inputs.

Important

Derived classes must implement this method unless they bind a compiled step with bind_native, in which case the default implementation calls it and, when shutdown is set, the optional _after_native_run hook.

The method takes the inputs as a numpy array of type complex with values in the order defined by keys. It advances a single time step, updating its internal state (if any) according to the update_state flag. It writes the outputs in-place to the pre-allocated, zero-initialized outputs array in the same order.

Args

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

update

Section titled “update”
update(self, *args, **kwargs)

Update this time stepper.

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

Args

  • *args (object): Positional arguments to the parametric time stepper function.
  • **kwargs (object): Keyword arguments to the parametric time stepper function.

Returns

TimeStepper: This time stepper.

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.

write_verilog_a

Section titled “write_verilog_a”
write_verilog_a(
    self,
    path,
    *,
    backend='openvaf',
    port_convention='travelling_wave',
    module_name=None,
    z0=50.0,
    field_impedance=None,
)

Write this configured time stepper as one Verilog-A module.

The time stepper must first be configured with setup or Component.setup_time_stepper. The writer creates source only; it does not compile the model or create a simulator deck. Requires a PhotonForge Photonic Canvas license.

Args

  • path (str | os.PathLike): Destination .va file.
  • backend (Literal[“openvaf”, “spectre”]): Compiler capability target recorded in the source.
  • port_convention (Literal[“travelling_wave”, “gf_45spclo_npe”]): External optical port convention. GF packed ports require the Spectre backend.
  • module_name (str | None): Module identifier derived from path when omitted.
  • z0 (float): Travelling-wave optical reference impedance.
  • field_impedance (float | None): GF electric-field scaling.

Returns

pathlib.Path: Absolute destination path.

Properties

Section titled “Properties”
PropertyDescription
status

status

Section titled “status”

No description available.

Attributes

Section titled “Attributes”
AttributeDescription
parametric_functionstr: Function used to update the time stepper.
parametric_kwargsdict[str, object]: Keyword arguments used to update the time stepper.
path_delaysdict[tuple[str, str], int] | None: Minimum delay in time steps of each (input key, output key) signal path; missing pairs have no path and None means every input reaches every output within the time step.
propertiesProperties: Object properties.
random_variableslist[RandomVariable]: Random variables associated to the time stepper’s parameters.

parametric_function

Section titled “parametric_function”

str: Function used to update the time stepper.

parametric_kwargs

Section titled “parametric_kwargs”

dict[str, object]: Keyword arguments used to update the time stepper.

path_delays

Section titled “path_delays”

dict[tuple[str, str], int] | None: Minimum delay in time steps of each (input key, output key) signal path; missing pairs have no path and None means every input reaches every output within the time step.

properties

Section titled “properties”

Properties: Object properties.

random_variables

Section titled “random_variables”

list[RandomVariable]: Random variables associated to the time stepper’s parameters.