autojob.bases package¶

This subpackage defines core base classes for autojob.

Submodules¶

autojob.bases.analysis_base module¶

This module defines the AnalysisBase protocol.

class autojob.bases.analysis_base.AnalysisBase(*args, **kwargs)[source]¶

Bases: Protocol

A protocol defining functions that perform a post-calculation analysis.

autojob.bases.harvester_base module¶

This module defines the HarvesterBase protocol.

class autojob.bases.harvester_base.HarvesterBase(*args, **kwargs)[source]¶

Bases: Protocol

A protocol for functions that harvest post-calculation analysis results.

autojob.bases.task_base module¶

Represent and model the results of a task.

class autojob.bases.task_base.InputWriter(*args, **kwargs)[source]¶

Bases: Protocol

A protocol for objects that can write their inputs to a directory.

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

Write inputs of the class to the directory for execution.

This method should also perform any modifications necesary to prepare inputs. For example, such a modification may be copying magnetic moments to initial magnetic moments.

Parameters:

dest – The directory to which the inputs will be written.
kwargs – Additional keyword arguments.

Returns:

A list of input files written.

class autojob.bases.task_base.PathLoadable(*args, **kwargs)[source]¶

Bases: Protocol

A protocol for objects that can be loaded from a directory.

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

Load an instance of the class from a directory.

Parameters:

src – The directory from which to load the object.
kwargs – Additional keyword arguments.

Returns:

An instance of the class or a subclass.

class autojob.bases.task_base.SetTaskClassMixin[source]¶

Bases: object

A mixin that sets task_class for the TaskMetadataBase of a task.

set_task_class() → Self[source]¶: Sets the task_class for the TaskMetadataBase of a task.

pydantic model autojob.bases.task_base.TaskBase[source]¶

Bases: BaseModel, ABC

An abstract base class for tasks.

Note that by definition, concrete implementations of the class adhere to the PathLoadable and InputWriter protocols.

Concrete implementations of this class must be defined such that they can be instantiated without arguments.

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

{
   "title": "TaskBase",
   "description": "An abstract base class for tasks.\n\nNote that by definition, concrete implementations of the class adhere to\nthe :class:`PathLoadable` and :class:`InputWriter` protocols.\n\nConcrete implementations of this class must be defined such that they\ncan be instantiated without arguments.",
   "type": "object",
   "properties": {
      "task_metadata": {
         "$ref": "#/$defs/TaskMetadataBase",
         "description": "Task metadata"
      },
      "task_inputs": {
         "$ref": "#/$defs/TaskInputsBase",
         "description": "Task inputs"
      },
      "task_outputs": {
         "anyOf": [
            {
               "$ref": "#/$defs/TaskOutputsBase"
            },
            {
               "type": "null"
            }
         ],
         "description": "Task outputs"
      }
   },
   "$defs": {
      "TaskInputsBase": {
         "additionalProperties": true,
         "description": "The set of task-level inputs.\n\nNote that :class:`TaskInputsBase` instances are ``PathLoadable``.",
         "properties": {
            "atoms": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Input or output ase.Atoms",
               "title": "Atoms"
            },
            "files_to_copy": {
               "default": [],
               "description": "The files to copy from the preceding task into the scratch directory of this task.",
               "items": {
                  "type": "string"
               },
               "title": "Files To Copy",
               "type": "array"
            },
            "files_to_delete": {
               "default": [],
               "description": "The files to delete from the directory of the task after job completion.",
               "items": {
                  "type": "string"
               },
               "title": "Files To Delete",
               "type": "array"
            },
            "files_to_carry_over": {
               "default": [],
               "description": "The files to carry over from the completed task to the new job.",
               "items": {
                  "type": "string"
               },
               "title": "Files To Carry Over",
               "type": "array"
            },
            "auto_restart": {
               "default": true,
               "description": "Whether or not to automatically restart this calculation with the same parameters if the task finishes unsuccessfully.",
               "title": "Auto Restart",
               "type": "boolean"
            },
            "atoms_filename": {
               "default": "in.traj",
               "description": "The filename of the input atoms",
               "title": "Atoms Filename",
               "type": "string"
            },
            "task_script": {
               "default": "run.sh",
               "description": "The default filename for the task script",
               "title": "Task Script",
               "type": "string"
            },
            "task_script_template": {
               "default": "run.sh.j2",
               "description": "The name of the default task script template",
               "title": "Task Script Template",
               "type": "string"
            }
         },
         "title": "TaskInputsBase",
         "type": "object"
      },
      "TaskMetadataBase": {
         "additionalProperties": true,
         "description": "The metadata for a task.\n\nNote that :class:`TaskMetadataBase` instances are ``PathLoadable``.",
         "properties": {
            "label": {
               "default": "",
               "description": "A description of the job",
               "title": "Label",
               "type": "string"
            },
            "tags": {
               "default": [],
               "description": "Metadata tagged to a given job",
               "items": {
                  "type": "string"
               },
               "title": "tag",
               "type": "array"
            },
            "uri": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The uri for the directory containing this task",
               "title": "Uri"
            },
            "study_group_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The study group uuid",
               "title": "Study Group Id"
            },
            "study_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The study uuid",
               "title": "Study Id"
            },
            "workflow_step_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The workflow step uuid",
               "title": "Workflow Step Id"
            },
            "task_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "string"
                  }
               ],
               "description": "A UUID identifying the task.",
               "title": "Task Id"
            },
            "task_group_id": {
               "anyOf": [
                  {
                     "format": "uuid4",
                     "type": "string"
                  },
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "A UUID identifying a group of tasks.",
               "title": "Task Group Id"
            },
            "date_created": {
               "description": "The date and time that the task was first created.",
               "format": "date-time",
               "title": "Date Created",
               "type": "string"
            },
            "last_updated": {
               "description": "Timestamp for the most recent calculation for this task document",
               "format": "date-time",
               "title": "Last Updated",
               "type": "string"
            },
            "task_class": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The plugin name of the concrete TaskBase implementation to which this metadata belongs (e.g., task)",
               "title": "Task Class"
            }
         },
         "title": "TaskMetadataBase",
         "type": "object"
      },
      "TaskOutcome": {
         "description": "The outcome of a task.\n\nThe meanings of each outcome are as follows:\n\nSUCCESS: The task completed successfully.\nFAILED: The task completed with errors.\nIDLE: The task is yet to run.\nRUNNING: The task is running.\nUNKNOWN: The outcome of the task is unknown.",
         "enum": [
            "success",
            "failed",
            "idle",
            "running",
            "unknown"
         ],
         "title": "TaskOutcome",
         "type": "string"
      },
      "TaskOutputsBase": {
         "description": "The set of task-level outputs.\n\nNote that :class:`TaskOutputsBase` instances are ``PathLoadable``.",
         "properties": {
            "atoms": {
               "anyOf": [
                  {
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Input or output ase.Atoms",
               "title": "Atoms"
            },
            "entry": {
               "anyOf": [
                  {
                     "properties": {
                        "@class": {
                           "enum": [
                              "ComputedEntry"
                           ],
                           "type": "string"
                        },
                        "@module": {
                           "enum": [
                              "pymatgen.entries.computed_entries"
                           ],
                           "type": "string"
                        },
                        "@version": {
                           "type": "string"
                        }
                     },
                     "required": [
                        "@class",
                        "@module"
                     ],
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The ComputedEntry from the task",
               "title": "Entry"
            },
            "outcome": {
               "$ref": "#/$defs/TaskOutcome",
               "default": "unknown",
               "description": "The outcome of the task"
            }
         },
         "title": "TaskOutputsBase",
         "type": "object"
      }
   },
   "additionalProperties": true,
   "required": [
      "task_metadata",
      "task_inputs",
      "task_outputs"
   ]
}

Config:

extra: str = allow

Fields:

task_inputs (autojob.bases.task_base.TaskInputsBase)
task_metadata (autojob.bases.task_base.TaskMetadataBase)
task_outputs (autojob.bases.task_base.TaskOutputsBase | None)

field task_inputs: TaskInputsBase [Required]¶: Task inputs

field task_metadata: TaskMetadataBase [Required]¶: Task metadata

field task_outputs: TaskOutputsBase | None [Required]¶: Task outputs

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

Load a task from a directory.

Parameters:

src – The directory from which to load the task.
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 task whose type is that of the calling class or one of its subclasses.

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

Write a task to the directory for execution.

Concrete implementations must at least write an inputs JSON, a metadata file, and the input Atoms (if non-None).

Parameters:

dest – The directory in which to write inputs.
kwargs – Additional keyword arguments.

pydantic model autojob.bases.task_base.TaskInputsBase[source]¶

Bases: _TaskIODoc

The set of task-level inputs.

Note that TaskInputsBase instances are PathLoadable.

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

{
   "title": "TaskInputsBase",
   "description": "The set of task-level inputs.\n\nNote that :class:`TaskInputsBase` instances are ``PathLoadable``.",
   "type": "object",
   "properties": {
      "atoms": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Input or output ase.Atoms",
         "title": "Atoms"
      },
      "files_to_copy": {
         "default": [],
         "description": "The files to copy from the preceding task into the scratch directory of this task.",
         "items": {
            "type": "string"
         },
         "title": "Files To Copy",
         "type": "array"
      },
      "files_to_delete": {
         "default": [],
         "description": "The files to delete from the directory of the task after job completion.",
         "items": {
            "type": "string"
         },
         "title": "Files To Delete",
         "type": "array"
      },
      "files_to_carry_over": {
         "default": [],
         "description": "The files to carry over from the completed task to the new job.",
         "items": {
            "type": "string"
         },
         "title": "Files To Carry Over",
         "type": "array"
      },
      "auto_restart": {
         "default": true,
         "description": "Whether or not to automatically restart this calculation with the same parameters if the task finishes unsuccessfully.",
         "title": "Auto Restart",
         "type": "boolean"
      },
      "atoms_filename": {
         "default": "in.traj",
         "description": "The filename of the input atoms",
         "title": "Atoms Filename",
         "type": "string"
      },
      "task_script": {
         "default": "run.sh",
         "description": "The default filename for the task script",
         "title": "Task Script",
         "type": "string"
      },
      "task_script_template": {
         "default": "run.sh.j2",
         "description": "The name of the default task script template",
         "title": "Task Script Template",
         "type": "string"
      }
   },
   "additionalProperties": true
}

Config:

extra: str = allow

Fields:

atoms_filename (str)
auto_restart (bool)
files_to_carry_over (list[str])
files_to_copy (list[str])
files_to_delete (list[str])
task_script (str)
task_script_template (str)

field atoms_filename: str = 'in.traj'¶: The filename of the input atoms

field auto_restart: bool = True¶: Whether or not to automatically restart this calculation with the same parameters if the task finishes unsuccessfully.

field files_to_carry_over: list[str] = []¶: The files to carry over from the completed task to the new job.

field files_to_copy: list[str] = []¶: The files to copy from the preceding task into the scratch directory of this task.

field files_to_delete: list[str] = []¶: The files to delete from the directory of the task after job completion.

field task_script: str = 'run.sh'¶: The default filename for the task script

field task_script_template: str = 'run.sh.j2'¶: The name of the default task script template

pydantic model autojob.bases.task_base.TaskMetadataBase[source]¶

Bases: BaseModel, ABC

The metadata for a task.

Note that TaskMetadataBase instances are PathLoadable.

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

{
   "title": "TaskMetadataBase",
   "description": "The metadata for a task.\n\nNote that :class:`TaskMetadataBase` instances are ``PathLoadable``.",
   "type": "object",
   "properties": {
      "label": {
         "default": "",
         "description": "A description of the job",
         "title": "Label",
         "type": "string"
      },
      "tags": {
         "default": [],
         "description": "Metadata tagged to a given job",
         "items": {
            "type": "string"
         },
         "title": "tag",
         "type": "array"
      },
      "uri": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The uri for the directory containing this task",
         "title": "Uri"
      },
      "study_group_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "description": "The study group uuid",
         "title": "Study Group Id"
      },
      "study_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "description": "The study uuid",
         "title": "Study Id"
      },
      "workflow_step_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The workflow step uuid",
         "title": "Workflow Step Id"
      },
      "task_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "string"
            }
         ],
         "description": "A UUID identifying the task.",
         "title": "Task Id"
      },
      "task_group_id": {
         "anyOf": [
            {
               "format": "uuid4",
               "type": "string"
            },
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "description": "A UUID identifying a group of tasks.",
         "title": "Task Group Id"
      },
      "date_created": {
         "description": "The date and time that the task was first created.",
         "format": "date-time",
         "title": "Date Created",
         "type": "string"
      },
      "last_updated": {
         "description": "Timestamp for the most recent calculation for this task document",
         "format": "date-time",
         "title": "Last Updated",
         "type": "string"
      },
      "task_class": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The plugin name of the concrete TaskBase implementation to which this metadata belongs (e.g., task)",
         "title": "Task Class"
      }
   },
   "additionalProperties": true
}

Config:

populate_by_name: bool = True
extra: str = allow

Fields:

date_created (datetime.datetime)
label (str)
last_updated (datetime.datetime)
study_group_id (uuid.UUID | str | None)
study_id (uuid.UUID | str | None)
tags (list[str])
task_class (str | None)
task_group_id (uuid.UUID | str | None)
task_id (uuid.UUID | str)
uri (str | None)
workflow_step_id (uuid.UUID | None)

field date_created: datetime [Optional]¶: The date and time that the task was first created.

field label: str = ''¶: A description of the job

field last_updated: datetime [Optional]¶: Timestamp for the most recent calculation for this task document

field study_group_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None [Optional]¶

The study group uuid

Constraints:

union_mode = left_to_right

field study_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None [Optional]¶

The study uuid

Constraints:

union_mode = left_to_right

field tags: list[str] = []¶: Metadata tagged to a given job

field task_class: str | None = None¶: The plugin name of the concrete TaskBase implementation to which this metadata belongs (e.g., task)

field task_group_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str | None [Optional]¶

A UUID identifying a group of tasks.

Constraints:

union_mode = left_to_right

field task_id: Annotated[UUID, UuidVersion(uuid_version=4)] | str [Optional]¶

A UUID identifying the task.

Constraints:

union_mode = left_to_right

field uri: str | None = None¶: The uri for the directory containing this task

field workflow_step_id: Annotated[UUID, UuidVersion(uuid_version=4)] | None = None¶: The workflow step uuid

abstractmethod classmethod from_directory(src: str | Path) → Self[source]¶: Load a TaskMetadataBase from a directory.

class autojob.bases.task_base.TaskOutcome(value)[source]¶

Bases: StrEnum

The outcome of a task.

The meanings of each outcome are as follows:

SUCCESS: The task completed successfully. FAILED: The task completed with errors. IDLE: The task is yet to run. RUNNING: The task is running. UNKNOWN: The outcome of the task is unknown.

FAILED = 'failed'¶

IDLE = 'idle'¶

RUNNING = 'running'¶

SUCCESS = 'success'¶

UNKNOWN = 'unknown'¶

pydantic model autojob.bases.task_base.TaskOutputsBase[source]¶

Bases: _TaskIODoc

The set of task-level outputs.

Note that TaskOutputsBase instances are PathLoadable.

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

{
   "title": "TaskOutputsBase",
   "description": "The set of task-level outputs.\n\nNote that :class:`TaskOutputsBase` instances are ``PathLoadable``.",
   "type": "object",
   "properties": {
      "atoms": {
         "anyOf": [
            {
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Input or output ase.Atoms",
         "title": "Atoms"
      },
      "entry": {
         "anyOf": [
            {
               "properties": {
                  "@class": {
                     "enum": [
                        "ComputedEntry"
                     ],
                     "type": "string"
                  },
                  "@module": {
                     "enum": [
                        "pymatgen.entries.computed_entries"
                     ],
                     "type": "string"
                  },
                  "@version": {
                     "type": "string"
                  }
               },
               "required": [
                  "@class",
                  "@module"
               ],
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The ComputedEntry from the task",
         "title": "Entry"
      },
      "outcome": {
         "$ref": "#/$defs/TaskOutcome",
         "default": "unknown",
         "description": "The outcome of the task"
      }
   },
   "$defs": {
      "TaskOutcome": {
         "description": "The outcome of a task.\n\nThe meanings of each outcome are as follows:\n\nSUCCESS: The task completed successfully.\nFAILED: The task completed with errors.\nIDLE: The task is yet to run.\nRUNNING: The task is running.\nUNKNOWN: The outcome of the task is unknown.",
         "enum": [
            "success",
            "failed",
            "idle",
            "running",
            "unknown"
         ],
         "title": "TaskOutcome",
         "type": "string"
      }
   }
}

Fields:

entry (pymatgen.entries.computed_entries.ComputedEntry | None)
outcome (autojob.bases.task_base.TaskOutcome)

field entry: ComputedEntry | None = None¶: The ComputedEntry from the task

field outcome: TaskOutcome = TaskOutcome.UNKNOWN¶: The outcome of the task