Skip to main content

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_2102 network, and the complete modular v2106 point-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)

Source distribution for e3nn-mlx 0.1.1
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)

Table of built distributions (wheels) for e3nn-mlx 0.1.1
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page