Geo Generator

Geometry and structure generators for ReaxFF simulations.

This module provides high-level utilities for creating, converting, and manipulating atomic structures used in ReaxFF workflows.

Capabilities include:

Conversion of XYZ files to GEO/XTLGRF format with full ReaxFF-compliant formatting.
Structure I/O wrappers based on ASE (CIF, POSCAR, VASP, XYZ, etc.).
Surface slab construction from bulk crystals.
Supercell generation via repetition or full 3×3 transformation matrices.
Hexagonal → orthorhombic cell transformations.
A Python reimplementation of the Fortran place2 algorithm for random molecular packing with periodic boundary conditions.
Programmatic insertion of sample restraint blocks into GEO files.

Generators in this module:

operate deterministically on input structures
write files or return ASE Atoms objects
do not perform simulation, analysis, or parsing of ReaxFF output

`add_restraints_to_geo(geo_file, *, out_file=None, kinds, params=None)`

Insert sample restraint blocks into a GEO/XTLGRF file.

Insert BEFORE first line starting with any of: CRYSTX, FORMAT ATOM, HETATM, ATOM else before END, else EOF.

For each kind write exactly 3 lines (NO blank lines): FORMAT ... # (guide) RESTRAINT ... (fields LEFT-aligned under guide headers)

Works on

ReaxFF GEO/XTLGRF structure files

Parameters:

Name	Type	Description	Default
`geo_file`	`str or Path`	Input GEO file.	required
`out_file`	`str or Path or None`	Output file path.	`None`
`kinds`	`sequence of str`	Restraint kinds to insert (e.g. BOND, ANGLE).	required
`params`	`dict or None`	Custom restraint parameter strings.	`None`

Returns:

Type	Description
`Path`	Path to the modified GEO file.

Examples:

>>> add_restraints_to_geo("geo", kinds=["BOND", "ANGLE"])

`build_surface(bulk, miller, layers, vacuum=15.0, center=True)`

Build a surface slab from a bulk structure using Miller indices.

Works on

ASE Atoms bulk structures

Parameters:

Name	Type	Description	Default
`bulk`	`Atoms`	Bulk crystal structure.	required
`miller`	`(h, k, l)`	Miller indices defining the surface orientation.	required
`layers`	`int`	Number of atomic layers.	required
`vacuum`	`float`	Vacuum thickness along the surface normal (Å).	`15.0`
`center`	`bool`	Center the slab along the surface-normal direction.	`True`

Returns:

Type	Description
`Atoms`	Surface slab structure.

Examples:

>>> slab = build_surface(bulk, (0,0,1), layers=6)

`make_supercell(atoms, transform)`

Generate a supercell or apply a lattice transformation.

Works on

ASE Atoms structures

Parameters:

Name	Type	Description	Default
`atoms`	`Atoms`	Input structure.	required
`transform`	`(nx, ny, nz) tuple or 3×3 integer matrix`	Repetition factors or full transformation matrix.	required

Returns:

Type	Description
`Atoms`	Transformed structure.

Examples:

>>> sc = make_supercell(atoms, (2,2,1))

`orthogonalize_hexagonal_cell(atoms)`

Convert a hexagonal unit cell into an orthorhombic cell.

Convert a hexagonal cell (90°, 90°, 120°) into an orthorhombic cell (90°, 90°, 90°) using the standard a-b, a+b transformation.

Works on

ASE Atoms structures with hexagonal lattice geometry

Parameters:

Name	Type	Description	Default
`atoms`	`Atoms`	Hexagonal structure.	required

Returns:

Type	Description
`Atoms`	Orthorhombic structure.

Examples:

>>> ortho = orthogonalize_hexagonal_cell(hex_atoms)

`place2(insert_molecule, base_structure=None, *, n_copies, box_length_x, box_length_y, box_length_z, alpha, beta, gamma, min_interatomic_distance, base_structure_placement_mode='as-is', max_placement_attempts_per_copy=50000, random_seed=None)`

Randomly place multiple copies of a molecule into a simulation cell.

Python reimplementation of the Fortran place2 algorithm

Works on

Molecular structure files and simulation boxes

Parameters:

Name	Type	Description	Default
`insert_molecule`	`str or Path`	Structure to be duplicated.	required
`base_structure`	`str or Path or None`	Initial structure to insert into.	`None`
`n_copies`	`int`	Number of copies to place.	required
`box_length_x`	`float`	Simulation box lengths (Å).	required
`box_length_y`	`float`	Simulation box lengths (Å).	required
`box_length_z`	`float`	Simulation box lengths (Å).	required
`alpha`	`float`	Cell angles (degrees).	required
`beta`	`float`	Cell angles (degrees).	required
`gamma`	`float`	Cell angles (degrees).	required
`min_interatomic_distance`	`float`	Minimum allowed atomic separation.	required
`base_structure_placement_mode`	`str`	Base structure positioning mode.	`'as-is'`
`max_placement_attempts_per_copy`	`int`	Maximum placement attempts.	`50000`
`random_seed`	`int or None`	Random seed for reproducibility.	`None`

Returns:

Type	Description
`Atoms`	Combined atomic system.

Examples:

>>> atoms = place2("H2O.xyz", n_copies=100, box_length_x=30,
...                box_length_y=30, box_length_z=30,
...                alpha=90, beta=90, gamma=90,
...                min_interatomic_distance=1.5)

`read_structure(path, format=None, index=0)`

Read a structure file using ASE.

Works on

ASE-supported structure formats (CIF, POSCAR, XYZ, etc.)

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Structure file path (CIF, POSCAR, XYZ, etc.).	required
`format`	`str`	ASE format string. If None, ASE infers from file extension.	`None`
`index`	`int \| str`	Image index if the file contains multiple structures.	`0`

Returns:

Type	Description
`Atoms`	Loaded structure.

Examples:

>>> atoms = read_structure("AlN.cif")

`write_structure(atoms, path, format=None, comment=None)`

Write a structure to file in any ASE-supported format.

Works on

ASE Atoms objects

Parameters:

Name	Type	Description	Default
`atoms`	`Atoms`	Structure to write.	required
`path`	`str or Path`	Output file path. Extension is used to guess format if `format` is None.	required
`format`	`str`	This is based on ASE format support as explained here: https://ase-lib.org/ase/io/io.html#ase.io.write ASE format string (e.g., "xyz", "cif", "vasp", "xsf"). If None, ASE guesses from the file extension.	`None`

Returns:

Type	Description
`None`

Examples:

>>> write_structure(atoms, "out.xyz")

`xtob(xyz_file, geo_file='geo', box_lengths=(1.0, 1.0, 1.0), box_angles=(90.0, 90.0, 90.0), sort_by=None, ascending=True)`

Convert an XYZ file to ReaxFF GEO/XTLGRF format.

This function reads a simple XYZ structure, optionally sorts atoms, assigns sequential atom IDs, and writes a fully formatted GEO file compatible with ReaxFF.

Works on

XYZ structure files

Parameters:

Name	Type	Description	Default
`xyz_file`	`str \| Path`	Input XYZ file.	required
`geo_file`	`str \| Path`	Output GEO file path (default: `"geo"`).	`'geo'`
`box_lengths`	`iterable of float`	Periodic cell lengths (a, b, c) in Å.	`(1.0, 1.0, 1.0)`
`box_angles`	`iterable of float`	Periodic cell angles (alpha, beta, gamma) in degrees.	`(90.0, 90.0, 90.0)`
`sort_by`	`('x', 'y', 'z', 'atom_type')`	If provided, sort atoms before writing.	`"x","y","z","atom_type"`
`ascending`	`bool`	Sort direction.	`True`

Returns:

Type	Description
`None`	Writes the GEO file to disk.

Examples:

>>> xtob("structure.xyz", "geo", box_lengths=(10,10,10))