Model¶

class photonforge.Model(**kwargs)¶

Abstract model class to calculate a component’s S matrix.

Models must be derived from this class and implement the method start().

Additionally, for model parameterization to work correctly, the __init__ method must call super().__init__ with all parameters as keyword arguments (see example below). By default, models are updated by calling their __init__ method with the new keyword values. If a different behavior is required, the __init__ method must replace parametric_kwargs with the proper values for the user-defined update function and keywords. The update function must update the model in place and also update parametric_kwargs when called.

Finally, the derived class must be registered with register_model_class() before it can be used in a phf file.

Important

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

Example

>>> class CustomModel(pf.Model):
...     def __init__(self, *, coeff):
...         super().__init__(coeff=coeff)
...         self.coeff = coeff
...
...     def start(self, component, frequencies, **kwargs):
...         # Do any type of model calculation
...         s_param = numpy.exp(self.coeff * frequencies)
...         s = {("port_in@mode_in", "port_out@mode_out"): s_param}
...         return pf.SMatrix(s)
...
...
>>> pf.register_model_class(CustomModel)
>>> model = CustomModel(coeff=5e-15j)

Methods

`estimate_cost`(args, *kwargs)	Estimate the cost for S matrix computation.
`s_matrix`(component, frequencies[, ...])	Compute the S matrix for a component using this model.
`setup_time_stepper`(component, time_step[, ...])	Obtain a time stepper for a component using this model.
`start`(component, frequencies, **kwargs)	Start the S matrix computation for a component using this model.
`update`(args, *kwargs)	Update this model.

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.
`time_stepper`	Time stepper associated with this model.

estimate_cost(*args, **kwargs)¶

Estimate the cost for S matrix computation.

Arguments and keyword arguments are passed to the model’s start method with the addition of the keyword argument cost_estimation=True.

Returns:: Cost estimation.
Return type:: float

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]

s_matrix(component, frequencies, show_progress=True, model_kwargs={})¶

Compute the S matrix for a component using this model.

Parameters:

component (Component) – Component to perform the calculation.
frequencies (Sequence[float]) – Frequency values at which to calculate the scattering parameters (in Hz).
show_progress (bool) – If True, show computation progress.
model_kwargs (dict[str, Any]) – Keyword arguments passed to Model.start(). Each model type can accept a different set of arguments. Check the documentation for the each model’s start method for more information.

Returns:

Computed S matrix.

Return type:

SMatrix

setup_time_stepper(component, time_step, carrier_frequency=0, show_progress=True, time_stepper_kwargs={})¶

Obtain a time stepper for a component using this model.

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 computation progress.
time_stepper_kwargs (dict[str, Any]) – Keyword arguments passed to TimeStepper.setup(). Each time stepper type can accept a different set of arguments. Check the documentation for the each time stepper’s setup_state method for more information.

Returns:

Initialized time stepper.

Return type:

TimeStepper

start(component, frequencies, **kwargs)¶

Start the S matrix computation for a component using this model.

Important

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

If the S matrix calculation can be performed immediately, this method should return it directly.

Otherwise, it must return an object with attributes status and s_matrix that will be pooled to check the calculation progress. The status attribute must return a dictionary with 'progress' (a number from 0 to 100 indicating the calculation progress) and 'message' (one of 'running', 'success', or 'error', indicating the current calculation status). The 's_matrix' attribute should return the computed SMatrix once the calculation is successful (or None otherwise).

Important

Once the start method returns, there are no guarantees that the components, technologies or any other objects used as arguments will remain constant. That means no references to the original arguments should be kept after the method returns if the S matrix computation will continue latter, because they might change externally before the computation finishes. If needed, copies of the required objects must be used.

Parameters:

component (Component) – Component to perform the calculation.
frequencies (Sequence[float]) – Frequency values at which to calculate the scattering parameters (in Hz).
**kwargs (Any) – Keyword arguments forwarded from the Component.s_matrix() call plus others generated by calling models (such as CircuitModel).

Returns:

Object with status and s_matrix.

Return type:

Any

time_stepper¶

Time stepper associated with this model.

Type:: TimeStepper | None

update(*args, **kwargs)¶

Update this model.

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

The model’s time stepper does not participate in the update, unless the __init__ method of the derived model class replaces it via set_time_stepper().

Parameters:

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

Returns:

This model.

Return type:

Model

Note

The original keyword arguments used to generate the model 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.