autojob.utils package

Miscellaneous autojob utility functions.

autojob.utils.alphanum_key(val: str) → tuple[str, bool | float | int | str | None]

Provides key to alphanumerically sort primitive types.

Parameters:

val – String representation of object for which to provide key.

Raises:

TypeError – The type of ‘val’ is invalid.

Returns:

A 2-tuple where the first element is a string indicating the type of the value (e.g., n = number, b = boolean, N = None, s = string) and the second element is the value.

Note

Numbers are converted to floats.

autojob.utils.alphanum_sort(vals: Iterable[str]) → list[str]

Alphanumerically sorts an iterable of strings.

Parameters:

vals – an iterable to be sorted.

Returns:

Alphanumerically sorted copy of vals.

autojob.utils.get_slurm_job_id(job_dir: Path) → int

Returns the SLURM job id for the job run in the directory “job_dir”.

Parameters:

job_dir – The directory containing the slurm output file.

Raises:

FileNotFoundError – SLURM output file not found.

Returns:

The SLURM job id.

autojob.utils.get_uri(dir_name: str | Path) → str

Return the URI path for a directory.

This allows files hosted on different file servers to have distinct locations.

Adapted from Atomate2.

Arg:

dir_name: A directory name.

Returns:

Full URI path, e.g., “fileserver.host.com – /full/path/of/dir_name”.

autojob.utils.iter_to_native(vals: Iterable[float | int | str | None]) → Iterable[float | int | str | None]

Converts values within an Iterable to their native types.

Parameters:

vals – an iterable of values to convert.

Returns:

Iterable – A shallow copy of the converted iterable.

Example

>>> from autojob.utils import iter_to_native
>>> iter_to_native(["0.1", "None", "-1", "dog"])
[0.1, None, -1, 'dog']

autojob.utils.parse_job_stats_file(dir_name: Path) → dict[str, float | int | str]

Parse a job stats file.

Parameters:

dir_name – Path to the job stats file.

Returns:

A dictionary mapping job stats to their values.

autojob.utils.val_to_native(val: float | int | str | None) → bool | float | int | str | None

Converts string representations to their native types.

Only floats, ints, or strings are supported.

Parameters:

val – a value to be converted.

Returns:

The value converted into a PRIMITIVE_TYPE.

Submodules

autojob.utils.atoms module

Utilities for manipulating Atoms objects.

autojob.utils.atoms.copy_atom_metadata(input_atoms: Atoms | None, output_atoms: Atoms) → None

Copy tags, constraints, and info from the input to output atoms.

This function modifies output_atoms in place.

Parameters:

• input_atoms – An ase.atoms.Atoms object.

• output_atoms – An ase.atoms.Atoms object.

autojob.utils.cli module

Utilities for CLI functions.

class autojob.utils.cli.MemoryFloat

Bases: ParamType

A float representing an amount of memory.

convert(value: str | float, param, ctx) → float

Convert a memory specification into bytes.

name: ClassVar[str] = 'memory float'

the descriptive name of this type

autojob.utils.cli.configure_settings(config: dict[str, Any]) → None

Set redefine autojob settings.

Parameters:

config – A dictionary mapping autojob settings names to their desired values.

autojob.utils.cli.construct_cli_call(allowed: list[str] | None = None) → str

Construct the original CLI call.

Parameters:

allowed – A list of strings indicating which parameters are to be considered to reconstruct the CLI call.

Returns:

A string representing the command-line call that would produce the present behaviour.

autojob.utils.cli.mods_to_dict(_: Any, param: str, value: Iterable[str]) → dict[str, Any]

Convert an iterable of key-value pairs to a dictionary.

Parameters:

• _ – The first argument is ignored but retained for click compatibility.

• param – The name of the parameter being set (e.g., calc_mods or slurm_mods).

• value – An iterable of key-value pairs should exist as a string in the form “key=value”. Note that only those values supported by ~validation.val_to_native can be correctly parsed.

Returns:

A dictionary mapping calculator parameter names to their Python values.

autojob.utils.files module

Utilities for handling files and directories.

autojob.utils.files.check_job_status(job_id: int) → str

Determine the status of a SLURM job.

Parameters:

job_id – The Slurm job ID.

Returns:

A string indicating the job status.

autojob.utils.files.copy_permissions_and_ownership(src: Path, dest: Path) → None

Copy file permissions and ownership bits.

Parameters:

• src – The file/directory whose permissions and ownership are to be copied.

• dest – The file/directory whose permissions and ownership are to be changed.

autojob.utils.files.create_job_stats_file(slurm_job_id: int, job_dir: str | Path) → Path

Creates file containing statistics from completed Slurm job.

Parameters:

• slurm_job_id – The Slurm job ID for the job.

• job_dir – The job directory.

Raises:

RuntimeError – Unable to create job stats file.

Returns:

A Path to the file containing the job statistics.

autojob.utils.files.find_finished_jobs(path: Path | None = None) → list[Path]

Find the directories and subdirectories containing finished jobs.

These jobs may have terminated due to errors, but they are no longer running.

Parameters:

path – The directory in which to search. Defaults to None (in which case the current working directory is searched).

Returns:

A list of Paths pointing to directories containing jobs that have finished.

autojob.utils.files.find_last_submitted_jobs(path: Path | None = None, ignore_unrun_jobs: bool = False) → list[Path]

Returns the directories of the most recently submitted jobs.

Only the directories in each calculation specified in “path” or subdirectories of “path” are returned.

Parameters:

• path – The directory specifying or containing calculations. Defaults to current working directory.

• ignore_unrun_jobs – If true, no job will be reported for calculation directories containing jobs that have yet been run. Otherwise, the most recently submitted job will be reported. Defaults to False.

Returns:

A list of Paths to directories containing newest jobs for each calculation in path or subdirectories of path.

autojob.utils.files.find_study_dirs(path: Path | None = None) → list[Path]

Find all study directories in the directory tree below path.

Parameters:

path – Top level directory to be searched. Defaults to current working directory.

autojob.utils.files.find_study_group_dirs(path: Path | None = None) → list[Path]

Find all study group directories in the directory tree below path.

Parameters:

path – Top level directory to be searched. Defaults to current working directory.

autojob.utils.files.find_task_dirs(path: Path | None = None) → list[Path]

Find all task directories in the directory tree below path.

Parameters:

path – Top level directory to be searched. Defaults to current working directory.

autojob.utils.files.find_task_group_dirs(path: Path | None = None) → list[Path]

Find all task group directories in the directory tree below path.

Parameters:

path – Top level directory to be searched. Defaults to current working directory.

autojob.utils.files.get_last_updated(dir_name: Path) → datetime

Get the date and time of the last updated file in a directory.

Parameters:

dir_name – The directory in which to search.

Returns:

A datetime object representing the last time a file in the directory was updated. If dir_name is empty, then the last time that dir_name was updated is returned.

autojob.utils.files.get_loader() → BaseLoader

Return the Jinja template loader.

autojob.utils.files.get_slurm_job_id(job_dir: Path) → int

Returns the SLURM job id for the job run in the directory “job_dir”.

Parameters:

job_dir – The directory containing the slurm output file.

Raises:

FileNotFoundError – SLURM output file not found.

Returns:

The SLURM job id.

autojob.utils.files.get_uri(dir_name: str | Path) → str

Return the URI path for a directory.

This allows files hosted on different file servers to have distinct locations.

Adapted from Atomate2.

Arg:

dir_name: A directory name.

Returns:

Full URI path, e.g., “fileserver.host.com – /full/path/of/dir_name”.

autojob.utils.files.template_script(dest: Path, *, scheduler_script_template: str = 'run.sh.j2', context: dict[str, Any]) → Path

Write the input script using the template given.

Parameters:

• dest – The filename to write.

• scheduler_script_template – The template file to use. Defaults to SETTINGS.SCHEDULER_SCRIPT_TEMPLATE.

• context – A dictionary containing context variables which will be passed to to jinja2.environment.Template.render().

autojob.utils.parsing module

Utilities for parsing data.

class autojob.utils.parsing.TimedeltaTuple(days: int = 0, hours: int = 0, minutes: int = 0, seconds: int = 0)

Bases: NamedTuple

Convenience wrapper around a timedelta object.

Create new instance of TimedeltaTuple(days, hours, minutes, seconds)

days: int

Alias for field number 0

static format_time(time_denomination: int) → str

Format time into a 0-padded integer.

classmethod from_slurm_time(time: str) → TimedeltaTuple

Parses a valid slurm time value into a TimedeltaTuple.

The six formats accepted by Slurm are:

1: minutes

2: minutes:seconds

3: hours:minutes:seconds

4: days-hours

5: days-hours:minutes

6: days-hours:minutes:seconds

Parameters:

time – the string containing the value of the –time slurm option

Raises:

ValueError – The string is not a valid value of the slurm –time option. See https://slurm.schedmd.com/sbatch.html for details.

Returns:

A TimedeltaTuple.

classmethod from_string(string: str, time_format: Literal['iso', 'slurm'] = 'slurm') → TimedeltaTuple

Return a TimedeltaTuple from a string.

Parameters:

• string – the time string to parse.

• time_format – One of “iso” or “slurm”. Determines how the time string is parsed.

Returns:

A TimedeltaTuple.

classmethod from_timedelta(delta: timedelta) → TimedeltaTuple

Break a timedelta instance into days, hours, minutes, and seconds.

Parameters:

delta – a timedelta instance.

Returns:

A 4-tuple of ints – days, hours, minutes, seconds

hours: int

Alias for field number 1

minutes: int

Alias for field number 2

seconds: int

Alias for field number 3

to_slurm_time() → str

Convert TimedeltaTuple into a SLURM-compatible time format.

to_timedelta() → timedelta

Convert a TimedeltaTuple to a timedelta instance.

autojob.utils.parsing.parse_job_stats_file(dir_name: Path) → dict[str, float | int | str]

Parse a job stats file.

Parameters:

dir_name – Path to the job stats file.

Returns:

A dictionary mapping job stats to their values.

autojob.utils.schemas module

Pydantic schema utilities.

pydantic model autojob.utils.schemas.AtomsAnnotation

Bases: BaseModel

The Pydantic-compatible annotation for an ase.atoms.Atoms object.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Show JSON schema

{
   "type": "object"
}

autojob.utils.schemas.atoms_as_dict(s: Atoms) → dict[str, str]

Represent an ase.atoms.Atoms object as a dictionary.

autojob.utils.schemas.atoms_from_dict(d: dict[str, Any]) → Atoms

Instantiate an ase.atoms.Atoms object from a dictionary.

autojob.utils.schemas.hyphenate(v: str) → str

Replace underscores with hyphens.

autojob.utils.schemas.id_factory(prefix: str) → Callable[[], Annotated[UUID, UuidVersion(uuid_version=4)] | str]

Create a default ID factory based on whether legacy mode is enabled.

autojob.utils.schemas.space_capitalize(v: str) → str

Replace underscores with spaces and capitalize each word.

autojob.utils.templates module

Utilities for templating strings.

autojob.utils.templates.substitute_placeholders(templated_value: str, /, **kwargs) → str

Subtitute values for placeholders.

Parameters:

• templated_value – The templated value.

• kwargs – Each keyword should be a valid Python identifier and the corresponding value is its replacement. Keywords will be converted by replacing hyphens with underscores.

Returns:

The original string with placeholders substituted.

Example:

>>> import pathlib
>>> from autojob.next.relaxation import substitute_placeholders

>>> substitute_placeholders(
        "This is the job id: {job_id}",
        job_id="j123456789",
    )
This is the job id: j123456789

autojob.utils.vasp module

VASP utilities.

autojob.utils.vasp.reorder_vasp_sequence(to_reorder: Iterable[_T], dir_name: str | Path, *, direction: Literal['to_ase', 'to_vasp'] = 'to_ase') → list[_T]

Reorder a sequence to/from a VASP ordering from/to an ASE ordering.