Installation

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 (pip package: expyre-wfl)

  • MACE — Machine Learning Accelerated Computational Engine (pip package: mace-torch)

  • sage-lib — Hybrid HDF5+SQLite structure database (GlobalDatabase backend)

  • mp-api — Materials Project API for fetching reference structures

  • numpy, polars, matplotlib, tqdm, pyyaml, pymatgen

HPC Setup

After installing, run the interactive wizard to register your HPC system(s):

alomancy add-hpc

The wizard configures:

  • ~/.expyre/config.json — ExPyRe scheduler entry (Slurm, partitions, scratch directory)

  • ~/.alomancy/hpc_config.yaml — ALomancy HPC profile (venv, DFT paths, node info)

Run it once per HPC system (or profile). See Examples for a full walkthrough.

Clearing local ExPyRe state

alomancy nuke

Deletes all local ExPyRe job state (job cache, unsynced stage directories) under ~/.expyre, leaving config.json untouched. Prompts for confirmation before deleting. Useful when local ExPyRe state gets out of sync with the remote HPC system and jobs won’t resubmit cleanly.

Materials Project API

Ensure you have a MP_API_KEY accessible in the local environment. You can generate your API key on their website

then you can ensure it is always accessible by adding the following line to your .bashrc

export MP_API_KEY <your key here>

or if you use fish, in your ~/.config/fish/config.fish

set -gx MP_API_KEY <your key here>

Development Installation

For contributors and developers:

# Clone and install with development dependencies
git clone https://github.com/julianholland/ALomancy.git
cd ALomancy
uv sync --extra docs

# Install pre-commit hooks
uv run pre-commit install