Usage¶

Enable Shell Completion¶

Shell completion is supported for the bash, zsh, and fish shells. Shell completion can be enabled by running autojob init and then restarting your shell.

CLI Commands¶

advance¶

Advance to the next task in a workflow.

Usage

advance [OPTIONS]

Options

-v, --verbose¶

Controls the verbosity. 0: Show messages of level warning and higher. 1: Show messages of level info and higher. 2: Show all messages-useful for debugging.

Default:: 0

-S, --submit, --no-submit¶

Whether or not to submit the newly created job.

Default:: False

--file-size-limit <MEM>¶

Specify the file size above which all files in the old job larger than this will be deleted. Integers will be interpreted in bytes. The suffixes, KB, MB, and GB, will cause the value to be interpreted as kilobytes, megabytes, and gigabytes, respectively.

Default:: inf

--config <config>¶: Configure autojob parameters (e.g., –config=”log_file=autojob.log”). This option can be repeated.

-p, --path <paths>¶: The path from which to create new job directories. This option can be repeated. Defaults to the current working directory.

-R, --recursive, ---no-recursive¶

Whether to search all subdirectories for jobs to restart in addition to those specified by the –path option.

Default:: False

--name-template <name_template>¶: A naming scheme to use for the restarted task directory. This can be a templated string-available fields include ‘structure’ and any task metadata.

EXAMPLES¶

Submit the next task upon creation.

autojob advance -S

config-gen¶

Generate a configuration file from autojob defaults.

Usage

config-gen [OPTIONS]

Options

--sort, --no-sort¶

Whether or not to sort configuration keys

Default:: False

coordinator¶

Runs the GUI for ‘Coordinator’.

This is a graphical user interface that enables you to design arbitrarily large studies which are parametrized with respect to input structures, any input variable for an ASE calculator, or even SLURM parameter.

Args:: template: a previously configured study group, study, calculation, or job with which to populate the GUI. Defaults to None.

Usage

coordinator [OPTIONS] [TEMPLATE] COMMAND [ARGS]...

Options

--template-dir <template_dir>¶: The directory from which to pull script templates. If not specified, autojob will use its own templates.

--dest <dest>¶: The root directory for study group creation.

Arguments

TEMPLATE¶: Optional argument

harvest¶

Harvest completed tasks from a directory.

Usage

harvest [OPTIONS] COMMAND [ARGS]...

Options

--path <dir_name>¶

--stem <stem>¶: The file stem to use to name the harvested data file.

--dest <dest>¶: The directory in which to save the archives.

--archive-mode <archive_mode>¶

The mode with which to archive the harvested tasks.

Options:: csv | json | both

--strict¶: Errors will immediately halt execution.

--relaxed¶: Every attempt will be made to harvest data from every directory. Incomplete data does not cause execution to halt.

--atomic¶: Only jobs for which no errors are thrown during harvesting will be harvested.

--use-cache, --no-use-cache¶: Whether or not to use cached results. If True, then cached results will be ignored and overwritten. Otherwise, outputs will be read from an existing cache.

--time-stamp, --no-time-stamp¶

Whether or not to time stamp the archived file.

Default:: False

--whitelist <whitelists>¶: Specify an exclusive list of jobs to harvest. Whitelists will be combined.

--blacklist <blacklists>¶: Specify a list of jobs not to harvest. Blacklists will be combined. When specified with –whitelist, –blacklist will take a higher priority.

init¶

Enable tab completion and create the autojob home directory.

Usage

init [OPTIONS]

new¶

Create new study group, study, task group, and task directories.

Usage

new [OPTIONS]

Options

-v, --verbose¶

Controls the verbosity. 0: Show messages of level warning and higher. 1: Show messages of level info and higher. 2: Show all messages-useful for debugging.

Default:: 0

--type <to_create>¶

The type of directory to create anew.

Default:: 'task'
Options:: task | task_group | study | study_group

-d, --dest <dest>¶: The parent of the new task directory.

--config <config>¶: Configure autojob configuration settings (e.g., –config=”log_file=autojob.log”). This option can be repeated.

-n, --name-template <name_template>¶: A naming scheme to use for the restarted task directory. This can be a templated string-available fields include ‘structure’ and any task metadata.

EXAMPLES¶

Create a new task directory as a sibling of the current working directory. The new task directory will be named identically to the present directory save for an index for uniqueness.

autojob new -d ../ -n calc

Template task directories with task metadata.

autojob new -d ../ -n ‘{label}-{task_id}’

Template task directories with Atoms object metadata.

autojob new -d ../ -n ‘{structure}’

restart¶

Restart a task.

Usage

restart [OPTIONS]

Options

-v, --verbose¶

Controls the verbosity. 0: Show messages of level warning and higher. 1: Show messages of level info and higher. 2: Show all messages-useful for debugging.

Default:: 0

-S, --submit, --no-submit¶

Whether or not to submit the newly created job.

Default:: False

--file-size-limit <MEM>¶

Default:: inf

-a, --auto-restart, --no-auto-restart¶

Whether or not to add logic to vasp.sh to automatically resubmit a job on time out.

Default:: False

-c, --calc-mod <MOD>¶: Specify modifications to calculator parameters. Modifications must be passed as quoted parameter-value strings separated by an equals sign (e.g., “parameter=value”). Values (even strings) must be specified without additional quotations as they will be parsed into native Python types. Values can only be parsed into integers, floats, strings, booleans, or None. This option can be repeated.

-L, --sched-mod <MOD>¶: Specify modifications to scheduler parameters. Modifications must be passed as quoted parameter-value strings separated by an equals sign (e.g., “parameter=value”). Values must be passed exactly as they should be passed to the scheduler (e.g., “mem=10GB”), and format strings may be used to substitute select parameters. Variables that may be substituted include the structure filename, the study group, study, calculation, or job ID. However, the use of placeholders is currentlyonly supported for the job-name SLURM option. This option may be repeated.

--config <config>¶: Configure autojob configuration settings (e.g., –config=”log_file=autojob.log”). This option can be repeated.

--carry-over <files_to_carry_over>¶

Indicate a file to copy from the directory of the completed job to the directory of the new job. This option can be repeated.

Default:

-p, --path <paths>¶: The path from which to create new job directories. This option can be repeated. Defaults to the current working directory.

-R, --recursive, ---no-recursive¶

Whether to search all subdirectories for jobs to restart in addition to those specified by the –path option.

Default:: False

--name-template <name_template>¶: A naming scheme to use for the restarted task directory. This can be a templated string-available fields include ‘structure’ and any task metadata.

--strict¶: Any errors incurred while harvesting the previous calculation will immediately halt execution.

--relaxed¶: Every attempt will be made to harvest the previous calculation. Incomplete data does not cause execution to halt.

Warning: When specifying sched_mods, be wary of setting mutually exclusive scheduler parameters (e.g, mem and mem_per_cpu or ntasks and ntasks_per_node). For example, if the “mem” parameter is set and one wants to set the mem_per_cpu parameter, set the “mem” key to None in sched_mods in addition to setting the “mem_per_cpu” key.

But this is unacceptable:

Vasp(atoms)

EXAMPLES¶

Submit the new job upon creation.

autojob restart -S

2. Copy the WAVECAR & CHGCAR, submit the new job upon creation, print out all messages.

autojob restart –carry-over WAVECAR –carry-over CHGCAR -S -vv

3. Submit the new job upon creation, enable auto-restart, print out all messages, delete all files 1 gigabyte or larger, reconfigure the calculator with ediff=1e-8.

autojob restart -Savv –file-size-limit 1GB -c “ediff=1e-8”

4. Submit the new job upon creation, set the job name to the name of the structure file with the suffix “-vib”.

autojob restart -S –sched-mod=”job-name={structure}-vib”

run¶

Run a Python script under a time limit.

This returns with exit code 124 if the time limit is reached and 0 otherwise.

Args:: COMMAND: The command to execute.

Usage

run [OPTIONS] [COMMAND]

Options

-T, --time <_time>¶

The time limit for the job. This takes precedence over the –time-source option.

Default:: Sentinel.UNSET

-t, --time-source <time_source>¶

The file from which to parse the time limit. This is overriden by the –time option.

Default:: Sentinel.UNSET

-b, --buffer <buffer>¶

Specify the time buffer for the task. A value greater than or equal to 0 and less than 1 will be interpreted as the fraction of the total time to use as a buffer. Values greater than or equal to 1 will be interpreted as seconds.

Default:: 0.0

-f, --frequency <frequency>¶

How frequently the process is checked for completion in seconds.

Default:: 30

Arguments

COMMAND¶: Optional argument

EXAMPLES¶

Run a command for 100 seconds.

autojob run –time=100 CMD

Run a command for 1 hour.

autojob run –time=1:00:00 CMD

Run a command for 1 day.

autojob run –time=1-00:00:00 CMD

Run a command. Read the time limit from the file containing the command. A line containing –time=TIME must be present.

autojob run –time-source=run.sh CMD

Run a command for 1 hour with a 10% time buffer.

autojob run –time=1:00:00 –buffer=0.1 CMD

Run a command for 1 hour with a 100 second buffer.

autojob run –time=1:00:00 –buffer=100 CMD