ALomancy

Modular Active Learning Workflows for Modern Computational Chemistry

Installation • Quick Start • Documentation • Examples • Contributing

🎯 Overview

ALomancy is a Python framework for running active learning (AL) workflows for training machine-learned inter-atomic potentials (MLIPs). This package focusses on customization and reproducibility to build robust training datasets and train MLIPs.

Key Features

• 🚀 Automated AL Workflows: End-to-end active learning with minimal manual intervention
• 🔧 HPC Integration: Built-in support for remote job submission on HPC clusters
• ⚡ Parallelization: Ensures that jobs run concurrently where possible increasing speed to results
• 🔄 Extensible Design: Abstract base classes for easy customization and extension
• 📊 Analysis Tools: Built-in utilities for monitoring and analyzing AL progress

Workflow Overview

flowchart TD
    A((Initial Dataset)) --> B[Train MLIP Committee]
    B --> C[Structure Generation]
    C --> D((Uncertainty-based Selection))
    D --> E[High-Accuracy Evaluation]
    E --> F((Update Training Dataset))
    F --> B

    style A fill:#e66027
    style B fill:#e87322
    style C fill:#eb861e
    style D fill:#efa119
    style E fill:#708e4c
    style F fill:#328566

🚀 Installation

From PyPI (Recommended)

pip install alomancy

From Source

git clone https://github.com/julianholland/ALomancy.git
cd ALomancy
uv sync            # creates .venv with alomancy (editable) + the dev tools

Without uv: pip install -e . (add pytest ruff mypy pre-commit yourself; the dev tools are a uv dependency group, not a pip extra).

Dependencies

• Python 3.10+
• ASE — Atomic Simulation Environment
• expyre-wfl — Remote HPC job execution
• MACE — Machine Learning Accelerated Computational Engine
• sage-lib — Hybrid HDF5+SQLite structure database
• mp-api — Materials Project API

⚡ Quick Start

1. Basic Active Learning Workflow

from alomancy import ALomancy

# The config picks everything: the AL skeleton (general.al_workflow) and
# every module (training.trainer, structure_generation.generator,
# high_accuracy_evaluation.evaluator). Every run setting (start_from,
# num_of_al_loops, verbose, ...) lives under the YAML's `general:` section.
ALomancy("standard_config.yaml").run()

2. Configuration File

Create a standard_config.yaml file to specify your computational setup:

general:
  al_workflow: "committee_uncertainty"
  elements: ["C", "O"]   # atomic symbols, not atomic numbers
  # Optional: start from existing data instead of generating it. See
  # docs/starting_a_run.md for all four start modes.
  # start_from:
  #   xyz: "my_dft_data.xyz"
  num_of_al_loops: 5
  verbose: 1
  dataset_kwargs:
    target_config_types: ["IsolatedAtom"]
    test_ratio: 0.1
  committee_uncertainty_kwargs:
    num_of_models_in_committee: 5

initialization:
  name: "init"
  max_time: "04:00:00"
  hpc:
    hpc_name: "local"
    partitions: [""]
    pre_cmds: []

training:
  name: "mace_training"
  trainer: "mace"   # selects the registered mlip_trainer backend
  max_time: "24:00:00"
  hpc:
    hpc_name: "gpu_cluster"
    partitions: ["gpu"]
    pre_cmds: ["module load cuda", "source activate mace"]

structure_generation:
  name: "md_generation"
  generator: "md"   # "md" (default) or "ezga"
  max_time: "12:00:00"
  hpc:
    hpc_name: "gpu_cluster"
    partitions: ["gpu"]
    pre_cmds: ["module load cuda", "source activate mace"]

high_accuracy_evaluation:
  name: "dft_evaluation"
  evaluator: "qe"   # "qe" (default) or "vasp"
  max_time: "48:00:00"
  hpc:
    hpc_name: "cpu_cluster"
    partitions: ["cpu"]
    pre_cmds: ["module load quantum-espresso"]

3. Adding a New Backend

There's no subclassing to extend ALomancy: each pluggable category (trainer, structure generator, DFT evaluator, initialiser) is a module registered against a name in src/alomancy/registry.py, resolved lazily from config at runtime (training.trainer, structure_generation.generator, high_accuracy_evaluation.evaluator). Adding a new backend means writing a new module with the category's expected entry points (output_paths, read_existing_result, and the category-specific worker function) and registering it — see any existing module under mlip/, structure_generation/, or high_accuracy_evaluation/dft/ for the pattern.

📚 Examples

Check out the examples/ directory for complete workflow examples:

• Basic Usage: Simple active learning workflow setup
• Custom HPC Configuration: Advanced cluster configuration
• Analysis Scripts: Post-processing and visualization tools

🏗️ Project Structure

alomancy/
├── analysis/           # Analysis and visualization tools
├── configs/           # Configuration management
├── core/              # Core active learning framework
├── high_accuracy_evaluation/  # DFT calculation modules
├── initialize/        # Initialization structure generation
├── mlip/              # Machine learning potential training
├── structure_generation/      # MD and structure generation
└── utils/             # Utility functions and helpers

🔧 Key Components

Core Framework

• ALomancy: The single entry point (from alomancy import ALomancy; ALomancy("config.yaml").run(), or alomancy run config.yaml); builds whichever AL skeleton general.al_workflow names
• CommitteeUncertaintyWorkflow: The default AL skeleton (al_workflow: committee_uncertainty); resolves its trainer/structure-generator/DFT-evaluator/initialiser from config via the shared module registry rather than subclassing
• GlobalDatabase: Persistent HDF5+SQLite store for all DFT-evaluated structures; deduplication by (config_type, formula)
• Structured Logging: All output routed through Python logging; verbose=0/1/2 controls console level; file always captures DEBUG

MLIP Training

• MACE Integration: Committee training with uncertainty quantification
• Remote Submission: HPC job management for GPU-accelerated training

Structure Generation

• Molecular Dynamics: ASE-based MD simulations with MACE potentials
• Uncertainty Sampling: Intelligent structure selection based on model disagreement

High-Accuracy Evaluation

• Pluggable DFT backend: Quantum Espresso (calculator: "qe", default) or VASP (calculator: "vasp") selected via config key; lazy imports keep optional dependencies isolated
• Job Management: Parallel submission and monitoring of DFT jobs; output directories use ase_output_ prefix

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/julianholland/ALomancy.git
cd ALomancy

# Install in development mode (alomancy editable + dev tools, from uv.lock)
uv sync

# Run tests
uv run pytest

# Run linting
ruff check .
ruff format .

Running Tests

# Run all tests
pytest

# Run specific test categories
pytest tests/core_tests/
pytest tests/mlip_train_tests/
pytest tests/high_acc_tests/

# Run with coverage
pytest --cov=alomancy

📝 Citation

If you use ALomancy in your research, please cite:

@software{alomancy2025,
  title={ALomancy: Modular Active Learning Workflows for Modern Computational Chemistry},
  author={Julian Holland},
  year={2025},
  url={https://github.com/julianholland/ALomancy},
  version={0.1.0}
}

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• The Fritz Haber Institute

📞 Support

• 📖 Documentation: https://alomancy.readthedocs.io
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: holland@fhi.mpg.de