tidy3d.web.api.container.Job#

class Job[source]#

Bases: WebContainer

Interface for managing the running of a Simulation on server.

Parameters:
  • simulation (Union[Simulation, HeatSimulation]) – Simulation to run as a ‘task’.

  • task_name (str) – Unique name of the task.

  • 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) – verbose : bool = True Whether to print info messages and progressbars.

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

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

  • task_id (Optional[str] = None) – Task ID number, set when the task is uploaded, leave as None.

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

status

Return current status of Job.

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.

real_cost([verbose])

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

run([path])

Run Job all the way through and return data.

start()

Start running a Job.

Inherited Common Usage

simulation#
task_name#
folder_name#
callback_url#
solver_version#
verbose#
simulation_type#
parent_tasks#
task_id#
run(path='simulation_data.hdf5')[source]#

Run Job all the way through and return data.

Parameters:

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

Returns:

Object containing simulation results.

Return type:

Union[SimulationData, HeatSimulationData]

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.

start()[source]#

Start running a Job.

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]

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.

__hash__()#

Hash method.