Quickstart

This page shows the three main workflows in AmorphGen.

1. Melt-and-quench pipeline

Run the full 7-stage pipeline on a crystalline input structure:

CLI

# Full pipeline
amorphgen POSCAR --model mace-mpa-0 --device cuda

# With YAML config
amorphgen POSCAR --config pipeline.yaml

# Hybrid (skip heating, resume from checkpoint)
amorphgen structure.xyz --stages 1 4 5 6 7 --config config.yaml --resume

Python API

from amorphgen import MeltQuenchPipeline

pipe = MeltQuenchPipeline(
    input_file="POSCAR",
    work_dir="my_run",
    cfg_override={"model": "mace-mpa-0", "device": "cuda"},
)
atoms = pipe.run()

# Hybrid with resume
atoms = pipe.run(stages=[1, 4, 5, 6, 7], resume=True)

The 7 stages

Stage	Name	Description
1	Optimise	Relax positions (+ cell with FrechetCellFilter)
2	Pre-melt equilibration	NVT at 300 K
3	Melt	Heat ramp to high temperature (configurable rate in K/ps)
4	High-T equilibration	Equilibrate at melt temperature
5	Quench	Cool to target temperature (configurable rate in K/ps)
6	Low-T equilibration	Equilibrate at low temperature
7	Final optimisation	Final relaxation

2. Random structure generation

Generate an ensemble of random amorphous structures with automated minimum separations from Shannon ionic radii:

CLI

# Basic (formula format: In2O3 * 8 formula units = 40 atoms)
amorphgen --random-gen --composition "In2O3*8" --n-structures 20

# Same thing with explicit atom counts
amorphgen --random-gen --composition In=16,O=24 --n-structures 20

# With target CN and density
amorphgen --random-gen --composition "SiO2*16" \
    --target-cn Si=4,O=2 --target-density 2.2

# With relaxation
amorphgen --random-gen --composition "In2O3*8" \
    --relax --model mace-mpa-0 --cell-filter none

Python API

from amorphgen.pipeline.random_gen import generate_random, batch_random

# Single structure (auto minsep from Shannon radii)
atoms = generate_random(
    composition={"In": 16, "O": 24},
    target_density=5.0,
    target_cn={"In": 6},
)

# Batch generation
paths = batch_random(
    composition={"Si": 16, "O": 32},
    n_structures=20,
    target_density=2.2,
    target_cn={"Si": 4, "O": 2},
)

3. Batch quench

Quench multiple snapshot structures through the final pipeline stages:

amorphgen --batch-quench \
    --snapshot-dir snapshots/ \
    --model mace-mpa-0 \
    --batch-stages 5 6 7 \
    --resume

Choosing a backend

from amorphgen.utils import get_calculator

# MACE (default).  device="auto" picks CUDA → MPS → CPU automatically;
# pass "cpu" / "cuda" / "mps" explicitly to override.
calc = get_calculator(model="mace-mpa-0", device="auto")

# CHGNet
calc = get_calculator(model="chgnet", device="auto")

# SevenNet
calc = get_calculator(model="7net-mf-ompa", device="auto")

# Classical potentials (no GPU needed, parameters via YAML or dict)
calc = get_calculator("buckingham", classical_params={
    "params": {("Si", "O"): {"A": 18003.76, "rho": 0.2052, "C": 133.54}},
    "charges": {"Si": 2.4, "O": -1.2},
    "cutoff": 10.0,
})

# Custom fine-tuned model
calc = get_calculator(model_path="/path/to/custom.model")

Accessing radii data

from amorphgen.utils import get_ionic_radius, classify_bond, default_minsep

get_ionic_radius("In", cn=6)   # 0.80 A
classify_bond("In", "O")       # "ionic"
default_minsep(["In", "O"])    # {"In-In": 3.11, "In-O": 1.87, "O-O": 2.24}