Merge branch 'main' into main

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_language_version:
   python: python3
 repos:
 - repo: https://github.com/charliermarsh/ruff-pre-commit
-  rev: v0.1.11
+  rev: v0.1.13
   hooks:
   - id: ruff
     args: [--fix]
@@ -35,7 +35,6 @@ repos:
     files: ^src/
     additional_dependencies:
     - tokenize-rt==4.1.0
-    - types-pkg_resources==0.1.2
     - types-paramiko
 - repo: https://github.com/codespell-project/codespell
   rev: v2.2.6

README.md

@@ -53,7 +53,7 @@ calculations will be performed:
 4. A non-self-consistent calculation on a high symmetry k-point path (for the line mode
    band structure).
 
-```python
+```py
 from atomate2.vasp.flows.core import RelaxBandStructureMaker
 from jobflow import run_locally
 from pymatgen.core import Structure

docs/dev/vasp_tests.md

@@ -59,7 +59,7 @@ The script should also contain some additional code that will allow
 `atm dev vasp-test-data` to process the reference data. Below we give an example
 used to generate the elastic constant workflow test data.
 
-```python
+```py
 from atomate2.vasp.flows.elastic import ElasticMaker
 from atomate2.vasp.powerups import update_user_kpoints_settings
 from pymatgen.core import Structure
@@ -161,7 +161,7 @@ The most important part is the section that mocks VASP and configures which chec
 to perform on the input files. For the elastic constant workflow, it looks something like
 this:
 
-```python
+```py
 # mapping from job name to directory containing test files
 ref_paths = {
     "elastic relax 1/6": "Si_elastic/elastic_relax_1_6",
@@ -214,7 +214,7 @@ the k-point density during the test.
 Finally, you should add `assert` statements to validate the workflow outputs. As an
 example, the full elastic workflow test is reproduced below.
 
-```python
+```py
 def test_elastic(mock_vasp, clean_dir):
     import numpy as np
     from jobflow import run_locally

docs/dev/workflow_tutorial.md

@@ -6,7 +6,7 @@ Every `atomate2` workflow is an instance of jobflow's `Flow ` class, which is a
 
 In the context of computational materials science, `Flow ` objects are most easily created by a `Maker`, which contains a factory method make() that produces a `Flow `, given certain inputs. Typically, the input to `Maker`.make() includes atomic coordinate information in the form of a `pymatgen` `Structure` or `Molecule` object. So the basic signature looks like this:
 
-```python
+```py
 class ExampleMaker(Maker):
     def make(self, coordinates: Structure) -> Flow:
         # take the input coordinates and return a `Flow `
@@ -18,7 +18,7 @@ The `Maker` class usually contains most of the calculation parameters and other
 One common task encountered in almost any materials science calculation is writing calculation input files to disk so they can be executed by the underlying software (e.g., VASP, Q-Chem, CP2K, etc.). This is preferably done via a `pymatgen` `InputSet` class. `InputSet` is essentially a dict-like container that specifies the files that need to be written, and their contents. Similarly to the way that `Maker` classes generate `Flow`s, `InputSet`s are most easily created by `InputGenerator` classes. `InputGenerator`
 have a method `get_input_set()` that typically takes atomic coordinates (e.g., a `Structure` or `Molecule` object) and produce an `InputSet`, e.g.,
 
-```python
+```py
 class ExampleInputGenerator(InputGenerator):
     def get_input_set(self, coordinates: Structure) -> InputSet:
         # take the input coordinates, determine appropriate
@@ -30,7 +30,7 @@ class ExampleInputGenerator(InputGenerator):
 
 **TODO - the code block below needs refinement. Not exactly sure how write_inputs() fits into a`Job`**
 
-```python
+```py
 class ExampleMaker(Maker):
     input_set_generator: ExampleInputGenerator = field(
         default_factory=ExampleInputGenerator

docs/user/atomate-1-vs-2.md

@@ -2,6 +2,7 @@
 
 This document contains introductory context for people coming from atomate 1.
 One of atomate2's core ideas is to allow scaling from a single material, to 100 materials, or 100,000 materials. Therefore, both local submission options and a connection to workflow managers such as FireWorks exist. We plan to support more workflow managers in the future to further ease job submission.
+
 ## Relation between managers running the actual jobs and the workflow as written in `atomate2`
 
 There is no leakage between job manager and the workflow definition in `atomate2`. For example, Fireworks is not a required dependency of `atomate2` or `jobflow`. Any `atomate2` workflow can be run using the local manager or an extensible set of external providers, Fireworks just one among them. E.g. all tests are run with mocked calls to the executables using the local manager.

docs/user/codes/vasp.md

@@ -260,7 +260,7 @@ LOBSTER_CMD: <<LOBSTER_CMD>>
 
 The corresponding flow could, for example, be started with the following code:
 
-```Python
+```py
 from jobflow import SETTINGS
 from jobflow import run_locally
 from pymatgen.core.structure import Structure
@@ -287,7 +287,7 @@ It is, however,  computationally very beneficial to define two different types o
 
 Specifically, you might want to change the `_fworker` for the LOBSTER runs and define a separate `lobster` worker within FireWorks:
 
-```python
+```py
 from fireworks import LaunchPad
 from jobflow.managers.fireworks import flow_to_workflow
 from pymatgen.core.structure import Structure
@@ -321,7 +321,7 @@ lpad.add_wf(wf)
 
 Outputs from the automatic analysis with LobsterPy can easily be extracted from the database and also plotted:
 
-```python
+```py
 from jobflow import SETTINGS
 from pymatgen.electronic_structure.cohp import Cohp
 from pymatgen.electronic_structure.plotter import CohpPlotter
@@ -339,15 +339,15 @@ result = store.query_one(
 )
 
 for number, (key, cohp) in enumerate(
-    result["output"]["lobsterpy_data"]["cohp_plot_data"].items()
+    result["output"]["lobsterpy_data"]["cohp_plot_data"]["data"].items()
 ):
     plotter = CohpPlotter()
     cohp = Cohp.from_dict(cohp)
     plotter.add_cohp(key, cohp)
     plotter.save_plot(f"plots_all_bonds{number}.pdf")
 
 for number, (key, cohp) in enumerate(
-    result["output"]["lobsterpy_data_cation_anion"]["cohp_plot_data"].items()
+    result["output"]["lobsterpy_data_cation_anion"]["cohp_plot_data"]["data"].items()
 ):
     plotter = CohpPlotter()
     cohp = Cohp.from_dict(cohp)
@@ -363,7 +363,7 @@ The inputs for a calculation can be modified in several ways. Every VASP job
 takes a {obj}`.VaspInputGenerator` as an argument (`input_set_generator`). One
 option is to specify an alternative input set generator:
 
-```python
+```py
 from atomate2.vasp.sets.core import StaticSetGenerator
 from atomate2.vasp.jobs.core import StaticMaker
 
@@ -382,7 +382,7 @@ The second approach is to edit the job after it has been made. All VASP jobs hav
 the `input_set_generator` attribute maker will update the input set that gets
 written:
 
-```python
+```py
 static_job.maker.input_set_generator.user_incar_settings["LOPTICS"] = True
 ```
 
@@ -392,7 +392,7 @@ functions called "powerups" that can apply settings updates to all VASP jobs in
 These powerups also contain filters for the name of the job and the maker used to
 generate them.
 
-```python
+```py
 from atomate2.vasp.powerups import update_user_incar_settings
 from atomate2.vasp.flows.elastic import ElasticMaker
 from atomate2.vasp.flows.core import DoubleRelaxMaker
@@ -485,7 +485,7 @@ There are two options when chaining workflows:
 These two examples are illustrated in the code below, where we chain a relaxation
 calculation and a static calculation.
 
-```python
+```py
 from jobflow import Flow
 from atomate2.vasp.jobs.core import RelaxMaker, StaticMaker
 from pymatgen.core.structure import Structure

docs/user/fireworks.md

@@ -13,9 +13,10 @@ FireWorks workflow using the {obj}`~jobflow.managers.fireworks.flow_to_workflow`
 The workflow can then be submitted to the launchpad in the usual way. For example, to
 submit an MgO band structure workflow using FireWorks:
 
-```python
+```py
 from fireworks import LaunchPad
 from atomate2.vasp.flows.core import RelaxBandStructureMaker
+from atomate2.vasp.powerups import add_metadata_to_flow
 from jobflow.managers.fireworks import flow_to_workflow
 from pymatgen.core import Structure
 
@@ -29,6 +30,14 @@ mgo_structure = Structure(
 # make a band structure flow to optimise the structure and obtain the band structure
 bandstructure_flow = RelaxBandStructureMaker().make(mgo_structure)
 
+# (Optional) add metadata to the flow task document.
+# Could be useful to filter specific results from the database.
+# For e.g., adding material project ID for the compound, use following lines
+bandstructure_flow = add_metadata_to_flow(
+    flow=bandstructure_flow,
+    additional_fields={"mp_id": "mp-190"},
+)
+
 # convert the flow to a fireworks WorkFlow object
 wf = flow_to_workflow(bandstructure_flow)
 

docs/user/install.md

@@ -5,14 +5,14 @@
 ## Introduction
 
 This guide will get you up and running in an environment for running high-throughput
-workflows with atomate2. atomate2 is built on the pymatgen, custodian, jobflow, and
-FireWorks libraries. Briefly:
+workflows with atomate2. atomate2 is built on the `pymatgen`, `custodian`, `jobflow`, and
+`FireWorks` libraries. Briefly:
 
-- [pymatgen] is used to create input files and analyze the output of materials science codes.
-- [custodian] runs your simulation code (e.g., VASP) and performs error checking/handling
+- [`pymatgen`] is used to create input files and analyze the output of materials science codes.
+- [`custodian`] runs your simulation code (e.g., VASP) and performs error checking/handling
   and checkpointing.
-- [jobflow] is used to design computational workflows.
-- [FireWorks] (optional) is used to manage and execute workflows on HPC machines.
+- [`jobflow`] is used to design computational workflows.
+- [`FireWorks`] (optional) is used to manage and execute workflows on HPC machines.
 
 Running and writing your own workflows are covered in later tutorials. For now, these
 topics will be covered in enough depth to get you set up and to help you know where to
@@ -21,10 +21,10 @@ troubleshoot if you're having problems.
 Note that this installation tutorial is VASP-centric since almost all functionality
 currently in atomate2 pertains to VASP.
 
-[pymatgen]: http://pymatgen.org
-[custodian]: https://materialsproject.github.io/custodian
-[fireworks]: https://materialsproject.github.io/fireworks
-[jobflow]: https://materialsproject.github.io/jobflow
+[`pymatgen`]: http://pymatgen.org
+[`custodian`]: https://materialsproject.github.io/custodian
+[`fireworks`]: https://materialsproject.github.io/fireworks
+[`jobflow`]: https://materialsproject.github.io/jobflow
 
 ### Objectives
 
@@ -76,16 +76,16 @@ MongoDB must be running and available to accept connections whenever you're runn
 workflows. Thus, it is strongly recommended that you have a server to run MongoDB or
 (simpler) use a hosting service. Your options are:
 
-- Use a commercial service to host your MongoDB instance. These are typically the
+1. Use a commercial service to host your MongoDB instance. These are typically the
   easiest to use and offer high-quality service but require payment for larger
   databases. [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) offers a free 500 MB
-  server which is certainly enough to get started for small to medium size projects, and
+  server which is certainly enough to get started for small to medium-sized projects, and
   it is easy to upgrade or migrate your database if you exceed the free allocation.
-- Contact your supercomputing center to see if they offer MongoDB hosting (e.g., NERSC
+1. Contact your supercomputing center to see if they offer MongoDB hosting (e.g., NERSC
   has this, Google "request NERSC MongoDB database").
-- Self-host a MongoDB server.
+1. Self-host a MongoDB server.
 
-If you're just starting, we suggest the first (with a free plan) or second option
+If you're just starting, we suggest option 1 (with a free plan) or 2
 (if available to you). The third option will require you to open up network settings to
 accept outside connections properly which can sometimes be tricky.
 
@@ -113,7 +113,7 @@ issues later in this tutorial, some options are:
 
 ## Create a directory scaffold for atomate2
 
-Installing atomate2 includes installation of codes, configuration files, and various
+Installing atomate2 includes the installation of codes, configuration files, and various
 binaries and libraries. Thus, it is useful to create a directory structure that
 organizes all these items.
 
@@ -140,7 +140,7 @@ Make sure to create a Python 3.8+ environment as recent versions of atomate2 onl
 support Python 3.8 and higher.
 ```
 
-We highly recommended that you organize your installation of the atomate2 and the other
+We highly recommend that you organize your installation of the atomate2 and the other
 Python codes using a conda virtual environment. Some of the main benefits are:
 
 - Different Python projects that have conflicting packages can coexist on the same
@@ -194,7 +194,7 @@ that are unique only to these databases.
 
 Create the following files in `<<INSTALL_DIR>>/config`.
 
-### jobflow.yaml
+### `jobflow.yaml`
 
 The `jobflow.yaml` file contains the credentials of the MongoDB server that will store
 calculation outputs. The `jobflow.yaml` file requires you to enter the basic database
@@ -351,14 +351,13 @@ workflows.
 ### Define the workflow
 
 Workflows are written using the `jobflow` software. Essentially, individual stages of
-a workflow are simple Python functions. Jobflow provides a way to connect jobs together
-in a natural way. For more details on connecting jobs together see:
-[](connecting_vasp_jobs).
+a workflow are simple Python functions. Jobflow provides a way to connect jobs in a natural way.
+For more details on connecting jobs see: [](connecting_vasp_jobs).
 
 Go to the directory where you would like your calculations to run (i.e., your scratch
 or work directory) and create a file called `relax.py` containing:
 
-```python
+```py
 from atomate2.vasp.jobs.core import RelaxMaker
 from jobflow import run_locally
 from pymatgen.core import Structure
@@ -416,7 +415,7 @@ on the Grid Engine scheduler, this would be using `qsub job.sh`.
 Once the job is finished, you can connect to the output database and check the job
 output.
 
-```python
+```py
 from jobflow import SETTINGS
 
 store = SETTINGS.JOB_STORE

docs/user/running-workflows.md

@@ -7,7 +7,7 @@
 Once you have a working installation of atomate2, you'll want to jump in and start
 running workflows. Atomate2 includes many workflows with reasonable settings that can
 get you started. This tutorial will quickly guide you through customizing and running a
-workflow to calculate the bandstructure of MgO.
+workflow to calculate the band structure of MgO.
 
 ### Objectives
 
@@ -16,7 +16,7 @@ workflow to calculate the bandstructure of MgO.
 
 ### Prerequisites
 
-In order for you to complete this tutorial you need
+For you to complete this tutorial you need
 
 * A working installation of atomate2.
 
@@ -60,7 +60,7 @@ workflow.
 
 Create a Python script named `mgo_bandstructure.py` with the following contents:
 
-```python
+```py
 from atomate2.vasp.flows.core import RelaxBandStructureMaker
 from jobflow import run_locally
 from pymatgen.core import Structure
@@ -116,7 +116,7 @@ results will be in your database.
 Finally, we'll plot the results that we calculated. Simply run the following Python
 code, either as a script or on the Python prompt.
 
-```python
+```py
 from jobflow import SETTINGS
 from pymatgen.electronic_structure.plotter import DosPlotter, BSPlotter
 from pymatgen.electronic_structure.dos import CompleteDos

pyproject.toml

@@ -42,7 +42,7 @@ amset = ["amset>=0.4.15", "pydash"]
 cclib = ["cclib"]
 mp = ["mp-api>=0.37.5"]
 phonons = ["phonopy>=1.10.8", "seekpath"]
-lobster = ["ijson>=3.2.2", "lobsterpy>=0.3.4"]
+lobster = ["ijson>=3.2.2", "lobsterpy>=0.3.6"]
 defects = ["dscribe>=1.2.0", "pymatgen-analysis-defects>=2022.11.30"]
 forcefields = [
     "ase>=3.22.1",
@@ -55,7 +55,7 @@ docs = [
     "FireWorks==2.0.3",
     "autodoc_pydantic==2.0.1",
     "furo==2023.9.10",
-    "ipython==8.19.0",
+    "ipython==8.20.0",
     "jsonschema[format]",
     "myst_parser==2.0.0",
     "numpydoc==1.6.0",
@@ -75,10 +75,10 @@ strict = [
     "click==8.1.7",
     "custodian==2023.10.9",
     "dscribe==2.1.0",
-    "emmet-core==0.75.2",
+    "emmet-core==0.76.2",
     "ijson==3.2.3",
     "jobflow==0.1.16",
-    "lobsterpy==0.3.4",
+    "lobsterpy==0.3.6",
     "mace-torch>=0.3.3",
     "matgl==0.9.1",
     "monty==2023.9.25",
@@ -87,7 +87,7 @@ strict = [
     "phonopy==2.21.0",
     "pydantic-settings==2.1.0",
     "pydantic==2.4.2",
-    "pymatgen-analysis-defects==2023.12.14",
+    "pymatgen-analysis-defects==2024.1.12",
     "pymatgen==2023.12.18",
     "quippy-ase==0.9.14",
     "seekpath==2.1.0",
@@ -157,7 +157,6 @@ ignore = [
     "PT006",   # pytest-parametrize-names-wrong-type
     "RUF013",  # implicit-optional
     # TODO remove PT011, pytest.raises() should always check err msg
-    "ANN001", # TODO remove this ignore
     "ANN002",
     "ANN003",
     "ANN101", # missing self type annotation