Streamline screening workflows

.github/workflows/docs.yml

@@ -14,18 +14,18 @@ jobs:
   build-docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0  # setuptools_scm needs the tags/history
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - name: Install the package and docs dependencies
         run: python -m pip install -e ".[docs]"
       - name: Build the documentation
-        run: python -m sphinx -b html docs docs/_build/html
+        run: python -m sphinx -W --keep-going -b html docs docs/_build/html
       - name: Upload the Pages artifact
-        uses: actions/upload-pages-artifact@v3
+        uses: actions/upload-pages-artifact@v5
         with:
           path: docs/_build/html
 
@@ -48,4 +48,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/publish.yml

@@ -14,10 +14,10 @@ jobs:
     permissions:
       id-token: write  # OIDC token for Trusted Publishing
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0  # setuptools_scm needs the tags
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - name: Build sdist and wheel

.github/workflows/python-app.yml

@@ -1,6 +1,3 @@
-# This workflow will install Python dependencies, run tests and lint with a single version of Python
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python
-
 name: Python application
 
 on:
@@ -18,12 +15,14 @@ permissions:
 jobs:
   build:
 
-    runs-on: ubuntu-latest   
+    runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v4
-    - name: Set up Python 3.12 with conda
-      uses: actions/setup-python@v3
+    - uses: actions/checkout@v7
+      with:
+        fetch-depth: 0
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v7
       with:
         python-version: "3.12"
     - name: Add conda to system path
@@ -34,22 +33,21 @@ jobs:
       run: |
         conda install -y -c conda-forge python=3.12 gsl dftbplus
         python -m pip install --upgrade pip
-        pip install . 
+        python -m pip install '.[test,lint]'
     - name: Lint with Pylint
-      run: |
-        pip install '.[lint]'
-        python -m pylint ThermoScreening
+      run: python -m pylint ThermoScreening
     - name: Test with pytest
+      run: python -m pytest --cov=ThermoScreening --cov-report=xml
+    - name: Build package
       run: |
-        pip install '.[test]'
-        python -m pytest --cov=ThermoScreening --cov-report=xml 
-      shell: bash
+        python -m pip install build
+        python -m build
 
     - name: Upload coverage to Codecov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v7
       with:
         token: ${{ secrets.CODECOV_TOKEN }}
-        env_vars: OS,PYTHON
+        files: ./coverage.xml
         fail_ci_if_error: true
         flags: unittests
         verbose: true

README.md

@@ -30,27 +30,30 @@ python -m sphinx -b html docs docs/_build/html   # open docs/_build/html/index.h
 
 ## Installation
 
-Install the package from a checkout:
+Install the released package:
 
 ```bash
-python -m pip install .
+python -m pip install thermoscreening
 ```
 
-For development and tests:
+For a complete environment with DFTB+, native xTB, and tblite:
 
 ```bash
-python -m pip install -e ".[test,lint]"
+conda create -n thermoscreening -c conda-forge \
+    python=3.12 dftbplus xtb tblite-python pip
+conda activate thermoscreening
+python -m pip install thermoscreening
 ```
 
-For a Conda-based development environment with all calculation backends
-(DFTB+, `modes`, xtb, tblite) included:
+From a source checkout, the equivalent development environment is:
 
 ```bash
 conda env create -f environment.yml
 conda activate thermoscreening
 ```
 
-Then `thermo doctor` should report every backend as found.
+Run `thermo doctor` to report the usable engines, or check one explicitly with
+`thermo doctor --engine dftb+`.
 
 ## DFTB+ Setup
 
@@ -65,25 +68,22 @@ Install DFTB+ with Conda if it is not already available:
 conda install -c conda-forge dftbplus
 ```
 
-Download the default `3ob-3-1` Slater-Koster files into a user-local directory:
+Download the default `3ob-3-1` Slater-Koster files into the automatically
+discovered user-local directory:
 
 ```bash
 thermo setup-dftb
 ```
 
-The command prints the `DFTB_PREFIX` export needed by DFTB+ and ThermoScreening:
-
-```bash
-export DFTB_PREFIX="$HOME/.local/share/thermoscreening/slakos/3ob-3-1/"
-```
-
-Add that line to your shell configuration for persistent use. Verify the setup with:
+Verify the setup with:
 
 ```bash
 thermo doctor
 ```
 
-ThermoScreening does not vendor Slater-Koster files. For custom installations, point the calculator to a parameter directory with `DFTB_PREFIX` or pass `slako_dir` explicitly:
+ThermoScreening does not vendor Slater-Koster files. For custom installations,
+override the discovered directory with `DFTB_PREFIX` or pass `slako_dir`
+explicitly:
 
 ```python
 from ThermoScreening.thermo.api import dftbplus_thermo
@@ -101,7 +101,16 @@ The bundled DFTB+ parameters were removed from the repository because they are l
 Run thermochemistry from an input file with the command-line entry point:
 
 ```bash
-thermo path/to/thermo.in
+thermo run path/to/thermo.in
+```
+
+The historic `thermo path/to/thermo.in` form remains supported.
+
+Run a complete reference-calibrated redox screen locally or as a Slurm array:
+
+```bash
+thermo redox molecules.csv --engine xtb-cli --solvent acetonitrile -o redox
+thermo slurm --tasks 32 --submit -- redox molecules.csv -o redox
 ```
 
 Use the Python API when integrating ThermoScreening into another workflow:

ThermoScreening/calculator/dftbplus.py

@@ -8,6 +8,13 @@
 from ase.calculators.dftb import Dftb
 from ase.io import read
 
+from ThermoScreening.dftb_data import (
+    DEFAULT_PARAMETER_SET,
+    REQUIRED_PARAMETER_FILE,
+    canonical_parameter_set,
+    default_parameter_dir,
+)
+
 from ..utils.physicalConstants import PhysicalConstants
 
 # --------------------------------------------------------------------------- #
@@ -34,12 +41,19 @@ def _read_hessian_matrix(filename, size):
     return values.reshape(size, size)
 
 
-def _slako_dir(slako_dir=None):
+def resolve_slako_dir(slako_dir=None, parameter_set=DEFAULT_PARAMETER_SET):
+    """Resolve an explicit, configured, or downloaded parameter directory."""
     selected_dir = slako_dir or os.getenv("DFTB_PREFIX")
+    if not selected_dir:
+        downloaded = default_parameter_dir(parameter_set)
+        if (downloaded / REQUIRED_PARAMETER_FILE).is_file():
+            selected_dir = downloaded
     if not selected_dir:
         raise FileNotFoundError(
             "Slater-Koster files are not bundled with ThermoScreening. "
-            "Set DFTB_PREFIX or pass slako_dir to the DFTB+ calculator."
+            f"Run 'thermo setup-dftb --parameter-set "
+            f"{canonical_parameter_set(parameter_set).split('-', maxsplit=1)[0]}', "
+            "set DFTB_PREFIX, or pass slako_dir explicitly."
         )
 
     selected_dir = os.path.abspath(os.path.expanduser(selected_dir))
@@ -51,6 +65,10 @@ def _slako_dir(slako_dir=None):
     return selected_dir + os.sep
 
 
+def _slako_dir(slako_dir=None, parameter_set=DEFAULT_PARAMETER_SET):
+    return resolve_slako_dir(slako_dir, parameter_set)
+
+
 # Atomic spin constants (Hartree): the spin constant of the highest occupied
 # shell per element (Wss for H, Wpp for the p-block, valence Wss for the s-block
 # and Zn), used with ShellResolvedSpin = No to match the atom-resolved SCC. These
@@ -245,7 +263,7 @@ def _dispersion_kwargs(dispersion=None):
 
 class Geoopt(Dftb):
     """
-    Custom DFTB+ calculator to optimize the system with the 'GeometryOptimisation' driver (Rational).
+    Custom DFTB+ calculator using the ``GeometryOptimisation`` Rational driver.
     It is a subclass of ase.calculators.dftb.Dftb. It uses the
     'LBFGS' driver.
 
@@ -258,8 +276,8 @@ class Geoopt(Dftb):
     charge : int
         Charge of the system. Default is 0.
     slako_dir : str
-        Path to the Slater-Koster files. If None, it will look for
-        the DFTB_PREFIX environment variable.
+        Path to the Slater-Koster files. If None, use ``DFTB_PREFIX`` or the
+        user-local set downloaded by ``thermo setup-dftb``.
     max_force : float
         Maximum force component. Default is 1.0e-6.
 
@@ -275,6 +293,7 @@ def __init__(
         label="geo_opt",
         charge=0,
         slako_dir=None,
+        parameter_set=DEFAULT_PARAMETER_SET,
         max_force=1.0e-6,
         **kwargs,
     ):
@@ -290,8 +309,8 @@ def __init__(
         charge : int
             Charge of the system. Default is 0.
         slako_dir : str
-            Path to the Slater-Koster files. If None, it will look
-            for the DFTB_PREFIX environment variable.
+            Path to the Slater-Koster files. If None, use ``DFTB_PREFIX`` or the
+            automatically discovered downloaded set.
         max_force : float
             Maximum force component. Default is 1.0e-6.
 
@@ -304,7 +323,7 @@ def __init__(
         super().__init__(
             atoms=atoms,
             label=label,
-            slako_dir=_slako_dir(slako_dir),
+            slako_dir=_slako_dir(slako_dir, parameter_set),
             Hamiltonian_Charge=charge,
             Driver_="GeometryOptimisation",
             Driver_Optimiser="Rational {}",
@@ -361,8 +380,8 @@ class Hessian(Dftb):
     charge : int
         Charge of the system. Default is 0.
     slako_dir : str
-        Path to the Slater-Koster files. If None, it will look for
-        the DFTB_PREFIX environment variable.
+        Path to the Slater-Koster files. If None, use ``DFTB_PREFIX`` or the
+        user-local downloaded set.
 
     Other Parameters:
     -----------------
@@ -377,6 +396,7 @@ def __init__(
         charge=0,
         delta=1.0e-4,
         slako_dir=None,
+        parameter_set=DEFAULT_PARAMETER_SET,
         **kwargs,
     ):
         """
@@ -393,8 +413,8 @@ def __init__(
         delta : float
             Finite difference step. Default is 1.0e-4.
         slako_dir : str
-            Path to the Slater-Koster files. If None, it will look
-            for the DFTB_PREFIX environment variable.
+            Path to the Slater-Koster files. If None, use ``DFTB_PREFIX`` or the
+            automatically discovered downloaded set.
 
         Other Parameters:
         -----------------
@@ -405,7 +425,7 @@ def __init__(
         super().__init__(
             atoms=atoms,
             label=label,
-            slako_dir=_slako_dir(slako_dir),
+            slako_dir=_slako_dir(slako_dir, parameter_set),
             Hamiltonian_Charge=charge,
             Driver_="SecondDerivatives",
             Driver_Delta=delta,