MANDALA

Getting started

  • Installation
    • Requirements
    • Clone the repository
    • Create the environment
      • CPU
      • CUDA 12.1
    • Tested environments
    • Import layout
    • Verify the installation
    • Build this documentation
  • Quickstart
    • Operators and observables
    • A model on the same structure
    • Where to go next
  • Your first model
    • The configuration
    • Check it
    • Train
    • Continue
    • Evaluate
    • Going further

User guide

  • Data
    • Supported sources
      • The periodic HDF5 interchange
    • The Snapshot
    • Block matrices and irrep vectors
    • Datasets
      • Graph supports
      • Caching
  • Configuration
    • A flat MANDALA configuration
    • The data section
    • The training section
    • Recipes: explicit architectures
    • Overrides on the command line
    • Python
  • Training
    • The trainer
    • What a run contains
    • Continuation and reproducibility
    • Observable and spectral guidance in practice
    • Fitted distance envelopes
    • Monitoring
    • Hyperparameter search
    • Fine-tuning
  • Inference and analysis
    • Predicting operators
      • From a reference snapshot
      • From a structure only
      • Lower-level calls
    • Post-processing
    • Exporting predictions
    • Reports
    • Derivatives

Theory

  • Symmetry and representations
    • The Euclidean group
    • Irreducible representations
    • Spherical harmonics
    • Tensor products and Clebsch–Gordan coefficients
    • Equivariant building blocks
    • How electronic-structure operators transform
  • Sparse operators and their irreps
    • Periodic block structure
      • Units and conventions
    • From blocks to irreps
      • Irrep atlas
      • The packed shell codec
    • Sparse operator algebra
      • Hermitian projection
      • Energy-gauge alignment
      • Electron-count normalization
    • Reciprocal space and band structures
  • The MANDALA E3GNN
    • Geometric embeddings
    • Encoders
    • The equivariant convolution
    • Node update
    • Edge update
    • Readout heads
    • Distance envelopes
    • The equivariant MLP and its variants
    • Equivariant nonlinearities
    • Cost
  • Training objectives
    • Matrix terms
    • Observable guidance
    • Spectral guidance
    • Derivative objectives
    • Fitted output statistics
    • Optimization and model selection

Architecture

  • The typed feature pipeline
    • Anatomy of a stage
    • Typed feature contracts
    • Built-in input slots
    • Resolution: shapes from data
    • Inspecting a pipeline
    • The registry
  • Component catalogue
    • Geometry and embeddings
    • Message passing
    • Feature operations
    • Frames and adapters
    • Readout and operator decoding
    • Reference presets

Extending MANDALA

  • Writing new layers and objectives
    • The extension mechanism
    • The symmetry checklist
    • Certifying a layer
  • Radial basis: bessel_basis
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Node encoder: periodic_table_embedding
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Edge encoder: radial_angular_encoder
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Tensor-product convolution: depthwise_convolution
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Message aggregation: tempered_softmax_aggregation
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Equivariant nonlinearity: squash_activation
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Equivariant normalization: degree_rms_norm
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Equivariant MLP block: equivariant_glu
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Residual update: rezero_residual
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Edge update: endpoint_bilinear_edge_update
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Operator readout: pair_mixture_readout
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Output envelope: learned_pair_envelope
    • Role
    • The new layer
    • Implementation
    • Usage
    • Variations
  • Assembling a network from new layers
    • The recipe
    • Verification
    • Training
  • Adding an observable objective
    • Why add an observable?
    • 1. Define the term
    • 2. Register it
    • 3. Enable it in YAML and train
    • Verification

Reproducing the paper

  • Reproducing the paper
    • Reference data
    • Environment
    • Workflow overview
      • Demonstration models
      • Ablations and scaling
  • Demonstration models
    • Model configurations
    • Training recipes
    • Validation metrics
    • Figures
    • Paper figures and tables
  • Ablations and scaling
    • Protocol
    • Running a sweep
    • Results
    • Inference scaling

Reference

  • API reference
    • Model
      • E3GNN
      • Config
      • resolve_configuration()
    • Pipeline
      • FeatureSpec
      • FeaturePipeline
      • register_transform()
      • build_transform()
      • default_graph()
    • Layers
      • NodeEncoder
      • EdgeEncoder
      • EquiConv
      • NodeUpdateBlock
      • EdgeUpdateBlock
      • DeepHead
      • E3MLP
      • RadialMLP
      • SeparateWeightTensorProduct
      • make_nonlinearity()
      • GateMagnitudes
      • E3LayerNorm
      • make_variant_block()
      • GaussianBasis
      • GatedRadialTensorProduct
      • GraphIrrepNorm
      • NeighborDensityInteraction
      • SymmetricProductContraction
      • AngularDegreeExpansion
      • ProjectedAttention
      • SpeciesIrrepAffine
    • Operators and data
      • Snapshot
      • BlockMatrix
      • IrrepsBlockData
      • DatasetFactory
      • E3GNNDataset
      • build_model_input_from_structure()
    • Orbitals and irreps
      • OrbitalIrrepConfig
      • BlockIrrepMapper
      • ShellTensorCodec
      • OrbitalFrameRotation
    • Sparse algebra and reciprocal space
      • trace_matmul_sparse_block_matrix()
      • trace_matmul_sparse_block_matrix_aligned()
      • build_trace_alignment()
      • shiftspace_to_kspace_dense()
      • kspace_to_shiftspace_dense()
    • Objectives
      • register_objective_term()
      • compute_spectral_eigenvalue_loss()
      • observable_loss()
      • load_pair_envelope_table()
      • evaluate_slater_soft_cutoff()
      • evaluate_slater_exp_quad_soft_wall()
    • Evaluation and export
      • evaluate_sample()
      • load_checkpoint()
      • predict_snapshot()
      • predictions_to_snapshot()
      • restore_config()
      • restore_model_for_snapshot()
      • export_model_openmx()
  • Configuration reference
  • Glossary
MANDALA
  • Overview: module code

All modules for which code is available

  • core.block_irrep_mapper
  • core.operator_layout
  • core.orbital_irrep_config
  • core.periodic_fourier
  • core.sparse_math
  • data.block_matrix
  • data.envelope
  • data.factory
  • data.gnn_dataset
  • data.openmx_writer
  • data.snapshot
  • data.structure_inference
  • net.activations
  • net.common
  • net.component_defaults
  • net.configuration
  • net.e3gnn
  • net.e3mlp_variants
  • net.encoders
  • net.evaluation
  • net.heads
  • net.layer_norm
  • net.layers
  • net.objectives
  • net.observable_metrics
  • net.pipeline
  • net.spectral_loss
  • net.training_policies
  • net.transforms.cluster
  • net.transforms.composition
  • net.transforms.equivariant

© Copyright 2026, MANDALA developers.

Built with Sphinx using a theme provided by Read the Docs.