Model¶

class photonforge.Model¶

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

Models must be derived from this class and implement:

start()
from_bytes()
as_bytes
__copy__(self): return a shallow copy of itself.
__deepcopy__(self, memo=None): return a deep copy of itself (argument memo is for internal libcopy use only).

Additionally, for model parameterization to work correctly, the __init__ method must call the base class __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_data 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_data["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: _metadata, parametric_data, random_variables, s_matrix(), update().

Example

>>> class CustomModel(Model):
...     def __init__(self, coeff):
...         super().__init__(coeff=coeff)
...         self.coeff = coeff
...
...     def __copy__(self):
...         return CustomModel(self.coeff)
...
...     def __deepcopy__(self, memo=None):
...         return CustomModel(self.coeff)
...
...     @property
...     def as_bytes(self):
...         c = complex(self.coeff)
...         return struct.pack('<2d', c.real, c.imag)
...
...     @classmethod
...     def from_bytes(cls, byte_repr):
...         real, imag = struct.unpack('<2d', byte_repr)
...         return cls(real + 1j * imag)
...
...     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 ModelResult(s)
...
...
>>> register_model_class(CustomModel)
>>> model = CustomModel(5e-15j)

Note

Modules struct and json can be useful in converting the model data to and from a byte representation. The first is used in the example, but, if all data is json-serializable, the conversions can be as easy as:

>>> # as_bytes: model data to bytes
>>> byte_repr = json.dumps(model_data).encode("utf-8")
>>> # from_bytes: bytes to model data
>>> model_data = json.loads(byte_repr.decode("utf-8"))

Methods

`from_bytes`(bytes)	Create a model object from its byte representation.
`s_matrix`(component, frequencies[, ...])	Compute the S matrix for a component using this model.
`start`	Start the S matrix computation for a component using this model.
`update`(args, *kwargs)	Update this model.

Attributes

`as_bytes`	Byte representation of the component for serialization (read only).
`parametric_function`	Function used to update a parametric component.
`parametric_kwargs`	Keyword arguments used to update a parametric component.
`random_variables`	List of `monte_carlo.RandomVariable` associated to this component's parameters.

as_bytes¶: Byte representation of the component for serialization (read only).

static from_bytes(bytes)¶

Create a model object from its byte representation.

Important

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

Parameters:: bytes – Byte sequence with the component data created from as_bytes.
Returns:: Model instance.

parametric_function¶: Function used to update a parametric component.

parametric_kwargs¶: Keyword arguments used to update a parametric component.

random_variables¶: List of monte_carlo.RandomVariable associated to this component’s parameters.

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

Compute the S matrix for a component using this model.

Parameters:

component – Component to perform the calculation.
frequencies – Sequence of frequency values at which to calculate the scattering parameters (in Hz).
show_progress – If True, show overall computation progress.
model_kwargs – Keyword arguments passed to the model call. Each model type can accept a different set of arguments. Check the documentation for the specific model for more information.

Returns:

Computed SMatrix.

start()¶

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

Important

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

The method 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).

Note

The ModelResult can be used to create the result for the start method when the calculation can be performed immediately.

Parameters:

component – Component to perform the calculation.
frequencies – Sequence of frequency values at which to calculate the scattering parameters (in Hz).
**kwargs – 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.

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.

Parameters:

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

Returns:

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