molscope 0.8.0__tar.gz → 0.8.2__tar.gz

molscope-0.8.2/CITATION.cff

@@ -0,0 +1,15 @@
+cff-version: 1.2.0
+message: "If you use MolScope in teaching, research, or software demos, please cite it."
+type: software
+title: "MolScope: lightweight molecular structure analysis, visualisation, graph export, and coarse-graining in Python"
+authors:
+  - family-names: Shrestha
+    given-names: Roshan
+version: 0.8.2
+date-released: "2026-05-28"
+license: MIT
+repository-code: "https://github.com/roshan2004/molscope"
+url: "https://github.com/roshan2004/molscope"
+abstract: >
+  MolScope is a lightweight Python toolkit for molecular structure analysis,
+  visualisation, descriptors, graph export, and coarse-graining workflows.

molscope-0.8.2/MANIFEST.in

@@ -0,0 +1,13 @@
+include CITATION.cff
+include LICENSE
+include README.md
+include mkdocs.yml
+include requirements.txt
+recursive-include docs *.md *.png
+recursive-include examples *.py
+recursive-include examples/data *.pdb *.xyz
+recursive-include notebooks *.ipynb
+recursive-include scripts *.py
+recursive-include tests *.py
+recursive-include tests/fixtures *.xyz *.pdb *.cif *.sdf
+prune notebooks/.ipynb_checkpoints

{molscope-0.8.0 → molscope-0.8.2}/PKG-INFO

@@ -1,11 +1,13 @@
 Metadata-Version: 2.4
 Name: molscope
-Version: 0.8.0
-Summary: Lightweight molecular structure analysis, visualisation, graph export, and coarse-graining in Python.
+Version: 0.8.2
+Summary: Lightweight molecular coordinate workflows for descriptors, graph ML, and coarse-grained beads.
 Author-email: Roshan Shrestha <roshanpra@gmail.com>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/roshan2004/molscope
 Project-URL: Repository, https://github.com/roshan2004/molscope
+Project-URL: Documentation, https://molscope.readthedocs.io/
+Project-URL: Issues, https://github.com/roshan2004/molscope/issues
 Keywords: chemistry,molecular-structure,pdb,xyz,mmcif,coarse-graining,molecular-graphs,machine-learning,visualization
 Classifier: Programming Language :: Python :: 3
 Classifier: Topic :: Scientific/Engineering :: Chemistry
@@ -17,6 +19,7 @@ Requires-Dist: numpy>=1.21
 Requires-Dist: matplotlib>=3.5
 Provides-Extra: test
 Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pytest-cov>=4; extra == "test"
 Provides-Extra: fast
 Requires-Dist: scipy>=1.7; extra == "fast"
 Provides-Extra: viz
@@ -27,6 +30,11 @@ Provides-Extra: chem
 Requires-Dist: rdkit>=2023.9; extra == "chem"
 Provides-Extra: cif
 Requires-Dist: gemmi>=0.7; extra == "cif"
+Provides-Extra: gpu
+Requires-Dist: torch>=2.0; extra == "gpu"
+Provides-Extra: validation
+Requires-Dist: mdanalysis>=2.7; extra == "validation"
+Requires-Dist: rdkit>=2023.9; extra == "validation"
 Provides-Extra: pyg
 Requires-Dist: torch>=2.0; extra == "pyg"
 Requires-Dist: torch-geometric>=2.3; extra == "pyg"
@@ -43,58 +51,105 @@ Dynamic: license-file
 # MolScope
 
 [![CI](https://github.com/roshan2004/molscope/actions/workflows/ci.yml/badge.svg)](https://github.com/roshan2004/molscope/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/roshan2004/molscope/branch/main/graph/badge.svg)](https://codecov.io/gh/roshan2004/molscope)
+[![Docs](https://readthedocs.org/projects/molscope/badge/?version=latest)](https://molscope.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/molscope.svg)](https://pypi.org/project/molscope/)
 [![Python](https://img.shields.io/badge/python-3.9%20%7C%203.11%20%7C%203.13-blue)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)
 [![Code style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
 
-Lightweight molecular structure analysis, visualisation, graph export, and
-coarse-graining in Python. Read `.xyz`, `.pdb`, `.cif` and `.sdf` files
-(optionally gzip-compressed), select and analyse atoms, and visualise them in
-3D. The `.cif` reader handles standard `_atom_site` coordinate loops, including
-quoted values; optional Gemmi-backed validation is available through
-`pip install "molscope[cif]"`.
+Lightweight molecular structure analysis, graph export, and coarse-graining in
+Python. MolScope is built around three polished workflows: turn coordinate
+files into descriptor tables, graph-ML inputs, or coarse-grained bead
+representations without pulling in a full simulation stack.
+
+Read `.xyz`, `.pdb`, `.cif` and `.sdf` files, select and analyse atoms, and
+visualise structures in 3D. Optional extras add Gemmi validation, RDKit chemical
+features, PyTorch Geometric, DGL, and other backend integrations only when a
+workflow needs them.
 
 | 3D structure (element) | Secondary structure (DSSP) | Residue contact map | Coarse-grained beads |
 | --- | --- | --- | --- |
 | ![Aquaporin-1 rendered as a 3D element-coloured molecular structure](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/aquaporin-structure-v2.png) | ![Aquaporin-1 coloured by DSSP secondary structure: helices red, turns cyan, coil grey](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/secondary-structure.png) | ![Residue-level contact map heatmap for Aquaporin-1](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/residue-contact-map.png) | ![Coarse-grained bead model of Aquaporin-1](https://raw.githubusercontent.com/roshan2004/molscope/main/docs/assets/readme/coarse-grained-beads-v2.png) |
 
-## What it does
-
-- **Read and write** XYZ, PDB, mmCIF and SDF (gzip-aware), preserve SDF/PDB
-  explicit bonds and SDF formal charges where present, fetch structures by id
-  from RCSB, and load multi-model NMR ensembles.
-- **Validate mmCIF** syntax, atom-site coordinate columns, and supplied
-  dictionary files with optional Gemmi support.
-- **Select and measure** by chain, element or residue; compute distances,
-  angles, dihedrals and Kabsch-aligned RMSD.
-- **Analyse** centroids, radius of gyration, the inertia tensor,
-  explicit/inferred bonds, and contacts.
-- **Contact maps** at atom or residue level, with heatmap plots.
-- **Secondary structure** via a self-contained, dependency-free DSSP, with
-  `plot(color_by="ss")`.
-- **Ensembles**: pairwise RMSD, RMSF, averaging, and conformer clustering.
-- **Export for ML**: flat structural descriptors and molecular graphs for
-  NetworkX, PyTorch Geometric and DGL.
-- **Chemical perception and descriptors**: optional RDKit-backed formal charge,
-  valence, aromaticity and scalar descriptor features with
-  `pip install "molscope[chem]"`.
-- **Coarse-grain** onto residue, Martini-style or custom bead mappings.
-- **Visualise** with 3D matplotlib plots, an interactive py3Dmol viewer, spin
-  GIFs, and a command-line interface.
+## Core workflows
 
-## Why MolScope?
+| Workflow | Start here | Output |
+| --- | --- | --- |
+| **PDB to descriptors** | [`docs/tutorials/pdb-to-descriptors.md`](docs/tutorials/pdb-to-descriptors.md) | Fixed-width structural and optional RDKit-backed feature tables for screening, QC, and classical ML. |
+| **PDB to graph/GNN** | [`docs/tutorials/pdb-to-graph-gnn.md`](docs/tutorials/pdb-to-graph-gnn.md) | Atom/bond, residue-contact, and PyTorch Geometric-ready graph data for message-passing experiments. |
+| **PDB to coarse-grained beads** | [`docs/tutorials/pdb-to-coarse-grained-beads.md`](docs/tutorials/pdb-to-coarse-grained-beads.md) | Residue, simplified Martini-style, custom, and virtual-site bead models for inspection and graph prototyping. |
+
+## Who is this for?
+
+- Students learning molecular-coordinate formats, structure analysis, and basic
+  visualisation from readable Python code.
+- Molecular modellers who want quick static-structure checks, selections,
+  contact maps, and lightweight coarse-grained mapping prototypes.
+- ML-for-molecules learners who need deterministic descriptors and graph exports
+  before moving to larger chemistry or simulation frameworks.
+
+## Supporting capabilities
+
+MolScope keeps the broad feature surface organized around those workflows:
+
+- **Input layer**: read and write XYZ, PDB, mmCIF and SDF, preserve explicit
+  bonds and charges where present, fetch structures from RCSB, and validate
+  mmCIF files with optional Gemmi support.
+- **Structure analysis**: select atoms by metadata, compute geometry, RMSD,
+  contacts, contact maps, interfaces, binding sites, and ensemble summaries.
+- **Annotations and descriptors**: run dependency-free secondary-structure
+  assignment, native structural descriptors, and optional RDKit-backed
+  chemistry descriptors.
+- **Representation outputs**: export descriptor tables, atom/bond graphs,
+  residue-contact graphs, and coarse-grained bead graphs to common ML backends.
+- **Inspection and automation**: visualize with Matplotlib or py3Dmol and use
+  the CLI for view, analyze, and export workflows.
+
+## Architecture
+
+```mermaid
+graph LR
+    A[XYZ, PDB, mmCIF, SDF files] --> B[read, fetch, validate]
+    B --> C[Molecule object]
+    C --> D[Geometry, contacts, DSSP, descriptors]
+    C --> E[Molecular graphs for NetworkX, PyG, DGL]
+    C --> F[Residue, simplified Martini-style, custom CG mappings]
+    C --> G[Matplotlib, py3Dmol, CLI visualisation]
+```
 
-MolScope is **not** intended to replace full molecular-simulation or
-cheminformatics frameworks. It is a lightweight **educational and prototyping**
-toolkit for reading common molecular structure files, performing simple
-structural analysis, exporting graph representations for ML workflows, and
-experimenting with coarse-grained mappings. Its core depends only on NumPy and
-Matplotlib, and the API is Python-first and scriptable.
+## Why MolScope?
 
-In particular, the coarse-graining tools are for **educational CG mapping and
-bead-graph prototyping**: useful for exploring mappings before moving to a
-production Martini workflow. They are not a validated Martini force-field
-generator.
+MolScope takes you from a structure file to a descriptor table, a
+machine-learning graph, or a coarse-grained model with the smallest install that
+gets the job done. The core depends only on NumPy and Matplotlib, so
+`pip install molscope` stays light. Everything heavier (RDKit, PyTorch, PyTorch
+Geometric, DGL, MDAnalysis, Gemmi) is an opt-in [extra](#install) you add only
+when one of those workflows needs it.
+
+That makes it an on-ramp rather than a framework:
+
+- **Structure to ML graph in a few lines.** `mol.to_graph()` runs with zero extra
+  dependencies; `mol.to_pyg_data()`, `mol.to_networkx()` and `mol.to_dgl_graph()`
+  hand off to the ecosystem when you want it. This is the path MolScope is built
+  to make easy.
+- **Descriptor tables without a framework.** Native structural descriptors and
+  optional RDKit-backed chemistry descriptors share the same `Molecule` and
+  batch-featurization APIs.
+- **CG as a representation tool.** Residue, simplified Martini-style, custom
+  bead, and virtual-site mappings are inspectable molecules and bead graphs,
+  not hidden simulation setup state.
+- **Light enough to teach and prototype with.** A readable, Python-first API over
+  static structures, with no trajectory engine or build step to wrestle.
+- **Honest about its numbers.** Bonds, geometry and DSSP are cross-checked against
+  reference tools (MDAnalysis, `mkdssp`) in CI, so you know where the results come
+  from.
+
+MolScope is **not** a replacement for full molecular-simulation or
+cheminformatics frameworks. In particular, the coarse-graining tools are for
+**educational CG mapping and bead-graph prototyping**: useful for exploring
+mappings before moving to a production Martini workflow, not a validated Martini
+force-field generator.
 
 | Tool | Main focus | How MolScope differs |
 | --- | --- | --- |
@@ -106,8 +161,8 @@ generator.
 | nglview | Notebook structure viewer | MolScope also does analysis, descriptors, graphs and CG, not just viewing |
 
 Reach for those tools when you need their depth and validation. Reach for
-MolScope when you want something small, readable, and quick to teach or
-prototype with.
+MolScope when you want the shortest path from a structure file to analysis, an
+ML graph, or a CG prototype.
 
 ## Install
 
@@ -115,7 +170,7 @@ With [uv](https://docs.astral.sh/uv/) (recommended):
 
 ```bash
 uv sync                     # creates .venv, installs deps + dev tools from the lockfile
-uv run molscope 1fqy.pdb  # run the CLI
+uv run molscope examples/data/1fqy.pdb  # run the CLI
 uv run pytest               # run the tests
 ```
 
@@ -125,6 +180,9 @@ uv run pytest               # run the tests
 With plain pip:
 
 ```bash
+pip install molscope
+
+# for local development from this checkout:
 python -m venv .venv && source .venv/bin/activate
 pip install -e ".[test]"    # or: pip install -r requirements.txt
 ```
@@ -142,25 +200,49 @@ python scripts/build_user_guide_pdf.py
 Docs source lives in `docs/`; the site configuration is `mkdocs.yml`. The PDF
 builder requires Pandoc and a LaTeX engine such as `xelatex`.
 
+Scientific validation is documented in
+[`docs/validation.md`](docs/validation.md): reference tools, assumptions,
+failure modes, and tolerances for MDAnalysis, RDKit, `mkdssp`, and invariant
+checks.
+
 ## Quickstart
 
 A runnable end-to-end tour over the bundled sample structures lives in
-[`example.py`](example.py):
+[`examples/tour.py`](examples/tour.py):
 
 ```bash
-uv run python example.py                  # opens 3D plot windows
-MPLBACKEND=Agg uv run python example.py   # headless: saves PNGs instead
+uv run python examples/tour.py                  # opens 3D plot windows
+MPLBACKEND=Agg uv run python examples/tour.py   # headless: saves PNGs instead
 ```
 
 It reads an `.xyz` and a `.pdb`, prints derived properties, compares the NMR
 models of `1aml`, writes a transformed structure back out, and renders a plot.
 
+For polished, focused workflows, start with the tutorials:
+[`PDB to descriptors`](docs/tutorials/pdb-to-descriptors.md),
+[`PDB to graph/GNN`](docs/tutorials/pdb-to-graph-gnn.md), and
+[`PDB to coarse-grained beads`](docs/tutorials/pdb-to-coarse-grained-beads.md).
+For coarse-graining as a runnable visual workflow, run
+[`examples/coarse_graining.py`](examples/coarse_graining.py): residue
+center-of-mass beads, residue centroids, and a simplified backbone/sidechain
+mapping with a visual atomistic-to-CG comparison.
+
+For protein-coordinate analysis from scratch, see
+[`docs/examples/protein-analysis-from-scratch.md`](docs/examples/protein-analysis-from-scratch.md)
+and [`notebooks/protein_analysis_from_scratch.ipynb`](notebooks/protein_analysis_from_scratch.ipynb):
+backbone atoms, residues, chains, alpha carbons, contact maps, NMR ensemble
+contacts, ligands, waters, binding sites, and simplified DSSP.
+
+For a runnable, narrated version of that ML walkthrough, open the notebook
+[`notebooks/pdb_to_gnn.ipynb`](notebooks/pdb_to_gnn.ipynb): structure file to a
+trained GNN, end to end (needs `pip install 'molscope[pyg]'`).
+
 ## Library
 
 ```python
 import molscope as ms
 
-mol = ms.read("1fqy.pdb")          # parser chosen from the extension
+mol = ms.read("examples/data/1fqy.pdb")  # parser chosen from the extension
 mol = ms.fetch("1fqy")             # ...or download straight from RCSB by id
 print(mol.summary())                # atoms, formula, chains, bounding box
 
@@ -193,6 +275,7 @@ mol[mask_or_indices]                # subset by numpy mask / index array
 mol.centroid, mol.center_of_mass    # geometric / mass-weighted centre
 mol.radius_of_gyration              # compactness (angstrom)
 mol.dimensions, mol.formula         # bounding box, Hill-order formula
+mol.distance_matrix()               # dense pairwise matrix (NumPy, Torch, CuPy)
 mol.bonds()                         # inferred bond index pairs (KD-tree if scipy)
 mol.contacts(cutoff=5.0)            # atom pairs within a distance
 mol.contact_count(cutoff=5.0)       # count pairs without returning them
@@ -246,15 +329,17 @@ mol.plot_contact_map(cutoff=8.0)                      # heatmap
 mol.contact_map(level="atom")                         # atom-level map
 mol.contact_map(level="residue", method="min")        # closest inter-residue atom
 mol.contact_map(level="residue", method="com")        # residue centre of mass
+mol.contact_map(level="residue", backend="torch", device="cuda")  # optional GPU
 ```
 
 ### Secondary structure (DSSP)
 
 Assign protein secondary structure from backbone hydrogen-bond patterns with a
-self-contained, pure-NumPy DSSP (no external `mkdssp` binary needed):
+self-contained, pure-NumPy, **simplified DSSP-style** implementation (no
+external `mkdssp` binary needed):
 
 ```python
-mol = ms.read("1fqy.pdb")
+mol = ms.read("examples/data/1fqy.pdb")
 ss = mol.secondary_structure()      # SecondaryStructure, one code per residue
 
 ss.string                           # e.g. '--HHHHHHHH--SS--EEEE--'
@@ -264,19 +349,23 @@ ss.summary()                        # helix/strand/coil counts and fractions
 mol.plot(color_by="ss")             # colour the 3D view by secondary structure
 ```
 
-Codes follow DSSP: `H`/`G`/`I` helices, `E`/`B` strands, `T` turn, `S` bend,
-`-` coil. This is a simplified **educational** implementation: it reproduces the
-main classes from the Kabsch-Sander hydrogen-bond model but is not bit-identical
-to the reference `mkdssp` on every edge case. It needs backbone N/CA/C/O atoms,
-so use PDB/mmCIF input (not a bare `.xyz`). The secondary-structure render in the
-showcase above (helices red, turns cyan, coil grey) is produced this way.
+Codes follow DSSP notation: `H`/`G`/`I` helices, `E`/`B` strands, `T` turn, `S`
+bend, `-` coil. This is a simplified **educational** implementation of the
+Kabsch-Sander hydrogen-bond model: not bit-identical to the reference `mkdssp`
+on every edge case, but validated against it. A CI cross-check
+(`tests/validation`) puts it at **~99% per-residue 3-state agreement**
+(helix/strand/coil) with `mkdssp` 4.2.2 on the bundled aquaporin (`1fqy`);
+strand-rich folds, where reference DSSP is hardest to match, will agree less
+closely. It needs backbone N/CA/C/O atoms, so use PDB/mmCIF input (not a bare
+`.xyz`). The secondary-structure render in the showcase above (helices red,
+turns cyan, coil grey) is produced this way.
 
 ### NMR ensembles
 
 ```python
 from molscope import ensemble
 
-models = ms.read_pdb_models("1aml.pdb")     # all 20 models
+models = ms.read_pdb_models("examples/data/1aml.pdb")     # all 20 models
 ensemble.rmsd_matrix(models)                 # pairwise RMSD matrix
 ensemble.rmsf(models)                        # per-atom fluctuation
 ensemble.average(models)                     # mean structure
@@ -324,7 +413,7 @@ to the common ML frameworks. The base `to_graph()` needs no extra dependencies;
 each exporter imports its backend lazily.
 
 ```python
-mol = ms.read("1fqy.pdb")
+mol = ms.read("examples/data/1fqy.pdb")
 
 g = mol.to_graph()                  # MolecularGraph: nodes + edges, no deps
 g.n_atoms, g.n_bonds                # counts
@@ -353,6 +442,18 @@ Graph feature presets are also available through
 `mol.to_graph(include_chemical_features=True)` to attach optional RDKit-backed
 aromatic atom and bond flags.
 
+For protein-scale spatial graphs, build a residue contact graph instead:
+
+```python
+rg = mol.to_residue_contact_graph(cutoff=8.0, method="ca", min_seq_sep=4)
+RG = rg.to_networkx()
+residue_data = rg.to_pyg_data(node_preset="ml", edge_preset="ml")
+```
+
+Use atom/bond graphs when covalent chemistry is the signal. Use residue or
+bead contact graphs when 3D neighborhoods, interfaces, folded shape or
+long-range contacts are the signal.
+
 ### Coarse-graining
 
 Map an atomistic structure onto a smaller set of beads. The result is an
@@ -360,11 +461,12 @@ ordinary `Molecule` (beads as "atoms") with explicit CG bonds attached, so it
 plots, transforms and graphs like anything else.
 
 ```python
-mol = ms.read("1fqy.pdb")
+mol = ms.read("examples/data/1fqy.pdb")
 
 cg = mol.coarse_grain("residue_com")        # one bead per residue (centre of mass)
 cg = mol.coarse_grain("residue_centroid")   # ...or geometric centroid
 cg = mol.coarse_grain("martini")            # simplified backbone + side-chain beads
+cg = mol.coarse_grain("martini", virtual_sites=[{"name": "MID", "parents": [0, 2]}])
 cg.plot(scale=200)                          # beads + backbone topology
 print(cg.mapping_report())                  # explain beads, dropped atoms, and bonds
 
@@ -380,31 +482,68 @@ cg = mol.coarse_grain({"head": [0, 1, 2, 3], "tail": [4, 5, 6, 7]},
 cg.to_graph()                               # CG bead network, ready for ML
 ```
 
+Visualise the mapping, inspect the per-bead assignment, and export it:
+
+```python
+ms.plot_mapping(mol, cg)                    # atoms coloured by bead, beads + bonds overlaid
+
+report = cg.coarse_grain_report             # structured assignment
+print(report.coverage())                    # "426 beads from 1661/1661 atoms"
+print(report.beads[0].atom_indices)          # source atoms folded into bead 0
+
+cg.write_mapping("mapping.json")            # round-trippable JSON record
+record = ms.read_cg_mapping("mapping.json")
+cg2 = ms.apply_cg_mapping(mol, record)      # rebuild on a matching structure
+cg.write_index("mapping.ndx")               # GROMACS-style index, one group per bead
+```
+
 Bead positions are mass-weighted (or centroids). For residue mappings bonds are
 generated automatically (within a residue, plus a backbone chain between
 residues); pass `bonds=` to define them yourself. Name-based bonds are intended
 for unique bead names such as `head`/`tail`; repeated names such as `BB`/`SC`
 are ambiguous, so use bead indices for those. Atoms you leave unassigned are
-dropped with a warning. This is meant
-for teaching and prototyping CG mappings, not as a replacement for production
-Martini parameters.
+dropped with a warning. The `"martini"` mapping teaches the idea of backbone and
+sidechain beads. Virtual sites are represented explicitly as derived coordinate
+sites and graph flags, but MolScope does not assign Martini bead types,
+bonded/nonbonded parameters, charges, exclusions, GROMACS virtual-site topology
+sections, or simulation-engine topology files. This is meant for teaching and
+prototyping CG mappings, not as a replacement for production Martini
+preparation: the JSON and `.ndx` exports describe a bead assignment for
+inspection and reuse, not a validated simulation topology.
+
+## Command-line interface
 
-## Command line
+MolScope provides a powerful CLI for visualization, batch analysis, and ML graph export.
 
+### View (default)
+Visualize a structure, apply transformations, and save images or animations.
 ```bash
-molscope helix_201.xyz --translate 1 2 -1
-molscope 1fqy.pdb --select atom_name=CA --color-by residue --save ca.png
+molscope examples/data/1fqy.pdb --select atom_name=CA --color-by residue --save ca.png
+molscope examples/data/1fqy.pdb --select "chain=A and atom_name=CA" --save chain-a-ca.png
 molscope --fetch 1aml --center --gif amyloid.gif
-python -m molscope 1fqy.pdb          # equivalent if not pip-installed
 ```
 
+### Analyze
+Batch compute molecular descriptors for many files and save to a CSV table.
+```bash
+molscope analyze examples/data/*.pdb --out results.csv --preset native-3d --jobs 4
+```
+
+### Export
+Batch export molecular graphs to PyTorch Geometric, DGL, or NetworkX formats.
+```bash
+molscope export "data/*.cif" --to pyg --out-dir pyg_graphs/ --pe laplacian --jobs 8
+```
+Supports advanced features like `--self-loops`, `--global-node`, and `--pe` (positional encodings).
+
+
 ## Sample structures
 
 | File | Contents |
 |------|----------|
-| `helix_201.xyz` | a helix (bare coordinates) |
-| `1fqy.pdb` | Aquaporin-1, single model (1661 atoms) |
-| `1aml.pdb` | Alzheimer amyloid A4 peptide, 20-model NMR ensemble |
+| `examples/data/helix_201.xyz` | a helix (bare coordinates) |
+| `examples/data/1fqy.pdb` | Aquaporin-1, single model (1661 atoms) |
+| `examples/data/1aml.pdb` | Alzheimer amyloid A4 peptide, 20-model NMR ensemble |
 
 ## Notes
 
@@ -422,6 +561,7 @@ python -m molscope 1fqy.pdb          # equivalent if not pip-installed
 - Optional extras: `pip install "molscope[fast]"` (scipy, faster bonds/contacts),
   `"molscope[viz]"` (py3Dmol, for `Molecule.view`), `"molscope[graph]"`
   (NetworkX), `"molscope[chem]"` (RDKit), `"molscope[cif]"` (Gemmi),
+  `"molscope[gpu]"` (PyTorch dense distance/contact-map backend),
   `"molscope[pyg]"`, `"molscope[dgl]"`, or `"molscope[gnn]"`. For custom CUDA,
   ROCm, Apple Silicon, or cluster builds, install the matching PyTorch stack
   first.
@@ -429,11 +569,18 @@ python -m molscope 1fqy.pdb          # equivalent if not pip-installed
 ## Tests and linting
 
 ```bash
-uv run pytest          # full test suite
-uv run ruff check .    # lint
+uv run pytest                      # full test suite
+uv run pytest tests/validation     # validation suite only
+uv run ruff check .                # lint
 ```
 
-CI (GitHub Actions) runs both across Python 3.9 / 3.11 / 3.13 on every push and PR.
+CI (GitHub Actions) runs the suite and linting across Python 3.9 / 3.11 / 3.13,
+smoke-imports the optional extras, and runs a separate **validation** job on
+every push and PR. `tests/validation` is a two-tier suite: dependency-free
+physical invariants (rigid-body algebra, geometry, coarse-grain conservation)
+that run everywhere, plus cross-checks against reference scientific tools (the
+simplified DSSP vs `mkdssp`) that turn "the tests pass" into a measured
+agreement number.
 
 ## License