Command-line interface

AmorphGen provides a single amorphgen command with multiple modes of operation.

Usage

amorphgen [INPUT] [OPTIONS]                      # Full melt-quench pipeline
amorphgen [INPUT] --mq-ensemble [OPTIONS]         # MQ ensemble (1-4 + N×5-7)
amorphgen --hybrid-ensemble --input-dir DIR       # Hybrid ensemble (4-7 per input)
amorphgen --random-gen [OPTIONS]                  # Random generation mode
amorphgen --batch-quench --snapshot-dir DIR       # Batch quench mode
amorphgen --batch-opt --input-dir DIR             # Batch optimisation mode
amorphgen --analyse --input-dir DIR               # Structure analysis mode
amorphgen --extract-snapshots TRAJ                # Extract N snapshots from a trajectory
amorphgen --rank-from-log LOG                     # Energy ranking from log file
amorphgen --list-models                           # Show available models

CLI reference

amorphgen.cli

Command-line interface for AmorphGen.

Examples

Full pipeline with MACE (default):: amorphgen POSCAR
Use CHGNet:: amorphgen POSCAR –model chgnet –device cpu
Use a custom fine-tuned model:: amorphgen POSCAR –model-path /data/InO_finetuned.model
List all available models:: amorphgen –list-models
Random structure generation:: amorphgen –random-gen –composition “In2O3*16” –relax amorphgen –random-gen –composition In=32,O=48 –target-density 5.5
Random generation with custom minsep:: amorphgen –random-gen –composition “In2O3*8” –target-density 5.5 –minsep In-In=2.8,In-O=1.9,O-O=2.5
Optimise with cubic cell constraint:: amorphgen POSCAR –stages 1 –cell-filter cubic –model mace-mpa-0-medium
Batch quench from snapshots:: amorphgen –batch-quench –snapshot-dir snapshots/ –n-runs 20
Convert structure files between formats (xyz/extxyz/vasp/cif):: amorphgen –convert snapshots/ –format vasp -o snapshots_vasp/ amorphgen –convert traj_frame.xyz –format cif amorphgen –config convert.yaml # YAML-driven (uses convert: block)

amorphgen.cli.parse_args()[source]: Parse command-line arguments.

amorphgen.cli.main()[source]

Examples

Full pipeline

amorphgen POSCAR --model mace-mpa-0 --device cuda

Full pipeline with YAML config

amorphgen POSCAR --config full_pipeline.yaml

MQ-ensemble (full pipeline + N independent quenches in one command)

The cleanest way to generate an ensemble of amorphous structures from a crystalline input. Internally runs stages 1–4 once, extracts N uniform snapshots from the stage-4 trajectory, and runs stages 5–7 on each snapshot. Resume-aware at every step.

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

Output layout:

ga2o3_mq/
├── shared/        # stages 1-4 outputs (incl. stage4_eq_traj.xyz)
├── snapshots/     # 20 uniform snapshots
├── quench_runs/   # per-snapshot stages 5-6-7 outputs
└── final/         # collected mq_0000.<fmt> ... mq_0019.<fmt>

Hybrid ensemble (random + quench)

Take a directory of disordered structures (e.g. --random-gen outputs) and run stages 4-5-6-7 on each:

amorphgen --hybrid-ensemble --input-dir random_structures/ \
    --config hybrid.yaml --device cuda --model chgnet \
    -o ga2o3_hybrid/

Useful for producing an amorphous ensemble from already-disordered starting structures (skipping the crystal-melt steps).

Extract snapshots from a trajectory

Standalone utility to extract N uniformly-spaced frames from any trajectory file:

amorphgen --extract-snapshots stage4_eq_traj.xyz \
    -n 20 --select uniform -o snapshots/

-n (or --n-structures) and the legacy --n-runs both control the snapshot count. Use --format vasp (or cif) to write POSCAR-style output instead of the default extxyz .xyz:

amorphgen --extract-snapshots stage4_eq_traj.xyz \
    -n 20 --burn-in-frames 50 --format vasp -o snapshots/

--batch-quench also accepts a trajectory file directly via --snapshot-dir <file.xyz> and extracts internally:

amorphgen --batch-quench --snapshot-dir stage4_eq_traj.xyz \
    --n-runs 20 --batch-stages 5 6 7 \
    --config mq_quench.yaml -o quench_runs/

Hybrid workflow (skip heating)

amorphgen structure.xyz --stages 1 4 5 6 7 --config hybrid.yaml

Pipeline with resume

amorphgen POSCAR --stages 1 4 5 6 7 --config config.yaml --resume

The --resume flag scans the work directory for completed stage checkpoints and skips them. Safe to resubmit HPC jobs without losing progress.

Random generation

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

# Atom count format (equivalent)
amorphgen --random-gen --composition In=16,O=24 --n-structures 20

# With relaxation and cubic cell constraint
amorphgen --random-gen --composition "Li2ZrCl6*4" \
    --relax --model chgnet --device cpu --cell-filter cubic

# Custom output directory
amorphgen --random-gen --composition "SiO2*16" \
    --work-dir my_SiO2_structures/

Batch optimisation

amorphgen --batch-opt --input-dir random_structures/ \
    --model chgnet --cell-filter cubic

Batch quench with resume

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

Structure analysis

# Basic analysis (RDF, CN, bond angles, density)
amorphgen --analyse --input-dir optimised/

# Per-structure comparison table + total RDF + Gaussian smearing for experimental comparison
amorphgen --analyse --input-dir optimised/ \
    --cutoff auto-rdf --per-structure --total-rdf --smearing 0.05 \
    --save-report report.txt --save-plot plots/

# Publication-quality plots (300 DPI, vector PDF)
amorphgen --analyse --input-dir optimised/ \
    --save-plot figs/ --save-pdf --dpi 600

# Validate against literature ranges defined in a reference YAML
amorphgen --analyse --input-dir optimised/ \
    --reference examples/reference_a_Ga2O3.yaml

Rank structures by energy (from a random-gen log)

When outputs are written as .vasp or .cif (which don’t carry per-atom energy), parse the relax log to rank structures by total energy without re-running the calculator:

amorphgen --rank-from-log random_structures/random_gen.log

Returns a sorted table of structure index, total energy, energy/atom, fmax, and step count. Useful for selecting the lowest-energy member of an ensemble for follow-up DFT work.

List available models

amorphgen --list-models

Default output directories

Mode	Default `--work-dir`
Pipeline	`melt_quench_run/`
`--mq-ensemble`	`mq_ensemble/`
`--hybrid-ensemble`	`hybrid_ensemble/`
`--random-gen --composition X=n,Y=m`	`random_XnYm/` (auto from composition)
`--batch-quench`	`batch_quench/`
`--batch-opt`	`batch_opt/`

Override any default with --work-dir my_dir/.