tidy3d.web.api.container.Job

class Job

Bases: WebContainer

Interface for managing the running of a Simulation on server.

Parameters:

• simulation (Attribute: simulation) –

  Type	Union[Simulation, HeatSimulation]
  Default
  Description	Simulation to run as a ‘task’.

• task_name (Attribute: task_name) –

  Type	str
  Default
  Description	Unique name of the task.

• folder_name (Attribute: folder_name) –

  Type	str
  Default	= default
  Description	Name of folder to store task on web UI.

• callback_url (Attribute: callback_url) –

  Type	Optional[str]
  Default	= None
  Description	Http PUT url to receive simulation finish event. The body content is a json file with fields {'id', 'status', 'name', 'workUnit', 'solverVersion'}.

• solver_version (Attribute: solver_version) –

  Type	Optional[str]
  Default	= None

• verbose (Attribute: verbose) –

  Type	bool
  Default	= True
  Description	Whether to print info messages and progressbars.

• simulation_type (Attribute: simulation_type) –

  Type	str
  Default	= tidy3d
  Description	Type of simulation, used internally only.

• parent_tasks (Attribute: parent_tasks) –

  Type	Optional[Tuple[str, …]]
  Default	= None
  Description	Tuple of parent task ids, used internally only.

• task_id (Attribute: task_id) –

  Type	Optional[str]
  Default	= None
  Description	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

• Running simulations through the cloud

• Performing parallel / batch processing of simulations

• Inverse taper edge coupler

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.

simulation

task_name

folder_name

callback_url

solver_version

verbose

simulation_type

parent_tasks

task_id

run(path='simulation_data.hdf5')

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()

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()

Start running a Job.

Note

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

get_run_info()

Return information about the running Job.

Returns:

Task run information.

Return type:

RunInfo

monitor()

Monitor progress of running Job.

Note

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

download(path='simulation_data.hdf5')

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')

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()

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.

Return type:

float

estimate_cost(verbose=True)

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.