AmorphGen Logo

Getting Started

  • Installation
    • Requirements
    • Pick the install for your task
    • Install from PyPI
      • The torch-sim engine
    • Install from source
    • Install with conda
    • Backend compatibility
    • HPC setup (SLURM)
    • Verify installation
  • Quickstart
    • 1. Melt-and-quench pipeline
      • The 7 stages
    • 2. Random structure generation
    • 3. Hybrid ensemble
    • Batch quench
    • Ensembles on a GPU with the torch-sim engine
    • Choosing a backend
    • Accessing radii data

User Guide

  • Random structure generation
    • How it works
      • Automated minsep
        • Bond-type classifier
        • Edge cases at the classifier boundary
        • Nonmetal cations: oxoanions and hydroxides
        • Hydrogenated networks: a-Si:H, a-C:H
      • Automated density
      • Coordination-aware placement (“SC”)
      • Transparency: the auto-derive log line
    • CLI examples
    • Placement-stall policy (--retry-mode)
    • Python API
    • Accessing radii data
    • Selecting structure indices
  • Generate until converged
    • Run a complete example
    • Declare the sampling contract
    • Stopping rule
    • Batches, limits and outcomes
    • Checkpoints and resume
  • Melt-and-quench pipeline
    • Overview
    • Stage descriptions
      • Stage 1: Structure optimisation
      • Stage 2: Pre-melt equilibration
      • Stage 3: Melt (heat ramp)
      • Stage 4: High-temperature equilibration
      • Stage 5: Quench (cooling ramp)
      • Stage 6: Low-temperature equilibration
      • Stage 7: Final optimisation
    • NPT integrators
      • Stability knobs
    • Running specific stages
    • Customising parameters
    • Run manifest
  • MQ-ensemble workflow
    • Concept
    • Single-command CLI: --mq-ensemble
    • Output layout
    • Burn-in, spacing and effective snapshot count
    • How much starting crystal survives the melt?
    • HPC job-array tip
    • Choosing protocol parameters: a note on methodology
    • Example mq.yaml for an oxide
    • Equivalent two-step manual workflow
    • HPC / Slurm split (best for parallelism)
    • Resume behaviour
    • When to use --mq-ensemble vs the alternatives
    • Validation
  • Batch quench
    • Use case
    • CLI usage
    • Python API
  • Hybrid workflow
    • Concept
    • Single-command CLI: --hybrid-ensemble
      • Batched on a GPU with torch-sim
    • Example hybrid.yaml for an oxide
    • When to use the hybrid workflow
    • Comparison to --mq-ensemble (crystal melt-quench)
    • Example: a-TiO₂
  • Best practices & limitations
    • Choose the ensemble and calculator together
      • Decision guide
    • Quantitative protocol: starting values and convergence
      • Timestep and physical duration
      • Cooling rate and simulation cost
      • Cell size and accessible length scales
      • Independent structures and a quantitative stopping rule
      • Worked starting configuration
    • Choosing the anneal temperature
    • Validate the density and override an uncertain estimate
    • Known limitations
    • Further reading
  • Analysis
    • Screening and analysis inclusion
    • Spread and uncertainty of the mean
    • Declared tolerances and ensemble convergence
    • Recipes
    • Which contacts count as bonds?
    • Cutoff
      • Cutoff robustness
      • Total coordination
    • Structure factor S(q) and simulated XRD
      • Example: a-Ga₂O₃
      • Compare measured S(q) or T(r)
    • Ring sizes and search coverage
    • Crystal-like order and the largest ordered cluster
    • Void, oxygen, elastic and vibrational descriptors
      • Void distribution
      • Bridging and non-bridging oxygen
      • Elastic moduli from calculator stresses
      • Harmonic vibrational density of states
    • Full CLI flag reference
    • Outputs explained
    • Python API
    • Troubleshooting
      • “Density is high but CN looks too low”
      • “Per-structure E/atom shows N/A”
      • “Si–Si appears as a bond in a-SiO₂”
      • “RDF goes to zero suddenly at large r”
  • Calculator backends
    • MLIP backends
      • MACE
      • CHGNet
      • SevenNet
      • Custom / fine-tuned models
    • Classical potentials
      • Lennard-Jones
      • Buckingham + Coulomb
    • Listing available models
    • Batched relaxation with torch-sim (optional)
      • Batched MD for the hybrid workflow
  • YAML configuration
    • Configuration precedence
    • Structure
    • MLIP failure checks and optional stabilisation
    • Example: full melt-quench pipeline
    • Example: hybrid (random + quench)
    • Example: validation reference YAML
    • Example: classical potential
    • Loading YAML in Python
    • Stage-1 vs stage-7 optimisation: the final_opt fallback
    • Selecting an NPT integrator
      • Tuning the Berendsen barostat
    • The analysis block
      • Ensemble precision targets
      • Optional material descriptors
    • Reproducibility: the seed key
    • Tips
  • Benchmarks: Random Generation Methods
    • Methods compared
    • Historical results
      • SiO₂ (48 atoms: Si₁₆O₃₂)
      • Si (40 atoms)
      • Li₂ZrCl₆ (72 atoms: Li₁₆Zr₈Cl₄₈)
    • Designing a comparison
    • Example protocols
      • SiO₂ with CHGNet MQ
      • Li₂ZrCl₆ with MACE MQ
      • Python API
    • Equilibration convergence
    • Random-placement comparison configs
  • CLI & Python API Reference
    • CLI Commands
      • Structure Generation
      • Batch Optimisation
      • Batch Quench
      • Melt-Quench Pipeline
      • Structure Analysis
      • Utility
    • Python API
      • Structure Generation
      • Batch Optimisation
      • Melt-Quench Pipeline
      • Structure Analysis
      • Batch Quench (Python API)
      • YAML Configuration
      • List Available Models
    • YAML Config Reference
    • Pipeline Stages
    • Default Output Directories
    • Random Generation: Automated Defaults
    • Cell Filter Options
  • HPC deployment
    • Generate a portable workflow
      • Arrays and dependencies
    • Checkpointing on signals and preemption
    • Configuring the bundled examples
    • Resuming timed-out jobs
      • Pipeline mode
      • Batch quench mode
      • Ensembles on the torch-sim engine
      • Python API

Tutorials

  • Tutorials

Validation

  • Validation
    • a-Ga₂O₃
      • Results vs DFT-PBE0 + experiment
      • Validation figure
      • Run a similar comparison
    • Data availability
    • Reference data sources

API Reference

  • Calculators
    • Calculator factory
      • get_calculator()
      • list_models()
    • Backend detection
      • backend_available()
      • available_backends()
      • require_backend()
    • MACE models
    • CHGNet
    • SevenNet models
    • Classical potentials
      • LennardJonesCalculator
        • LennardJonesCalculator.implemented_properties
        • LennardJonesCalculator.calculate()
      • BuckinghamCalculator
        • BuckinghamCalculator.implemented_properties
        • BuckinghamCalculator.calculate()
    • Deprecated aliases
      • get_mace_calculator()
  • Random structure generation
    • amorphgen.pipeline.random_gen
    • generate_random()
    • batch_random()
    • random_gen_dir_hint()
  • Pipeline
    • MeltQuenchPipeline
      • MeltQuenchPipeline
        • MeltQuenchPipeline.STAGE_NAMES
        • MeltQuenchPipeline.STAGE_CHECKPOINTS
        • MeltQuenchPipeline.run()
    • Stage modules
      • Stage 1: Structure optimisation
        • amorphgen.pipeline.opt_cell
        • run()
        • batch_optimize()
      • Stage 2, 4, 6: Equilibration
        • amorphgen.pipeline.equilibrate
        • run()
      • Stage 3: Melt (heat ramp)
        • amorphgen.pipeline.melt_cell
        • run()
      • Stage 5: Quench (cooling ramp)
        • amorphgen.pipeline.quench
        • run()
      • Stage 7: Final optimisation
        • amorphgen.pipeline.final_opt
        • run()
      • Batch quench
        • amorphgen.pipeline.batch_quench
        • run()
        • run_torchsim()
  • Structure analysis
    • StructureAnalyser
      • StructureAnalyser
        • StructureAnalyser.__init__()
        • StructureAnalyser.screen()
        • StructureAnalyser.screened()
        • StructureAnalyser.total_coordination()
        • StructureAnalyser.density()
        • StructureAnalyser.coordination()
        • StructureAnalyser.cutoff_robustness()
        • StructureAnalyser.dimer_report()
        • StructureAnalyser.bond_order()
        • StructureAnalyser.bond_distances()
        • StructureAnalyser.bond_angles()
        • StructureAnalyser.angle_distribution()
        • StructureAnalyser.rdf()
        • StructureAnalyser.structure_factor()
        • StructureAnalyser.structure_factor_direct()
        • StructureAnalyser.total_correlation()
        • StructureAnalyser.xrd_pattern()
        • StructureAnalyser.compare_experiment()
        • StructureAnalyser.averaged_rdf()
        • StructureAnalyser.ring_statistics()
        • StructureAnalyser.polyhedral_connectivity()
        • StructureAnalyser.voronoi()
        • StructureAnalyser.void_distribution()
        • StructureAnalyser.oxygen_speciation()
        • StructureAnalyser.elastic_moduli()
        • StructureAnalyser.vibrational_dos()
        • StructureAnalyser.energy_ranking()
        • StructureAnalyser.averaged_cn()
        • StructureAnalyser.convergence_report()
        • StructureAnalyser.summary()
        • StructureAnalyser.per_structure_summary()
        • StructureAnalyser.save_report()
        • StructureAnalyser.plot()
    • Screening
      • validate_screening_config()
      • screen_structures()
      • mark_screening_analysed()
      • format_screening_report()
      • write_screening_outputs()
    • Ring sizes and void clearance
    • Cutoff robustness
      • format_cutoff_robustness()
      • save_cutoff_robustness()
    • Measured scattering and XRD
      • load_experiment()
      • compare_experiment()
      • format_experiment_report()
      • save_experiment_comparison()
      • compute_xrd_pattern()
      • save_xrd_pattern()
    • Optional material descriptors
      • compute_bond_order()
      • compute_void_distribution()
      • compute_oxygen_speciation()
      • compute_elastic_moduli()
      • compute_vibrational_dos()
      • Bond order result
      • Initial-crystal retention
        • compute_melt_memory()
        • format_melt_memory()
    • Ensemble convergence
      • convergence_report()
      • format_convergence_report()
      • save_convergence_report()
    • Reference-validation helpers
      • validate_against_reference()
      • format_validation_report()
    • Energy ranking helpers
      • compute_energy_ranking()
      • rank_from_log()
      • format_log_ranking()
    • Comparing ensembles
      • EnsembleSpec
        • EnsembleSpec.label
        • EnsembleSpec.files
        • EnsembleSpec.color
        • EnsembleSpec.cutoff
        • EnsembleSpec.resolve_files()
        • EnsembleSpec.analyser()
        • EnsembleSpec.from_analyser()
      • compare_ensembles()
    • Submodule reference
  • Command-line interface
    • Usage
    • CLI reference
      • amorphgen.cli
      • Examples (advanced)
      • parse_args()
      • main()
    • Examples
      • Full pipeline
      • Full pipeline with YAML config
      • MQ-ensemble (full pipeline + N quenches in one command)
      • Hybrid ensemble (random + quench)
      • Extract snapshots from a trajectory
      • Hybrid workflow (skip heating)
      • Pipeline with resume
      • Random generation
      • Batch optimisation
      • Batch quench with resume
      • Structure analysis
      • Rank structures by energy (from a random-gen log)
      • List available models
    • Default output directories
  • Configuration
    • Default configuration
      • amorphgen.configs.default_config
    • Configuration keys
    • Configuration precedence
    • Override examples
      • Python API
      • YAML config
  • Utilities
    • Common helpers
      • amorphgen.utils.common
      • compute_density_gcm3()
      • DivergenceError
      • assert_finite()
      • resolve_device()
      • make_cubic()
      • cubic_cell_filter()
      • calculator_supports_stress()
      • require_stress()
      • build_md_dynamics()
      • parse_index_spec()
      • stage_rng()
      • scoped_run_index()
      • run_index_from_cwd()
      • run_index_for()
      • resolve_ramp()
      • MDLogger
        • MDLogger.log()
        • MDLogger.close()
      • TrajectoryWriter
        • TrajectoryWriter.write()
        • TrajectoryWriter.close()
      • attach_outputs()
      • read_md_checkpoint()
      • resume_md_stage()
      • needs_velocity_init()
      • ramp_resume_position()
      • set_md_temperature()
      • merge_config()
      • stage_file()
      • extract_snapshots()
    • Radii, classification and auto-derivation
      • amorphgen.utils.radii
      • infer_oxidation_state()
      • cation_nonmetals()
      • auto_target_cn()
      • classify_bond()
      • get_ionic_radius()
      • get_metallic_radius()
      • get_effective_radius()
      • default_minsep()
      • estimate_density()
      • get_packing_factor()
      • anion_elements()
      • estimate_cell_length()
      • format_auto_derive_summary()
    • Format conversion
      • amorphgen.utils.convert
      • convert()
    • MD equilibration convergence analysis
      • amorphgen.utils.equilibration
      • Usage
      • parse_md_log()
      • running_average()
      • extract_energies()
      • plot_energy_convergence()
      • block_average_test()
      • plot_block_averages()
      • compute_msd()
      • plot_msd()
      • plot_temperature()
      • plot_rdf_time_windows()
      • compute_cn_vs_time()
      • plot_cn_vs_time()
      • convergence_report()
    • Other utility modules

Methodology

  • S(q) and XRD: methodology notes
    • Choosing a method
    • Normalization of the direct method
    • Fourier transform of g(r)
    • Checks and experimental comparison
  • Scattering methods and citations
    • Sources used by the implementation
    • Reporting a calculation

Development

  • Contributing
    • Getting started
    • Development setup
    • Running tests
    • Code style
    • How to contribute
      • Reporting bugs
      • Suggesting features
      • Submitting changes
      • Adding a new MLIP backend
      • Tutorials
      • Documentation
    • Project structure
    • Code of conduct
    • Questions?
    • AI-assisted development disclosure
  • Changelog
    • Unreleased
      • Added
      • Fixed
    • v1.0.0rc4 (2026-09-24)
      • Added
      • Fixed
      • Added after the rc4 upload (on GitHub main, 2026-09-24; not in the rc4 wheel on PyPI)
      • Fixed after the rc4 upload (on GitHub main; not in the rc4 wheel on PyPI)
    • v1.0.0rc3 (2026-09-22)
      • Added
      • Fixed
      • Added
      • Changed
    • v1.0.0rc2 (2026-05-22)
      • Changed (breaking)
      • Added
      • Fixed
AmorphGen
  • Python Module Index

Python Module Index

a
 
a
- amorphgen
    amorphgen.analysis.energy
    amorphgen.analysis.validate
    amorphgen.cli
    amorphgen.configs.default_config
    amorphgen.pipeline.batch_quench
    amorphgen.pipeline.equilibrate
    amorphgen.pipeline.final_opt
    amorphgen.pipeline.melt_cell
    amorphgen.pipeline.opt_cell
    amorphgen.pipeline.quench
    amorphgen.pipeline.random_gen
    amorphgen.utils.common
    amorphgen.utils.convert
    amorphgen.utils.equilibration
    amorphgen.utils.radii

© Copyright 2026, Chaiyawat Kaewmeechai.

Built with Sphinx using a theme provided by Read the Docs.