AMSRun¶

The scm.amsrun package and the amsrun command let you work with AMSjobs queue definitions and job files from a terminal or from Python.

They use the same queue definitions and run conventions as AMSjobs. This means that you can inspect, submit, follow, cancel, fetch, and clean up the same jobs from the GUI, from the CLI, or from Python.

For most users, amsrun is the main entry point.

Note

Python scripts and Jupyter notebooks will be executed using amspython

Quick Start from a Shell¶

List your configured queues:

amsrun queue list

Check that a queue is configured correctly:

amsrun queue test Sequential

Submit a job to a given queue:

amsrun submit MyJob --queue MyQueue

Check the status of jobs in the current directory:

amsrun list

Typical Local Workflow¶

Given a simple bash script called test.sh which you would like to run:

#!/bin/bash
# test.sh

for i in {1..20}
do
    echo "Progress $i/20"
    sleep 1
done

Use amsrun submit --queue to choose a queue and submit the job:

amsrun submit test --queue Sequential

The progress of the job can be monitored in real time with amsrun follow. The default followed stream is the AMSjobs logfile. To follow standard output instead:

amsrun follow test --stream out

The status of all the jobs in the directory can be monitored with amsrun list --watch:

amsrun list --watch

If the job already has runtime files from a previous run, amsrun submit refuses to overwrite them. Use --force when you intentionally want to rerun the job in place.

amsrun submit test --queue Sequential --force

If you need to stop the job:

amsrun cancel test

Remove temporary helper artifacts after the job is done:

amsrun cleanup test

Remove local job artifacts and results while keeping the source script:

amsrun remove test

Use --hard if the .run, .sh, .py, or .ipynb source file should be removed as well.

Typical Remote Workflow¶

For remote queues, given the same test.sh script, similarly use amsrun submit --queue to choose a queue and submit a job:

amsrun submit test --queue MyRemoteQueue

If the selected queue uses $options in its run command, you can override the per-job options value at submit time:

amsrun submit test --queue MyRemoteQueue --options 32

The progress of the job can be monitored in real time with amsrun follow. When the job is complete, the results will automatically be fetched from the remote:

amsrun follow test --stream out

The status of all the jobs in the directory can be monitored with amsrun list --watch --fetch. Note the --fetch argument is needed if you wish the status of running remote jobs to be updated automatically.

amsrun list --watch --fetch

All job files can also be manually copied back using amsrun fetch:

amsrun fetch test

Or a subset using an rsync-style selector:

amsrun fetch test --selector ".results/**"

To clean up all files on the remote side:

amsrun cleanup test remote

To clean up both local helper artifacts and the remote working directory:

amsrun cleanup test all

Queue Management¶

Queue definitions are stored in the AMS GUI preferences directory and can also be managed from the shell.

Use amsrun queue create --from-template to create a new queue definition from a template:

amsrun queue create MyQueue --from-template SLURM

Or amsrun queue create --from to copy an existing queue:

amsrun queue create MyQueue2 --from MyQueue

The definition of a queue can be displayed using amsrun queue show:

amsrun queue show MyQueue2

Specific fields on the queue definition can then be modified using amsrun queue set:

amsrun queue set MyQueue2 hostname cluster.example.org

The queue file can be directly edited using amsrun queue edit:

amsrun queue edit MyQueue2

Finally, a queue can be deleted with amsrun queue remove:

amsrun queue remove MyQueue2

Job Discovery and Housekeeping¶

Discover runnable jobs under a directory use amsrun list:

amsrun list
amsrun list --recursive
amsrun list --status queued
amsrun list --recent
amsrun list --recursive --recent 12

Show running jobs tracked in the local AMSjobs joblist:

amsrun list --all --status running
amsrun list --all
amsrun list --all --recent 12 --limit 20
amsrun list --all --status running --watch

Environment and File Conventions¶

scm.amsrun expects the same basic setup as AMSjobs:

AMSHOME should point to the AMS installation or source tree so the package can find queue templates and GUI helper scripts.
queue definitions are read from the normal AMS GUI preferences directory, or from SCM_GUIPREFSDIR if you override it.
remote execution uses the configured SSH and rsync preferences from .scm_guirc when they are present.
set SCM_REQUIRE_SSH_MULTIPLEXING=1 to make remote SSH operations fail instead of falling back to non-multiplexed SSH when a master connection cannot be started.

amsrun list shows both Type and AMS Type. Type is the runnable source format: run, sh, python, or ipynb. AMS Type is the AMS engine or workflow type, such as adf, band, params, cosmo, or bee. For Python scripts and notebooks this is unknown unless explicit job metadata identifies an AMS job type.

JOB may be a job root path, or a .run, .sh, .py, .ipynb, or .pid path. For example, these selectors all refer to the same job:

amsrun fetch test .out
amsrun fetch test.run .out
amsrun fetch test.pid .out

Cloud queues are not currently supported by scm.amsrun.

The same job files will be produced as in AMSjobs. For example, submitting a job called dftb_go will produce the files:

├── dftb_go.err
├── dftb_go.info
├── dftb_go.job
├── dftb_go.logfile
├── dftb_go.out
├── dftb_go.pid
├── dftb_go.results
│  ├── ams.rkf
│  ├── dftb.rkf
│  └── output.xyz
├── dftb_go.run

The output and log files will be in the top level directory and the results in a <JOB>.results directory. Note that for Jupyter notebooks, the completed copy of the notebook with the cell outputs will be in the results directory.

Python Usage¶

If you want to script the same tasks from Python, use scm.amsrun.AMSRun as the friendly single entry point.

The supported public entry points are exported directly from scm.amsrun:

from scm.amsrun import AMSRun, Jobs, Queues

For most scripts, use:

scm.amsrun.AMSRun as the main entry point mirroring the CLI job verbs
scm.amsrun.Queues through runner.queues for queue definitions, queue status, dynamic sync, and queue tests
scm.amsrun.Jobs through runner.jobs for lower-level job loading, discovery, transfer, and housekeeping

AMSRun forwards the most common job operations:

AMSRun.submit()
AMSRun.set_queue()
AMSRun.follow()
AMSRun.cancel()
AMSRun.fetch()
AMSRun.push()
AMSRun.cleanup()
AMSRun.remove()
AMSRun.list()

Note

scm.amsrun does not replace PLAMS. PLAMS is the higher-level workflow library for constructing and running AMS jobs from Python. scm.amsrun focuses on AMSjobs-style queues, job records, and remote file handling.

Example: Create and Test a Queue¶

This example creates a queue from a built-in template, updates a few fields, shows the configured queues, and prints the resulting queue definition:

Queue templates can use $options for the full options string, $options[0] for the first positional option, and $options[name] for a named option value.

from scm.amsrun import AMSRun

runner = AMSRun()

print(runner.queues.list())

my_slurm_queue = runner.queues.create("MySlurmQueue", template="SLURM")

my_slurm_queue = runner.queues.update(
   my_slurm_queue,
   host_name="cluster.example.org",
   user_name="me",
   prolog="module load ams",
   run_cmd='sbatch $options "$job"',
)

print(my_slurm_queue.format())

runner.queues.test(my_slurm_queue, jobs=runner.jobs)

Example: Submit and Follow a Job¶

This example finds a job, assigns a queue, submits it, follows it, and fetches selected files:

from pathlib import Path

from scm.amsrun import AMSRun

runner = AMSRun()

job = runner.jobs.get("test", root=Path("."))

print(runner.jobs.show(job))

job = runner.submit(job, queue="MySlurmQueue")

for line in runner.follow(job, stream="logfile"):
   print(line)

runner.fetch(job, [".out", ".logfile", ".results/ams.rkf"])

Python API Reference¶

Convenience facade for the public scm.amsrun API.

AMSRun keeps the explicit manager split available as .jobs and .queues, while forwarding the most common job operations so scripts can use an API shaped like the amsrun command line.

cancel(job: Job | Path | str) → None¶

Cancel one queued or running job.

Parameters:: job – Runtime job object or canonical job root path.
Returns:: None.

cleanup(job: Job | Path | str, scope: str = 'local') → None¶

Clean up local and/or remote helper artifacts for one job.

Parameters:

job – Runtime job object or canonical job root path.
scope – Cleanup scope: local, remote, or all.

Returns:

None.

early_stop(job: Job | Path | str) → Path¶

Request a graceful stop for one running AMS job.

Parameters:: job – Runtime job object or canonical job root path.
Returns:: Local stop-file path that was written.

fetch(job: Job | Path | str, patterns: Sequence[str] = (), *, selector: str = '', **kwargs) → None¶

Download files from a remote job.

Parameters:

job – Runtime job object or canonical job root path.
patterns – Filename patterns or suffixes to transfer.
selector – Optional rsync-style selector string.
kwargs – Additional keyword arguments forwarded to Jobs.fetch().

Returns:

None.

follow(job: Job | Path | str, *, interval: float = 2.0, fetch_on_exit: bool = True, stream: str = 'logfile') → Iterator[str]¶

Follow one job output stream until terminal status.

Parameters:

job – Runtime job object or canonical job root path.
interval – Polling interval in seconds.
fetch_on_exit – Whether remote results should be fetched on terminal status.
stream – Stream to follow: logfile or out.

Returns:

Iterator yielding follow-output lines.

list(path: Path = PosixPath('.'), *, recursive: bool = False, all: bool = False, recent: float | None = None, status: str = 'all', limit: int = 0, fetch: bool = False) → List[Tuple[str, str, str, str, str, str, str]]¶

Return the same rows shown by amsrun list.

Parameters:

path – Root path to scan when all is false.
recursive – Whether to scan recursively below path.
all – Whether to list jobs from the AMSjobs joblist.
recent – Optional recent-job time window in hours.
status – Comma-separated recorded status filter.
limit – Maximum number of rows to return. 0 means unlimited.
fetch – Refresh remote metadata before rendering rows.

Returns:

Rendered job-list rows.

push(job: Job | Path | str, file_paths: Sequence[Path], **kwargs) → None¶

Upload files to a remote job.

Parameters:

job – Runtime job object or canonical job root path.
file_paths – Filesystem paths to upload.
kwargs – Additional keyword arguments forwarded to Jobs.push().

Returns:

None.

remove(job: Job | Path | str, *, keep_source: bool = True) → Sequence[Path]¶

Remove local files and result directories associated with one job.

Parameters:

job – Runtime job object or canonical job root path.
keep_source – Whether .run and .sh source scripts are preserved.

Returns:

Paths that were removed.

Apply a queue to one job using the same selector rules as amsrun set-queue.

Parameters:

job – Runtime job object or canonical job root path.
queue_id – Queue id or unique displayed queue name.
options – Optional queue options override to persist on the job.

Returns:

Updated job snapshot.

Submit one job and return the reloaded job snapshot.

Parameters:

job – Runtime job object or canonical job root path.
queue – Optional queue identifier to apply before submission.
options – Optional submit-time queue options override.
force – Allow overwriting existing runtime artifacts.

Returns:

Reloaded job snapshot after submission.

class Jobs(store: JobStore | None = None, queues: Queues | None = None, amshome: Path | None = None, timeout: float | None = None)¶

Public API for inspecting and operating on AMSjobs-style jobs.

Jobs works directly with the file-backed job state used by AMSjobs: source scripts, .pid records, helper files, and result directories. It is the main lower-level entry point behind AMSRun.

cancel(job_or_root: Job | Path | str) → None¶

Cancel a queued or running job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: None.

cleanup(job_or_root: Job | Path | str, scope: str = 'local') → None¶

Clean up local and/or remote helper artifacts for one job.

Parameters:

job_or_root – Runtime job object or canonical job root path.
scope – Cleanup scope: local, remote, or all.

Returns:

None.

delete_remote(job_or_root: Job | Path | str) → None¶

Delete the remote working directory for one job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: None.

early_stop(job_or_root: Job | Path | str) → Path¶

Request a graceful stop for one running AMS job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: Local stop-file path that was written.

fetch(job_or_root: Job | Path | str, patterns: Sequence[str] = (), *, selector: str = '', **kwargs) → None¶

Download files from a remote job.

Parameters:

job_or_root – Runtime job object or canonical job root path.
patterns – Filename patterns or suffixes to transfer.
selector – Optional rsync-style selector string.
kwargs – Additional keyword arguments forwarded to the underlying helper.

Returns:

None.

follow(job_or_root: Job | Path | str, *, interval: float = 2.0, fetch_on_exit: bool = True, stream: str = 'logfile') → Iterator[str]¶

Follow one job output stream until the job reaches a terminal status.

Parameters:

job_or_root – Runtime job object or canonical job root path.
interval – Polling interval in seconds.
fetch_on_exit – Whether remote result files are fetched at terminal status.
stream – Output stream to follow: logfile or out.

Returns:

Iterator yielding follow-output lines.

get(selector: str | Path, root: str | Path = '.') → Job¶: Find and load one job by selector, relative path, or concrete job-related path.

load(job_root: str | Path) → Job¶

Load one job snapshot from the AMSjobs files on disk.

The returned Job has its queue resolved against the current queue definitions, so stale embedded queue ids can be repaired when possible.

Parameters:: job_root – Canonical AMSjobs job root path.
Returns:: Loaded job snapshot.

logs(job_or_root: Job | Path | str, lines: int = 200) → str¶

Return trailing logfile text for one job.

For remote jobs, this may fetch the logfile first when the local copy is missing.

Parameters:

job_or_root – Runtime job object or canonical job root path.
lines – Number of trailing logfile lines to return.

Returns:

Trailing logfile text, including a final newline when non-empty.

monitor(job_or_root: Job | Path | str, append_local_pid_status: bool = False) → Iterator[str]¶

Stream monitor output for one job.

Parameters:

job_or_root – Runtime job object or canonical job root path.
append_local_pid_status – Whether remote status lines should be appended to the local .pid file.

Returns:

Iterator yielding monitor output lines.

push(job_or_root: Job | Path | str, file_paths: Sequence[Path], **kwargs) → None¶

Upload files to a remote job.

Parameters:

job_or_root – Runtime job object or canonical job root path.
file_paths – Filesystem paths to upload.
kwargs – Additional keyword arguments forwarded to the underlying helper.

Returns:

None.

refresh_remote(job_or_root: Job | Path | str, *, stream: str = 'logfile') → Job¶

Refresh lightweight local metadata for one remote job.

This updates the local snapshot from remote .pid / .jid files and one output stream, then reloads the job from disk.

Parameters:

job_or_root – Runtime job object or canonical job root path.
stream – Preferred stream to refresh: logfile or out.

Returns:

Reloaded job snapshot after refresh.

remote_dir(job_or_root: Job | Path | str) → str¶

Return the effective local or remote working directory for one job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: Effective local or remote working directory.

remote_prefix(job_or_root: Job | Path | str) → str¶

Return the remote SCM_ROOT prefix used for one job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: Remote SCM_ROOT prefix used for one job.

remove(job_or_root: Job | Path | str, *, keep_source: bool = True) → List[Path]¶

Delete local files and result directories associated with one job.

Parameters:

job_or_root – Runtime job object or canonical job root path.
keep_source – Whether .run and .sh source scripts are preserved.

Returns:

Paths that were deleted.

save(job: Job) → Path¶

Persist one job snapshot back to its .pid file.

Parameters:: job – Runtime job instance.
Returns:: Path to the written .pid file.

Apply a named queue to a job and return the updated snapshot.

Parameters:

job_or_root – Runtime job object or job selector.
queue – Queue id or unique displayed queue name.
options – Optional queue options override to persist on the job.

Returns:

Updated job snapshot after the queue change.

show(job_or_root: Job | Path | str) → str¶

Return a human-readable multi-line summary for one job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: Summary text suitable for CLI or logging output.

status(job_or_root: Job | Path | str) → str¶

Return the current recorded status string for one job.

Parameters:: job_or_root – Runtime job object or canonical job root path.
Returns:: Recorded job status string.

Submit one job for local or remote execution.

Parameters:

job_or_root – Runtime job object or canonical job root path.
queue – Optional queue identifier to apply before submission.
options – Optional submit-time queue options override.
force – Allow overwriting existing runtime artifacts.

Returns:

Reloaded job snapshot after submission.

class Queues(store: QueueStore | None = None, amshome: Path | None = None)¶

Public API for loading, editing, and testing AMSjobs-style queue definitions.

Queues operates on .tid files in the configured queue store and exposes both low-level queue-definition methods and CLI-shaped helper methods such as list(), show(), and test().

create(name: str, *, display_name: str | None = None, template: str | None = None, source: str | Queue | None = None) → Queue¶

Create and save a new queue definition.

Parameters:

name – Canonical queue identifier for the new queue.
display_name – Optional displayed queue name written into the definition.
template – Optional built-in template name to copy from.
source – Optional existing queue id or object to copy from.

Returns:

Newly created queue snapshot.

default() → str¶

Resolve the default runnable queue id using GUI preference rules.

Returns:: Canonical queue id of the default runnable queue, or "" when none exist.

edit(queue: str | Queue, editor: str | None = None) → Queue¶

Open a queue’s backing file in an editor and re-validate it afterwards.

Parameters:

queue – Canonical queue identifier or queue object.
editor – Explicit editor command to use.

Returns:

Reloaded queue snapshot after editing.

get(queue: str | Queue) → Queue¶

Return one valid queue selected by canonical id or queue object.

Parameters:: queue – Canonical queue identifier or queue object.
Returns:: Matching queue snapshot.

list(queue_type: str = 'configured') → List[Tuple[str, str]]¶

Return the same queue-list rows shown by amsrun queue list.

Parameters:: queue_type – Queue type filter used by the CLI.
Returns:: Queue-list rows as (name, type) tuples.

classmethod queue_matches_type(queue: Queue | InvalidQueue, queue_type: str) → bool¶: Return whether one queue row should be shown for a type filter.

static queue_type_name(queue: Queue | InvalidQueue) → str¶: Return the queue type label shown by amsrun queue list.

remove(queue: str | Queue) → Path¶

Remove one configured queue definition.

Parameters:: queue – Canonical queue identifier or queue object.
Returns:: Path of the removed queue-definition file.

rename(queue: str | Queue, new_id: str, *, name: str | None = None) → Queue¶

Rename one queue id and optionally its user-facing name.

Parameters:

queue – Canonical queue identifier or queue object.
new_id – Canonical identifier for the new target.
name – Optional new displayed name to write into the definition.

Returns:

Renamed queue snapshot.

reset(queue: str | Queue, *field_names: str) → Queue¶

Reset queue fields to their default serialized values.

Parameters:

queue – Canonical queue identifier or queue object.
field_names – Public field names to reset.

Returns:

Updated queue snapshot.

resolve(selector: str, *, allow_invalid: bool = False) → str¶

Resolve a queue selector to a canonical queue id.

Selectors may be canonical ids or unique displayed queue names. Invalid queue definitions are only considered when allow_invalid is true.

Parameters:

selector – Queue id or unique displayed queue name.
allow_invalid – Whether invalid queue files are eligible matches.

Returns:

Canonical queue id.

set(name: str | Queue, field: str, value: str) → Queue¶

Update one queue field using amsrun queue set selector rules.

Parameters:

name – Queue id, unique displayed queue name, or queue object.
field – Public queue field name.
value – New field value.

Returns:

Updated queue snapshot.

show(name: str | Queue) → List[Tuple[str, str]]¶

Return the same field/value rows shown by amsrun queue show.

Parameters:: name – Queue id, unique displayed queue name, or queue object.
Returns:: Queue field/value rows.

status() → str¶

Collect and format system status output for all runnable queues.

Returns:: Human-readable multi-queue status report.

sync_dynamic() → None¶

Refresh dynamically discovered queue files from configured remote hosts.

This removes previously synchronized remote queue files and replaces them with the latest definitions discovered on the configured hosts.

Returns:: None.

test(queue: str | Queue, *, jobs: Jobs | None = None, keep_workdir: bool = False, timeout: float = 120.0, progress_callback=None, verbose: bool = False)¶

Exercise one queue with the built-in queue test workflow.

Parameters:

queue – Canonical queue identifier or queue object.
jobs – Optional Jobs instance used for queue test operations.
keep_workdir – Whether to keep the temporary working directory on completion.
timeout – Maximum time in seconds to wait for each test phase.
progress_callback – Optional callback that receives progress messages.
verbose – Print progress messages to stdout when no callback is provided.

Returns:

Queue test report object.

unset(name: str | Queue, field: str) → Queue¶

Reset one queue field using amsrun queue unset selector rules.

Parameters:

name – Queue id, unique displayed queue name, or queue object.
field – Public queue field name to reset.

Returns:

Updated queue snapshot.

update(queue: str | Queue, **changes: str) → Queue¶

Update one queue using public queue field names.

Parameters:

queue – Canonical queue identifier or queue object.
changes – Public field updates keyed by field name.

Returns:

Updated queue snapshot.

AMSRun¶

Quick Start from a Shell¶

Typical Local Workflow¶

Typical Remote Workflow¶

Queue Management¶

Job Discovery and Housekeeping¶

Environment and File Conventions¶

Python Usage¶

Example: Create and Test a Queue¶

Example: Submit and Follow a Job¶

Python API Reference¶

See also¶