Jl/manifest by jnsLs · Pull Request #790 · atomistic-machine-learning/schnetpack

jnsLs · 2026-08-10T13:25:51Z

Packaging, CI/CD and docs overhaul

Fixes a release bug that made spkmd unusable in every published wheel, replaces black with ruff, unifies the workflows, and switches the tutorials to jupytext.

Fixes

Release bug: md_configs/**/*.yaml was never included in wheels/sdists, so spkmd was broken in any non-editable install. The build job now asserts the config counts and py.typed are present in the wheel and smoke-tests all five console scripts from a venv install.
.github was listed in .gitignore, so workflow changes were invisible to git — removed.
import schnetpack was broken: eleven modules imported from their own package's init instead of the defining module, which only worked by accident of star-import ordering.
Neighbor-list cache errors were swallowed by bare except/print (a Ctrl-C during teardown looked like a hang); all NL backends now convert torch→numpy consistently.
Invalid escape sequences in the source (SyntaxWarning today, SyntaxError later), guarded by a new whole-source test that re-parses every file — a filterwarnings entry alone can't catch these once pycache is warm.

Packaging

py.typed added.
Scripts are real [project.scripts] entry points instead of script-files; spkconvert/spkdeploy moved into the package as schnetpack.cli_scripts.
Runtime deps cleaned up — black, pytest, pre-commit, protobuf, progressbar were being installed for every user. New test/dev/doc extras; version floors tightened (ase>=3.23, hydra-core>=1.3,<2, pytorch_lightning>=2.2,<3, setuptools>=70.1.0).

CI/CD

Single ci.yml (lint / test py3.12+3.13 / slow / build / docs) replacing black.yml, with concurrency cancellation and push-only-on-master so PRs don't run twice. Coverage is printed with --cov-report=term-missing; slow/download tests are deselected there and run in a Monday cron, so they read as uncovered in the PR run.
Publish workflow uses PyPI Trusted Publishing (OIDC), with build and publish as separate jobs so the credential-holding job never runs build code.
black → ruff (check + format); pre-commit is the single source of truth foace/YAML/merge-conflict hooks. tox.ini deleted, Makefile added so local runsmatch CI by construction.
pytest strict = true, registered slow/download markers, error::SyntaxWarni

Docs

Docs are now CI-gated: sphinx-build -W on every PR (render-only), full not cron, RTD fail_on_warning: true and installs the doc extra(sphinx-requirements.txt deleted). This is what would have caught the ase Exntly broke RTD.
conf.py rewritten: no autodoc_mock_imports, version read from installed metadata, examples/ copied in at build time instead of symlinked (symlinks broke nbsphinx figure paths).
Tutorials/how-tos stored as jupytext py:percent files to avoid diff noise. Per-notebook nbsphinx.execute flag controls what the docs build runs. Instructions in examples/README.md.
API .rst cleanup, improved SchNet/embedding docstrings, references added to the getting-started page.

Everything else in the diff is ruff formatting and import sorting.

Before merge

Register the Trusted Publisher on PyPI (repo atomistic-machine-learnin-publish.yml, environment pypi) and create the pypi GitHub environment — the job fails without it, even with OIDC set up. Drop PYPI_API_TOKEN after the first succesful release.
Version is still 2.2.0; the release also carries the breaking data-API changes from AtomsDataset and DataModule Refactor #781, so it needs a bump and a CHANGELOG / migration note.

Known gaps

py.typed is shipped but no type checker runs anywhere — the type information is unverified.
Coverage is log-only (no upload, badge, or threshold); failures of the weekly slow/docs jobs notify no one.
CI is Linux-only, latest-torch-only (the torch>=2.5 floor is never exercised), no GPU/DDP job.

…ments.txt

Follow-up to moving dev/doc dependencies into optional-dependency extras. Fix a bare `.github` entry in .gitignore that silently excluded any new file under that directory. The two existing workflows were tracked only because they predated the entry; adding a test workflow was impossible until this was removed. Add a Tests workflow. The suite previously never ran in CI, so releases were published to PyPI without a test gate. pyproject.toml: - drop `wheel` from build-system requires, unused by setuptools.build_meta - drop `readthedocs-sphinx-search` from the doc extra; its entry point sphinx_search.extension is not registered in docs/conf.py - collapse the dev extra to `black[jupyter]==24.4.2`; the separate bare `black==24.4.2` resolved to the same distribution - add [project.urls] Format notebooks consistently: the dev extra declared black[jupyter], but the pre-commit hook and CI installed plain black, which skips .ipynb files without failing. Switch the hook to black-jupyter and install the jupyter extra in CI. All 7 tracked notebooks are already compliant, so this is a no-op on file contents. Also pin the black workflow to Python 3.12, refresh its actions to checkout@v4 / setup-python@v5, and update tox envlist from py38 to py312 to match requires-python >=3.12. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/conf.py hardcoded version/release as "2.0-dev0" while the package is at 2.2.0, so the published docs advertised the wrong version. Read it from the installed distribution instead, matching the dynamic version pyproject.toml already builds from. Read the Docs installs the package (`path: .`), so the metadata is available at build time; fall back to a placeholder when it is not. getstarted.rst told users to `pip install tensorboard`, but tensorboard has been a hard runtime dependency since it was added to `dependencies`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Keeps draft plans and working notes out of the repository while leaving them in the working tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR modernizes SchNetPack’s development and documentation workflow by shifting dev/test/doc dependencies into pyproject.toml extras, updating CI for Python 3.12, and refining documentation/tutorial content (including reference formatting and example correctness). It also includes a small functional adjustment to neighbor list construction for ASE-based backends by converting torch tensors to NumPy before creating ASE Atoms.

Changes:

Add/update CI workflows (tests + Black) and align tooling with Python 3.12 and notebook formatting.
Move dev/test/doc dependencies into optional extras and update tox/Read the Docs configuration accordingly.
Improve docs/docstrings and tutorial notebooks for clarity, correctness, and consistent references.

Reviewed changes

Copilot reviewed 42 out of 43 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tox.ini	Updates tox envs to Python 3.12 and installs extras for test/qa runs.
src/schnetpack/transform/neighborlist.py	Converts inputs to NumPy before constructing ASE `Atoms` for neighbor list computation.
src/schnetpack/representation/schnet.py	Docstring wording and references update.
src/schnetpack/representation/painn.py	Docstring expanded with reference context.
src/schnetpack/representation/field_schnet.py	Docstring formatting/line wrapping and reference spacing cleanup.
src/schnetpack/nn/radial.py	Adds a reference mention in the docstring.
src/schnetpack/nn/equivariant.py	Docstring updated to include reference context.
src/schnetpack/nn/embedding.py	Fixes/normalizes docstring indentation for args.
src/schnetpack/nn/blocks.py	Improves docstring with Sphinx class reference markup.
src/schnetpack/model/base.py	Adjusts docstring example formatting for Sphinx (literal block).
src/schnetpack/md/system.py	Docstring formatting tweaks (literal blocks).
src/schnetpack/md/simulator.py	Docstring bullet list formatting cleanup.
src/schnetpack/md/simulation_hooks/thermostats.py	Docstring restructuring for readability and references.
src/schnetpack/md/simulation_hooks/thermostats_rpmd.py	Docstring restructuring and spelling/formatting cleanup.
src/schnetpack/md/calculators/orca_calculator.py	Docstring clarity and literal markup fixes for `*`/templates.
src/schnetpack/md/calculators/base_calculator.py	Docstring literal markup fix for `*`.
src/schnetpack/interfaces/ase_interface.py	Module docstring reorganized for clarity and reference placement.
src/schnetpack/datasets/rmd17.py	Dataset docstring references formatted with proper links.
src/schnetpack/datasets/qm7x.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/omdb.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/md22.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/md17.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/materials_project.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/iso17.py	Dataset docstring reference formatting cleanup.
src/schnetpack/datasets/ani1.py	Dataset docstring reference formatting cleanup.
src/schnetpack/data/splitting.py	Docstring updated to reference `ASEAtomsData`.
src/schnetpack/atomistic/nuclear_repulsion.py	Docstring expanded with references and formatting.
src/schnetpack/atomistic/electrostatic.py	Docstring clarified and reference formatting improved.
src/schnetpack/atomistic/atomwise.py	Docstrings expanded with reference context and line wrapping.
readthedocs.yaml	Switches RTD install to use `doc` extra.
pyproject.toml	Moves dev/test/doc dependencies into extras and bumps core deps (e.g., ASE).
examples/tutorials/tutorial_05_materials.ipynb	Updates API usage (`ASEAtomsData.create`) and cell filter class; minor text fixes needed.
examples/tutorials/tutorial_04_molecular_dynamics.ipynb	Updates documentation link target in tutorial text.
docs/userguide/overview.rst	Updates user guide text for data classes and transforms; formatting tweaks.
docs/userguide/configs.rst	Minor RST link markup adjustments.
docs/sphinx-requirements.txt	Removed in favor of `doc` extra.
docs/Makefile	Enhances `clean` target to remove stale autosummary output.
docs/getstarted.rst	Updates getting started narrative and adds citations.
docs/conf.py	Dynamically reads package version, sets language, namespaces section labels, updates intersphinx.
.pre-commit-config.yaml	Switches to `black-jupyter` hook for notebook formatting.
.gitignore	Stops ignoring `.github` and adds `.plans/` to ignores.
.github/workflows/tests.yml	Adds a test workflow for pushes/PRs using Python 3.12 and `.[test]`.
.github/workflows/black.yml	Updates action versions, pins Python 3.12, installs `black[jupyter]`.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

jnsLs · 2026-08-10T14:42:51Z

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["setuptools", "wheel"]
+requires = ["setuptools"]


@copilot set setuptools >= 70.1.0 to safely remove wheel

Done — updated build-system.requires to ["setuptools>=70.1.0"] in commit Set setuptools>=70.1.0 in build-system requires.

 # The short X.Y version.
-version = "2.0-dev0"
-# The full version, including alpha/beta/rc tags.
-release = "2.0-dev0"
+version = ".".join(release.split(".")[:2])


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Co-authored-by: jnsLs <50694766+jnsLs@users.noreply.github.com>

…nd notebooks are not executed when building docs

…k output cleaner in precommit, modernized pyproject (project.scripts), test adopts, removed dead tox.ini, made markfile to run CI workflow locally

Commit ae82521 alphabetised the star-imports in the package __init__.py files but did not include the accompanying import fixes, so `import schnetpack` currently fails: ImportError: cannot import name 'SchNetPackCalculator' from partially initialized module 'schnetpack.md.calculators' Root cause: eleven modules imported from their own package's __init__ rather than from the module that defines the name, e.g. lj_calculator.py did `from schnetpack.md.calculators import SchNetPackCalculator`. That reaches back through the half-built package and only worked because the __init__ star-imported schnetpack_calculator on the preceding line - an undocumented, unenforced ordering constraint that any import sort breaks. Each is now imported from its defining sibling (`from .system import System`), which removes the ordering dependency entirely. isort is therefore no longer suppressed for __init__.py. Also adds __all__ to the four modules that were star-exported without one, which stopped their whole namespace leaking: schnetpack.md. simulation_hooks.h5py / .json / .np / .os and various typing helpers are no longer publicly reachable. Verified no real export was lost - only those 18 pollution names. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

teardown() used three bare `except: pass` clauses around cache cleanup. Besides hiding real filesystem failures, a bare except also catches KeyboardInterrupt, SystemExit and MemoryError - which is why pressing Ctrl-C during teardown could look like a hang. Each is now scoped to OSError and logged at debug level. The cache-write handler was worse: it caught Exception and then called print(e), so a failed write was invisible to anyone configuring logging. It now logs a warning with a traceback. Also fixes the implicit Optional on cache_workdir and sorts the imports. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

`"\_"` in a non-raw string is a SyntaxWarning today and becomes a SyntaxError in a future Python. The filterwarnings entry in pyproject cannot guard this on its own: SyntaxWarning is emitted at bytecode compile time, so it fires only on the first uncached compile and stays silent once __pycache__ is warm. Re-parsing every module from source makes the check deterministic. The test was verified non-vacuous: it fails on the pre-fix cli.py banners and passes on the current tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Both entries were inaccurate. B008 (function call in default argument) has zero hits in this codebase, so the ignore suppressed nothing and documented a pattern that is not used here. Removed. E741 was ignored globally on the grounds that `l` is angular momentum and `I` a moment of inertia. Only three of its six hits are physics - the spherical harmonic degree in nn/so3.py and nn/ops/so3.py, where the single-letter name matches the notation in the equations and is worth keeping. There is no `I` anywhere. The other three were just sloppy names and are renamed: a logger (cli.py), a line of text (qm9.py) and a length (test_data.py). E741 is now scoped to the two SO(3) modules instead of being off everywhere, so the rule applies to new code. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The notebooks carried metadata recording whose machine ran them -- kernelspec.display_name, language_info.version, leftover PyCharm cell blocks -- which churned on every save. Commit d9d6cb4 is a pure instance: its entire content is display_name -> "schnetpack" and version -> 3.13.13. A py:percent file has no metadata, no cell ids and no outputs by construction, so nbstripout and the --keep-id question it raised are removed outright. The .py is now the version-controlled source; opening one in Jupyter creates a paired .ipynb, which is gitignored. Docs are unaffected: they already rendered without outputs (nbsphinx_execute = "never"), toctree entries are extensionless, and nbsphinx reads the .py through jupytext via nbsphinx_custom_formats. Registering ".py" as a source suffix means conf.py and locally paired .ipynb have to be excluded, or Sphinx claims them as documents. Conversion is content-preserving: cell sources match the notebooks exactly and markdown differs only in trailing whitespace. Module-level imports were hoisted to the top of each file -- ruff exempts notebooks from E402 but not flat .py files -- which deduplicates two imports, and one indented `!wget` became urllib since jupytext comments magics out and would have left an empty if-block. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Storing the tutorials as jupytext .py files removed the obvious path of double-clicking an .ipynb, so say what replaces it: convert with `jupytext --to notebook`, open the .py directly in JupyterLab, or just read the rendered versions on readthedocs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

jnsLs and others added 8 commits August 10, 2026 11:46

refactor: update documentation dependencies and remove sphinx-require…

1b6f910

…ments.txt

Ignore local .plans/ working notes directory

e760e59

Keeps draft plans and working notes out of the repository while leaving them in the working tree. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

all nbh lists convert torch to numpy arrays consistently

b15099b

improved doc strings and cleaned up sphinx files

965f2d2

new schnet docstring

b54d762

Refactor docstring for SchNet class to improve readability and structure

fa3899b

Copilot AI lite review requested due to automatic review settings August 10, 2026 13:25

Copilot started reviewing on behalf of jnsLs August 10, 2026 13:26 View session

Copilot AI reviewed Aug 10, 2026

View reviewed changes

typo

597b866

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of jnsLs August 10, 2026 14:43 View session

Set setuptools>=70.1.0 in build-system requires

20dc891

Co-authored-by: jnsLs <50694766+jnsLs@users.noreply.github.com>

Copilot finished work on behalf of jnsLs August 10, 2026 14:44

Copilot started work on behalf of jnsLs August 10, 2026 14:58 View session

Copilot AI and others added 2 commits August 10, 2026 14:59

Fix version extraction to strip pre-release suffixes in docs/conf.py

96d2cd3

Co-authored-by: jnsLs <50694766+jnsLs@users.noreply.github.com>

Add missing re import in docs/conf.py

13ee9e7

Co-authored-by: jnsLs <50694766+jnsLs@users.noreply.github.com>

Copilot finished work on behalf of jnsLs August 10, 2026 15:01

jnsLs and others added 6 commits August 10, 2026 18:28

refactor: sphinx conf.py is cleaned up, no more using mock imports, a…

d89aa14

…nd notebooks are not executed when building docs

unified CI/CD workflows, switched from black to ruff, include noteboo…

ae82521

…k output cleaner in precommit, modernized pyproject (project.scripts), test adopts, removed dead tox.ini, made markfile to run CI workflow locally

jnsLs marked this pull request as draft August 11, 2026 11:44

jnsLs added 4 commits August 12, 2026 08:58

removed test adopts

c3473f4

slow tests are solely run weekly but not after push or PR

3c88603

testing only for latest torch

f0725a1

test py3.12 and py3.13

5353c74

jnsLs and others added 5 commits August 12, 2026 10:43

fix: update CI badge and add Ruff badge in README

23066c4

test nb CI

d9d6cb4

docs are checked in CI

a8a91ed

jnsLs marked this pull request as ready for review August 12, 2026 12:53

Navigation Menu

Uh oh!

Jl/manifest - #790

Jl/manifest#790
jnsLs wants to merge 27 commits into
devfrom
jl/manifest

jnsLs commented Aug 10, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

jnsLs Aug 10, 2026

Uh oh!

Copilot AI Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

jnsLs commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

jnsLs Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jnsLs commented Aug 10, 2026 •

edited

Loading