tidy3d.web.api.container.Batch

class Batch

Bases: WebContainer

Interface for submitting several Simulation objects to sever.

Parameters:

• simulations (Mapping[str, Annotated[Union[tidy3d.components.simulation.Simulation, tidy3d.components.heat.simulation.HeatSimulation], FieldInfo(default=PydanticUndefined, discriminator='type', extra={})]]) – Mapping of task names to Simulations to run as a batch.

• folder_name (str = default) – Name of folder to store member of each batch on web UI.

• verbose (bool = True) – Whether to print info messages and progressbars.

• solver_version (Optional[str] = None) – callback_url : Optional[str] = None Http PUT url to receive simulation finish event. The body content is a json file with fields {'id', 'status', 'name', 'workUnit', 'solverVersion'}.

• simulation_type (str = tidy3d) – Type of each simulation in the batch, used internally only.

• parent_tasks (Optional[Mapping[str, Tuple[str, ...]]] = None) – Collection of parent task ids for each job in batch, used internally only.

• jobs (Optional[Mapping[str, Job]] = None) – Mapping of task names to individual Job object for each task in the batch. Set by Batch.upload, leave as None.

Notes

Commonly one needs to submit a batch of Simulation. The built-in Batch object is the best way to upload, start, monitor, and load a series of tasks. The batch object is like a Job, but stores task metadata for a series of simulations.

See also

tidy3d.web.api.webapi.run_async()

Submits a set of Simulation objects to server, starts running, monitors progress, downloads, and loads results as a BatchData object.

Job:

Interface for managing the running of a Simulation on server.

Notebooks

• Running simulations through the cloud

• Performing parallel / batch processing of simulations

• Inverse taper edge coupler

Attributes

Methods

delete()	Delete server-side data associated with each task in the batch.
download([path_dir])	Download results of each task.
estimate_cost([verbose])	Compute the maximum FlexCredit charge for a given Batch.
get_info()	Get information about each task in the Batch.
get_run_info()	get information about a each of the tasks in the Batch.
load([path_dir])	Download results and load them into BatchData object.
monitor()	Monitor progress of each of the running tasks.
real_cost([verbose])	Get the sum of billed costs for each task associated with this batch.
run([path_dir])	Upload and run each simulation in Batch.
start()	Start running all tasks in the Batch.

Inherited Common Usage

simulations

folder_name

verbose

solver_version

callback_url

simulation_type

parent_tasks

jobs

run(path_dir='.')

Upload and run each simulation in Batch.

Parameters:

path_dir (str) – Base directory where data will be downloaded, by default current working directory.

Returns:

Contains Union[SimulationData, HeatSimulationData] for each Union[Simulation, HeatSimulation] in Batch.

Return type:

BatchData

Note

A typical usage might look like:

>>> from tidy3d.web.api.container import Batch
>>> custom_batch = Batch()
>>> batch_data = custom_batch.run() 
>>> for task_name, sim_data in batch_data.items(): 
...     # do something with data. 

bach_data does not store all of the data objects in memory, rather it iterates over the task names and loads the corresponding data from file one by one. If no file exists for that task, it downloads it.

get_info()

Get information about each task in the Batch.

Returns:

Mapping of task name to data about task associated with each task.

Return type:

Dict[str, TaskInfo]

start()

Start running all tasks in the Batch.

Note

To monitor the running simulations, can call Batch.monitor().

get_run_info()

get information about a each of the tasks in the Batch.

Returns:

Dict[str – Maps task names to run info for each task in the Batch.

Return type:

RunInfo]

monitor()

Monitor progress of each of the running tasks.

Note

To loop through the data of completed simulations, can call Batch.items().

download(path_dir='.')

Download results of each task.

Parameters:

path_dir (str = './') – Base directory where data will be downloaded, by default the current working directory.

Note

To load and iterate through the data, use Batch.items().

The data for each task will be named as {path_dir}/{task_id}.hdf5. The Batch hdf5 file will be automatically saved as {path_dir}/batch.hdf5, allowing one to load this Batch later using batch = Batch.from_file().

load(path_dir='.')

Download results and load them into BatchData object.

Parameters:

path_dir (str = './') – Base directory where data will be downloaded, by default current working directory.

Returns:

• BatchData – Contains Union[SimulationData, HeatSimulationData] for each Union[Simulation, HeatSimulation] in Batch.

• The Batch hdf5 file will be automatically saved as {path_dir}/batch.hdf5,

• allowing one to load this Batch later using batch = Batch.from_file().

delete()

Delete server-side data associated with each task in the batch.

real_cost(verbose=True)

Get the sum of billed costs for each task associated with this batch.

Parameters:

verbose (bool = True) – Whether to log the cost and helpful messages.

Returns:

Billed cost for the entire Batch.

Return type:

float

estimate_cost(verbose=True)

Compute the maximum FlexCredit charge for a given Batch.

Parameters:

verbose (bool = True) – Whether to log the cost and helpful messages.

Note

Cost is calculated assuming the simulation runs for the full run_time. If early shut-off is triggered, the cost is adjusted proportionately.

Returns:

Estimated total cost of the tasks in FlexCredits.

Return type:

float

__hash__()

Hash method.