tidy3d.web.api.container.Job

tidy3d.web.api.container.Job#

class Job[source]#

Bases: WebContainer

Interface for managing the running of a Simulation on server.

Parameters:

  • attrs (dict = {}) – Dictionary storing arbitrary metadata for a Tidy3D object. This dictionary can be freely used by the user for storing data without affecting the operation of Tidy3D as it is not used internally. Note that, unlike regular Tidy3D fields, attrs are mutable. For example, the following is allowed for setting an attr obj.attrs['foo'] = bar. Also note that Tidy3D will raise a TypeError if attrs contain objects that can not be serialized. One can check if attrs are serializable by calling obj.json().

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

  • 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) – Custom solver version to use, otherwise uses default for the current front end version.

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

  • simulation_type (Literal['tidy3d', 'microwave', 'tidy3d_design', 'tidy3d_autograd', 'tidy3d_autograd_async', 'autograd_fwd', 'autograd_bwd'] = tidy3d) – Type of simulation, used internally only.

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

  • 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 (PayType = AUTO) – Specify the payment method.

  • 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 tidy3d.web.api.container.Job, you can upload it to our servers with:

tidy3d.web.upload(simulation, task_name="task_name", verbose=verbose)`

It will not run until you explicitly tell it to do so with:

tidy3d.web.api.webapi.start(job.task_id)

To monitor the simulation’s progress and wait for its completion, use

tidy3d.web.api.webapi.monitor(job.task_id, verbose=verbose)

After running the simulation, you can load the results using for example:

sim_data = tidy3d.web.api.webapi.load(job.task_id, path="out/simulation.hdf5", verbose=verbose)

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

Attributes

postprocess_status

Return current postprocess status of Job if it is a Component Modeler.

status

Return current status of Job.

task_id

The task ID for this Job.

attrs

Methods

delete()

Delete server-side data associated with Job.

download([path])

Download results of simulation.

estimate_cost([verbose])

Compute the maximum FlexCredit charge for a given Job.

get_info()

Return information about a Job.

get_run_info()

Return information about the running Job.

load([path])

Download job results and load them into a data object.

monitor()

Monitor progress of running Job.

postprocess_start([worker_group, verbose])

If the job is a modeler batch, checks if the run is complete and starts the postprocess phase.

real_cost([verbose])

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

run([path, priority])

Run Job all the way through and return data.

set_task_name_if_none(values)

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

start([priority])

Start running a Job.

to_file(fname)

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

upload()

Upload this Job.

Inherited Common Usage

simulation#
task_name#
folder_name#
callback_url#
solver_version#
verbose#
simulation_type#
parent_tasks#
task_id_cached#
reduce_simulation#
pay_type#
lazy#
to_file(fname)[source]#

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

Parameters:

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

Example

>>> simulation.to_file(fname='folder/sim.json')
run(path='simulation_data.hdf5', priority=None)[source]#

Run Job all the way through and return data.

Parameters:

  • path (str = "./simulation_data.hdf5") – Path to download results file (.hdf5), including filename.

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

Returns:

Object containing simulation results.

Return type:

WorkflowDataType

property task_id#

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

upload()[source]#

Upload this Job.

get_info()[source]#

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.

property postprocess_status#

Return current postprocess status of Job if it is a Component Modeler.

start(priority=None)[source]#

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.

Note

To monitor progress of the Job, call Job.monitor() after started.

get_run_info()[source]#

Return information about the running Job.

Returns:

Task run information.

Return type:

RunInfo

monitor()[source]#

Monitor progress of running Job.

Note

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

download(path='simulation_data.hdf5')[source]#

Download results of simulation.

Parameters:

path (str = "./simulation_data.hdf5") – Path to download data as .hdf5 file (including filename).

Note

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

load(path='simulation_data.hdf5')[source]#

Download job results and load them into a data object.

Parameters:

path (str = "./simulation_data.hdf5") – Path to download data as .hdf5 file (including filename).

Returns:

Object containing simulation results.

Return type:

Union[SimulationData, HeatSimulationData, EMESimulationData]

delete()[source]#

Delete server-side data associated with Job.

real_cost(verbose=True)[source]#

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.

Return type:

float

estimate_cost(verbose=True)[source]#

Compute the maximum FlexCredit charge for a given Job.

Parameters:

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

Returns:

Estimated cost of the task in FlexCredits.

Return type:

float

Note

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

postprocess_start(worker_group=None, verbose=True)[source]#

If the job is a modeler batch, checks if the run is complete and starts the postprocess phase.

This function does not wait for postprocessing to finish and is only applicable to Component Modeler batch jobs.

Parameters:

  • worker_group (Optional[str] = None) – The specific worker group to run the postprocessing task on.

  • verbose (bool = True) – Whether to print info messages. This overrides the Job’s ‘verbose’ setting for this call.

classmethod set_task_name_if_none(values)[source]#

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

__hash__()#

Hash method.