Skip to content

ELFES

ELFES (Equivariant Learning Framework for Electronic Structure) is a unified, model-agnostic framework for learning electronic structure at scale, built on PyTorch.

ELFES brings data from different DFT codes into a common physical description across spin configurations and boundary conditions. Different model architectures share the same physical data types, IO, datasets, and training infrastructure. This framework supports research on Hamiltonians, density matrices, electron and magnetization densities, energies, and forces, with consistent physical conventions from data preparation to the interpretation of predictions.

Architecture and workflow

ELFES covers the workflow from first-principles data to equivariant modeling, training, and physical analysis. Physical quantities retain consistent definitions across these stages, with distinct components handling source formats, dataset storage, and model computation.

ELFES data flow and learning components Raw DFT data become physical quantities through elfes.io, then pass through ELFES HDF5, Dataset and batched tensors. An encoder produces equivariant features, layers update them, and a decoder produces prediction tensors. Loss compares predictions with reference targets in the batch. Predictions return to physical objects for analysis and export. The engine manages training and evaluation. elfes.physics NumPy PyTorch elfes.data elfes.modules Equivariant model Raw DFT data Physical quantities ELFES HDF5 Dataset Batched tensors Equivariant features Equivariant features Prediction tensors Physical quantities elfes.io Write Read DataLoader Encoder Layers Decoder Loss Restore physical objects Analysis & export Training & evaluation · elfes.engine ELFES data flow and learning components Raw DFT data become physical quantities through elfes.io, then pass through ELFES HDF5, Dataset and batched tensors. An encoder produces equivariant features, layers update them, and a decoder produces prediction tensors. Loss compares predictions with reference targets in the batch. Predictions return to physical objects for analysis and export. The engine manages training and evaluation. Raw DFT data elfes.io Physical quantities elfes.physics Write ELFES HDF5 Read Dataset elfes.data DataLoader Batched tensors Encoder Equivariant features elfes.modules Layers Equivariant features Decoder Prediction tensors Restore physical objects Physical quantities Loss Analysis & export Training & evaluation · elfes.engine

Data and training at scale

ELFES is designed for growth in dataset size, model capacity, and computational resources. Efficient dataset access and distributed training extend the optimized model components into a complete workflow for large-scale electronic-structure learning.

Spin and periodicity

Spin and periodicity are part of the physical description throughout ELFES. Shared data types and conventions describe magnetic and nonmagnetic systems across finite and periodic geometries. Their physical meaning and transformation rules remain consistent through data processing, equivariant modeling, and analysis.

Modular design

Physical targets, model architectures, and learning methods are independent choices. ELFES separates physical definitions from model design and training execution, allowing data, scientific operations, and training infrastructure to be reused across research tasks. Components can be developed and optimized independently while retaining consistent physical conventions.

Optimized computation

ELFES optimizes the geometric and equivariant operations shared by many models, including tensor products, spherical transformations, and neighbor construction. Specialized CPU and GPU kernels make these operations available as reusable model components, so computational improvements carry across architectures.

Documentation