Job control¶
This document describes how to monitor, inspect, cancel and control jobs started on Deep Origin.
Job dataframes¶
View all jobs¶
To view all Jobs on Deep Origin, use:
from deeporigin.tools.job import get_dataframe
df = get_dataframe()
| Column Name | Description |
|---|---|
| id | Job ID, e.g.: 9e9eb45e-93a6-4432-963e-669e982fde62 |
| created_at | Time stamp when Job request was received |
| execution_id | (internal) execution ID. |
| completed_at | Time stamp of when the Job was completed |
| started_at | Time stamp of when the Job was started |
| status | One of Succeeded Cancelled Failed Running or Queued |
| tool_key | Key of tool corresponding to this Job |
| tool_version | Version of tool |
| user_name | Name (or ID) of user that started this job |
| run_duration_minutes | Runtime in minutes, rounded to nearest minute |
View all jobs by Status¶
Only jobs matching certain status(es) can be retrieved. For example,
from deeporigin.tools.job import get_dataframe
df = get_dataframe(only_with_status=["Running"])
only retrieves currently running jobs.
Multiple statuses can be retrieved using a single function call:
from deeporigin.tools.job import get_dataframe
df = get_dataframe(only_with_status=["Running", "Succeeded"])
View Job metadata, inputs and outputs¶
By default, the job dataframe does not include information about metadata, inputs, and outputs. These can be included in the dataframe using:
from deeporigin.tools.job import get_dataframe
df = get_dataframe(
include_metadata=True,
include_inputs=True,
include_outputs=True,
)
Resolve user names¶
By default, user IDs are not resolved to names. To use user names in the dataframe, use:
from deeporigin.tools.job import get_dataframe
df = get_dataframe(
resolve_user_names=True,
)
The Job class¶
The Job class allows you to view jobs on Deep Origin, track and visualize their progress, and cancel them.
Constructing Job objects¶
From Tools¶
Typically, tools will return Job objects when you run them. For example, starting a docking or ABFE run will return a job object:
# here, sim is a Complex
job = sim.docking.run(pocket=pockets[0])
From Job IDs¶
Jobs can also be constructed from one or more Job IDs:
from deeporigin.tools.job import Job
# construct a single job from many IDs
job = Job.from_ids(["...", "..."])
# construct a job from a single ID
job = Job.from_id("job-id")
Inspecting a Job¶
A job can be viewed by simply inspecting it:
job
A widget such as the following will be shown.
Jupyter notebook required
Inspecting jobs using the Job widget requires a Jupyter notebook (or lab). Other interactive environments, such as marimo, are not fully supported yet.
Progress monitoring¶
To monitor the progress of a Job as it proceeds, use:
job.watch()
This causes the widget to auto-update on a fixed timer till the job reaches a terminal state.
To to stop watching, use:
job.stop_watching()
Cancelling jobs¶
To cancel a job, use:
job.cancel()