tidy3d.web.run

tidy3d.web.run#

Bases:

Submit one or many simulations and return results in the same container shape.

This is a convenience wrapper around the autograd runners that accepts a single WorkflowType or an arbitrarily nested container of simulations (list, tuple, or dict values). Internally, all simulations are collected, deduplicated by object hash, executed either synchronously (single) or asynchronously (batch), and the returned data objects are reassembled to mirror the input structure.

Path behavior

Single simulation: results are downloaded to f"{path}.hdf5".
Multiple simulations: path is treated as a directory, and each task will write its own results file inside that directory.

Lazy loading

If lazy is not specified: single runs default to False (eager load); batch runs default to True (proxy objects that load on first access).

Parameters:

simulation (Union[Simulation, HeatSimulation, EMESimulation] | list | tuple | dict) – A simulation or a container whose leaves are simulations. Supported containers are list, tuple, and dict (values only). Dict keys must not be simulations.
task_name (Optional[str], default None) – Optional name for a single run. Prefixed for multiple runs.
folder_name (str = "default") – Folder shown on the web UI.
path (Optional[PathLike] = None) – Output path. Interpreted as a file path for single simulations and a directory for multiple simulations. Defaults are “simulation.hdf5” (single simulation) and the current directory (multiple simulations).
callback_url (Optional[str] = None) – Optional HTTP PUT endpoint to receive completion events.
verbose (bool = True) – If True, print status and progress; otherwise run quietly.
progress_callback_upload (Optional[Callable[[float], None]] = None) – Callback invoked with byte counts during upload (single-run path only).
progress_callback_download (Optional[Callable[[float], None]] = None) – Callback invoked with byte counts during download (single-run path only).
solver_version (Optional[str] = None) – Target solver version.
worker_group (Optional[str] = None) – Worker group to target.
simulation_type (str = "tidy3d") – Simulation type label passed through to the runners.
parent_tasks (Optional[List[str]] = None) – Parent task IDs, if any.
local_gradient (Optional[bool] = None) – Compute gradients locally (more downloads; useful for experimental features). Defaults to config.adjoint.local_gradient when not provided. Remote gradients always use server-side defaults.
max_num_adjoint_per_fwd (Optional[int] = None) – Maximum number of adjoint simulations allowed per forward run. Defaults to config.adjoint.max_adjoint_per_fwd when not provided.
reduce_simulation ({"auto", True, False} = "auto") – Whether to reduce structures to the simulation domain (mode solver only).
pay_type (Union[PayType, str] = PayType.AUTO) – Payment method selection.
priority (Optional[int] = None) – Queue priority for vGPU (1 = lowest, 10 = highest).
max_workers (Optional[int] = None) – Maximum parallel submissions for batch runs. None submits all at once.
lazy (Optional[bool] = None) – Whether to load the actual data (lazy=False) or return a proxy that loads the data when accessed (lazy=True).

Returns:

A data object (or nested container of data objects) matching the input container shape. Leaves are instances of the corresponding WorkflowDataType.

Return type:

RunOutput

Notes

Simulations are indexed by hash(sim). If the same object appears multiple times in the input, it is executed once and its data is reused at all positions. The last occurrence wins if duplicates with the same hash are encountered.
For each simulation, a mode-solver compatibility patch is applied so that the returned data exposes expected convenience attributes.
progress_callback_* are only used in the single-run code path.

Raises:

ValueError – If no simulations are found in simulation.
TypeError – If an unsupported container element is encountered, or if a dict key is a simulation object.

Examples

Single run (eager by default):

.. code-block:: python

sim_data = run(sim, task_name=”wg_bend”, path=”out/bend”) # writes: “out/bend.hdf5”

Batch run with nested structure (lazy by default):

.. code-block:: python

sims = {
“coarse”: [sim_a, sim_b], “fine”: sim_c,

} data = run(sims, path=”out/batch_dir”, max_workers=4)

# ‘data’ mirrors ‘sims’ structure: # data[“coarse”][0] -> data for sim_a, etc.

tidy3d.web.run

Contents

tidy3d.web.run#