API Reference

WaterPacker

water_packer.WaterPacker

alias of WaterPackerOptimized

pack_water

water_packer.pack_water(system, n_waters=None, min_distance=2.0, pairwise_distances=None, water_density=None, seed=None)

Convenience function to pack water into a system.

Uses optimized implementation with batch generation and spatial hash grid.

Return type:

Any

Converters

System type converters for ASE, hyobj, and raw arrays.

water_packer.converters.detect_input_type(system)

Detect the type of input system.

Returns:

One of ‘ase’, ‘hyobj’, ‘dict’, ‘unknown’.

Return type:

str

water_packer.converters.from_arrays(cell, positions, species=None)

Convert raw arrays to internal dict format.

Parameters:

• cell (np.ndarray) – (3, 3) cell vectors or (3,) for orthorhombic.

• positions (np.ndarray) – (N, 3) atomic positions in Angstrom.

• species (list of str, optional) – Element symbols. If None, all atoms are ‘X’.

Returns:

Internal representation.

Return type:

dict

water_packer.converters.from_ase(atoms)

Convert ASE Atoms to internal dict format.

Parameters:

atoms (ase.Atoms) – ASE Atoms object.

Returns:

Internal representation with ‘cell’, ‘positions’, ‘species’.

Return type:

dict

water_packer.converters.from_hyobj(system)

Convert hyobj PeriodicSystem to internal dict format.

Parameters:

system (hyobj.PeriodicSystem) – Hylleraas PeriodicSystem object.

Returns:

Internal representation.

Return type:

dict

water_packer.converters.to_arrays(data)

Convert internal dict to raw arrays.

Parameters:

data (dict) – Internal representation.

Return type:

Tuple[ndarray, ndarray, List[str]]

Returns:

• cell (np.ndarray) – (3, 3) cell vectors.

• positions (np.ndarray) – (N, 3) atomic positions.

• species (list of str) – Element symbols.

water_packer.converters.to_ase(data)

Convert internal dict to ASE Atoms.

Parameters:

data (dict) – Internal representation.

Returns:

ASE Atoms object.

Return type:

ase.Atoms

water_packer.converters.to_hyobj(data, units='metal')

Convert internal dict to hyobj PeriodicSystem.

Parameters:

• data (dict) – Internal representation.

• units (str) – Unit system for hyobj (default ‘metal’ = Angstrom/eV).

Returns:

Hylleraas PeriodicSystem object.

Return type:

hyobj.PeriodicSystem

Distance Manager

class water_packer.DistanceManager(default_distance=2.0, pairwise_distances=None)

Bases: object

Manage species-specific minimum distances.

Default distances are based on typical vdW radii sums, with values appropriate for MD simulations.

DEFAULT_DISTANCES: Dict[Tuple[str, str], float] = {('H', 'Al'): 2.0, ('H', 'C'): 2.2, ('H', 'Ca'): 2.2, ('H', 'Fe'): 2.0, ('H', 'H'): 1.5, ('H', 'K'): 2.2, ('H', 'Mg'): 2.0, ('H', 'N'): 2.0, ('H', 'Na'): 2.0, ('H', 'Si'): 2.2, ('O', 'Al'): 2.4, ('O', 'C'): 2.6, ('O', 'Ca'): 2.4, ('O', 'Fe'): 2.3, ('O', 'H'): 1.6, ('O', 'K'): 2.6, ('O', 'Mg'): 2.0, ('O', 'N'): 2.6, ('O', 'Na'): 2.3, ('O', 'O'): 2.4, ('O', 'Si'): 2.6}

__init__(default_distance=2.0, pairwise_distances=None)

Initialize distance manager.

Parameters:

• default_distance (float) – Fallback minimum distance for pairs not in lookup tables.

• pairwise_distances (dict, optional) – User-specified distances that override defaults. Keys are (species1, species2) tuples (order doesn’t matter).

get_exclusion_radius(species)

Get the half-distance exclusion radius for substrate atom.

This is half the typical water-O to substrate distance, representing the substrate’s “share” of the interface exclusion.

Parameters:

species (str) – Element symbol of substrate atom.

Returns:

Exclusion radius in Angstrom.

Return type:

float

get_min_distance(species1, species2)

Get minimum distance for a species pair.

Priority: user-specified > defaults > fallback

Parameters:

• species1 (str) – Element symbols.

• species2 (str) – Element symbols.

Returns:

Minimum allowed distance in Angstrom.

Return type:

float