MuxDemuxModel

MuxDemuxModel(
    *,
    frequencies: collections.abc.Sequence[
        typing.Annotated[float, minimum=0, units='Hz']
    ] = (),
    wavelengths: collections.abc.Sequence[
        typing.Annotated[float, exclusiveMinimum=0, units='μm']
    ] = (),
    bandwidth: Annotated[float, exclusiveMinimum=0]
    | collections.abc.Sequence[Annotated[float, exclusiveMinimum=0]] = (),
    order: Annotated[int, exclusiveMinimum=0]
    | collections.abc.Sequence[Annotated[int, exclusiveMinimum=0]] = 3,
    insertion_loss: Annotated[float, minimum=0, units='dB']
    | collections.abc.Sequence[Annotated[float, minimum=0, units='dB']] = 0,
    group_delay: Annotated[float, minimum=0, units='s']
    | collections.abc.Sequence[Annotated[float, minimum=0, units='s']] = 0,
    free_spectral_range: Annotated[float, minimum=0, units='Hz'] = 0.0,
    periodic_orders: Annotated[int, minimum=0] = 3,
    crosstalk: Annotated[float, units='dB'] | None = None,
    reflection: complex | collections.abc.Sequence[complex] = 0,
    temperature_sensitivity: Annotated[
        float | collections.abc.Sequence[float], units='*/K'
    ] = 0.0,
    temperature: Annotated[float, minimum=0, units='K'] = 293.0,
    reference_temperature: Annotated[float, minimum=0, units='K'] = 293.0,
    ports: collections.abc.Sequence[str] | None = None,
) -> None

Wavelength multiplexer/demultiplexer (WDM).

Each channel is represented by a causal Butterworth band-pass with analytically known poles and residues.

Args

frequencies: Central frequency for each channel. Use only one of frequencies or wavelengths.
wavelengths: Central wavelength for each channel. Use only one of frequencies or wavelengths.
bandwidth: 3 dB frequency bandwidth for each channel when used with frequencies (in Hz). When wavelengths is used, this is the 3 dB wavelength bandwidth for each channel (in μm), converted locally to frequency at the channel center.
order: Butterworth filter order.
insertion_loss: Insertion loss per channel.
group_delay: Additional constant group delay per channel.
free_spectral_range: Period of the response. Channels repeat every FSR and the replicas alias back onto their own ports. Zero gives a single passband per channel.
periodic_orders: Number of orders of FSR to include inteh response.
crosstalk: Floor on off-channel transmission.
reflection: Constant reflection coefficient for incident fields. If a sequence is used, the first value is for the common port and the remaining values are for the frequency-filtered ports.
temperature_sensitivity: Temperature sensitivity for central frequencies (in Hz/K) or wavelengths (in μm/K).
temperature: Operating temperature.
reference_temperature: Reference temperature.
ports: Port names, with the common port first. If not set, the naturally sorted component port names are used.

Note

Sequences can set different values per channel. Their lengths must match the number of channels, except for reflection and ports, which include one additional entry for the common port.

Configurations that are not passive emit a warning and are evaluated without modification.

Methods

Method	Description
`autograd_smatrix`	Compute an autograd-compatible S matrix for traced parameters.
`black_box_component`	Create a black-box component using this model.
`estimate_cost`	Estimate the cost for S matrix computation.
`s_matrix`	Compute the S matrix for a component using this model.
`setup_time_stepper`	Obtain a time stepper for a component using this model.
`start`	Compute the analytic S matrix response.
`transform`	Apply a transformation to this model.
`update`	Update this model.

autograd_smatrix

autograd_smatrix(
    self,
    *,
    component,
    traced_params,
    frequencies,
    component_for_params,
    param_names,
    show_progress=True,
    model_kwargs=None,
)

Compute an autograd-compatible S matrix for traced parameters.

Important

This is an abstract method that must be implemented by derived classes that support autograd-based S-matrix computation.

Args

component (Component): Nominal component associated with this autograd evaluation.
traced_params (ndarray): Traced parameter vector used by autograd.
frequencies (Sequence[float]): Frequency values at which to calculate the scattering parameters (in Hz).
component_for_params (Callable[[ndarray], Component]): Callback that returns the component for a given traced parameter vector.
param_names (Sequence[str]): Flattened traced parameter names aligned with traced_params.
show_progress (bool): Progress display hint from Component.s_matrix.
model_kwargs (dict[str, Any] | None): Model-specific keyword arguments forwarded from Component.s_matrix.

Returns

AutogradSMatrix: Autograd-compatible S matrix.

black_box_component

black_box_component(
    self,
    port_spec: str | photonforge.PortSpec | None = None,
    technology: photonforge.Technology | None = None,
    name: str | None = None,
) -> photonforge.Component

Create a black-box component using this model.

The layout is the model’s schematic symbol in a box, sized by the port width, with the port profiles drawn as stubs.

Args

port_spec: Port specification used in the component. If None, look for "port_spec" in config.default_kwargs.
technology: Component technology. If None, the default technology is used.
name: Component name. If None, a default is used.

Returns

Component with ports and model.

estimate_cost

estimate_cost(self, *args, **kwargs)

Estimate the cost for S matrix computation.

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

Returns

float: Cost estimation.

s_matrix

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

Compute the S matrix for a component using this model.

Args

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, object]): Keyword arguments passed to Model.start. Accepted arguments depend on the model type.

Returns

SMatrix: Computed S matrix.

Example

Compute only the responses from mode 0 of P0 with Tidy3D to reduce the number and cost of simulations:

>>> model = pf.Tidy3DModel()
>>> s_matrix = model.s_matrix(  # doctest: +SKIP
...     component,
...     frequencies,
...     model_kwargs={"inputs": ("P0@0",)},
... )

A port name such as ("P0",) selects all modes of that port. All outputs for the selected inputs are returned; responses from unselected inputs are not computed. Use Model.estimate_cost with the same inputs passed directly to estimate the reduced run.

setup_time_stepper

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

Obtain a time stepper for a component using this model.

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 computation progress.
time_stepper_kwargs (dict[str, object]): 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

TimeStepper: Initialized time stepper.

start

start(
    self,
    component: photonforge.Component,
    frequencies: collections.abc.Sequence[float],
    temperature: Annotated[float, minimum=0, units='K'] | None = None,
    **kwargs: object,
) -> photonforge.SMatrix

Compute the analytic S matrix response.

Args

component: Component from which to compute the S matrix.
frequencies: Frequencies at which to evaluate the response.
temperature: Operating temperature override.
**kwargs: Unused.

Returns

Causal mux/demux S matrix.

transform

transform(
    self, translation=(0, 0), rotation=0, scaling=1, x_reflection=False
)

Apply a transformation to this model.

The base implementation is a no-op and returns self. Derived classes can override this method to transform model-specific geometry settings.

Args

translation (Sequence[float] | complex): Translation vector.
rotation (float): Rotation angle in degrees.
scaling (float): Magnification factor.
x_reflection (bool): Mirror across the horizontal axis.

Returns

Model: This object with transformations applied.

update

update(self, *args, **kwargs)

Update this model.

All contents of the model are updated with the contents from the updated version. object 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.

Args

*args (object): Positional arguments to the parametric model.
**kwargs (object): Keyword arguments to the parametric model.

Returns

Model: 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.

Attributes

Attribute	Description
`parametric_function`	str: Function used to update the model.
`parametric_kwargs`	dict[str, object]: Keyword arguments used to update the model.
`properties`	Properties: Object properties.
`random_variables`	list[RandomVariable]: Random variables associated to the model’s parameters.
`time_stepper`	TimeStepper \| None: Time stepper associated with this model.

parametric_function

str: Function used to update the model.

parametric_kwargs

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

properties

Properties: Object properties.

random_variables

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

time_stepper

TimeStepper | None: Time stepper associated with this model.