monte_carlo.s_matrix

s_matrix(
    component,
    frequencies,
    *variables,
    show_progress=True,
    random_samples=0,
    corner_samples=0,
    corner_coverage=0.95,
    random_seed=None,
    parallel_jobs=0,
    chain_technology_updates=True,
    chain_component_updates=True,
    component_args=(),
    component_kwargs={},
    model_kwargs={},
    callback_fn=None,
)

Compute variations of a component’s S matrix.

Technologies are updated before components and sub-components are updated before parents. Models are updated after components.

Args

component (Component | Callable[…, Component]): Main component or function that returns a component.
frequencies (Sequence[float]): Frequencies to use in the S matrix computation.
variables (RandomVariable | tuple[object, …]*): Random variables to include in the computation. More info below. If no variables are defined, all random variables present in the main component, its active model, and technology are used.
show_progress (bool): If True, show overall computation progress.
random_samples (int): Number of random samples to evaluate.
corner_samples (int): Number of corner cases to evaluate (randomly sampled). If negative or larger than the total number of corner cases, all cases are tested once.
corner_coverage (float): For variables with normal distribution, the lower and upper bounds are defined such that this value is the probability that a random sample is within those bounds. For example, a 0.95 probability sets the bounds at approximately 2 standard deviations from the mean.
random_seed (int | None): If set, value used as the random generator seed.
parallel_jobs (int): Number of computations to start simultaneously. If set to zero or negative, removes the limit.
chain_technology_updates (bool): If set, a technology update will trigger an update for all components using that technology.
chain_component_updates (bool): If set, a component update will trigger an update for all components referencing it.
component_args (tuple[object, …]): Tuple of positional arguments for the component function or parametric component update.
component_kwargs (dict[str, object]): Dictionary of keyword arguments for the component function or parametric component update.
model_kwargs (dict[str, object]): Dictionary of keyword arguments used in the call to Component.s_matrix.
callback_fn (Callable[[Component, tuple[object, …]], object] | None): Function called before the S matrix computation for each variation, after the component has been updated. The function must receive 2 arguments: component (the current variation) and a tuple with all random variables in their current state.

Returns

Tuple with list of variables (in update order) and list of results.

Arguments variables can be:

RandomVariable instance.
(parameter_name, object): Look for the random variable named parameter_name within object, which can be a Component, Model, or Technology instance, or one of "component", "model", or "technology". The strings are used to indicate the main component, its model, and its technology, respectively, which can be useful when the argument component is a function.
(parameter_name, object, random_variable_kwargs): Create a new random variable named parameter_name for the specified object using random_variable_kwargs.
(ref_spec, updates): Add Reference.update keyword arguments for the specified reference. Dictionary updates can contain the following keys:
```
{
    "technology_updates": [tech_var1, tech_var2, ...],
    "component_updates": [comp_var1, comp_var2, ...],
    "model_updates": [model_var1, model_var2, ...],
}
```
and each value is a list of random variables for the specified reference’s component, its technology, or its active model. The reference specification ref_spec follows the same format as the keys in CircuitModel.start, which is used for evaluation of the updates.

Important

Variables for references will only be used if the specified reference is computed by a CircuitModel, that is, all components in the tree leading to that reference have an active Circuit model for their S parameter computation.

Examples

>>> var1 = pf.monte_carlo.RandomVariable(
...     "var1", sub_component, values=[1, 2, 3]
... )
>>> var4 = pf.monte_carlo.RandomVariable(
...     "length", value=1, stdev=0.1
... )
>>> monte_carlo.s_matrix(
...     component,
...     frequencies,
...     var1,
...     ("var2", "component"),
...     ("var3", "model", {"value": 0.5, "stdev": 0.01}),
...     ((None, "DELAY"), {"model_updates": [var4]}),
...     random_samples=12,
... )

In this case, we use var1 as defined, look for a random variable named “var2” in the main component, create a new random variable named “var3” with normal distribution applied to the main component’s active model, and use var4 in the model of any component named “DELAY” among the dependencies of component.

Note

After the computations, all parametric components and models are updated with their original keyword values.

See Also

Cascaded MZI Filter