Reference

This page describes the responsibilities of the main components for users.

The complete generated listing of classes, methods, arguments, type annotations, and docstrings is available at packmol_util.

AmorphousBuilder

The high-level interface that coordinates structure generation.

Main responsibilities:

• Store element symbols and composition ratios

• Reconcile total atom count with composition ratios

• Determine the composition-unit multiplier

• Determine cell size from mass density or number density

• Register Packmol templates

• Generate Packmol input

• Run Packmol

• Convert output to POSCAR

This is the usual entry point.

Packmol

Handles Packmol execution and associated numerical operations.

Main responsibilities:

• Atomic masses and mean atomic mass

• Conversion between mass density and number density

• Cell-size calculation from atom count and number density

• Packmol execution

• XYZ-to-POSCAR conversion

PackmolInp

Constructs Packmol input files.

It translates structure templates, copy counts, placement regions, packing radii, and other settings into Packmol input syntax.

model

Handles structure templates and recipes supplied to Packmol.

It can generate XYZ templates for individual atoms and multi-atom structural units.

Config

Loads packmol_util settings from configuration files.

param

Stores constants used in density and cell-size calculations, including atomic masses.

API Reference

• packmol_util
  • packmol_util package

This section is not maintained manually. docs/build.sh scans src/packmol_util and generates it during the documentation build.

Distinctions among public APIs

Component	Main APIs	Purpose
AmorphousBuilder	__init__, multiplier, add_template, build	Generate structures from composition, density, and templates
PackmolInp	__init__, add_structure, write	Generate .inp files
Packmol	number_density_from_mass_density, mass_density_from_number_density, cell_length_from_number_density	Density and cell-edge calculations
Packmol	compute_element_counts, compute_cell_sizes, get_unit_atom_count	Atom counts and composition ratios
Packmol	run_packmol, xyz_to_poscar, write_fnc_file, count_atoms_in_xyz	Execution, conversion, and FNC output
model	write_xyz_template, write_single_atom_xyz, write_tetrahedral_unit_xyz	Create XYZ templates
model	StructureSpec, MaterialRecipe, make_material_recipe, make_atomic_mixture_recipe	Placement recipes
model	make_tetrahedral_unit_fnc_pairs, make_tetrahedral_unit_fnc_spec_from_ranges, TetrahedralUnitFncSpec	Tetrahedral FNC constraints
model	solve_packing_radii_from_pair_distances	Approximate packing radii from element-pair distances
Config	__init__(yaml_path=...), load_yaml()	Load YAML settings

AmorphousBuilder arguments

symbols and ratios specify corresponding elements and integer composition ratios. total_atom_count is the requested number of atoms; minimum_separation is Packmol’s tolerance; mass_density is in g/cm³; number_density is in Å⁻³; and packmol_bin is an executable name or path. Number density takes precedence if both density parameters are supplied. In add_template(xyz_file, number, packing_radii=None, fnc_pairs_in_template=None, fnc_distance_ranges=None, fnc_output_constraint_types=None), number means the number of template copies, not the number of atoms.

PackmolInp arguments

PackmolInp(minimum_separation_distance, output_xyz, box_length, use_pbc=False) uses a cubic cell. The radii dictionary passed to add_structure(xyz_file, number, packing_radii_by_atom_symbol=None) is keyed by element symbol. write(inp_file) converts element symbols in the template into 1-based Packmol atom indices and, when needed, writes atoms ... radius ... end atoms blocks.

Loading Config

Config(yaml_path="settings.yaml") overrides instance attributes with YAML keys, whereas Config.load_yaml("settings.yaml") overrides class attributes. Unknown keys produce a NO SUCH VAR: message. When called without an argument, load_yaml() consults the PACKMOL_UTIL_CONFIG_YAML environment variable. Omitting yaml_path when constructing an instance does not load YAML. The defaults in Config are example settings for Fe–Si–B and are not automatically consumed by AmorphousBuilder.

Limitations

Packmol.write_fnc_file() requires consecutive constraint types starting at type 1. Packmol.xyz_to_poscar() obtains the cubic cell edge length from the first inside box line in the Packmol input. PackmolInp uses the same cell edge length for pbc and inside box. If you edit the input file manually, keep the cell dimensions consistent with these assumptions.

Installing bundled scripts and examples

After pip install packmol-util, run the following commands in the working directory where you want the files:

packmol_util install scripts
packmol_util install example

The first command copies the contents of the repository’s scripts/ directory, while the second copies example/. Subdirectory structures are preserved. For example, example/Li3PO4/non_builder/make_Li3PO4.py becomes ./Li3PO4/non_builder/make_Li3PO4.py.

Existing files are not overwritten by default. To overwrite files with the same name, use --force:

packmol_util install scripts --force
packmol_util install example --force

Files are copied into the current working directory. Unrelated files are not deleted. This feature does not install the external Packmol executable.