Merge remote-tracking branch 'upstream/main'

Author: esoteric-ephemera

.github/workflows/docs.yml

@@ -33,8 +33,15 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          pip install "setuptools==77.0.3"
           pip install .[strict,docs]
 
+      - name: Copy tutorials
+        run: |
+          cp -r tutorials docs/
+          jupyter nbconvert --to markdown docs/tutorials/*.ipynb
+          jupyter nbconvert --to markdown docs/tutorials/*/*.ipynb
+
       - name: Build
         run: sphinx-build docs docs_build
 

.github/workflows/testing.yml

@@ -58,7 +58,7 @@ jobs:
 
       - name: Install conda dependencies
         run: |
-          micromamba install -n a2 -c conda-forge enumlib packmol bader openbabel openff-toolkit==0.16.2 openff-interchange==0.3.22 --yes
+          micromamba install -n a2 -c conda-forge enumlib packmol bader --yes
 
       - name: Install dependencies
         run: |
@@ -87,7 +87,8 @@ jobs:
         # However this `splitting-algorithm` means that tests cannot depend sensitively on the order they're executed in.
         run: |
           micromamba activate a2
-          pytest --splits 3 --group ${{ matrix.split }} --durations-path tests/.pytest-split-durations --splitting-algorithm least_duration --ignore=tests/ase --cov=atomate2 --cov-report=xml
+          pytest --splits 3 --group ${{ matrix.split }} --durations-path tests/.pytest-split-durations --splitting-algorithm least_duration --ignore=tests/ase --ignore=tests/openff_md --ignore=tests/openmm_md --cov=atomate2 --cov-report=xml
+
 
       - uses: codecov/codecov-action@v1
         if: matrix.python-version == '3.10' && github.repository == 'materialsproject/atomate2'
@@ -96,6 +97,62 @@ jobs:
           name: coverage${{ matrix.split }}
           file: ./coverage.xml
 
+  test-openff:
+    # prevent this action from running on forks
+    if: github.repository == 'materialsproject/atomate2'
+
+    services:
+      local_mongodb:
+        image: mongo:4.0
+        ports:
+          - 27017:27017
+
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0} # enables conda/mamba env activation by reading bash profile
+    strategy:
+      matrix:
+        python-version: ["3.10","3.11","3.12"]
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up micromamba
+        uses: mamba-org/setup-micromamba@main
+
+      - name: Create mamba environment
+        run: |
+          micromamba create -n a2 python=${{ matrix.python-version }} --yes
+
+      - name: Install uv
+        run: micromamba run -n a2 pip install uv
+
+      - name: Install conda dependencies
+        run: |
+          micromamba install -n a2 -c conda-forge enumlib packmol bader openbabel openff-toolkit==0.16.2 openff-interchange==0.3.22 --yes
+
+      - name: Install dependencies
+        run: |
+          micromamba activate a2
+          python -m pip install --upgrade pip
+          uv pip install .[strict-openff,tests]
+
+      - name: Install pymatgen from master if triggered by pymatgen repo dispatch
+        if: github.event_name == 'repository_dispatch' && github.event.action == 'pymatgen-ci-trigger'
+        run: |
+          micromamba activate a2
+          uv pip install --upgrade 'git+https://github.com/materialsproject/pymatgen@${{ github.event.client_payload.pymatgen_ref }}'
+
+      - name: Test split ${{ matrix.split }}
+        env:
+          MP_API_KEY: ${{ secrets.MP_API_KEY }}
+
+        run: |
+          micromamba activate a2
+          pytest tests/{openff_md,openmm_md}
+
   test-notebooks-and-ase:
     # prevent this action from running on forks
     if: github.repository == 'materialsproject/atomate2'
@@ -148,9 +205,11 @@ jobs:
         run: uv pip install --upgrade 'git+https://github.com/materialsproject/pymatgen@${{ github.event.client_payload.pymatgen_ref }}'
 
       - name: Test Notebooks
+        env:
+          MP_API_KEY: ${{ secrets.MP_API_KEY }}
         run: |
           micromamba activate a2
-          pytest --nbmake ./tutorials --ignore=./tutorials/openmm_tutorial.ipynb
+          pytest --nbmake ./tutorials --ignore=./tutorials/openmm_tutorial.ipynb --ignore=./tutorials/force_fields
 
       - name: Test ASE
         env:
@@ -165,6 +224,81 @@ jobs:
           token: ${{ secrets.CODECOV_TOKEN }}
           file: ./coverage.xml
 
+  test-force-field-notebook:
+    # prevent this action from running on forks
+    if: github.repository == 'materialsproject/atomate2'
+
+    services:
+      local_mongodb:
+        image: mongo:4.0
+        ports:
+          - 27017:27017
+
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -l {0} # enables conda/mamba env activation by reading bash profile
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up micromamba
+        uses: mamba-org/setup-micromamba@main
+
+      - name: Create mamba environment
+        run: |
+          micromamba create -n a2 python=${{ matrix.python-version }} --yes
+
+      - name: Install uv
+        run: micromamba run -n a2 pip install uv
+
+      - name: Install conda dependencies
+        run: |
+          micromamba install -n a2 -c conda-forge enumlib packmol bader openbabel openff-toolkit==0.16.2 openff-interchange==0.3.22 --yes
+
+      - name: Install dependencies
+        run: |
+          micromamba activate a2
+          python -m pip install --upgrade pip
+          mkdir -p ~/.abinit/pseudos
+          cp -r tests/test_data/abinit/pseudos/ONCVPSP-PBE-SR-PDv0.4 ~/.abinit/pseudos
+          uv pip install .[strict,strict-forcefields,tests,abinit]
+          uv pip install torch-runstats
+          uv pip install --no-deps nequip==0.5.6
+
+      - name: Install pymatgen from master if triggered by pymatgen repo dispatch
+        if: github.event_name == 'repository_dispatch' && github.event.action == 'pymatgen-ci-trigger'
+        run: |
+          micromamba activate a2
+          uv pip install --upgrade 'git+https://github.com/materialsproject/pymatgen@${{ github.event.client_payload.pymatgen_ref }}'
+
+      - name: Forcefield tutorial
+        env:
+          MP_API_KEY: ${{ secrets.MP_API_KEY }}
+
+        # regenerate durations file with `pytest --store-durations --durations-path tests/.pytest-split-durations`
+        # Note the use of `--splitting-algorithm least_duration`.
+        # This helps prevent a test split having no tests to run, and then the GH action failing, see:
+        # https://github.com/jerry-git/pytest-split/issues/95
+        # However this `splitting-algorithm` means that tests cannot depend sensitively on the order they're executed in.
+        run: |
+          micromamba activate a2
+          pytest --nbmake ./tutorials/force_fields
+
+
+      - uses: codecov/codecov-action@v1
+        if: matrix.python-version == '3.10' && github.repository == 'materialsproject/atomate2'
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          name: coverage
+          file: ./coverage.xml
+
+
+
   docs:
     runs-on: ubuntu-latest
 
@@ -186,7 +320,7 @@ jobs:
         run: sphinx-build docs docs_build
 
   automerge:
-    needs: [lint, test-non-ase, test-notebooks-and-ase, docs]
+    needs: [lint, test-non-ase, test-notebooks-and-ase, test-force-field-notebook, docs]
     runs-on: ubuntu-latest
 
     permissions:

.gitignore

@@ -5,6 +5,8 @@ docs/_build/*
 docs/_build/*/*
 docs/_build/*/*/*
 docs_build/*
+docs/tutorials/*
+docs/tutorials/*/*
 
 # C extensions
 *.so

.pre-commit-config.yaml

@@ -7,6 +7,7 @@ repos:
   hooks:
   - id: ruff
     args: [--fix]
+    exclude: tutorials/grueneisen_workflow.ipynb
   - id: ruff-format
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v5.0.0

README.md

@@ -13,7 +13,7 @@ Atomate2 is a free, open-source software for performing complex materials scienc
 workflows using simple Python functions. Features of atomate2 include
 
 - It is built on open-source libraries: [pymatgen], [custodian], [jobflow], and
-  [FireWorks].
+  [jobflow-remote] or [FireWorks].
 - A library of "standard" workflows to compute a wide variety of desired materials
   properties.
 - The ability scale from a single material, to 100 materials, or 100,000 materials.
@@ -81,8 +81,8 @@ See the [installation] steps for details how to set all of this up.
 
 In this example, we execute the workflow immediately. In many cases, you might want
 to perform calculations on several materials simultaneously. To achieve this, all
-atomate2 workflows can be run using the [FireWorks] software. See the
-[documentation][atomate2_fireworks] for more details.
+atomate2 workflows can be run using the [jobflow-remote] or [FireWorks] software. See the
+[jobflow-remote-specific documentation][atomate2-jobflow-remote] or [fireworks-specific documentation][atomate2_fireworks] for more details.
 
 ## Installation
 
@@ -96,6 +96,7 @@ started:
 
 - [Introduction to running workflows][running-workflows]
 - [Using atomate2 with FireWorks][atomate2_fireworks]
+- [Overview of key concepts][key-concepts]
 - [List of VASP workflows][vasp_workflows]
 
 ## Need help?
@@ -140,6 +141,7 @@ A journal submission of `atomate2` is undergoing peer review. In the meantime, p
 [pymatgen]: https://pymatgen.org
 [fireworks]: https://materialsproject.github.io/fireworks/
 [jobflow]: https://materialsproject.github.io/jobflow/
+[jobflow-remote]: https://github.com/Matgenix/jobflow-remote
 [custodian]: https://materialsproject.github.io/custodian/
 [VASP]: https://www.vasp.at
 [AMSET]: https://hackingmaterials.lbl.gov/amset/
@@ -151,7 +153,9 @@ A journal submission of `atomate2` is undergoing peer review. In the meantime, p
 [contributors]: https://materialsproject.github.io/atomate2/about/contributors.html
 [license]: https://raw.githubusercontent.com/materialsproject/atomate2/main/LICENSE
 [running-workflows]: https://materialsproject.github.io/atomate2/user/running-workflows.html
+[key-concepts]: https://materialsproject.github.io/atomate2/user/key_concepts_overview.html#key-concepts-in-atomate2-job-flow-makers-inputset-taskdocument-and-builder
 [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
 [RelaxBandStructure]: https://materialsproject.github.io/atomate2/user/codes/vasp.html#relax-and-band-structure
 [Lobster]: http://www.cohp.de

docs/dev/vasp_tests.md

@@ -146,6 +146,28 @@ name. For example, there cannot be two calculations called "relax". Instead you
 should ensure they are named something like "relax 1" and "relax 2".
 ```
 
+### 2a. Dealing with larger amounts of test data / directories.
+
+Some complex workflows and tutorials might require a larger than normal amount of test data to execute.
+You might also realize that a branching workflow requires many steps, leading to a sprawling reference directory structure.
+In this case, you may want to use separate tools in `atomate2` which bundle your VASP test data into JSON format archives.
+To do this for a single VASP calculation directory, you might run:
+
+```python
+from atomate2.utils.testing.vasp import VaspTestData
+
+vasp_test_data = VaspTestData.from_directory(
+    "/Users/alex/atomate2/job_2021-11-08-17-24-31-799852-28250"
+)
+vasp_test_data.to_file("tight_relax_1.json.lzma")
+```
+
+You can use any other compression method supported by `monty.io.zpath`, such as GZIP (`.gz`) or bzip2 (`.bz2`).
+The LZMA compression method is shown here because this offers generally the highest compression ratio of the three and is fairly quick to decompress, but it is CPU intensive to compress.
+
+The `VaspTestData` class handles removal of POTCAR copyright information, converting them to POTCAR.spec files as before.
+The test infrastructure using `mock_vasp` is also equipped to handle extraction of VASP files from a compressed JSON archive.
+
 ## 3. Copy the test data folder into atomate2
 
 You can now copy the WF_NAME folder into the atomate2 test files. VASP test files live
@@ -283,10 +305,25 @@ def test_elastic(mock_vasp, clean_dir):
     )
 ```
 
-Note that the `mock_vasp` and `clean_dir` arguments to the test function are
+<b>Note:</b> The `mock_vasp` and `clean_dir` arguments to the test function are
 [pytest fixtures](https://docs.pytest.org/en/6.2.x/fixture.html) and are essential
 for the test to run successfully.
 
+<b>Note:</b> If you used the `VaspTestData` method of creating JSON archives for the test data, you would use the following for `ref_paths`:
+
+```py
+ref_paths = {
+    "elastic relax 1/6": "Si_elastic/elastic_relax_1_6.json.lzma",
+    "elastic relax 2/6": "Si_elastic/elastic_relax_2_6.json.lzma",
+    "elastic relax 3/6": "Si_elastic/elastic_relax_3_6.json.lzma",
+    "elastic relax 4/6": "Si_elastic/elastic_relax_4_6.json.lzma",
+    "elastic relax 5/6": "Si_elastic/elastic_relax_5_6.json.lzma",
+    "elastic relax 6/6": "Si_elastic/elastic_relax_6_6.json.lzma",
+    "tight relax 1": "Si_elastic/tight_relax_1.json.lzma",
+    "tight relax 2": "Si_elastic/tight_relax_2.json.lzma",
+}
+```
+
 ```{warning}
 For `mock_vasp` to work correctly, all imports needed for the test must be
 imported in the test function itself (rather than at the top of the file).

docs/index.md

@@ -4,10 +4,13 @@
 user/index
 user/install
 user/running-workflows
+user/key_concepts_overview
 user/docs-schemas-emmet
+user/jobflow-remote
 user/fireworks
 user/atomate-1-vs-2
 user/codes/index
+tutorials/tutorials
 ```
 
 ```{toctree}