Attention

This project is still in an early phase of development.

The python API is not yet stable, and some aspects of the schema for the blueprint and workplan will likely evolve. Therefore whilst you are welcome to try out using the package, we cannot yet guarantee backwards compatibility. We expect to reach a more stable version in 2026.

SchedulerJob

class cstar.execution.scheduler_job.SchedulerJob(scheduler: Scheduler, commands: str, account_key: str, cpus: int, nodes: int | None = None, cpus_per_node: int | None = None, script_path: str | Path | None = None, run_path: str | Path | None = None, job_name: str | None = None, output_file: str | Path | None = None, queue_name: str | None = None, send_email: bool | None = True, walltime: str | None = None, depends_on: Iterable[str] = ())

Bases: ExecutionHandler, ABC

Abstract base class for representing a job submitted to a scheduler.

This class defines the structure and common behavior for jobs managed by schedulers such as SLURM and PBS. Subclasses must implement methods for submitting jobs and retrieving job status.

scheduler

The scheduler managing this job (e.g., a SlurmScheduler or PBSScheduler instance)

Type:

Scheduler

commands

The commands to execute within the job script.

Type:

str

account_key

The account key associated with the job for resource tracking.

Type:

str

cpus

The total number of CPUs required for the job.

Type:

int

nodes

The number of nodes to request. If not provided and a specific nodes x cpus distribution is required, C-Star will attempt to calculate an appropriate number of nodes.

Type:

int or None

cpus_per_node

The number of CPUs per node to request. If not provided and a specific nodes x cpus distribution is required, C-Star will attempt to calculate an appropriate number of nodes.

Type:

int or None

script_path

The file path where the job script will be saved.

Type:

Path

run_path

The directory where the job will be executed.

Type:

Path

job_name

The name of the job.

Type:

str

output_file

The file path for job output.

Type:

Path

queue_name

The name of the queue to which the job will be submitted.

Type:

str

queue

The queue object corresponding to queue_name.

Type:

Queue

walltime

The maximum walltime for the job, in the format “HH:MM:SS”.

Type:

str

id

The unique job ID assigned by the scheduler. None if the job has not been submitted.

Type:

int or None

status

A representation of the current status of the job, e.g. RUNNING or CANCELLED

Type:

ExecutionStatus

script

The job script to be submitted to the scheduler.

Type:

str

save_script()

Save the job script to the specified file path.

submit()

Abstract method for submitting the job to the scheduler.

updates(seconds=10)

Stream live updates from the job’s output file for the specified duration.

Methods

SchedulerJob.save_script()	Save the job script to a file.
SchedulerJob.submit()	Submit the job to the scheduler.
SchedulerJob.updates([seconds])	Stream live updates from the task's output file.

Attributes

SchedulerJob.account_key	The account key associated with the job for resource tracking.
SchedulerJob.commands	The commands to execute within the job script.
SchedulerJob.cpus	The total number of CPUs required for the job.
SchedulerJob.cpus_per_node	The number of CPUs per node to request.
SchedulerJob.id	Retrieve the unique job ID assigned by the scheduler.
SchedulerJob.job_name	The name of the job.
SchedulerJob.log	Return the logger instance for this class.
SchedulerJob.nodes	The number of nodes to request.
SchedulerJob.output_file	The file in which to write this job's STDOUT and STDERR.
SchedulerJob.queue	The queue to which the job will be submitted.
SchedulerJob.queue_name	The name of the queue to which the job will be submitted.
SchedulerJob.scheduler	The scheduler managing this job (e.g., a SlurmScheduler or PBSScheduler instance)
SchedulerJob.script	Generate the job script to be submitted to the scheduler.
SchedulerJob.status	Retrieve the current status of the job.
SchedulerJob.walltime	SS`.