Metadata-Version: 2.5
Name: matterlens
Version: 0.0.1
Summary: Hooks, caches, and lenses for machine-learning interatomic potentials and other geometric GNNs (the TransformerLens idea, for MLIPs).
Project-URL: Homepage, https://github.com/Garden-AI/matterlens
Project-URL: Repository, https://github.com/Garden-AI/matterlens
Author-email: Owen Price Skelly <owenpriceskelly@uchicago.edu>
License: MIT
Keywords: equivariant,gnn,interatomic-potential,interpretability,mace,mlip,uma
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.11
Requires-Dist: ase>=3.23
Requires-Dist: numpy
Requires-Dist: torch>=2.4
Provides-Extra: dev
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Provides-Extra: fairchem
Requires-Dist: fairchem-core>=2.20; extra == 'fairchem'
Provides-Extra: mace
Requires-Dist: mace-torch>=0.3.15; extra == 'mace'
Requires-Dist: torch<2.10; extra == 'mace'
Provides-Extra: orb
Requires-Dist: orb-models<0.8,>=0.6.2; extra == 'orb'
Provides-Extra: sevenn
Requires-Dist: sevenn>=0.10.0; extra == 'sevenn'
Description-Content-Type: text/markdown

# matterlens

Hooks, caches, and lenses for machine-learning interatomic potentials and
other geometric GNNs. The TransformerLens idea, built for models whose
activations are per-atom irreps rather than a token residual stream.

Status (2026-09-10): design stage. Read `docs/v0-design.md` for what the first
release is and why. `docs/architecture-survey.md` records what MACE, SevenNet,
Orb, and UMA module trees actually look like; `docs/prior-art.md` records the
landscape. `scripts/spike_hooked_mace.py` is a runnable feasibility spike.

Intended v0 usage:

```python
from matterlens import load
hm = load("mace", "mace-mp-0-medium")          # native mace-torch model underneath
batch = hm.from_atoms(atoms)
out, cache = hm.run_with_cache(batch)
cache["blocks.1.node_feats"].shape             # [n_atoms, 256] as 128x0e+128x1o
cache.blocks("blocks.1.node_feats")[1]         # [n_atoms, 128, 3] the vector channels
with hm.hooks({"blocks.0.node_feats": lambda a, hp: torch.zeros_like(a)}):
    ablated = hm.model(batch)
```

Part of the Amatterlens program (interpretability for scientific discovery),
workstream 1. Companion to Rootstock, which supplies the isolated
per-family environments each adapter installs into.

Run the spike:

```bash
uv run scripts/spike_hooked_mace.py
```
