atomate2

atomate2 provides a wide range of pre-defined VASP workflows for various materials science tasks. These include:

• Static: Single-point calculation without relaxation.
• Relax: Full structural relaxation.
• Tight Relax: Relaxation with tight convergence parameters (useful for phonons).
• Dielectric: Calculation of dielectric properties using DFPT.
• Transmuter: Transforms the structure (e.g., supercells, symmetrization) before writing input sets.
• HSE06 variants: Static, Relax, and Tight Relax workflows using the HSE06 functional.
• Double Relax: Two back-to-back relaxations to mitigate Pulay stress.
• Band Structure: Three-step flow (Static $\rightarrow$ Dense Uniform Mesh $\rightarrow$ High-symmetry k-point path).
• Uniform Band Structure: Two-step flow (Static $\rightarrow$ Dense Uniform Mesh).
• Line-Mode Band Structure: Two-step flow (Static $\rightarrow$ High-symmetry k-point path).
• Elastic Constant: Tight relaxation followed by lattice perturbations and stress tensor calculation.
• Optics: Static calculation followed by an LOPTICS non-scf calculation.
• Phonons: Tight relaxation, supercell generation, and force computation (supports Phonopy and Pheasy).
• Grüneisen parameter: Calculates mode-dependent parameters via volume expansion/contraction.
• Quasi-harmonic (QHA): Computes thermodynamic properties via constant volume optimizations.
• Equation of State (EOS): Performs optimizations at constant volumes followed by an EOS fit.
• LOBSTER: Bonding analysis using LOBSTER and LobsterPy.

A Builder (provided by the maggma toolkit) is a data processing step used to build data pipelines. It follows a specific lifecycle to transform data from a Store into processed output documents.

To implement a custom Builder, you must implement three core methods:

1. get_items(): Retrieves raw data from the source store(s).
2. process_item(item): Handles the input items and creates the output document.
3. update_targets(items): Updates the target store(s) with the newly processed results.

class Builder(MSONable, metaclass=ABCMeta):
    """
    Base Builder class
    At minimum this class should implement:
    get_items - Get items from the sources
    update_targets - Updates the sources with results

    Multiprocessing and MPI processing can be used if all
    the data processing is limited to process_items
    """
    """[...]"""

    @abstractmethod
    def get_items(self) -> Iterable:

    def process_item(self, item: Any) -> Any:

    @abstractmethod
    def update_targets(self, items: List):

The output key within a JobStoreDocument contains the specific results of a calculation. For VASP calculations, this is known as a TaskDoc. While the schema varies by calculation type, TaskDoc models are hierarchical and share several common top-level keys:

Structure Metadata

Contains basic structural information:

• nsites: Number of sites.
• composition: Full material composition.
• elements: List of elements.
• formula_pretty: Cleaned formula string.
• chemsys: Dash-delimited element string.

Key Data Sections

• structure: The final output structure as a serialized pymatgen.Structure object.
• builder_meta: Information about the software versions used (e.g., emmet_version, pymatgen_version).
• task_type: A standardized label for the calculation (e.g., "Structure Optimization").
• task_label: A user-definable label.
• dir_name: Path to the calculation directory.
• run_stats: Computational resource usage (walltime, CPU time, memory, etc.).
• input: Summarized final input data (e.g., Structure, INCAR settings, pseudopotentials).
• output: Summary of final results (e.g., energy, energy_per_atom, bandgap, structure).
• orig_inputs: The original inputs provided by the user (useful for provenance if custodian modified settings).
• custodian: A list of corrections or changes made during the calculation.
• calcs_reversed: A list containing inputs and outputs for all calculation steps in reverse order (index [0] is the most recent step). This section is designed to capture all information available in a VASP OUTCAR or vasprun.xml.

{
  "task_type": "Structure Optimization",
  "task_label": "relax",
  "dir_name": "/path/to/job",
  "run_stats": {
              "average_memory": 0,
              "max_memory": 241584,
              "elapsed_time": 18.833,
              "system_time": 1.114,
              "user_time": 16.166,
              "total_time": 17.28,
              "cores": 40
          },
  "input": { ... },
  "output": { ... },
  "calcs_reversed": [ ... ]
}

Every Job run in atomate2 is stored as a JobStoreDocument. This document follows a standard schema that ensures consistency across all jobs. Key fields include:

• uuid: A unique identifier for the Job.
• output: The actual calculation results (the contents of the Job).
• completed_at: Timestamp of job completion.
• name: The name of the job (e.g., "relax").
• @module, @class, @version: Metadata used to re-create the document model from a dictionary.
• index: An integer index.
• metadata: A dictionary for additional metadata.
• hosts: A list of host identifiers.

These schemas are implemented using pydantic.BaseModel, providing data type validation (e.g., guaranteeing name is a str).

[
  {
   "uuid":"c2b5eb7d-838b-4dee-896f-95f21867b62b",
   "index":1,
   "output":{...},
   "completed_at":"2024-05-19T17:13:46.400349",
   "metadata":{},
   "hosts":["dbaebabf-134d-426a-b91c-15abf799da65"],
   "name":"relax",
   "@module":"jobflow.core.schemas",
   "@class":"JobStoreDocument",
   "@version":"0.1.17"
   }
]

atomate2 uses MongoDB to store calculation results and workflow state details (when using FireWorks).

Requirements

• A running MongoDB instance accessible by your worker nodes (compute nodes).
• A database created with an account having admin access.
• You must record the hostname, port, and credentials to configure jobflow later.

Hosting Options

1. MongoDB Atlas: A commercial hosting service. The free tier (500 MB) is sufficient for small to medium projects.
2. HPC Hosting: Check if your supercomputing center (e.g., NERSC) provides MongoDB hosting.
3. Self-hosting: Running your own server (requires careful network/firewall configuration).

Troubleshooting Connectivity

If your compute nodes cannot reach the MongoDB server due to firewalls, consider:

• Requesting your computing center to allow connections to your MongoDB server.
• Hosting the database on the supercomputing network itself.
• Using a proxy service like mongo-proxy to forward connections.
• Setting up an SSH tunnel (must be kept alive during workflow execution).

An InputSet is a dict-like container used to manage and write input files for various computational codes (e.g., VASP, Q-Chem, LAMMPS). It is a core class from pymatgen used within atomate2 to handle the setup of calculation parameters.

Key capabilities:

• Writing files: Use .write_input(directory, ...) to generate the actual files on disk.
• Loading files: Use the .from_directory(directory) classmethod to reconstruct an InputSet from existing files.
• Validation: Many implementations (like VaspInputSet) provide an .is_valid property to check for conflicting settings before running a calculation.

For specific codes, use the corresponding InputGenerator classes to create predefined 'recipes' for tasks like structural relaxation or band structure calculations.

class InputSet(MSONable, MutableMapping):
    def write_input(
        self,
        directory: str | Path,
        make_dir: bool = True,
        overwrite: bool = True,
        zip_inputs: bool = False,
    ):
        """Write Inputs to one or more files."""
        pass

    @classmethod
    def from_directory(cls, directory: str | Path):
        """Construct an InputSet from a directory of one or more files."""
        pass