Merge branch 'master' into fix-multi-branch-band-struct

.github/workflows/release.yml

@@ -66,6 +66,9 @@ jobs:
   release:
     needs: [build_wheels, build_sdist]
     runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pymatgen
     permissions:
       # For PyPI trusted publishing
       id-token: write
@@ -87,7 +90,3 @@ jobs:
         with:
           skip-existing: true
           verbose: true
-          repository-url: >
-            ${{ github.event_name == 'workflow_dispatch' &&
-            github.event.inputs.task == 'test-release' &&
-            'https://test.pypi.org/legacy/' || '' }}

.github/workflows/test.yml

@@ -61,36 +61,34 @@ jobs:
       - 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 pmg python=${{ matrix.config.python }} --yes
+        uses: mamba-org/setup-micromamba@main
+        with:
+          environment-name: pmg
+          create-args: >-
+            python=${{ matrix.config.python }}
 
       - name: Install ubuntu-only conda dependencies
         if: matrix.config.os == 'ubuntu-latest'
         run: |
           micromamba install -n pmg -c conda-forge bader enumlib \
             openff-toolkit packmol pygraphviz tblite --yes
 
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
       - name: Install pymatgen and dependencies via uv
         run: |
           micromamba activate pmg
-
-          pip install uv
-
           # TODO1 (use uv over pip) uv install torch is flaky, track #3826
           # TODO2 (pin torch version): DGL library (matgl) doesn't support torch > 2.2.1,
           # see: https://discuss.dgl.ai/t/filenotfounderror-cannot-find-dgl-c-graphbolt-library/4302
           pip install torch==2.2.1
 
           # Install from wheels to test the content
-          uv pip install build
-          python -m build --wheel
-
-          uv pip install dist/*.whl
-          uv pip install pymatgen[${{ matrix.config.extras }}] --resolution=${{ matrix.config.resolution }}
+          uv build --wheel --no-build-logs
+          WHEEL_FILE=$(ls dist/pymatgen*.whl)
+          uv pip install $WHEEL_FILE[${{matrix.config.extras}}] --resolution=${{matrix.config.resolution}}
 
       - name: Install optional Ubuntu dependencies
         if: matrix.config.os == 'ubuntu-latest'

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ ci:
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.7.2
+    rev: v0.8.1
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes]
@@ -36,7 +36,7 @@ repos:
         exclude: src/pymatgen/analysis/aflow_prototypes.json
 
   - repo: https://github.com/MarcoGorelli/cython-lint
-    rev: v0.16.2
+    rev: v0.16.6
     hooks:
       - id: cython-lint
         args: [--no-pycodestyle]
@@ -48,7 +48,7 @@ repos:
       - id: blacken-docs
 
   - repo: https://github.com/igorshubovych/markdownlint-cli
-    rev: v0.42.0
+    rev: v0.43.0
     hooks:
       - id: markdownlint
         # MD013: line too long
@@ -59,12 +59,12 @@ repos:
         args: [--disable, MD013, MD024, MD025, MD033, MD041, "--"]
 
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.0
+    rev: 0.8.1
     hooks:
       - id: nbstripout
         args: [--drop-empty-cells, --keep-output]
 
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.387
+    rev: v1.1.389
     hooks:
       - id: pyright

CONTRIBUTING.md

@@ -10,25 +10,29 @@ For developers interested in expanding `pymatgen` for their own purposes, we rec
 
 1. Create a free GitHub account (if you don't already have one) and perform the necessary setup (e.g., install SSH keys etc.).
 
-1. Fork the `pymatgen` GitHub repo, i.e., go to the main [`pymatgen` GitHub repo](https://github.com/materialsproject/pymatgen) and click fork to create a copy of the `pymatgen` code base on your own GitHub account.
+2. Fork the `pymatgen` GitHub repo, i.e., go to the main [`pymatgen` GitHub repo](https://github.com/materialsproject/pymatgen) and click fork to create a copy of the `pymatgen` code to your own GitHub account.
 
-1. Install `git` on your local machine (if you don't already have it).
+3. Install `git` on your local machine (if you haven't already).
 
-1. Clone *your forked repo* to your local machine. You will work mostly with your local repo and only publish changes when they are ready to be merged:
+4. Clone *your forked repo* to your local machine. You will work mostly with your local repo and only publish changes when they are ready to be merged:
 
     ```sh
     git clone https://github.com/<username>/pymatgen
+
+    # (Alternative/Much Faster) If you don't need a full commit history/other branches
+    # git clone --depth 1 https://github.com/<username>/pymatgen
+    # git pull --unshallow  # if you need the complete repo at some point
     ```
 
     Note that the entire Github repo is fairly large because of the presence of test files, but these are necessary for rigorous testing.
 
-1. Make a new branch for your contributions
+5. Make a new branch for your contributions:
 
     ```sh
     git checkout -b my-new-fix-or-feature # should be run from up-to-date master
     ```
 
-1. Code (see [Coding Guidelines](#coding-guidelines)). Commit early and commit often. Keep your code up to date. You need to add the main repository to the list of your remotes.
+6. Code (see [Coding Guidelines](#coding-guidelines)). Commit early and commit often. Keep your code up to date. You need to add the main repository to the list of your remotes:
 
     ```sh
     git remote add upstream https://github.com/materialsproject/pymatgen
@@ -48,19 +52,19 @@ For developers interested in expanding `pymatgen` for their own purposes, we rec
 
     Remember, pull is a combination of the commands fetch and merge, so there may be merge conflicts to be manually resolved.
 
-1. Publish your contributions. Assuming that you now have a couple of commits that you would like to contribute to the main repository. Please follow the following steps:
+7. Publish your contributions. Assuming that you now have a couple of commits that you would like to contribute to the main repository. Please follow the following steps:
 
     1. If your change is based on a relatively old state of the main repository, then you should probably bring your repository up-to-date first to see if the change is not creating any merge conflicts.
 
-    1. Check that everything compiles cleanly and passes all tests. The `pymatgen` repo comes with a complete set of tests for all modules. If you have written new modules or methods, you must write tests for the new code as well (see [Coding Guidelines](#coding-guidelines)). Install and run `pytest` in your local repo directory and fix all errors before continuing further.
+    2. Check that everything compiles cleanly and passes all tests. The `pymatgen` repo comes with a complete set of tests for all modules. If you have written new modules or methods, you must write tests for the new code as well (see [Coding Guidelines](#coding-guidelines)). Install and run `pytest` in your local repo directory and fix all errors before continuing further.
 
-    1. If everything is ok, publish the commits to your GitHub repository.
+    3. If everything is ok, publish the commits to your GitHub repository:
 
     ```sh
     git push origin master
     ```
 
-1. Now that your commit is published, it doesn't mean that it has already been merged into the main repository. You should issue a merge request to `pymatgen` maintainers. They will pull your commits and run their own tests before releasing.
+8. Now that your commit is published, it doesn't mean that it has already been merged into the main repository. You should issue a merge request to `pymatgen` maintainers. They will pull your commits and run their own tests before releasing.
 
 "Work-in-progress" pull requests are encouraged, especially if this is your first time contributing to `pymatgen`, and the maintainers will be happy to help or provide code review as necessary. Put "\[WIP\]" in the title of your pull request to indicate it's not ready to be merged.
 
@@ -69,24 +73,30 @@ For developers interested in expanding `pymatgen` for their own purposes, we rec
 Given that `pymatgen` is intended to be a long-term code base, we adopt very strict quality control and coding guidelines for all contributions to `pymatgen`. The following must be satisfied for your contributions to be accepted into `pymatgen`.
 
 1. **Unit tests** are required for all new modules and methods. The only way to minimize code regression is to ensure that all code is well-tested. Untested contributions will not be accepted.
-   To run the testsuite in you repository follow these steps
+   To run the testsuite in you repository follow these steps:
 
    ```sh
    cd path/to/repo
-   pip install -e .  # install the package in your environment as "editable" == dev package
-   PMG_TEST_FILES_DIR=$(pwd)/tests/files pytest tests  # run the test suite providing the path for the datafiles
+
+   # Option One (Recommended): Install in editable mode
+   pip install -e '.[ci]'  # or more optional dependencies
+   pytest tests
+
+   # Option Two: Use environment variable PMG_TEST_FILES_DIR
+   pip install '.[ci]'
+   PMG_TEST_FILES_DIR=$(pwd)/tests/files pytest tests  # run the test suite providing the path for the test files
    ```
 
-1. **Python PEP 8** [code style](https://python.org/dev/peps/pep-0008). We allow a few exceptions when they are well-justified (e.g., Element's atomic number is given a variable name of capital Z, in line with accepted scientific convention), but generally, PEP 8 must be observed. Code style will be automatically checked for all PRs and must pass before any PR is merged. To aid you, you can install and run the same set of formatters and linters that will run in CI using
+2. **PEP 8** [code style](https://python.org/dev/peps/pep-0008). We allow a few exceptions when they are well-justified (e.g., Element's atomic number is given a variable name of capital Z, in line with accepted scientific convention), but generally, PEP 8 should be observed. Code style will be automatically checked for all PRs and must pass before any PR is merged. To aid you, you can install and run the same set of formatters and linters that will run in CI using:
 
    ```sh
    pre-commit install  # ensures linters are run prior to all future commits
    pre-commit run --files path/to/changed/files  # ensure your current uncommitted changes don't offend linters
    # or
-    pre-commit run --all-files  # ensure your entire codebase passes linters
+   pre-commit run --all-files  # ensure your entire codebase passes linters
    ```
 
-1. **Python 3**. We only support Python 3.10+.
-1. **Documentation** is required for all modules, classes and methods. In particular, the method doc strings should make clear the arguments expected and the return values. For complex algorithms (e.g., an Ewald summation), a summary of the algorithm should be provided and preferably with a link to a publication outlining the method in detail.
+3. **Python 3**. We only support Python 3.10+.
+4. **Documentation** is required for all modules, classes and methods. We prefer [Google Style Docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html). In particular, the method doc strings should make clear the arguments expected and the return values. For complex algorithms (e.g., an Ewald summation), a summary of the algorithm should be provided and preferably with a link to a publication outlining the method in detail.
 
 For the above, if in doubt, please refer to the core classes in `pymatgen` for examples of what is expected.

README.md

@@ -21,7 +21,7 @@ Pymatgen (Python Materials Genomics) is a robust, open-source Python
 library for materials analysis. These are some of the main features:
 
 1. Highly flexible classes for the representation of `Element`, `Site`, `Molecule` and `Structure` objects.
-2. Extensive input/output support, including support for [VASP](https://cms.mpi.univie.ac.at/vasp), [ABINIT](https://abinit.org), [CIF](https://wikipedia.org/wiki/Crystallographic_Information_File), [Gaussian](https://gaussian.com), [XYZ](https://wikipedia.org/wiki/XYZ_file_format), and many other file formats.
+2. Extensive input/output support, including support for [VASP](https://www.vasp.at/), [ABINIT](https://abinit.github.io/abinit_web/), [CIF](https://wikipedia.org/wiki/Crystallographic_Information_File), [Gaussian](https://gaussian.com), [XYZ](https://wikipedia.org/wiki/XYZ_file_format), and many other file formats.
 3. Powerful analysis tools, including generation of phase diagrams, Pourbaix diagrams, diffusion analyses, reactions, etc.
 4. Electronic structure analyses, such as density of states and band structure.
 5. Integration with the [Materials Project] REST API.

dev_scripts/potcar_scrambler.py

@@ -164,7 +164,7 @@ def generate_fake_potcar_libraries() -> None:
                 zpath(f"{func_dir}/{psp_name}/POTCAR"),
             ]
             if not any(map(os.path.isfile, paths_to_try)):
-                warnings.warn(f"Could not find {psp_name} in {paths_to_try}")
+                warnings.warn(f"Could not find {psp_name} in {paths_to_try}", stacklevel=2)
             for potcar_path in paths_to_try:
                 if os.path.isfile(potcar_path):
                     os.makedirs(rebase_dir, exist_ok=True)

pyproject.toml

@@ -87,8 +87,7 @@ Issues = "https://github.com/materialsproject/pymatgen/issues"
 Pypi = "https://pypi.org/project/pymatgen"
 
 [project.optional-dependencies]
-# PR4128: netcdf4 1.7.[0/1] yanked, 1.7.1.post[1/2]/1.7.2 cause CI error
-abinit = ["netcdf4>=1.6.5,!=1.7.1.post1,!=1.7.1.post2,!=1.7.2"]
+abinit = ["netcdf4>=1.7.2"]
 ase = ["ase>=3.23.0"]
 ci = ["pytest-cov>=4", "pytest-split>=0.8", "pytest>=8"]
 docs = ["invoke", "sphinx", "sphinx_markdown_builder", "sphinx_rtd_theme"]
@@ -193,7 +192,6 @@ ignore = [
 
     # Single rules
     "B023",    # Function definition does not bind loop variable
-    "B028",    # No explicit stacklevel keyword argument found
     "B904",    # Within an except clause, raise exceptions with ...
     "C408",    # unnecessary-collection-call
     "D105",    # Missing docstring in magic method
@@ -293,12 +291,17 @@ module = ["requests.*", "tabulate.*"]
 ignore_missing_imports = true
 
 [tool.codespell]
-ignore-words-list = """
-titel,alls,ans,nd,mater,nwo,te,hart,ontop,ist,ot,fo,nax,coo,
-coul,ser,leary,thre,fase,rute,reson,titels,ges,scalr,strat,
-struc,hda,nin,ons,pres,kno,loos,lamda,lew,atomate,nempty
+# TODO: un-ignore "ist/nd/ot/ontop/CoO" once support file-level ignore with pattern
+ignore-words-list = """Nd, Te, titel, Mater,
+Hart, Lew, Rute, atomate,
+ist, nd, ot, ontop, CoO
+"""
+# TODO: un-skip lammps/test_inputs.py once support block ignore with pattern
+skip = """*.json,
+src/pymatgen/analysis/chemenv/coordination_environments/coordination_geometries_files/allcg.txt,
+src/pymatgen/entries/MPCompatibility.yaml,
+tests/io/lammps/test_inputs.py,
 """
-skip = "pymatgen/analysis/aflow_prototypes.json"
 check-filenames = true
 
 [tool.pyright]

src/pymatgen/alchemy/materials.py

@@ -362,7 +362,7 @@ def to_snl(self, authors: list[str], **kwargs) -> StructureNL:
             StructureNL: The generated StructureNL object.
         """
         if self.other_parameters:
-            warn("Data in TransformedStructure.other_parameters discarded during type conversion to SNL")
+            warn("Data in TransformedStructure.other_parameters discarded during type conversion to SNL", stacklevel=2)
         history = []
         for hist in self.history:
             snl_metadata = hist.pop("_snl", {})

src/pymatgen/analysis/bond_dissociation.py

@@ -30,7 +30,7 @@ class BondDissociationEnergies(MSONable):
     fragments, or, in the case of a ring bond, from the energy of the molecule obtained from breaking
     the bond and opening the ring. This class should only be called after the energies of the optimized
     principle molecule and all relevant optimized fragments have been determined, either from quantum
-    chemistry or elsewhere. It was written to provide the analysis after running an Atomate fragmentation
+    chemistry or elsewhere. It was written to provide the analysis after running an `atomate` fragmentation
     workflow.
     """
 
@@ -107,7 +107,8 @@ def __init__(
         if multibreak:
             warnings.warn(
                 "Breaking pairs of ring bonds. WARNING: Structure changes much more likely, meaning dissociation values"
-                " are less reliable! This is a bad idea!"
+                " are less reliable! This is a bad idea!",
+                stacklevel=2,
             )
             self.bond_pairs = []
             for ii, bond in enumerate(self.ring_bonds, start=1):
@@ -164,7 +165,8 @@ def fragment_and_process(self, bonds):
                         warnings.warn(
                             f"Missing ring opening fragment resulting from the breakage of {specie[bonds[0][0]]} "
                             f"{specie[bonds[0][1]]} bond {bonds[0][0]} {bonds[0][1]} which would yield a "
-                            f"molecule with this SMILES string: {smiles}"
+                            f"molecule with this SMILES string: {smiles}",
+                            stacklevel=2,
                         )
                     elif len(good_entries) == 1:
                         # If we have only one good entry, format it and add it to the list that will eventually return
@@ -212,14 +214,14 @@ def fragment_and_process(self, bonds):
                     smiles = pb_mol.write("smi").split()[0]
                     for charge in self.expected_charges:
                         if charge not in frag1_charges_found:
-                            warnings.warn(f"Missing {charge=} for fragment {smiles}")
+                            warnings.warn(f"Missing {charge=} for fragment {smiles}", stacklevel=2)
                 if len(frag2_charges_found) < len(self.expected_charges):
                     bb = BabelMolAdaptor(fragments[1].molecule)
                     pb_mol = bb.pybel_mol
                     smiles = pb_mol.write("smi").split()[0]
                     for charge in self.expected_charges:
                         if charge not in frag2_charges_found:
-                            warnings.warn(f"Missing {charge=} for fragment {smiles}")
+                            warnings.warn(f"Missing {charge=} for fragment {smiles}", stacklevel=2)
                 # Now we attempt to pair fragments with the right total charge, starting with only fragments with no
                 # structural change:
                 for frag1 in frag1_entries[0]:  # 0 -> no structural change