Merge branch 'main' into mol_for_forcefield

Author: JaGeo

.github/workflows/testing.yml

@@ -199,6 +199,7 @@ jobs:
           micromamba activate a2
           python -m pip install --upgrade pip
           uv pip install .[strict,tests]
+          uv pip install tblite>=0.4.0
 
       - name: Install pymatgen from master if triggered by pymatgen repo dispatch
         if: github.event_name == 'repository_dispatch' && github.event.action == 'pymatgen-ci-trigger'

CHANGELOG.md

@@ -1,5 +1,55 @@
 # Change log
 
+## v0.0.21
+
+### Bug Fixes 🐛
+* switch to CONTCAR read for LOBSTERTaskDoc by @naik-aakash in https://github.com/materialsproject/atomate2/pull/1204
+* cover cases where optimizer does additional steps even though step is set to 0 or 1 for writing xyz files by @JaGeo in https://github.com/materialsproject/atomate2/pull/1207
+* Remove walrus operator to avoid unassigned vmax by @Jonas-Finkler in https://github.com/materialsproject/atomate2/pull/1203
+### Enhancements 🛠
+* add file output xyz file including final atoms object to ase and forcefield jobs by @JaGeo in https://github.com/materialsproject/atomate2/pull/1206
+### Documentation 📖
+* Add video tutorials to README by @JaGeo in https://github.com/materialsproject/atomate2/pull/1191
+* be more concrete for tutorial video names in readme by @JaGeo in https://github.com/materialsproject/atomate2/pull/1192
+* Adding download statistics to readme by @JaGeo in https://github.com/materialsproject/atomate2/pull/1209
+
+## New Contributors
+* @Jonas-Finkler made their first contribution in https://github.com/materialsproject/atomate2/pull/1203
+
+**Full Changelog**: https://github.com/materialsproject/atomate2/compare/v0.0.20...v0.0.21
+
+## v0.0.20
+
+### Enhancements 🛠
+* Add MatPES forcefields by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1158
+* Add `DynamicOpenMMFlowMaker` for dynamic OpenMM Simulations by @shehan807 in https://github.com/materialsproject/atomate2/pull/1115
+* atomate2 / OpenMM OPLS-AA Enhancements by @shehan807 in https://github.com/materialsproject/atomate2/pull/1111
+* Add updated MP workflows + cleanup by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1139
+### Documentation 📖
+* Improve documentation LOBSTER and PHONON workflow by @JaGeo in https://github.com/materialsproject/atomate2/pull/1117
+* Add key concept tutorial to tutorial list in README by @QuantumChemist in https://github.com/materialsproject/atomate2/pull/1120
+* Fixing headline levels in key_concepts_overview.md by @QuantumChemist in https://github.com/materialsproject/atomate2/pull/1121
+* try to fix the doc by @JaGeo in https://github.com/materialsproject/atomate2/pull/1125
+* Added code snippets for Grüneisen, QHA and EOS wfs documentation by @QuantumChemist in https://github.com/materialsproject/atomate2/pull/1130
+* a few improvements for the tutorials by @QuantumChemist in https://github.com/materialsproject/atomate2/pull/1132
+* Update tutorials.md by @JaGeo in https://github.com/materialsproject/atomate2/pull/1138
+* Electrode workflow and documentation improvements by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1055
+* Update index.md by @JaGeo in https://github.com/materialsproject/atomate2/pull/1155
+### House-Keeping 🧹
+* More CI fixes by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1141
+### Other Changes
+* Pin MACE calculator version, add missing metadata to AseStructureTaskDoc by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1119
+* Tutorials for QHA and Grüneisen workflows by @JaGeo in https://github.com/materialsproject/atomate2/pull/1122
+* add more headlines to tutorials and fix a typo by @JaGeo in https://github.com/materialsproject/atomate2/pull/1126
+* Minor update to tutorials by @naik-aakash in https://github.com/materialsproject/atomate2/pull/1128
+* adjust example flow names by @QuantumChemist in https://github.com/materialsproject/atomate2/pull/1131
+* Aims phonon tutorials by @tpurcell90 in https://github.com/materialsproject/atomate2/pull/1136
+* fix gruneisen tutorial by @JaGeo in https://github.com/materialsproject/atomate2/pull/1142
+* fix link again for aims tutorial by @JaGeo in https://github.com/materialsproject/atomate2/pull/1143
+* Append name relax by @JaGeo in https://github.com/materialsproject/atomate2/pull/1150
+* add more info on jobflow-remote by @JaGeo in https://github.com/materialsproject/atomate2/pull/1154
+* Add example MP-compatible phase diagram tutorial by @esoteric-ephemera in https://github.com/materialsproject/atomate2/pull/1159
+
 ## v0.0.19
 
 ### Bug Fixes 🐛

README.md

@@ -4,8 +4,9 @@
 [![code coverage](https://img.shields.io/codecov/c/gh/materialsproject/atomate2)](https://codecov.io/gh/materialsproject/atomate2)
 [![pypi version](https://img.shields.io/pypi/v/atomate2?color=blue)](https://pypi.org/project/atomate2)
 ![supported python versions](https://img.shields.io/pypi/pyversions/atomate2)
-[![Zenodo](https://img.shields.io/badge/DOI-10.5281/zenodo.10677081-blue?logo=Zenodo&logoColor=white)](https://zenodo.org/records/10677081)
+[![Zenodo](https://img.shields.io/badge/DOI-10.5281/zenodo.10677080-blue?logo=Zenodo&logoColor=white)](https://doi.org/10.5281/zenodo.15603088)
 [![This project supports Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
+[![PyPI](https://img.shields.io/pypi/dm/atomate2.svg?maxAge=2592000)](https://pypi.python.org/pypi/atomate2)
 
 [Documentation][docs] | [PyPI][pypi] | [GitHub][github]
 
@@ -98,6 +99,14 @@ started:
 - [Using atomate2 with FireWorks][atomate2_fireworks]
 - [Overview of key concepts][key-concepts]
 - [List of VASP workflows][vasp_workflows]
+- [Executable tutorials for different workflows][tutorials]
+
+In March 2025, the first dedicated school on atomate2 (including the workflow language jobflow and the workflow manager jobflow-remote) took place, and one can access the video material here:
+
+- [Jobflow and Jobflow-remote][videotutorial1]
+- [atomate2][videotutorial2]
+- [Advanced Workflows in atomate2: Part 1][videotutorial3]
+- [Advanced Workflows in atomate2: Part 2][videotutorial4]
 
 ## Need help?
 
@@ -157,10 +166,15 @@ A journal submission of `atomate2` is undergoing peer review. In the meantime, p
 [atomate2_fireworks]: https://materialsproject.github.io/atomate2/user/fireworks.html
 [atomate2-jobflow-remote]: https://materialsproject.github.io/atomate2/user/jobflow-remote.html
 [vasp_workflows]: https://materialsproject.github.io/atomate2/user/codes/vasp.html
+[tutorials]: https://materialsproject.github.io/atomate2/tutorials/tutorials.html
 [RelaxBandStructure]: https://materialsproject.github.io/atomate2/user/codes/vasp.html#relax-and-band-structure
 [Lobster]: http://www.cohp.de
 [lobsterpy]: https://github.com/JaGeo/LobsterPy
 [phonopy]: https://github.com/phonopy/phonopy
 [docs]: https://materialsproject.github.io/atomate2/
 [github]: https://github.com/materialsproject/atomate2
 [pypi]: https://pypi.org/project/atomate2
+[videotutorial1]: https://lhumos.org/collection/0/680bb4d7e4b0f0d2028027ce
+[videotutorial2]: https://lhumos.org/collection/0/680bb4d3e4b0f0d2028027c9
+[videotutorial3]: https://lhumos.org/collection/0/680bb4d0e4b0f0d2028027c5
+[videotutorial4]: https://lhumos.org/collection/0/680bb4c7e4b0f0d2028027c1

docs/user/codes/vasp.md

@@ -97,7 +97,25 @@ functional. Full structural relaxation is performed.
 ### Double Relax
 
 Perform two back-to-back relaxations. This can often help avoid errors arising from
-Pulay stress.
+[Pulay stress](https://www.vasp.at/wiki/index.php/Pulay_stress).
+
+In short: While the cell size, shape, symmetry, etc. can change during a relaxation, the *k* point grid does not change with it.
+Additionally, the number of plane waves is held constant during a relaxation.
+Both features lead to artificial (numerical) stress due to under-convergence of a relaxation with respect to the basis set.
+To avoid this, we perform a single relaxation, and input its final structure to another relaxation calculation.
+At the start of the second relaxation, the *k*-point mesh and plane waves are adjusted to reflect the new symmetry of the cell.
+
+### Materials Project structure optimization
+
+The Materials Project hosts a large database of, among other physical properties, optimized structures and their associated total energy, formation enthalpy, and basic electronic structure properties.
+To generate this data, the Materials Project uses a simple double-relaxation followed by a final static calculation.
+While in principle, if the second relaxation calculation is converged, a final static calculation would not be needed.
+However, the second relaxation may have residual Pulay stress, and VASP averages some electronic structure data ([like the density of states](https://www.vasp.at/wiki/index.php/DOSCAR)) during a relaxation.
+Thus we need to perform a final single-point (static) calculation, usually using the corrected tetrahedron method (`ISMEAR=-5`) to ensure accurate electronic structure properties.
+
+The workflows used to produce PBE GGA or GGA+*U* and r<sup>2</sup>SCAN thermodynamic data are, respectively, `MPGGADoubleRelaxStaticMaker` and `MPMetaGGADoubleRelaxStaticMaker` in `atomate2.vasp.flows.mp`.
+Moving forward, the Materials Project prefers r<sup>2</sup>SCAN calculations, but maintains its older set of GGA-level data which currently has wider coverage.
+For documentation about the calculation parameters used, see the [Materials Project documentation.](https://docs.materialsproject.org/methodology/materials-methodology/calculation-details)
 
 ### Band Structure
 
@@ -616,6 +634,33 @@ written:
 static_job.maker.input_set_generator.user_incar_settings["LOPTICS"] = True
 ```
 
+To update *k*-points, use the `user_kpoints_settings` keyword argument of an input set generator.
+You can supply either a `pymatgen.io.vasp.inputs.Kpoints` object, or a `dict` containing certain [keys](https://github.com/materialsproject/pymatgen/blob/b54ac3e65e46b876de40402e8da59f551fb7d005/src/pymatgen/io/vasp/sets.py#L812).
+We generally recommend the former approach unless the user is familiar with the specific style of *k*-point updates used by `pymatgen`.
+For example, to use just the $\Gamma$ point:
+
+```py
+from pymatgen.io.vasp.inputs import Kpoints
+from atomate2.vasp.sets.core import StaticSetGenerator
+from atomate2.vasp.jobs.core import StaticMaker
+
+custom_gamma_only_set = StaticSetGenerator(user_kpoints_settings=Kpoints())
+gamma_only_static_maker = StaticMaker(input_set_generator=custom_gamma_only_set)
+```
+
+For those who are more familiar with manual *k*-point generation, you can use a VASP-style KPOINTS file or string to set the *k*-points as well:
+
+```py
+kpoints = Kpoints.from_str(
+    """Uniform density Monkhorst-Pack mesh
+0
+Monkhorst-pack
+5 5 5
+"""
+)
+custom_static_set = StaticSetGenerator(user_kpoints_settings=kpoints)
+```
+
 Finally, sometimes you have a workflow containing many VASP jobs. In this case it can be
 tedious to update the input sets for each job individually. Atomate2 provides helper
 functions called "powerups" that can apply settings updates to all VASP jobs in a flow.
@@ -663,8 +708,7 @@ modification of several additional VASP settings, such as the k-points
 
 If a greater degree of flexibility is needed, the user can define a default set of input
 arguments (`config_dict`) that can be provided to the {obj}`.VaspInputGenerator`.
-By default, the {obj}`.VaspInputGenerator` uses a base set of VASP input parameters
-from {obj}`.BaseVaspSet.yaml`, which each `Maker` is built upon. If desired, the user can
+By default, the {obj}`.VaspInputGenerator` uses a base set of VASP input parameters (`atomate2.vasp.sets.base._BASE_VASP_SET`), which each `Maker` is built upon. If desired, the user can
 define a custom `.yaml` file that contains a different base set of VASP settings to use.
 An example of how this can be done is shown below for a representative static
 calculation.

pyproject.toml

@@ -28,7 +28,7 @@ dependencies = [
     "PyYAML",
     "click",
     "custodian>=2024.4.18",
-    "emmet-core>=0.84.3rc3",
+    "emmet-core>=0.84.8",
     "jobflow>=0.1.11",
     "monty>=2024.12.10",
     "numpy",
@@ -51,7 +51,7 @@ defects = [
     "python-ulid>=2.7",
 ]
 forcefields = [
-    "ase>=3.23.0",
+    "ase>=3.25.0",
     "calorine>=3.0",
     "chgnet>=0.2.2",
     "mace-torch>=0.3.3",
@@ -62,11 +62,10 @@ forcefields = [
     "sevenn>=0.9.3",
     "torchdata<=0.7.1",                            # TODO: remove when issue fixed
 ]
-ase = ["ase>=3.23.0"]
-# tblite py3.12 support tracked in https://github.com/tblite/tblite/issues/198
-ase-ext = ["tblite>=0.3.0; python_version < '3.12'"]
+ase = ["ase>=3.25.0"]
+ase-ext = ["tblite>=0.3.0; platform_system=='Linux'"]
 openmm = [
-    "mdanalysis>=2.7.0",
+    "mdanalysis>=2.8.0",
     "openmm-mdanalysis-reporter>=0.1.0",
     "openmm>=8.1.0",
 ]
@@ -82,7 +81,7 @@ docs = [
     "sphinx-copybutton==0.5.2",
     "sphinx==8.1.3",
     "sphinx_design==0.6.1",
-    "jupyterlab==4.3.6",
+    "jupyterlab==4.4.2",
 ]
 dev = ["pre-commit>=2.12.1"]
 tests = [
@@ -95,27 +94,26 @@ tests = [
 ]
 strict = [
     "PyYAML==6.0.2",
-    "ase==3.24.0",
+    "ase==3.25.0",
     "cclib==1.8.1",
-    "click==8.1.7",
+    "click==8.2.0",
     "custodian==2025.4.14",
     "dscribe==2.1.1",
-    "emmet-core==0.84.5",
-    "ijson==3.3.0",
+    "emmet-core==0.84.8",
+    "ijson==3.4.0",
     "jobflow==0.1.19",
     "lobsterpy==0.4.9",
     "monty==2025.3.3",
-    "mp-api==0.45.4",
+    "mp-api==0.45.7",
     "numpy",
     "phonopy==2.30.1",
-    "pydantic-settings==2.8.1",
+    "pydantic-settings==2.9.1",
     "pydantic==2.11.3",
     "pymatgen-analysis-defects==2025.1.18",
     "pymatgen==2025.2.18",
     "pymongo==4.10.1",
     "python-ulid==3.0.0",
     "seekpath==2.1.0",
-    "tblite==0.3.0; python_version < '3.12'",
     "typing-extensions==4.13.2",
 ]
 strict-openff = [
@@ -125,8 +123,7 @@ strict-openff = [
     "mdareporter @ git+https://github.com/sef43/openmm-mdanalysis-reporter.git@86e8bdffb63bbe9b13430ba97e2a67b85c996048",
     "h5py==3.13",
     "openmm==8.1.1",
-    "pymatgen==2025.4.20", # TODO: open ff is extremely sensitive to pymatgen version
-    "mdanalysis==2.9.0"
+    "pymatgen==2024.11.13", # TODO: open ff is extremely sensitive to pymatgen version
 ]
 strict-forcefields = [
     "calorine==3.0",
@@ -187,6 +184,7 @@ exclude_lines = [
     '^\s*@overload( |$)',
     '^\s*assert False(,|$)',
     'if typing.TYPE_CHECKING:',
+    'if TYPE_CHECKING:',
 ]
 
 [tool.ruff]

src/atomate2/ase/jobs.py

@@ -254,7 +254,7 @@ def run_ase(
         if self.steps < 0:
             logger.warning(
                 "WARNING: A negative number of steps is not possible. "
-                "Behavior may vary..."
+                "Defaulting to a static calculation."
             )
 
         relaxer = AseRelaxer(

src/atomate2/ase/utils.py

@@ -16,6 +16,7 @@
 from ase.constraints import FixSymmetry
 from ase.filters import FrechetCellFilter
 from ase.io import Trajectory as AseTrajectory
+from ase.io import write as ase_write
 from ase.optimize import BFGS, FIRE, LBFGS, BFGSLineSearch, LBFGSLineSearch, MDMin
 from ase.optimize.sciopt import SciPyFminBFGS, SciPyFminCG
 from monty.serialization import dumpfn
@@ -328,14 +329,18 @@ def relax(
         fmax: float = 0.1,
         steps: int = 500,
         traj_file: str = None,
+        final_atoms_object_file: str | os.PathLike[str] = "final_atoms_object.xyz",
         interval: int = 1,
         verbose: bool = False,
         cell_filter: Filter = FrechetCellFilter,
+        filter_kwargs: dict | None = None,
         **kwargs,
     ) -> AseResult:
         """
         Relax the molecule or structure.
 
+        If steps <= 1, this will perform a single-point calculation.
+
         Parameters
         ----------
         atoms : ASE Atoms, pymatgen Structure, or pymatgen Molecule
@@ -346,6 +351,8 @@ def relax(
             Max number of steps for relaxation.
         traj_file : str
             The trajectory file for saving.
+        final_atoms_object_file: str | os.PathLike
+            The final atoms object file for saving.
         interval : int
             The step interval for saving the trajectories.
         verbose : bool
@@ -363,19 +370,23 @@ def relax(
 
         if isinstance(atoms, Structure | Molecule):
             atoms = self.ase_adaptor.get_atoms(atoms)
+
+        input_atoms = atoms.copy()
         if self.fix_symmetry:
             atoms.set_constraint(FixSymmetry(atoms, symprec=self.symprec))
         atoms.calc = self.calculator
         with contextlib.redirect_stdout(sys.stdout if verbose else io.StringIO()):
             obs = TrajectoryObserver(atoms)
-            if self.relax_cell and (not is_mol):
-                atoms = cell_filter(atoms)
-            optimizer = self.opt_class(atoms, **kwargs)
-            optimizer.attach(obs, interval=interval)
             t_i = time.perf_counter()
-            optimizer.run(fmax=fmax, steps=steps)
-            t_f = time.perf_counter()
+            if steps > 1:
+                if self.relax_cell and (not is_mol):
+                    atoms = cell_filter(atoms, **(filter_kwargs or {}))
+                optimizer = self.opt_class(atoms, **kwargs)
+                optimizer.attach(obs, interval=interval)
+                optimizer.run(fmax=fmax, steps=steps)
             obs()
+            t_f = time.perf_counter()
+
         if traj_file is not None:
             obs.save(traj_file)
         if isinstance(atoms, cell_filter):
@@ -389,6 +400,17 @@ def relax(
             np.linalg.norm(traj.frame_properties[-1]["forces"][idx]) < abs(fmax)
             for idx in range(len(struct))
         )
+
+        if final_atoms_object_file is not None:
+            if steps <= 1:
+                write_atoms = input_atoms
+                write_atoms.calc = self.calculator
+            else:
+                write_atoms = atoms
+            ase_write(
+                final_atoms_object_file, write_atoms, format="extxyz", append=True
+            )
+
         return AseResult(
             final_mol_or_struct=struct,
             trajectory=traj,

src/atomate2/common/flows/electrode.py

@@ -120,6 +120,10 @@ def make(
             relax = self.bulk_relax_maker.make(structure)
         else:
             relax = self.relax_maker.make(structure)
+
+        _shown_steps = str(n_steps) if n_steps else "inf"
+        relax.append_name(f" 0/{_shown_steps}")
+
         # add ignored_species to the structure matcher
         sm = _add_ignored_species(self.structure_matcher, inserted_element)
         # Get the inserted structure
@@ -132,6 +136,7 @@ def make(
             get_charge_density=self.get_charge_density,
             n_steps=n_steps,
             insertions_per_step=insertions_per_step,
+            n_inserted=1,
         )
         relaxed_summary = RelaxJobSummary(
             structure=relax.output.structure,