autojob.tasks namespace

Submodules

autojob.tasks.calculation module

Store the results of a calculation.

This module defines the Calculation, CalculationInputs, and CalculationOutputs classes. Instances of these classes represent the results of a calculation, its inputs, and its outputs, respectively.

For building the respective documents from a folder, the Calculation and CalculationOutputs classes are PathLoadable.

Example

from autojob.tasks.calculation import Calculation

src = "path/to/calculation/directory"
results = Calculation.from_directory(src)
class autojob.tasks.calculation.Calculation(*, scheduler_inputs: SchedulerInputs = <factory>, scheduler_outputs: SchedulerOutputs | None = None, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, calculation_inputs: CalculationInputs = <factory>, calculation_outputs: CalculationOutputs | None = None, **extra_data: Any)[source]

Bases: Task, ScheduledMixin

A record representing a calculation.

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.

calculation_inputs: CalculationInputs
calculation_outputs: CalculationOutputs | None
classmethod from_directory(src: str | Path, **kwargs) → Self[source]

Generate a Calculation document from a task directory.

Parameters:

  • src – The directory of a calculation.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to fail on any error. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

A Calculation or a subclass of a Calculation.

See also

task.Task.from_directory()

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

static patch_task(*, task_outputs: TaskOutputs | None, input_atoms: Atoms | None, output_atoms: Atoms | None, state: JobState, converged: bool) → None[source]

Patch Task attributes using Calculation values.

Note that this method modifies the Task in place. The following attributes are patched:

  • Task.task_outputs.atoms: replaced with output_atoms with metadata inherited from input_atoms

  • Task.task_inputs.files_to_carryover: replaced with files_to_carry_over

  • Task.task_outputs.outcome: set according to converged and state

Parameters:

  • task_outputs – The TaskOutputs to be patched.

  • input_atoms – An Atoms object representing the input geometry.

  • output_atoms – An Atoms object representing the output geometry.

  • state – The state of the scheduler job.

  • converged – Whether or not the Calculation converged.

prepare_input_atoms() → None[source]

Copy the final magnetic moments to initial magnetic moments.

This function modifies atoms in place. Note that if atoms were obtained from a vasprun.xml via ase.io.read("vasprun.xml"), no magnetic moments will be read. In order to ensure continuity between runs, it is a good idea to retain the WAVECAR between runs.

write_calculation_script(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the calculation script used to run the task.

Parameters:

  • dest – The directory in which to write the Python script.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the calculation inputs that will be written to the calculation script. Defaults to an empty dictionary.

Returns:

A Path object representing the filename of the written calculation script.

write_input_atoms(dest: str | Path) → Path | None[source]

Write the input atoms to a file.

Parameters:

dest – The directory in which to write the Atoms file.

Returns:

The filename in which the Atoms where written.

write_inputs(dest: str | Path, **kwargs) → list[Path][source]

Write the required inputs for a Calculation to a directory.

Parameters:

  • dest – The directory in which to write the inputs.

  • kwargs – Additional keyword arguments.

Returns:

A list of Path objects where each Path represents the filename of an input written to dest.

write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the calculation inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

Returns:

The filename in which the inputs JSON written.

write_task_script(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the SLURM input script using the template given.

Parameters:

  • dest – The directory in which to write the SLURM file.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the task inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

Returns:

A Path representing the filename of the written SLURM script.

class autojob.tasks.calculation.CalculationInputs(*, calculator: str = 'vasp', optimizer: str | None = None, calc_params: dict[str, Any] = {}, opt_params: dict[str, Any] | None = None, analyses: dict[str, tuple[list[Any], dict[str, Any]]] = {}, calculation_script: str = 'run.py', calculation_script_template: str = 'run.py.j2', **extra_data: Any)[source]

Bases: BaseModel

The inputs for the calculation.

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.

analyses: dict[str, ArgSpec]
calc_params: dict[str, Any]
calculation_script: str
calculation_script_template: str
calculator: str
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

opt_params: dict[str, Any] | None
optimizer: str | None
class autojob.tasks.calculation.CalculationOutputs(*, energy: float | None = None, forces: list[list[float]] | None = None, converged: bool = False, calculator_results: dict[str, Any] | None = None, optimizer_results: list[dict[str, Any]] | None = None, analysis_results: dict[str, dict[str, Any]] | None = None, **extra_data: Any)[source]

Bases: BaseModel

The outputs of a calculation.

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.

analysis_results: dict[str, dict[str, Any]] | None
calculator_results: dict[str, Any] | None
converged: bool
energy: float | None
forces: list[list[float]] | None
classmethod from_directory(*, src: str | Path, calculator: str | None = None, optimizer: str | None = None, analyses: list[str] | None = None, strict_mode: bool | None = None) → CalculationOutputs[source]

Retrieve calculation outputs from a calculation directory.

Parameters:

  • src – The directory of a calculation.

  • calculator – The name of the ASE calculator used to perform the calculation. This will be used to determine which harvester plugin will be used to retrieve the calculator-specific results. Defaults to the harvester defined in mod:autojob.harvest.harvester.default.

  • optimizer – The name of the ASE optimizer used to perform the calculation. Defaults to None, in which case no optimizer results are harvested. This argument is not yet implemented.

  • analyses – A list of post-calculation analyses whose results are to be harvested. Defaults to an empty list.

  • strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs. Defaults to SETTINGS.STRICT_MODE.

Returns:

A CalculationOutputs object.

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

optimizer_results: list[dict[str, Any]] | None
serialize_calculator_results(v: dict[str, Any] | None, _: SerializerFunctionWrapHandler, info: FieldSerializationInfo) → dict[str, Any] | None[source]

Serialize the calculator results.

autojob.tasks.md module

Store the results of a molecular dynamics simulation.

class autojob.tasks.md.MDInitParams[source]

Bases: TypedDict

The initialization parameters for an ASE molecular dynamics object.

Variables:

  • timestep (float) – The time step in ASE time units. Note that although this key is not required, ase.md.md.MolecularDynamics objects require this parameter for initialization.

  • trajectory (str | None) – The name of a file in which to save the molecular dynamics trajectory.

  • logfile (str | None) – The name of a file to be used to log the results. Use ‘-’ for stdout.

  • loginterval (int) – The frequency with which results are logged.

  • append_trajectory (bool) – Whether or not to append to the trajectory with each step in the molecular dynamics run.

append_trajectory: bool
logfile: str | None
loginterval: int
timestep: float
trajectory: str | None
class autojob.tasks.md.MDInputs(*, md_init_params: MDInitParams = <factory>, md_run_params: MDRunParams = <factory>, **extra_data: Any)[source]

Bases: BaseModel

The inputs of a molecular dynamics calculation.

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.

md_init_params: MDInitParams
md_params_to_inputs() → Self[source]

Set MDInputs from old md_params data model.

md_run_params: MDRunParams
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class autojob.tasks.md.MDOutputs(*, md_trajectory: list[Annotated[Atoms, AtomsAnnotation]] | None = None, md_trajectory_results: list[dict[str, Any]] | None = None)[source]

Bases: BaseModel

The outputs of a molecular dynamics calculation.

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.

classmethod from_directory(src: Path, *, trajectory: str | None = None, strict_mode: bool | None = None) → Self[source]

Load the outputs of a molecular dynamics run from a directory.

Parameters:

  • src – The directory from which to load the results.

  • trajectory – The name of the trajectory file. Defaults to None in which case no trajectory will be loaded.

  • strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs. Defaults to SETTINGS.STRICT_MODE.

md_trajectory: list[Annotated[Atoms, AtomsAnnotation]] | None
md_trajectory_results: list[dict[str, Any]] | None
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

serialize_md_trajectory_results(v: list[dict[str, Any]] | None, _: SerializerFunctionWrapHandler, info: FieldSerializationInfo) → list[dict[str, Any]] | None[source]

Serialize the molecular dynamics results.

class autojob.tasks.md.MDRunParams[source]

Bases: TypedDict

The initialization parameters for an ASE molecular dynamics object.

Variables:

steps (int) – The number of molecular dynamics steps for which to run the calculation.

steps: int
class autojob.tasks.md.MolecularDynamics(*, scheduler_inputs: SchedulerInputs = <factory>, scheduler_outputs: SchedulerOutputs | None = None, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, calculation_inputs: CalculationInputs = <factory>, calculation_outputs: CalculationOutputs | None = None, md_inputs: MDInputs = <factory>, md_outputs: MDOutputs | None = None, **extra_data: Any)[source]

Bases: Calculation

A molecular dynamics calculation.

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.

classmethod from_directory(src, **kwargs)[source]

Generate a MolecularDynamics document from a task directory.

Parameters:

  • src – The directory of a molecular dynamics simulation.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to fail on any error. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

A MolecularDynamics or a subclass of a MolecularDynamics.

See also

calculation.Calculation.from_directory()

md_inputs: MDInputs
md_outputs: MDOutputs | None
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None, **kwargs) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the task inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

  • kwargs – Additional keyword arguments.

Returns:

The filename in which the inputs JSON written.

autojob.tasks.mh module

Store the results of a minima hopping simulation.

class autojob.tasks.mh.MHInitParams[source]

Bases: TypedDict

Initialization parameters for a minima hopping calculation.

Variables:

  • T0 (float) – The initial temperature for molecular dynamics steps (in Kelvin).

  • beta1 (float) – The first temperature adjustment parameter. The temperature for the molecular dynamics step will be multiplied by this number if the previous optimum is found.

  • beta2 (float) – The second temperature adjustment parameter. The temperature for the molecular dynamics step will be multiplied by this number if a previous (but not the immediately previous) optimum is found.

  • beta3 (float) – The third temperature adjustment parameter. The temperature for the molecular dynamics step will be multiplied by this number if a new minimum is found with energy below Ediff.

  • Ediff0 (float) – The initial energy acceptance threshold.

  • alpha1 (float) – The first energy threshold adjustment parameter. Ediff will be multiplied by this number whenever a unique minima is found with energy lower than Ediff.

  • alpha2 (float) – The first energy threshold adjustment parameter. Ediff will be multiplied by this number whenever a unique minima is found with energy higher than Ediff.

  • mdmin (int) – The number of minima that must be passed to stop MD simulations.

  • logfile (str) – A text log file for recording the progress of the calculation.

  • minima_threshold (float) – A distance threshold (in Angstromgs) for identifying identical structures.

  • timestep (float) – The timestep for MD simulations.

  • optimizer (str) – The fully qualified class name for an ASE optimizer to use.

  • minima_traj (str) – The storage file for minima. Currently, this key must be set for things to work correctly.

  • fmax (float) – Maximum force criteria for structure optimizations.

  • rng (int) – An integer to be used as a random seed.

Ediff0: float
T0: float
alpha1: float
alpha2: float
beta1: float
beta2: float
beta3: float
fmax: float
logfile: str
mdmin: int
minima_threshold: float
minima_traj: str
optimizer: str
rng: int
timestep: float
class autojob.tasks.mh.MHInputs(*, mh_init_params: MHInitParams = <factory>, mh_run_params: MHRunParams = <factory>, md_traj_pattern: str = 'md(?P<index>\\d{5}).traj', opt_traj_pattern: str = 'qn(?P<index>\\d{5}).traj', **extra_data: Any)[source]

Bases: BaseModel

The inputs of a minima hopping calculation.

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.

md_params_to_inputs() → Self[source]

Set MHInputs from old md_params data model.

md_traj_pattern: str
mh_init_params: MHInitParams
mh_run_params: MHRunParams
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

opt_traj_pattern: str
class autojob.tasks.mh.MHOutputs(*, minima: list[Annotated[Atoms, AtomsAnnotation]] | None = None, minima_results: list[dict[str, Any]] | None = None, md_trajectories: list[list[Annotated[Atoms, AtomsAnnotation]]] | None = None, md_trajectory_results: list[list[dict[str, Any]]] | None = None, opt_trajectories: list[list[Annotated[Atoms, AtomsAnnotation]]] | None = None, opt_trajectory_results: list[list[dict[str, Any]]] | None = None)[source]

Bases: BaseModel

The outputs of a minima hopping calculation.

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.

classmethod from_directory(src: Path, *, minima_traj: str, md_traj_pattern: str, opt_traj_pattern: str, strict_mode: bool | None = None) → Self[source]

Load the outputs of a minima hopping run from a directory.

Parameters:

  • src – The directory from which to load the results.

  • minima_traj – The name of the minima trajectory file.

  • md_traj_pattern – A regex pattern for identifying trajectory files of molecular dynamics steps.

  • opt_traj_pattern – str: A regex pattern for identifying trajectory files of optimization steps.

  • strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs. Defaults to SETTINGS.STRICT_MODE.

md_trajectories: list[list[Annotated[Atoms, AtomsAnnotation]]] | None
md_trajectory_results: list[list[dict[str, Any]]] | None
minima: list[Annotated[Atoms, AtomsAnnotation]] | None
minima_results: list[dict[str, Any]] | None
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

opt_trajectories: list[list[Annotated[Atoms, AtomsAnnotation]]] | None
opt_trajectory_results: list[list[dict[str, Any]]] | None
serialize_minima_results(v: list[dict[str, Any]] | None, _: SerializerFunctionWrapHandler, info: FieldSerializationInfo) → list[dict[str, Any]] | None[source]

Serialize trajectory results.

serialize_trajectory_results(v: list[list[dict[str, Any]]] | None, _: SerializerFunctionWrapHandler, info: FieldSerializationInfo) → list[list[dict[str, Any]]] | None[source]

Serialize trajectory results.

class autojob.tasks.mh.MHRunParams[source]

Bases: TypedDict

Run parameters for a minima hopping calculation.

Variables:

  • totalsteps (int) – The maximum number of steps that the calculation will run.

  • maxtemp (float) – The maximum temperature (in Kelvin) for the calculation.

maxtemp: float
totalsteps: int
class autojob.tasks.mh.MinimaHopping(*, scheduler_inputs: SchedulerInputs = <factory>, scheduler_outputs: SchedulerOutputs | None = None, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, calculation_inputs: CalculationInputs = <factory>, calculation_outputs: CalculationOutputs | None = None, mh_inputs: MHInputs = <factory>, mh_outputs: MHOutputs | None = None, **extra_data: Any)[source]

Bases: Calculation

A minima hopping calculation.

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.

classmethod from_directory(src, **kwargs)[source]

Generate a MinimaHopping document from a task directory.

Parameters:

  • src – The directory of a molecular dynamics simulation.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to fail on any error. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

A MinimaHopping or a subclass of a MinimaHopping.

See also

md.Calculation.from_directory()

mh_inputs: MHInputs
mh_outputs: MHOutputs | None
model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None, **kwargs) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the task inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

  • kwargs – Additional keyword arguments.

Returns:

The filename in which the inputs JSON written.

autojob.tasks.scan module

Store the results of scan calculations.

This module defines the autojob.tasks.scan.BondScan, autojob.tasks.scan.BondScanInputs, and autojob.tasks.scan.BondScanOutputs classes. Instances of these classes represent the results of a scan calculation, its inputs, and its outputs, respectively.

For building the respective documents from a folder, each class exposes a from_directory() method.

Example

from autojob.tasks.scan import BondScan

src = "path/to/calculation/directory"
results = BondScan.from_directory(src)
class autojob.tasks.scan.BondScan(*, scheduler_inputs: SchedulerInputs = <factory>, scheduler_outputs: SchedulerOutputs | None = None, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, calculation_inputs: CalculationInputs = <factory>, calculation_outputs: CalculationOutputs | None = None, bond_scan_inputs: BondScanInputs = <factory>, bond_scan_outputs: BondScanOutputs | None = None, **extra_data: Any)[source]

Bases: Calculation

A record representing a bond scan calculation.

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.

bond_scan_inputs: BondScanInputs
bond_scan_outputs: BondScanOutputs | None
classmethod from_directory(src: str | Path, **kwargs) → Self[source]

Generate a BondScan document from a task directory.

Parameters:

  • src – The directory of a bond scan calculation.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to fail on any error. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

A BondScan or a subclass of a BondScan.

See also

calculation.Calculation.from_directory()

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None, **kwargs) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the bond scan inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

  • kwargs – Additional keyword arguments.

Returns:

The filename in which the inputs JSON written.

class autojob.tasks.scan.BondScanInputs(*, bond_scan_params: list[BondScanParams] | None = None, scan_step: float = 0.1, write_traj: bool = True, traj_template: str = 'scan_{}_{}.traj', **extra_data: Any)[source]

Bases: BaseModel

The inputs for the calculation.

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.

bond_scan_params: list[BondScanParams] | None
model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

scan_step: float
traj_template: str
classmethod validate_bond_scan_params(v: Any, handler: ValidatorFunctionWrapHandler, _: ValidationInfo) → float | None[source]

Validate the bond scan parameters.

write_traj: bool
class autojob.tasks.scan.BondScanOutputs(*, images: dict[~typing.Annotated[tuple[int, int], ~pydantic.functional_validators.WrapValidator(func=~autojob.tasks.scan._validate_bond_tuple, json_schema_input_type=PydanticUndefined)], list[~ase.atoms.Annotated[~ase.atoms.Atoms, ~autojob.utils.schemas.AtomsAnnotation]]] = <factory>, bond_scan_results: dict[~typing.Annotated[tuple[int, int], ~pydantic.functional_validators.WrapValidator(func=~autojob.tasks.scan._validate_bond_tuple, json_schema_input_type=PydanticUndefined)], list[dict[str, ~typing.Any]]] = <factory>)[source]

Bases: BaseModel

The raw data of a bond scan calculation.

Note that data under each key in results must correspond to the data under images of the same index.

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.

bond_scan_results: BondScanResults
property bonds: list[tuple[int, int]]

A list of paired atomic indices indicating bonded atom pairs.

classmethod from_directory(*, src: str | Path, traj_template: str = 'scan_{}_{}.traj', strict_mode: bool | None = None) → Self[source]

Retrieve bond scan outputs from a directory.

Parameters:

  • src – The directory of a calculation.

  • traj_template – A format string to be used to name the trajectory files of each linear scan. The format string must accept two fields, which correspond to the atomic indices of the atoms in the bond for which the linear bond scan is being performed. Defaults to "scan_{}_{}.traj".

  • strict_mode – Whether or not to require all results. If True, errors will be thrown on missing results. Defaults to SETTINGS.STRICT_MODE.

Returns:

A BondScanOutputs object.

images: dict[BondTuple, list[PydanticAtoms]]
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

serialize_bond_scan_results(v: dict[Annotated[tuple[int, int], WrapValidator(func=_validate_bond_tuple, json_schema_input_type=PydanticUndefined)], list[dict[str, Any]]] | None, _: SerializerFunctionWrapHandler, info: FieldSerializationInfo) → dict[Annotated[tuple[int, int], WrapValidator(func=_validate_bond_tuple, json_schema_input_type=PydanticUndefined)], list[dict[str, Any]]] | None[source]

Serialize the bond scan results.

class autojob.tasks.scan.BondScanParams(a0: int, a1: int, mask: list[bool] | None = None, indices: list[int] | None = None, fix: float = 0.5, bond_lims: tuple[float, float] = (0.7, 4.0))[source]

Bases: NamedTuple

Parameters for modifying bond scans.

a0, a1, mask, indices, and fix map to the parameters in set_distance`(). bond_lims specifies the minimum and maximum bond lengths for the bond scan. The endpoint may be excluded if the scan step does not evenly divide the difference between the minimum and maximum bond lengths.

Create new instance of BondScanParams(a0, a1, mask, indices, fix, bond_lims)

a0: int

Alias for field number 0

a1: int

Alias for field number 1

bond_lims: tuple[float, float]

Alias for field number 5

fix: float

Alias for field number 4

indices: list[int] | None

Alias for field number 3

mask: list[bool] | None

Alias for field number 2

autojob.tasks.task module

This module defines a concrete implementation of TaskBase.

class autojob.tasks.task.Task(*, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, **extra_data: Any)[source]

Bases: TaskBase, SetTaskClassMixin

A concrete implementation of TaskBase.

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.

classmethod from_directory(src: str | Path, **kwargs) → Self[source]

Generate a Task document from a completed task’s directory.

Parameters:

  • src – The directory of a completed Task.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

An instance of Task or a Task subclass.

classmethod load_magic(src: str | Path, *, strict_mode: bool = True) → Self[source]

Load a TaskBase subclass using its “base class” metadata.

Parameters:

  • src – The directory from which to load the task.

  • strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs. Defaults to SETTINGS.STRICT_MODE.

Raises:

RuntimeError – No build class specified in the task metadata. Only raised if strict_mode is True.

Returns:

The loaded task.

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

task_inputs: TaskInputs
task_metadata: TaskMetadata
task_outputs: TaskOutputs | None
write_input_atoms(dest: str | Path) → Path | None[source]

Write the input atoms to a file.

Parameters:

dest – The directory in which to write the Atoms file.

Returns:

The filename in which the Atoms where written.

write_inputs(dest: str | Path, **kwargs) → list[Path][source]

Write required inputs for a task to a diretory.

Parameters:

  • dest – The directory in which to save the task results.

  • kwargs – Additional keyword arguments.

Returns:

A list of input files written.

write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the task inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

Returns:

The filename in which the inputs JSON written.

write_metadata(dest: str | Path) → Path[source]

Write the task metadata to a file.

Parameters:

dest – The directory in which to write the task metadata.

Returns:

The filename in which the task metadata was written.

write_task_script(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the SLURM input script using the template given.

Parameters:

  • dest – The directory in which to write the SLURM file.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the task inputs that will be written to the task script. Defaults to an empty dictionary.

Returns:

A Path representing the filename of the written SLURM script.

class autojob.tasks.task.TaskInputs(*, atoms: Annotated[list[Annotated[Atoms, AtomsAnnotation]] | Annotated[Atoms, AtomsAnnotation] | None, _PydanticGeneralMetadata(union_mode='left_to_right')] = None, files_to_copy: list[str] = [], files_to_delete: list[str] = [], files_to_carry_over: list[str] = [], auto_restart: bool = True, atoms_filename: str = 'in.traj', task_script: str = 'run.sh', task_script_template: str = 'run.sh.j2', **extra_data: Any)[source]

Bases: TaskInputsBase

The set of task-level inputs.

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.

atoms_filename: str
auto_restart: bool
files_to_carry_over: list[str]
files_to_copy: list[str]
files_to_delete: list[str]
classmethod from_directory(src: str | Path, **kwargs) → TaskInputs[source]

Generate a TaskInputs document from a completed task’s directory.

Parameters:

  • src – The directory of a completed Task.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to raise an error if the input atoms are not found. Defaults to SETTINGS.STRICT_MODE.

Returns:

A class – TaskInputs object.

model_config: ClassVar[ConfigDict] = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

task_script: str
task_script_template: str
class autojob.tasks.task.TaskMetadata(*, label: str = '', tags: list[str] = [], uri: str | None = None, study_group_id: UUID, ~pydantic.types.UuidVersion(uuid_version=4)] | str | None, _PydanticGeneralMetadata(union_mode='left_to_right')] = <factory>, study_id: UUID, ~pydantic.types.UuidVersion(uuid_version=4)] | str | None, _PydanticGeneralMetadata(union_mode='left_to_right')] = <factory>, workflow_step_id: UUID, ~pydantic.types.UuidVersion(uuid_version=4)] | None = None, task_id: UUID, ~pydantic.types.UuidVersion(uuid_version=4)] | str, _PydanticGeneralMetadata(union_mode='left_to_right')] = <factory>, task_group_id: UUID, ~pydantic.types.UuidVersion(uuid_version=4)] | str | None, _PydanticGeneralMetadata(union_mode='left_to_right')] = <factory>, date_created: datetime = <factory>, last_updated: datetime = <factory>, task_class: str | None = None, **extra_data: Any)[source]

Bases: TaskMetadataBase

A concrete implementation of TaskMetadataBase.

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.

date_created: datetime
classmethod from_directory(src: str | Path) → TaskMetadataBase[source]

Create a TaskMetadata document from a task directory.

label: str
last_updated: datetime
model_config = {'extra': 'allow', 'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

study_group_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None
study_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None
tags: list[str]
task_class: str | None
task_group_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None
task_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str
uri: str | None
classmethod validate_ids(v: Any, handler: ValidatorFunctionWrapHandler, info: ValidationInfo) → str | Annotated[UUID, UuidVersion(uuid_version=4)][source]

Validate an ID.

IDs can either be a UUID or a 10-digit alphanumeric shortuuid string.

workflow_step_id: Annotated[UUID, UuidVersion(uuid_version=4)] | None
class autojob.tasks.task.TaskOutputs(*, atoms: Annotated[list[Annotated[Atoms, AtomsAnnotation]] | Annotated[Atoms, AtomsAnnotation] | None, _PydanticGeneralMetadata(union_mode='left_to_right')] = None, entry: ComputedEntry | None = None, outcome: TaskOutcome = TaskOutcome.UNKNOWN)[source]

Bases: TaskOutputsBase

The set of task-level outputs.

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.

entry: ComputedEntry | None
classmethod from_directory(src: str | Path, **kwargs) → TaskOutputs[source]

Generate a TaskOutputs document from a completed task’s directory.

Parameters:

  • src – The directory of a completed task.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to catch thrown errors. Errors will not be caught if strict_mode=True. Defaults to SETTINGS.STRICT_MODE.

Returns:

A TaskOutputs object.

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

outcome: TaskOutcome

autojob.tasks.vibration module

Store the results of a vibration calculation.

This module defines the Vibration, VibrationInputs, and VibrationOutputs classes. Instances of these classes represent the results of a vibration calculation, its inputs, and its outputs, respectively.

For building the respective documents from a folder, the Vibration and VibrationnOutputs classes are PathLoadable.

In addition, this module defines the freeze_atoms() function-a utility function for fixing the atoms of an Atoms object by tag.

Examples

Create a vibration calculation with frozen atoms

from ase.build import add_adsorbate, fcc100, molecule

from autojob.tasks.task import TaskInputs
from autojob.tasks.vibration import freeze_atoms, Vibration

slab = fcc100("Cu")
co = molecule("CO")
# All atoms with this tag will NOT be frozen
tag = -99
co.set_tags([tag] * len(co))
add_adsorbate(slab, co, 1.8)

# Freeze the atoms that should not be displaced during the vibration
# analysis
freeze_atoms(slab, [tag])

# Create the vibration calculation
tinputs = TaskInputs(atoms=slab)
vib = Vibration(task_inputs=tinputs)

Create a vibration calculation with frozen atoms

from ase.build import add_adsorbate, fcc100, molecule

from autojob.tasks.task import TaskInputs
from autojob.tasks.vibration import Vibration, VibrationInputs

slab = fcc100("Cu")
co = molecule("CO")
add_adsorbate(slab, co, 1.8)

# Create the vibration calculation
tinputs = TaskInputs(atoms=slab)
indices = [a.index for a in slab if a.symbol != "Cu"]
vinputs = VibrationInputs(indices=indices)
vib = Vibration(task_inputs=tinputs, vibration_inputs=vinputs)

Load the results of vibration calculation

from autojob.tasks.vibration import Vibration

src = "path/to/calculation/directory"
results = Vibration.from_directory(src)
class autojob.tasks.vibration.Vibration(*, scheduler_inputs: SchedulerInputs = <factory>, scheduler_outputs: SchedulerOutputs | None = None, task_metadata: TaskMetadata = <factory>, task_inputs: TaskInputs = <factory>, task_outputs: TaskOutputs | None = None, calculation_inputs: CalculationInputs = <factory>, calculation_outputs: CalculationOutputs | None = None, vibration_inputs: VibrationInputs = <factory>, vibration_outputs: VibrationOutputs | None = None, **extra_data: Any)[source]

Bases: Calculation

A record representing a vibrational calculation.

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.

classmethod from_directory(src: str | Path, **kwargs) → Self[source]

Generate a Vibration document from a calculation directory.

Parameters:

  • src – The directory of a calculation.

  • kwargs – Additional keyword arguments:

  • - strict_mode – Whether or not to fail on any error. Defaults to SETTINGS.STRICT_MODE.

  • - magic_mode – Whether or not to instantiate subclasses. If True, the task returned must be an instance determined by metadata in the directory. Defaults to False.

Returns:

A Vibration or a subclass of a Vibration.

See also

calculation.Calculation.from_directory()

model_config = {'extra': 'allow'}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vibration_inputs: VibrationInputs
vibration_outputs: VibrationOutputs | None
write_inputs_json(dest: str | Path, *, additional_data: dict[str, Any] | None = None) → Path[source]

Write the inputs JSON to a file.

Parameters:

  • dest – The directory in which to write the inputs JSON.

  • additional_data – A dictionary mapping strings to JSON-serializable values to be merged with the vibration inputs that will be written to the inputs JSON. Defaults to an empty dictionary.

Returns:

The filename in which the inputs JSON written.

class autojob.tasks.vibration.VibrationInputs(*, name: str = 'vib', nfree: Literal[2, 4] = 4, delta: float = 0.015, indices: list[int] | None = None)[source]

Bases: BaseModel

The inputs of a vibrational calculation.

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.

delta: float
indices: list[int] | None
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str
nfree: Literal[2, 4]
class autojob.tasks.vibration.VibrationOutputs(*, atoms: Annotated[Atoms, AtomsAnnotation] | None = None, hessian: list[list[list[list[float]]]] | None = None, indices: list[int] | None = None, vib_energies: list[complex] | None = None, zero_point_energy: float | None = None)[source]

Bases: BaseModel

The outputs of a vibrational calculation.

This class is intended to wrap the ase.vibrations.data.VibrationsData class.

Example

Observe vibrational modes

import ase.io
from ase.vibrations.data import VibrationsData

from autojob.calculation.vibration import VibrationOutputs

atoms = ase.io.read("atoms.traj")
outputs = VibrationOutputs.from_directory(...)
vib_data = VibrationsData(
    atoms=atoms,
    hessian=outputs.hessian,
    indices=outputs.indices,
)

for i, _ in enumerate(vib.get_energies()):
    vib.write_mode(i)

Example

Calculate thermodynamic quantities

from ase.build import molecule
from ase.calculators.emt import EMT
from ase.vibrations.data import IdealGasThermo
from ase.vibrations.vibrations import Vibrations

from autojob.calculation.vibration import VibrationOutputs

# Run a Vibration Task
atoms = molecule("CO2")
atoms.calc = EMT()
vib = Vibrations(atoms=atoms, nfree=4, name=label, delta=0.015)
vib.run()

# Dump the results to a file
with Path('vib.json').open(mode="r", encoding="utf-8") as f:
    vib.write(f)

# ... Then come back to the directory ...

# This provides validation and fall backs to reading other files
outputs = VibrationOutputs.from_directory(...)
vib_data = VibrationsData(
    atoms=atoms,
    hessian=outputs.hessian,
    indices=outputs.indices,
)
# Get G, H, S, ZPE
ig_thermo = IdealGasThermo(
    atoms=atoms,
    vib_energies=vib_data.get_energies(),
    geometry="linear",
    potentialenergy=0.0,
    symmetrynumber=1,
    spin=0,
)
ig_thermo.get_gibbs_energy()
ig_thermo.get_entropy()
ig_thermo.get_enthalpy()
ig_thermo.get_ZPE_correction()

See also

ase.vibrations.data.VibrationsData

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.

atoms: Annotated[Atoms, AtomsAnnotation] | None
classmethod from_directory(src: str | Path, *, name: str = 'vib', strict_mode: bool | None = None) → VibrationOutputs[source]

Extract thermo data from the input structure of the directory.

Parameters:

  • src – The directory of the completed calculation.

  • name – The name used to write vibration calculation results. This should either be the name of the directory containing the cache files or the filename stem for a JSON containing the output of a vibration calculation such as that produced by write().

  • strict_mode – Whether or not to require all outputs. If True, errors will be thrown on missing outputs.

Returns:

The thermodynamic data as VibrationOutputs. If no data is found, and strict_mode = False every value will be None.

hessian: list[list[list[list[float]]]] | None
indices: list[int] | None
model_config: ClassVar[ConfigDict] = {'populate_by_name': True, 'validate_by_alias': True, 'validate_by_name': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

vib_energies: list[complex] | None
zero_point_energy: float | None
autojob.tasks.vibration.freeze_atoms(atoms: Atoms, tags_to_unfreeze: list[int]) → None[source]

Freeze atoms of an input structure.

This function modifies atoms in place.

Parameters:

  • atoms – An Atoms object.

  • tags_to_unfreeze – A list of integers. Atoms with tags in this list will not be frozen.