v2.10 Refactor Migration

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.

See also

This guide is also included as part of the comprehensive v2.10 RF Refactor Migration Guide guide, which covers all v2.10 RF/microwave breaking changes.

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.

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