MQ-ensemble workflow

Generate N independent amorphous structures from a single crystalline input with one CLI command. This is the standard melt-quench MD ensemble pattern used in nearly every amorphous-oxide DFT/MLIP paper, packaged as a single AmorphGen mode.

Concept

Crystalline supercell  →  shared stages 1-4  →  extract N snapshots  →  N × stages 5-7  →  N amorphous structures

The key efficiency win: stages 1-4 (opt + premelt + heat + high-T equilibration) run only once on the shared trajectory. Snapshots taken at evenly-spaced intervals from the long stage-4 trajectory are statistically independent samples of the equilibrium liquid; quenching each independently yields a diverse ensemble of amorphous structures.

Single-command CLI: --mq-ensemble

amorphgen GaO.xyz --mq-ensemble --n-structures 20 \
    --config mq.yaml --device cuda --model chgnet \
    -o ga2o3_mq/

That’s the entire workflow. Internally:

  1. Stages 1-4 run once on GaO.xyz, writing ga2o3_mq/shared/ (incl. stage4_eq_traj.xyz).

  2. N=20 uniformly-spaced snapshots are extracted from the stage-4 trajectory into ga2o3_mq/snapshots/.

  3. Stages 5-6-7 run independently on each snapshot, output to ga2o3_mq/quench_runs/run_NNNN/.

  4. Final amorphous structures are collected to ga2o3_mq/final/mq_NNNN.<format>.

--resume is honoured at every step. Re-running the same command picks up wherever it stopped without redoing completed work.

Output layout

ga2o3_mq/
├── shared/
│   ├── stage1_opt.xyz
│   ├── stage2_eq.xyz
│   ├── stage3_melted.xyz
│   ├── stage4_eq.xyz             # final state of stage 4
│   ├── stage4_eq_traj.xyz        # full trajectory (snapshots taken from here)
│   └── stage*.log                # per-stage MDLogger output
├── snapshots/
│   ├── snapshot_0000_frame*.xyz
│   └── ...
├── quench_runs/
│   ├── run_0000/                 # stages 5-7 outputs for snapshot_0000_*
│   │   ├── stage5_quenched.xyz
│   │   ├── stage6_eq.xyz
│   │   ├── stage7_opt.cif
│   │   ├── stage7_opt.xyz
│   │   └── final_amorphous.xyz
│   └── ...
└── final/
    ├── mq_0000.vasp              # collected, ready for analysis
    ├── mq_0001.vasp
    └── ...

The inner run_NNNN/ is named after the source snapshot’s index (parsed from the snapshot_NNNN_frame*.xyz filename), so run_0007/ always corresponds to snapshot_0007_* — making it easy to trace any final structure back to its high-T starting frame.

HPC job-array tip

When splitting the per-snapshot quenches across SLURM array tasks, point all tasks at the same quench_runs/ output dir; AmorphGen names the per-task subdir from the snapshot index, so there’s no collision. Don’t pass each task its own -o quench_runs/run_${TASK} — that nests inside another run_NNNN/ created by batch_quench and gives you the unhelpful quench_runs/run_0007/run_0007/.

A clean per-task command looks like:

mkdir -p inputs_per_task/task_${TASK}
cp snapshots/snapshot_${TASK}_frame*.xyz inputs_per_task/task_${TASK}/
amorphgen --batch-quench \
  --snapshot-dir inputs_per_task/task_${TASK} \
  --config mq_stages_567.yaml --stages 5 6 7 \
  --model chgnet --device cuda \
  -o quench_runs        # shared across all array tasks

A full SLURM array template ships with the package at examples/run_quench_array_bluebear.slurm.

Choosing protocol parameters — a note on methodology

The defaults below match the common DFT-MD melt-quench protocol used in much of the amorphous-oxide literature (e.g. Kaewmeechai et al., Phys. Rev. B 111, 035203, 2025), with one substitution forced by computational cost:

  • Heating rate (Stage 3). DFT melt-quench studies typically use 0.5–1 K/ps heating ramps. With foundation MLIPs (chgnet, MACE, SevenNet) on a single GPU, that translates to days of wall time per ramp. The default below uses 100 K/ps, which is ~100× faster while still producing fully thermalised liquid configurations after the long Stage-4 equilibration. If you are publishing a comparison to DFT melt-quench, document the heating-rate substitution explicitly in your methods section.

  • Cooling rate (Stage 5). 100 K/ps matches the upper end of the cooling rates used in published DFT melt-quench studies of oxides (typical range 0.5–100 K/ps). Defensible without methodology notes.

  • High-T anneal duration (Stage 4). 100 ps matches typical DFT MD high-T equilibration. Long enough that snapshots taken at uniform intervals are statistically independent samples of the liquid.

  • Melt temperature (Stage 4). AmorphGen’s default is 3000 K (eq_high.T: 3000), inside the training window of all supported MLIPs. The example YAML below sets 4000 K as a deliberate override matching the protocol of Kaewmeechai et al. (PRB 111, 035203, 2025): well above oxide melting points (~2000 K typical) but outside chgnet’s training window. MACE and SevenNet handle 4000 K reliably for most systems; with chgnet, drop back to 3000 K if you see instability or non-physical behaviour.

  • Ensemble. NPT throughout lets the cell volume relax to the equilibrium liquid density at high T, then back to amorphous-solid density on cooling. NVT is an alternative if you trust the input cell volume and want to constrain it; matches AmorphGen’s examples/hybrid_airss_mq.yaml template.

Equivalent two-step manual workflow

If you want to inspect or analyse the stage-4 trajectory before quenching, run the two halves separately:

# Step 1: stages 1-4 only (writes stage4_eq_traj.xyz)
amorphgen GaO.xyz --config mq.yaml --stages 1 2 3 4 --resume -o shared/

# Step 2: extract N snapshots and quench each
amorphgen --batch-quench --snapshot-dir shared/stage4_eq_traj.xyz \
    --n-runs 20 --batch-stages 5 6 7 \
    --config mq.yaml --resume -o quench_runs/

--batch-quench accepts a trajectory file directly (polymorphic --snapshot-dir) — internally extracts N snapshots, then runs the per-snapshot stages. Same final output as --mq-ensemble but split into two CLI invocations.

HPC / Slurm split (best for parallelism)

For a cluster with multiple GPUs, run the two halves as separate slurm jobs so the per-snapshot quenches can execute in parallel via a slurm array:

# Job 1: stages 1-4 (single GPU, ~10 h on A100 for 100 ps eq_high)
sbatch 01_shared_bluebear.slurm
# Note the JOBID

# Job 2: array of 20 quench tasks (20 GPUs concurrent, ~5 h wall)
sbatch --dependency=afterok:<JOBID> 02_quench_array_bluebear.slurm

Example slurm scripts for BlueBEAR and Sulis ship in the AmorphGen repo under examples/hpc/. Both use amorphgen --extract-snapshots and amorphgen --batch-quench --snapshot-dir snapshots/ internally — same dispatch as --mq-ensemble, just split for HPC parallelism.

Pattern

Wall time

Best for

--mq-ensemble (single command)

~30 h sequential

Local / single-GPU

Two slurm jobs (shared + array)

~15 h with 20 concurrent GPUs

HPC with array support

Resume behaviour

Interruption point

What --resume recovers

Mid stages 1-4

Skips completed stages, re-runs the interrupted one from start. (Frame-level resume is on the roadmap; see CLAUDE.md.)

Between stage 4 and snapshot extraction

Skips stages 1-4, re-extracts snapshots, runs 5-7.

Mid quench-runs

Skips completed runs (looks for final_amorphous.xyz), re-runs the interrupted one.

After all done

Reports “all complete”, returns. Idempotent.

When to use --mq-ensemble vs the alternatives

Use case

Recommended mode

Compare directly to published DFT melt-quench

--mq-ensemble (full crystal → liquid → quench protocol)

Generate amorphous structures from random starting points

--hybrid-ensemble (Hybrid workflow)

Single amorphous structure (no ensemble)

Default pipeline (no flag, just amorphgen INPUT --config ...)

Quench pre-extracted snapshots from an existing trajectory

--batch-quench --snapshot-dir TRAJ

Validation

amorphgen --analyse --input-dir ga2o3_mq/final/ \
    --cutoff auto-rdf --per-structure \
    --reference reference_a_Ga2O3.yaml \
    --save-report mq_report.txt --save-plot mq_plots/ --save-pdf

This produces a publication-quality structural analysis (RDF, CN, bond angles) and a validation table comparing each metric to literature ranges. See YAML configuration for the reference YAML format.