Random structure generation

amorphgen.pipeline.random_gen

Generate amorphous structures by random atom placement with minimum-separation constraints, then optionally relax with a foundation model.

This provides an alternative to the melt-and-quench route: instead of melting a crystal and cooling it, we place atoms randomly inside a box subject to pairwise distance constraints, then optimise the structure.

Data tables (Shannon ionic radii, metallic radii, electronegativities, element classification) and helper functions (bond classification, minsep calculation, density estimation) are in amorphgen.utils.radii.

amorphgen.pipeline.random_gen.generate_random(composition, cell_length_ang=None, target_density=None, density_scale=1.0, minsep=None, minsep_scale=0.85, seed=None, max_attempts_per_atom=700000, pbc=True, target_cn=None, dmax=None, cn_tolerance=None, dmax_factor=1.5, repair_iters=0)[source]

Generate a single random structure.

Parameters:

  • composition (dict) – Atom counts per element, e.g. {“In”: 32, “O”: 48} for 80-atom In2O3. The CLI also accepts formula format (In2O3*16) which is converted to this dict form automatically.

  • cell_length_ang (float, optional) – Cubic cell edge length. If None, estimated from target_density.

  • target_density (float, optional) – Target density in g/cm3 for cell size estimation. If supplied, density_scale is ignored.

  • density_scale (float, default 1.0) – Multiplier applied to the auto-estimated density (sphere-packing or elemental-mixing path) before cell sizing. Useful for tight-network compositions (covalent semiconductors, metallic glasses) where the sphere-packing model underestimates the equilibrium amorphous density by 15-25%; setting density_scale=1.2 boosts the auto density 20%. Has no effect when target_density is supplied explicitly.

  • minsep (dict, optional) – Minimum pair separations, e.g. {“In-In”: 2.8, “In-O”: 1.9}. If None, auto-generated from Shannon ionic / metallic / covalent radii with bonding-type-aware scale factors.

  • minsep_scale (float) – Fallback scale factor for default minsep (default 0.85).

  • seed (int, optional) – Random seed for reproducibility.

  • max_attempts_per_atom (int) – Max placement attempts per atom before raising an error.

  • pbc (bool) – Periodic boundary conditions.

  • target_cn (dict, optional) – Target coordination numbers, e.g. {“Si”: 4, “O”: 2}. Enables coordination-aware placement (atoms biased toward existing under-coordinated sites within the bonding shell). Also uses CN-specific Shannon radii for tighter minsep.

  • dmax (dict, optional) – Maximum bond distances (defines “bonded”), e.g. {“Si-O”: 2.0}. Auto-generated from minsep * 1.5 if not provided.

  • cn_tolerance (int) – Over-coordination tolerance for coordination-aware placement. Default 0 (strict: reject if any neighbour is at target CN). Set to 1 to allow temporary +1 over-coordination for tighter CN matching.

  • dmax_factor (float) – Multiplier for auto dmax: dmax = minsep * dmax_factor (default 1.5). Controls the width of the bonding shell. Ignored if dmax is provided explicitly.

  • repair_iters (int, default 0) – Experimental. If > 0, run a post-placement repair loop that relocates under-coordinated atoms within the bonding shell of other under-coordinated atoms, accepting moves that reduce the total under-coord count. Useful for tetrahedral covalent networks (a-Si, a-Ge) where greedy placement leaves many atoms below target CN. Default 0 (off). See _repair_undercoordination() for caveats.

Return type:

ase.Atoms

amorphgen.pipeline.random_gen.batch_random(composition, n_structures=1, output_dir='random_structures', output_format='xyz', relax=False, calc=None, fmax=0.05, max_relax_steps=200, optimizer='FIRE', cell_filter='FrechetCellFilter', max_retries=10, resume=False, **kwargs)[source]

Generate multiple random structures, optionally relaxing each.

Parameters:

  • composition (dict)

  • n_structures (int)

  • output_dir (str)

  • output_format (str) – Output file format: “xyz” (default, extxyz format), “vasp”, “cif”.

  • relax (bool) – If True and calc is provided, optimise each structure.

  • calc (ASE calculator, optional)

  • fmax (float)

  • max_relax_steps (int)

  • optimizer (str)

  • cell_filter (str)

  • max_retries (int)

  • **kwargs – Forwarded to generate_random().

  • resume (bool)

Returns:

Paths to generated structure files. Returns file paths (not Atoms objects) because batch generation writes each structure to disk as it is created, enabling recovery from interruptions and keeping memory usage constant regardless of batch size.

Return type:

list of str

Notes

For a single structure as an Atoms object, use generate_random() directly. Keyword arguments (target_cn, minsep, dmax, minsep_scale, cn_tolerance, target_density, density_scale, cell_length_ang, max_attempts_per_atom) are forwarded to generate_random().