improve docs

Author: esoteric-ephemera

.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'

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

@@ -63,8 +63,7 @@ forcefields = [
     "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-ext = ["tblite>=0.3.0; platform_system=='Linux'"]
 openmm = [
     "mdanalysis>=2.7.0",
     "openmm-mdanalysis-reporter>=0.1.0",
@@ -115,7 +114,6 @@ strict = [
     "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 = [