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:

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:

uv run scripts/spike_hooked_mace.py