S-Matrix Component Modelers Plugin

S-Matrix Component Modelers Plugin#

This plugin provides component modelers for computing S-parameters (scattering parameters) for both photonics and RF/microwave applications. The plugin supports:

Photonics: Modal component modelers for photonic devices (waveguides, splitters, filters, etc.)
RF/Microwave: Terminal component modelers for microwave circuits and antennas (available in tidy3d.rf subpackage as well)

Warning

Breaking changes were introduced in v2.10.0, please see the v2.10 Refactor Migration guide for help migrating your code.

Photonics Component Modelers#

For photonics applications, use the ModalComponentModeler which computes modal S-parameters based on mode overlap integrals.

`tidy3d.plugins.smatrix.ModalComponentModeler`	A tool for modeling devices and computing scattering matrix elements.
`tidy3d.plugins.smatrix.ModalComponentModelerData`	A data container for the results of a `ModalComponentModeler` run.
`tidy3d.plugins.smatrix.Port`	Specifies a port for S-matrix calculation.
`tidy3d.plugins.smatrix.ModalPortDataArray`	Port parameter matrix elements for modal ports.

RF/Microwave Component Modelers#

v2.10 Refactor Migration#

In version v2.10.0rc1, smatrix plugin classes were refactored to improve web and GUI support for RF capabilities. This guide helps you update your scripts to the new, more robust API.

Key Changes#

Rename: ComponentModeler has been renamed ModalComponentModeler.
Web Interface: Web parameters like verbose and path_dir are now passed to tidy3d.web.run() instead of the modeler class constructor.
Immutable Data Structures: Modeler classes are now immutable. ComponentModelerData classes hold simulation results, separating data from the modeler definition.
Explicit Method Calls: Running simulations and fetching results are now done through explicit function calls like tidy3d.web.run() and tidy3d.web.load().

Updated Workflow#

The new workflow is more explicit and aligns with the general tidy3d API.

Before (Old API):

import tidy3d.plugins.smatrix as sm

# Modeler class was mutable and included web parameters
tcm = sm.TerminalComponentModeler(
    simulation=sim,
    ports=[LP1, LP2],
    freqs=freqs,
    verbose=True,
    path_dir="data",
)
# The run method was part of the modeler class
s_matrix = tcm.run()

After (New API):

import tidy3d.web as web
# Rf classes now found in tidy3d.rf
import tidy3d.rf as rf

# Modeler class is now immutable and cleaner
tcm = rf.TerminalComponentModeler(
    simulation=sim,
    ports=[LP1, LP2],
    freqs=my_freqs,
)
# Use web.run to execute the simulation
modeler_data = web.run(tcm, verbose=True, path="data/modeler_data.hdf5")
s_matrix = modeler_data.smatrix()

Note

The S-matrix is now computed from the ComponentModelerData objects, so it is accessed via the .smatrix() method.

Cost Estimation#

Cost estimation is now done by uploading the modeler to the web API.

Before:

est_flex_credits = tcm.estimate_cost()
real_flex_credits = tcm.real_cost()

After:

task_id = web.upload(tcm)
est_flex_credits = web.estimate_cost(task_id)
# After the run is complete
real_flex_credits = web.real_cost(task_id)

Data Handling#

The new API introduces immutable data containers for simulation results, ensuring that your data is more predictable and easier to manage.

tidy3d.rf.TerminalComponentModeler returns a tidy3d.rf.TerminalComponentModelerData object.
ModalComponentModeler returns a ModalComponentModelerData object.

These data objects contain the S-matrix, port impedance, and other relevant results.

Before:

# batch_data was a mutable property of the modeler
tcm_batch = tcm.batch_data
sim_data = tcm_batch["smatrix_LP1"]

After:

# web.run returns an immutable data object
modeler_data = web.run(tcm)
# Access simulation data for each port
sim_data = modeler_data.data["smatrix_LP1"]

Migration Utilities#

To ease the transition, we provide utilities that mimic the old workflow.

Warning

These migration helpers are temporary and will be deprecated in a future release.

Run a batch of simulations: If you prefer to manage the batch run yourself, you can create and run a batch explicitly.

from tidy3d.plugins.smatrix.run import create_batch

batch = create_batch(modeler=my_modeler)
batch_data = batch.run()

Compose data from a batch: If you have a tidy3d.web.BatchData object from a manual run, you can still create the corresponding ModalComponentModelerData or TerminalComponentModelerData object.

from tidy3d.plugins.smatrix.run import compose_modeler_data_from_batch_data

modeler_data = compose_modeler_data_from_batch_data(
    modeler=my_modeler, batch_data=batch_data
)

API Reference#

For more details, see the API documentation for the new classes and functions:

`tidy3d.plugins.smatrix.ModalComponentModeler`	A tool for modeling devices and computing scattering matrix elements.
`tidy3d.plugins.smatrix.ModalComponentModelerData`	A data container for the results of a `ModalComponentModeler` run.
`tidy3d.rf.TerminalComponentModeler`	Tool for modeling two-terminal multiport devices and computing port parameters with lumped and wave ports.
`tidy3d.rf.TerminalComponentModelerData`	Data associated with a `TerminalComponentModeler` simulation run.
`tidy3d.SimulationMap`	An immutable dictionary-like container for simulations.
`tidy3d.SimulationDataMap`	An immutable dictionary-like container for simulation data.
`tidy3d.plugins.smatrix.run.create_batch`(...)	Create a simulation Batch from a component modeler.
`tidy3d.plugins.smatrix.run.compose_modeler_data_from_batch_data`(...)	Select the correct composer based on modeler type and create the data object.
`tidy3d.plugins.smatrix.run.compose_modeler_data`(...)	Create a modeler data object from a modeler and indexed simulation data.

`tidy3d.plugins.smatrix.AbstractComponentModeler`	Tool for modeling devices and computing port parameters.
`tidy3d.SimulationMap`	An immutable dictionary-like container for simulations.
`tidy3d.SimulationDataMap`	An immutable dictionary-like container for simulation data.

`tidy3d.plugins.smatrix.TerminalComponentModeler`	Tool for modeling two-terminal multiport devices and computing port parameters with lumped and wave ports.
`tidy3d.plugins.smatrix.TerminalComponentModelerData`	Data associated with a `TerminalComponentModeler` simulation run.
`tidy3d.plugins.smatrix.LumpedPort`	Class representing a single rectangular lumped port.
`tidy3d.plugins.smatrix.CoaxialLumpedPort`	Class representing a single coaxial lumped port.
`tidy3d.rf.WavePort`	Class representing a single wave port
`tidy3d.rf.MicrowaveSMatrixData`	Stores the computed S-matrix and reference impedances for the terminal ports.
`tidy3d.rf.TerminalPortDataArray`	Port parameter matrix elements for terminal-based ports.
`tidy3d.rf.PortDataArray`	Array of values over dimensions of frequency and port name.