e3nn_mlx
Incremental refactor of e3nn into a backend-neutral core plus an MLX-native runtime.
The current implementation provides:
- backend-agnostic O(3) metadata in
e3nn_core - e3nn-compatible real Wigner-3j and Clebsch--Gordan coefficients
- batched real Wigner matrices and O(3) parity transforms through arbitrary
l - spherical harmonics generated recursively from the canonical Wigner basis
- weighted and unweighted MLX tensor products and standard wrappers
- lightweight MLX Linear, Gate, Norm, and reduction operations
- graph/radial utilities, the gated
gate_points_2102network, and the complete modularv2106point-model family - pinned upstream e3nn numerical fixtures and Apple-Silicon CI coverage
Numerical compatibility is guaranteed through l=6; reference and structural
tests exercise selected operations through l=8. See
docs/COMPATIBILITY.md for conventions, shapes,
normalization, and the release gate.
Installation
Install the published package with:
python -m pip install e3nn-mlx
Python 3.11 or newer is required. Apple Silicon uses MLX's Metal backend; Linux installs the MLX CPU backend. Generated Metal kernels automatically fall back to general MLX operations when Metal is unavailable.
e3nn-style API
New code can use the familiar upstream namespace layout with ordinary MLX arrays:
import mlx.core as mx
from e3nn_mlx import nn, o3
linear = o3.Linear("16x0e + 16x1o", "32x0e + 16x1o")
x = mx.random.normal((128, linear.irreps_in.dim))
y = linear(x)
e3nn_mlx.o3, e3nn_mlx.nn, e3nn_mlx.math, and
e3nn_mlx.nn.models.v2106 mirror the implemented PyTorch/e3nn organization.
Raw inputs return raw MLX arrays; IrrepsArray inputs preserve typed outputs.
The original flat API remains backward-compatible. See
docs/HIGH_LEVEL_API.md for migration examples,
model imports, compilation, deliberate differences, and no-overhead evidence.
Development
Install the test dependencies and run the suite on Apple Silicon:
python -m pip install -e '.[test]'
python -m pytest
MLX tests may skip when Metal is unavailable locally. The required macOS CI job
sets E3NN_MLX_REQUIRE_RUNTIME=1, which turns such skips into failures.
Gate-points model
e3nn_mlx.models.gate_points_2102.Network ports the upstream gated point-cloud
network. It accepts a dictionary containing pos, x, z, and an optional
integer batch array and returns an IrrepsArray. GatePointsNetwork and
GatePointsConvolution are also exported from e3nn_mlx.
Neighbor discovery with radius_graph is eager because MLX 0.31 does not have
a device-side dynamic nonzero operation. For compiled training or inference,
construct the topology once and call Network.forward_with_edges; the radial
embedding, spherical harmonics, message passing, gating, and graph reduction
then remain inside the compiled MLX graph.
The complete modular June 2021 family is available from
e3nn_mlx.models.v2106. It includes Convolution, MessagePassing,
SimpleNetwork, and NetworkForAGraphWithAttributes; both networks support
eager dictionary input and compiled fixed-edge execution. See
docs/V2106_POINT_MODELS.md for their APIs,
compilation boundary, upstream semantics, and verification coverage.
Performance evaluation
The compact cross-framework harness in
evals/
always compares three isolated workers: upstream e3nn on Torch CPU using all
available CPU threads, compiled general MLX, and compiled MLX with generated
kernels. It covers spherical harmonics, tensor products, Linear, and scatter
aggregation in forward and training modes. Smoke and full presets produce
synchronized JSON, CSV, SVG, and HTML reports. Separate seeded randomized
harnesses qualify numerical outputs and VJPs against upstream e3nn.
JVP and generated-kernel boundary
A Jacobian-vector product (JVP) propagates a chosen input perturbation through a function without constructing its complete Jacobian. Most users do not call JVP directly: ordinary inference and standard training—including MACE energy, force, and parameter-gradient training—use forward evaluation and reverse-mode gradients.
JVP is useful for more specialized atomistic workflows, including:
- Hessian-vector products and directional force-constant calculations;
- phonon, vibrational-response, and stability algorithms that propagate a displacement direction;
- mixed position/parameter response calculations;
- tangent dynamics, sensitivity analysis, and forward-mode Jacobian APIs;
- debugging equivariance by differentiating along an infinitesimal rotation.
MLX 0.31 cannot currently apply JVP directly to a CustomKernel primitive.
For these workflows, select the fully differentiable MLX implementation:
import e3nn_mlx
# Spherical harmonics and fixed-topology graph reduction
y = e3nn_mlx.spherical_harmonics(
degrees, vectors, use_custom_kernel=False
)
summed = e3nn_mlx.scatter_sum(
messages,
edge_dst,
num_nodes,
use_custom_kernel=False,
jvp_safe=True,
)
# TensorProduct: use this callable inside mx.jvp
y = tensor_product.differentiable_arrays(left, right, weights)
Because MLX 0.31's indexed-add primitive does not implement JVP, the scatter fallback requires eager, fixed indices. It uses a sparse sorted prefix sum with linear memory rather than a dense node-by-edge incidence matrix. Ordinary scatter calls keep the faster indexed-add implementation.
This changes execution strategy, not mathematical conventions or accuracy.
Reverse-mode gradients and reverse-over-reverse second derivatives remain
supported by the generated kernels. See the
evals/ guide
for the three-way performance comparison and randomized parity commands.
Metadata
Release files for e3nn-mlx 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| e3nn_mlx-0.1.1.tar.gz | 150.1 kB | With provenance | Details for e3nn_mlx-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| e3nn_mlx-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for e3nn_mlx-0.1.1-py3-none-any.whl |
Total release size: 247.5 kB
Release files / e3nn_mlx-0.1.1.tar.gz
| Download URL | e3nn_mlx-0.1.1.tar.gz |
|---|---|
| Size | 150.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b1de9225c977e346966261ec906b419698dc09a34db92e7b7cbb8420225a8c0
|
|
BLAKE2b-256 checksum How to use checksums |
76e386ef8b9f8d5edb97fe778df9e06ced09d36c1a4be482e8c4bd09d93499a9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / e3nn_mlx-0.1.1-py3-none-any.whl
| Download URL | e3nn_mlx-0.1.1-py3-none-any.whl |
|---|---|
| Size | 97.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
60607009a9521e14b68c5b07f98f9006b92dd12207494bd58227da743ff694f6
|
|
BLAKE2b-256 checksum How to use checksums |
be6fa6643fe6afff183de0f59e9c113ccdf38a5733ad1b86c5f5dba250b95dfa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logSecurity for e3nn-mlx 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for e3nn_mlx-0.1.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.