tidy3d.web.Job

class Job

Bases: WebContainer

Interface for managing the running of a Simulation on server.

Parameters:

• simulation (Union[Simulation, HeatChargeSimulation, HeatSimulation, EMESimulation, ModeSolver, ModeSimulation, VolumeMesher, ModalComponentModeler, TerminalComponentModeler]) – Simulation to run as a ‘task’.

• workflow (Optional[Workflow] = None) – Internal workflow definition. If unset, resolved from simulation type.

• task_name (Optional[str] = None) – Unique name of the task. Will be auto-generated if not provided.

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

• 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'}.

• solver_version (Optional[str] = None) – Deprecated direct option for internal use only. Internal workflows should set td.config.run.solver_version instead; external users should leave unset.

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

• simulation_type (Optional[str] = None) – Internal simulation type label; external users should leave unset.

• parent_tasks (Optional[tuple[str, ...]] = None) – Tuple of parent task ids, used internally only.

• task_id_cached (Optional[str] = None) – Optional field to specify task_id. Only used as a workaround internally so that task_id is written when Job.to_file() and then the proper task is loaded from Job.from_file(). We recommend leaving unset as setting this field along with fields that were not used to create the task will cause errors.

• state_cached (Optional[JobState] = None) – Cached runtime workflow state used for job serialization.

• reduce_simulation (Literal['auto', True, False] = auto) – Whether to reduce structures in the simulation to the simulation domain only. Note: currently only implemented for the mode solver.

• pay_type (Optional[PayType] = None) – Deprecated direct option for internal use only. Internal workflows should set td.config.run.pay_type instead; external users should leave unset.

• lazy (bool = False) – Whether to load the actual data (lazy=False) or return a proxy that loads the data when accessed (lazy=True).

Notes

This class provides a more convenient way to manage single simulations, mainly because it eliminates the need for keeping track of the task_id and original Simulation.

We can get the cost estimate of running the task before actually running it. This prevents us from accidentally running large jobs that we set up by mistake. The estimated cost is the maximum cost corresponding to running all the time steps.

Another convenient thing about Job objects is that they can be saved and loaded just like other tidy3d components.

Examples

Once you’ve created a job object using Job, you can upload it to our servers, run it, monitor it, and load the results with:

job = tidy3d.web.Job(simulation=simulation, task_name="task_name")
sim_data = job.run(path="out/simulation.hdf5")

Multi-step jobs expose per-step identifiers through job.task_ids and can be advanced one step at a time with job.step().

The job container has a convenient method to save and load the results of a job that has already finished, without needing to know the task_id, as below:

# Saves the job metadata to a single file.
job.to_file("data/job.json")

# You can exit the session, break here, or continue in new session.

# Load the job metadata from file.
job_loaded = tidy3d.web.api.container.Job.from_file("data/job.json")

# Download the data from the server and load it into a SimulationData object.
sim_data = job_loaded.load(path="data/sim.hdf5")

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.

Batch

Interface for submitting several Simulation objects to sever.

Notebooks

• Running simulations through the cloud

• Performing parallel / batch processing of simulations

• Inverse taper edge coupler

Attributes

is_multi_step	Whether this job executes more than one workflow step.
load_if_cached	Checks if results are cached and (if yes) restores them into our shared stash file.
state	Snapshot of current runtime workflow state.
status	Return current status of Job.
steps	Resolved workflow steps for this job.
task_id	The task ID for this Job.
task_ids	Task ids for all resolved steps.
simulation
workflow
task_name
folder_name
callback_url
solver_version
verbose
simulation_type
parent_tasks
task_id_cached
state_cached
reduce_simulation
pay_type
lazy

Methods

clear_stash()	Delete all stash files for this job.
delete()	Delete server-side data associated with Job.
download([path])	Download results of simulation.
estimate_cost([verbose])	Estimate the maximum FlexCredit charge for this Job.
get_info()	Return information about a Job.
get_run_info()	Return information about the running Job.
load([path, progress_callback])	Download job results and load them into a data object.
load_step(step_name[, path, progress_callback])	Load the default user-facing data associated with a completed workflow step.
monitor([worker_group])	Monitor progress of running Job.
real_cost([verbose])	Get the billed cost for the task associated with this job.
run([path, priority, vgpu_allocation, ...])	Run Job all the way through and return data.
set_task_name_if_none(data)	Auto-assign a task_name if user did not provide one.
start([priority, vgpu_allocation, ...])	Start running a Job.
step([path, progress_callback_upload, ...])	Run one incomplete workflow step and return its default loadable data.
to_file(fname)	Exports Tidy3dBaseModel instance to .yaml, .json, or .hdf5 file
upload([progress_callback])	Upload this Job if not already got cached results.

simulation

workflow

task_name

folder_name

callback_url

solver_version

verbose

simulation_type

parent_tasks

task_id_cached

state_cached

reduce_simulation

pay_type

lazy

property steps

Resolved workflow steps for this job.

property is_multi_step

Whether this job executes more than one workflow step.

property state

Snapshot of current runtime workflow state.

property task_ids

Task ids for all resolved steps.

clear_stash()

Delete all stash files for this job.

to_file(fname)

Exports Tidy3dBaseModel instance to .yaml, .json, or .hdf5 file

Parameters:

fname (PathLike) – Full path to the .yaml or .json file to save the Tidy3dBaseModel to.

Example

>>> simulation.to_file(fname='folder/sim.json') 

step(path=None, progress_callback_upload=None, progress_callback_download=None, worker_group=None, priority=None, vgpu_allocation=None, ignore_memory_limit=None)

Run one incomplete workflow step and return its default loadable data.

For HeatSimulation and HeatChargeSimulation jobs, this means running the mesh step first and the solve step on the next call. Raises if all steps are complete.

load_step(step_name, path=None, progress_callback=None)

Load the default user-facing data associated with a completed workflow step.

run(path=None, priority=None, vgpu_allocation=None, ignore_memory_limit=None, *, progress_callback_upload=None, progress_callback_download=None, worker_group=None)

Run Job all the way through and return data.

HeatSimulation and HeatChargeSimulation jobs execute through the internal mesh-then-solve workflow and return the final simulation data object.

Parameters:

• path (Optional[PathLike] = None) – Path to download results file (.hdf5), including filename. When None, a default filename is used.

• priority (int = None) – Priority of the simulation in the Virtual GPU (vGPU) queue (1 = lowest, 10 = highest). It affects only simulations from vGPU licenses and does not impact simulations using FlexCredits.

• vgpu_allocation (int = None) – Number of virtual GPUs to allocate for the simulation (1, 2, 4, or 8). Only applies to vGPU license users. If not specified, the system automatically determines the optimal GPU count.

• ignore_memory_limit (Optional[bool] = None) – If True, allows the simulation to run even when estimated vGPU memory exceeds the allocation limit (up to 2x the limit). Only applies to vGPU license users. Default None leaves the server behaviour unchanged.

Returns:

Object containing simulation results.

Return type:

WorkflowDataType

property load_if_cached

Checks if results are cached and (if yes) restores them into our shared stash file.

property task_id

The task ID for this Job. Uploads the Job if it hasn’t already been uploaded.

upload(progress_callback=None)

Upload this Job if not already got cached results.

get_info()

Return information about a Job.

Returns:

TaskInfo object containing info about status, size, credits of task and others.

Return type:

TaskInfo

property status

Return current status of Job.

start(priority=None, vgpu_allocation=None, ignore_memory_limit=None, *, worker_group=None)

Start running a Job.

Parameters:

• priority (int = None) – Priority of the simulation in the Virtual GPU (vGPU) queue (1 = lowest, 10 = highest). It affects only simulations from vGPU licenses and does not impact simulations using FlexCredits.

• vgpu_allocation (int = None) – Number of virtual GPUs to allocate for the simulation (1, 2, 4, or 8). Only applies to vGPU license users. If not specified, the system automatically determines the optimal GPU count.

• ignore_memory_limit (Optional[bool] = None) – If True, allows the simulation to run even when estimated vGPU memory exceeds the allocation limit (up to 2x the limit). Only applies to vGPU license users. Default None leaves the server behaviour unchanged.

Note

To monitor progress of the Job, call Job.monitor() after started. Function has no effect if cache is enabled and data was found in cache.

get_run_info()

Return information about the running Job.

Returns:

Task run information.

Return type:

RunInfo

monitor(worker_group=None)

Monitor progress of running Job.

Note

To load the output of completed simulation into SimulationData objects, call Job.load().

download(path=None)

Download results of simulation.

Parameters:

path (Optional[PathLike] = None) – Path to download data as .hdf5 file (including filename). When None, a default filename is used.

Note

To load the data after download, use Job.load().

load(path=None, progress_callback=None)

Download job results and load them into a data object.

Parameters:

path (Optional[PathLike] = None) – Path to download data as .hdf5 file (including filename). When None, a default filename is used.

Returns:

• Union[SimulationData, HeatSimulationData,

• EMESimulationData] – Object containing simulation results.

delete()

Delete server-side data associated with Job.

real_cost(verbose=True)

Get the billed cost for the task associated with this job.

Parameters:

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

Returns:

Billed cost of the task in FlexCredits, or None if unavailable.

Return type:

Optional[float]

estimate_cost(verbose=True)

Estimate the maximum FlexCredit charge for this Job.

For multi-step jobs, estimates the first incomplete workflow step only. Returns 0.0 when every step is already complete.

Parameters:

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

Returns:

Estimated cost of the task in FlexCredits.

Return type:

float

Note

FDTD cost is calculated assuming the simulation runs for the full run_time. If early shutoff is triggered, the cost is adjusted proportionately. For charge simulations, the billed cost depends on the number of solver iterations required for convergence. For Mode, EME, and Heat simulations, the estimated cost is the final billed cost.

classmethod set_task_name_if_none(data)

Auto-assign a task_name if user did not provide one.