Skip to content

Add matscipy as an ASE v4 neighbour-list plugin - #317

Closed
jameskermode wants to merge 2 commits into
masterfrom
add-ase-neighbour-list-plugin
Closed

Add matscipy as an ASE v4 neighbour-list plugin#317
jameskermode wants to merge 2 commits into
masterfrom
add-ase-neighbour-list-plugin

Conversation

@jameskermode

Copy link
Copy Markdown
Member

Summary

Exposes matscipy's compiled neighbour list as a user-selectable neighbour-list backend for ASE 4 (ase._4), via the single ase.plugins entry-point group. When matscipy is installed, ASE callers can opt in explicitly:

from ase.neighborlist import get_neighbor_list, available_neighbor_list_backends
available_neighbor_list_backends()      # {'ase': True, 'matscipy': True, ...}
nl = get_neighbor_list("matscipy")      # the compiled backend
i, j, d, D, S = nl("ijdDS", atoms, 5.0)

Selection is explicit and never automatic — this only makes the backend available under the name "matscipy"; ASE still defaults to its built-in "ase" backend.

What's here

  • matscipy/_ase_plugin.py — a thin adapter matching ASE's NeighborListFunction contract (fn(quantities, atoms, cutoff, *, self_interaction=False)). matscipy's neighbour_list already returns the same (i, j, d, D, S) flat arrays and quantity letters; the adapter only adds the self_interaction keyword, rejecting self_interaction=True (which matscipy does not support) rather than silently differing. The heavy matscipy.neighbours import is lazy (only on call), and the __ase_plugins__ registration is guarded so installing matscipy alongside an ASE that predates the v4 plugin API registers nothing instead of breaking plugin discovery.
  • pyproject.toml — declares the ase.plugins entry point (matscipy_neighbours = "matscipy._ase_plugin").
  • matscipy/meson.build — installs the new module.

Notes / dependencies

  • Targets ASE's in-flight v4 plugin system (the ase.plugins entry-point group + NeighborListPlugin type). On current released ASE the guard makes this a no-op, so it is safe to merge ahead of that landing.
  • Validated against an ASE branch carrying the v4 NeighborListPlugin: matscipy's edge sets are byte-identical to ASE's reference backend across fcc, hcp, and mixed-pbc slab systems (cutoffs 3 and 5 Å), the D = pos[j] - pos[i] + S @ cell identity holds, and matscipy works through ASE's backend-agnostic Verlet skin-reuse wrapper.

🤖 Generated with Claude Code

jameskermode and others added 2 commits June 9, 2026 10:14
CubicCrystalDislocation.view_cyl (via _plot_DXA_disloc_line) builds a
colour key and segment name with fractions.Fraction(elem) over the DXA
Burgers vector components. Newer OVITO returns segment.true_burgers_vector
as float32, and Fraction() rejects numpy.float32 (it is not a subclass of
Python float, unlike numpy.float64) with:

    TypeError: argument should be a string or a Rational instance

This broke the documentation build (docs/applications/cylinder_configurations.ipynb).
Convert each component to a native Python float before passing to Fraction.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Expose matscipy's compiled neighbour list under the `ase.plugins` entry
point group as a NeighborListPlugin named "matscipy", so ASE v4 callers can
select it explicitly via ase.neighborlist.get_neighbor_list("matscipy") (or,
in due course, a calculator's neighbor_list= option). Import is lazy and
selection is never automatic.

- matscipy/_ase_plugin.py: adapter matching ASE's NeighborListFunction
  contract (rejects self_interaction=True, which matscipy does not support)
  plus a guarded __ase_plugins__ that registers nothing on an ASE without the
  v4 plugin API, so plugin discovery never breaks.
- pyproject.toml: ase.plugins entry point.
- matscipy/meson.build: install the new module.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@jameskermode
jameskermode force-pushed the add-ase-neighbour-list-plugin branch from 4c4df2e to a4e4f71 Compare June 18, 2026 17:41
@jameskermode

Copy link
Copy Markdown
Member Author

Closing without merging. We're integrating the neighbour-list backend via the standalone matscipy-neighbours package instead of adding the ASE plugin to full matscipy — see libAtoms/matscipy-neighbours#2, which adds pip packaging (scikit-build-core) plus the same ase.plugins NeighborListPlugin adapter there.

Rationale: matscipy-neighbours is a slim, separately-installable extraction of matscipy.neighbours (same (i, j, d, D, S) API, optional CUDA/HIP GPU backend), so ASE users can opt into the compiled neighbour list without pulling in all of matscipy. In a fresh benchmark it was also the fastest CPU backend measured (~3× full matscipy, lowest memory). Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant