Jl/v3

.github/workflows/ci.yml

@@ -105,16 +105,16 @@ jobs:
 
   docs:
     runs-on: ubuntu-latest
+    timeout-minutes: 20
     steps:
       - uses: actions/checkout@v5
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
           cache: pip
           cache-dependency-path: pyproject.toml
-      # nbsphinx shells out to pandoc for markdown cells; the Read the Docs
-      # image ships it, GitHub's runner image does not guarantee it.
-      - run: sudo apt-get update && sudo apt-get install -y pandoc
+      - uses: pandoc/actions/setup@v1
+      - run: pip install torch --index-url https://download.pytorch.org/whl/cpu
       - run: pip install -e ".[doc]"
       - if: github.event_name == 'schedule'
         run: pip install -e ".[mace]"

.github/workflows/python-publish.yml

@@ -11,9 +11,6 @@ name: Upload Python Package
 on:
   release:
     types: [published]
-  # Dry run of the same job against TestPyPI: `git push origin testpypi-<n>`.
-  push:
-    tags: ["testpypi-*"]
 
 permissions:
   contents: read
@@ -33,18 +30,10 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         pip install build
-    # TestPyPI accepts every version only once, so each test run uploads its own
-    # dev version and the release version stays free.
-    - name: Use a dev version for TestPyPI
-      if: github.event_name == 'push'
-      run: |
-        sed -i -E 's/^__version__ = "([^"]+)"/__version__ = "\1.dev${{ github.run_number }}"/' src/schnetpack/__init__.py
-        grep '^__version__' src/schnetpack/__init__.py
     - name: Build package
       run: python -m build
     - name: Publish package
       uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
       with:
         user: __token__
-        password: ${{ github.event_name == 'release' && secrets.PYPI_API_TOKEN || secrets.TEST_PYPI_API_TOKEN }}
-        repository_url: ${{ github.event_name == 'release' && 'https://upload.pypi.org/legacy/' || 'https://test.pypi.org/legacy/' }}
+        password: ${{ secrets.PYPI_API_TOKEN }}

.pre-commit-config.yaml

@@ -2,8 +2,25 @@
 ci:
   autoupdate_schedule: monthly
   autofix_prs: true
+  skip: [jupytext-sync]
 
 repos:
+  # The tutorials and how-tos are tracked as jupytext .py files; the paired .ipynb is
+  # gitignored (see examples/jupytext.toml). This hook makes sure that jupytext .py files
+  # are synced with locally modified notebooks.
+  - repo: local
+    hooks:
+      - id: jupytext-sync
+        name: jupytext sync
+        entry: >-
+          bash -c 'find examples/howtos examples/tutorials_deprecated -name "*.ipynb"
+          -not -path "*/.ipynb_checkpoints/*" -print0 | xargs -0 -r -n1 jupytext --sync'
+        language: python
+        additional_dependencies: ["jupytext==1.19.5"]
+        # the .ipynb is gitignored, so pre-commit never sees it staged
+        always_run: true
+        pass_filenames: false
+
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: v0.16.2
     hooks:

docs/userguide/md.rst

@@ -19,6 +19,11 @@ The inputs which need to be provided for every ``spkmd`` run are:
 * the path to a trained ML model (``calculator.model_file``)
 * and the cutoff used in the neighbor list (``calculator.neighbor_list.cutoff``)
 
+.. warning::
+
+   Model files, checkpoints and restart files are pickled PyTorch objects. Loading them executes code contained in
+   the file, so only use files from sources you trust.
+
 Assuming the model and structure file are present in the local directory, the  command line call would be::
 
     spkmd simulation_dir=mdtut_cli system.molecule_file=md_ethanol.xyz calculator.model_file=md_ethanol.model calculator.neighbor_list.cutoff=5.0

examples/README.md

@@ -14,15 +14,18 @@ jupytext --to notebook howtos/howto_batchwise_relaxations.py
 ```
 
 This writes `howto_batchwise_relaxations.ipynb` next to it, which you open in Jupyter as
-usual. The generated notebook is git-ignored, so any outputs you produce stay local.
-
-With jupytext installed you can also skip the conversion and open the `.py` directly from
-the JupyterLab file browser (*right-click → Open With → Notebook*). Your edits are then
+usual. With jupytext installed you can also skip the conversion and open the `.py` directly from the JupyterLab file browser (*right-click → Open With → Notebook*). Your edits are then
 written back to the `.py` automatically.
 
 If you just want to read them, the rendered versions are at
 [schnetpack.readthedocs.io](https://schnetpack.readthedocs.io).
 
+**For developers:** You can also edit the `.ipynb` in an editor that does not know about jupytext, such as
+VS Code. The `jupytext-sync` pre-commit hook writes every paired notebook back into its
+`.py` before a commit. If it rewrote a `.py`, the commit fails: `git add` the `.py` and
+commit again. A notebook you created from scratch gets a new `.py` that you have to
+`git add` yourself.
+
 ## Which ones CI executes
 
 Read the Docs and pull requests only render the examples. The weekly `docs` CI job