Pipeline

The pipeline module implements the 7-stage melt-and-quench molecular dynamics workflow.

MeltQuenchPipeline

class amorphgen.pipeline.run_pipeline.MeltQuenchPipeline(input_file, work_dir='melt_quench_run', cfg_override=None, share_calc=True)

Bases: object

End-to-end melt-and-quench pipeline for amorphous structure generation.

Parameters:

• input_file (str) – Path to the starting crystalline structure (any ASE-readable format).

• work_dir (str) – Directory where all output files are written. Created if absent.

• cfg_override (dict, optional) –

  Any keys in DEFAULT_CONFIG to override, including:

  • "model" : foundation model short name (any backend)

  • "model_path" : path to local .model file (overrides model)

  • "device" : "cuda" or "cpu"

  • "eq_premelt" : {"ensemble": "NVT" or "NPT", ...}

  • "melt" : {"ensemble": "NVT" or "NPT", ...}

  • "quench" : {"ensemble": "NVT" or "NPT", ...}

  • "eq_high" : {"ensemble": "NVT" or "NPT", ...}

  • "eq_low" : {"ensemble": "NVT" or "NPT", ...}

• share_calc (bool) – If True, one calculator is shared across all stages.

STAGE_NAMES = {1: 'Structure optimisation (crystalline)', 2: 'Pre-melt equilibration (300 K)', 3: 'Melt (heat ramp)', 4: 'High-T equilibration', 5: 'Quench (cooling ramp)', 6: 'Low-T equilibration', 7: 'Final optimisation (amorphous)'}

STAGE_CHECKPOINTS = {1: 'stage1_opt.xyz', 2: 'stage2_eq.xyz', 3: 'stage3_melted.xyz', 4: 'stage4_eq.xyz', 5: 'stage5_quenched.xyz', 6: 'stage6_eq.xyz', 7: 'stage7_opt.xyz'}

run(stages=None, input_file=None, resume=False)

Execute the pipeline.

Parameters:

• stages (list of int, optional) – Which stages to run (default: all, i.e. [1, 2, 3, 4, 5, 6, 7]).

• input_file (str, optional) – Override the input structure file (useful for resuming from a mid-pipeline checkpoint).

• resume (bool) – If True, scan work_dir for completed stage checkpoints and skip stages that already have output files. Automatically determines which stage to resume from and which input file to use.

Returns:

The final optimised amorphous structure.

Return type:

ase.Atoms

Stage modules

Stage 1 & 7: Structure optimisation

amorphgen.pipeline.opt_cell

Stage 1 – Structural optimisation of the crystalline input cell. Stage 7 – Final optimisation of the quenched amorphous structure.

Supported optimisers (set via cfg[“opt”][“optimizer”]):

“LBFGS” – default, fast quasi-Newton (recommended) “FIRE” – molecular dynamics based, good for difficult cases “BFGSLineSearch” – robust line-search BFGS “BFGS” – classic BFGS “MDMin” – simple MD minimiser

amorphgen.pipeline.opt_cell.run(atoms_or_file, cfg_override=None, calc=None, stage_key='opt', **kwargs)

Optimise a structure using a chosen optimizer + cell filter.

Parameters:

• atoms_or_file (str or ase.Atoms)

• cfg_override (dict, optional)

• calc (ASE calculator, optional)

• stage_key (str) – Config section to read (“opt”).

Return type:

ase.Atoms

amorphgen.pipeline.opt_cell.batch_optimize(input_dir, output_dir=None, cfg_override=None, calc=None, pattern='*.xyz', **kwargs)

Optimise all structures in a directory using opt_cell.run().

Parameters:

• input_dir (str) – Directory containing input structure files.

• output_dir (str, optional) – Directory for output files. If None, a subdirectory input_dir + "_opt" is created.

• cfg_override (dict, optional) – Config overrides (passed to run()).

• calc (ASE calculator, optional) – Shared calculator. If None, one is created from cfg.

• pattern (str) – Glob pattern for input files (default: *.xyz).

• **kwargs – Forwarded to run().

Returns:

Paths to optimised output files (.xyz).

Return type:

list of str

Stage 2, 4, 6: Equilibration

amorphgen.pipeline.equilibrate

Stages 2, 4 & 6 – Constant-temperature equilibration.

Stage 2 (stage=”premelt”): pre-melt equilibration at 300 K Stage 4 (stage=”high”): high-T equilibration after melting Stage 6 (stage=”low”): low-T equilibration after quenching

amorphgen.pipeline.equilibrate.run(atoms_or_file, cfg_override=None, calc=None, stage='high', **kwargs)

Equilibrate the structure at a fixed temperature.

Parameters:

• atoms_or_file (str or ase.Atoms)

• cfg_override (dict, optional)

• calc (ASE calculator, optional)

• stage (str) – “premelt” for Stage 2 (eq_premelt), “high” for Stage 4 (eq_high), or “low” for Stage 6 (eq_low).

Return type:

ase.Atoms

Stage 3: Melt (heat ramp)

amorphgen.pipeline.melt_cell

Stage 3 – Heat the structure from T_start to T_end via a temperature ramp.

Ensemble is configurable: NPT (default) or NVT.

amorphgen.pipeline.melt_cell.run(atoms_or_file, cfg_override=None, calc=None, **kwargs)

Heat the structure from T_start -> T_end.

Parameters:

• atoms_or_file (str or ase.Atoms)

• cfg_override (dict, optional)

• calc (ASE calculator, optional)

Return type:

ase.Atoms — melted structure at T_end

Stage 5: Quench (cooling ramp)

amorphgen.pipeline.quench

Stage 5 – Cool the melt from T_start down to T_end via a temperature ramp.

Ensemble is configurable: NVT (default) or NPT.

amorphgen.pipeline.quench.run(atoms_or_file, cfg_override=None, calc=None, **kwargs)

Cool the structure from T_start -> T_end.

Parameters:

• atoms_or_file (str or ase.Atoms)

• cfg_override (dict, optional)

• calc (ASE calculator, optional)

Return type:

ase.Atoms — quenched structure at T_end

Final optimisation

amorphgen.pipeline.final_opt

Stage 7 – Final structural optimisation of the quenched amorphous structure.

Delegates to opt_cell.run() with stage_key=”final_opt”.

amorphgen.pipeline.final_opt.run(atoms_or_file, cfg_override=None, calc=None, **kwargs)

Final optimisation of the amorphous structure.

Wraps opt_cell.run() — see that function for full parameter docs.

Batch quench

amorphgen.pipeline.batch_quench

Run a subset of pipeline stages independently on each of N input structures, producing a library of amorphous candidates.

Typical use cases:

• MQ snapshot quench (default stages=[5, 6, 7]): take N snapshots extracted from a Stage 4 high-T equilibration trajectory and quench each through stages 5 (cooling) -> 6 (low-T eq) -> 7 (final opt).

• Hybrid workflow (stages=[4, 5, 6, 7]): take N already-disordered inputs (e.g. --random-gen outputs), anneal at high T, then quench.

Stage numbers follow the canonical 7-stage pipeline: 4 = eq_high, 5 = quench, 6 = eq_low, 7 = final_opt.

amorphgen.pipeline.batch_quench.run(snapshot_files, n_runs=None, select='uniform', cfg_override=None, work_dir='batch_quench', stages=None, calc=None, resume=False)

Batch quench multiple snapshots.

Parameters:

• snapshot_files (list of str) – Paths to snapshot structure files.

• n_runs (int, optional) – Number of runs (defaults to len(snapshot_files)).

• select (str) – How to select snapshots: “uniform” or “last”.

• cfg_override (dict, optional)

• work_dir (str) – Base output directory.

• stages (list of int) – Which stages to run per snapshot. Stage numbers follow the canonical 7-stage pipeline: 4=eq_high, 5=quench, 6=eq_low, 7=final_opt. Default [5, 6, 7] (quench + eq_low + final_opt — the standard post-Stage-4 batch workflow). Include 4 when starting from random / already-disordered structures that need to be annealed first (the ‘hybrid’ workflow).

• calc (ASE calculator, optional)

• resume (bool) – If True, skip runs whose final output already exists.