MANDALA
The hosted documentation is at https://mandala-org.github.io/Mandala/.
MANDALA learns the electronic structure of molecules and materials as operators. Given atomic positions, species and (for crystals) a lattice, an E(3)-equivariant graph neural network predicts the sparse, atom-pair-resolved Hamiltonian \(H\), overlap \(S\) and density matrix \(D\) in a localized atomic-orbital basis. Observables are computed from those operators rather than by separate surrogate models:
Because these quantities remain differentiable functions of the network output, they can also guide training: band energies, electron counts and eigenvalue spectra near the Fermi level enter the loss next to the matrix elements themselves.
What makes MANDALA distinctive
Operators, not numbers. Hamiltonian, overlap and density blocks are predicted jointly from one equivariant latent representation and keep their exact transformation law under rotations, reflections and translations.
Physics in the loss. Sparse trace contractions and differentiable generalized eigensolvers turn \(\Tr(DH)\), \(\Tr(DS)\) and band eigenvalues into training objectives.
One typed pipeline for every architecture. The default MANDALA network, DeepH, DeepH-E3, MACE-H and arbitrary hybrids are configurations of the same stage compiler. Each stage declares the entities, irreducible representations, coordinate frame and support it reads and writes; invalid compositions are rejected before allocation.
Extensible by registration. A new layer is an
nn.Moduleplus a factory that states its contract. The layer cookbook implements a new member of every layer family and certifies each one.Reproducible by construction. Runs freeze the resolved configuration, input hashes, split membership and fitted statistics; continuation resumes exactly at epoch boundaries.
Getting started
User guide
Theory
Architecture
Extending MANDALA
- Writing new layers and objectives
- Radial basis:
bessel_basis - Node encoder:
periodic_table_embedding - Edge encoder:
radial_angular_encoder - Tensor-product convolution:
depthwise_convolution - Message aggregation:
tempered_softmax_aggregation - Equivariant nonlinearity:
squash_activation - Equivariant normalization:
degree_rms_norm - Equivariant MLP block:
equivariant_glu - Residual update:
rezero_residual - Edge update:
endpoint_bilinear_edge_update - Operator readout:
pair_mixture_readout - Output envelope:
learned_pair_envelope - Assembling a network from new layers
- Adding an observable objective
Reproducing the paper