How orbital-materials/orb-models works
Project Type and Purpose
• This is an open-source Python library (“orb-models”) providing pretrained neural network potentials for atomic simulations (energies, forces, stresses).
• It integrates with ASE (Atomic Simulation Environment) and PyTorch to build graph representations of atomic systems, load/compile pretrained models, run inference, and optionally fine-tune on new datasets.
High-Level Components
a. Library Code (orb_models package)
• dataset: wrappers around ASE SQLite databases and data augmentations
• forcefield: core ML components (graph regressor, conservative/direct models, featurizers, embedding, pairwise terms, loss functions)
– atomic_system: functions to convert ASE Atoms ↔ AtomGraphs
– calculator: ASE calculator interface (ORBCalculator)
– pretrained: model factory functions that load/compile pretrained v2/v3 models
• utils: shared utilities (IO, common tensor ops)
b. Entry-Points & Scripts
• finetune.py: CLI for fine-tuning pretrained models on custom ASE databases
• examples/ & aws, azure/: demonstration notebooks and input files
c. Configuration & Deployment
• pyproject.toml, Dockerfile: packaging and containerization
• CI workflows (.github/workflows): test & publish pipelines
d. Tests
• tests/: unit tests covering atomgraphs, forcefield modules, model back-compatibility
Component Interactions & Data Flow
1. User code (e.g. examples or external scripts) imports orb_models.forcefield.pretrained → selects a model variant → backend loads PyTorch weights and compiles the model
2. AtomicSystem builder (orb_models.forcefield.atomic_system) takes an ASE Atoms object, along with system_config (cutoffs, periodicity) → produces a message-passing graph representation on CPU/GPU; optionally accelerated by cuML for neighbor graph creation
3. The graph is batched (orb_models.forcefield.base.batch_graphs) and fed into the model’s .predict() method → outputs energy, force, stress tensors
4. If using ORBCalculator, the same graph-building + inference pipeline is wrapped in ASE’s calculator API, so standard ASE workflows (optimization, MD) can be performed
5. finetune.py reuses dataset modules to load a custom ASE SQLite DB → constructs DataLoader → trains a model variant via PyTorch, saving checkpoints in ckpts/
Architectural Patterns & Design Principles
• Modular Python package: clear separation between data ingestion, graph construction, model architecture, inference, and ASE integration
• Factory functions for pretrained models ensure decoupling of model configuration (v2 vs v3, direct vs conservative) from inference code
• Pluggable backend acceleration: pure-Python graph builder with optional cuML integration for GPU speedups
• Scriptable CLI for extensibility (fine-tuning)
• CI/CD pipelines enforce code quality, testing, and publishing to PyPI