utils module

Full Documentation for hippynn.databases.utils module. Click here for a summary page.

Generic, reusable database helpers that are not tied to a specific Database subclass.

Includes tools for loading and exporting databases in EXTXYZ format, and for auto-detecting standard database key names (e.g. species, coordinates, energy, forces, cell) from a dictionary of arrays.

auto_detect_key(keys, keyset_or_hint: list[str] | str, required=True)[source]

Auto-detect a database key from a set of possible names using case-insensitive matching.

This function searches among keys returns the first unique match. If multiple matches are found, a ValueError is raised to avoid ambiguity. If no matches are found and the key is required, a ValueError is raised with available keys listed.

See BUILTIN_AUTO_KEYSETS for valid hints.

Parameters:

  • keys – available keys in the array dictionary

  • keyset_or_hint – list of possible key name patterns to match, or a single hint string. If a hint string is given, it is matched (case-insensitively) against the aliases in the built-in keysets above, and the matching keyset is used in its place.

  • required – whether this key is required (if False, returns None with warning if not found)

Returns:

detected key name or None

Raises:

ValueError – if a hint matches zero or more than one built-in keyset, if ambiguous (multiple matches), or if missing a required key

Examples

>>> from hippynn.databases.utils import auto_detect_key, 
>>> auto_detect_key(keys, 'atomic_numbers')  # hint resolves to SPECIES_KEYSET
'Species'
load_database(data_file: str | PathLike, seed: int = 101, num_workers: int = 2, species_key: str = 'species', coordinates_key: str = 'coordinates', energies_key: str = 'energy', forces_key: str = 'forces', name: str | None = None, files: list | None = None)[source]

Load a database with a consistent interface, dispatching on data_file:

  • .npz file -> NPZDatabase

  • .h5/.hdf5 file -> PyAniFileDB

  • directory containing .h5/.hdf5 files -> PyAniDirectoryDB

  • directory containing .npy files -> DirectoryDatabase (requires name)

Parameters:

  • data_file – path to the dataset file or directory

  • seed – random seed for the database split

  • num_workers – number of dataloader workers (see Database)

  • species_key – key name for species/atomic numbers in the dataset

  • coordinates_key – key name for atomic coordinates in the dataset

  • energies_key – key name for energies in the dataset

  • forces_key – key name for forces in the dataset

  • name – filename prefix for a directory of .npy files; required only in that case

  • files – explicit list of .h5 filenames to load from a directory; if None, all .h5 files in the directory are used

Returns:

database

write_extxyz(database, filename: str | PathLike, overwrite: bool = False, pbc: bool | Tuple[bool, bool, bool] = False, split: str | None = None)[source]

Write a hippynn Database to an EXTXYZ file using ASE.

See also

hippynn.molecular_dynamics.writers.write_extxyz() for exporting MD trajectories instead of a Database.

Expected keys in database.arr_dict, all optional except coordinates and species: coordinates (n, max_atoms, 3), species (n, max_atoms) int padded with <= 0, forces (n, max_atoms, 3), atomenergies (n, max_atoms, 1) or (n, max_atoms), energy/energies (n,), cell (n, 3, 3), stress (n, 3, 3) or (n, 9).

Parameters:

  • database – hippynn Database (or any object exposing arr_dict and, for split, splits/write_npz) to export

  • filename – output path for the EXTXYZ file

  • overwrite – if False, raise FileExistsError when filename already exists

  • pbc – False for non-periodic (default), True for periodic in all directions, or a tuple/list of three bools for per-axis periodicity

  • split – if a split name, write only that split; if True, write the full dataset (as it would be written to NPZ); if None (default), write database.arr_dict directly

BUILTIN_AUTO_KEYSETS = {'CELL_KEYSET': ['cell', 'lattice', 'box', 'unit_cell', 'c'], 'CHARGES_KEYSET': ['charges', 'charge', 'partial_charges', 'q'], 'COORDINATES_KEYSET': ['coordinates', 'positions', 'pos', 'coords', 'r'], 'DIPOLE_KEYSET': ['dipole', 'dipoles', 'dipole_moment', 'mu'], 'ENERGIES_KEYSET': ['energy', 'energies', 'e', 'total_energy'], 'FORCES_KEYSET': ['forces', 'force', 'f'], 'HESSIAN_KEYSET': ['hessian', 'hessians'], 'QUADRUPOLE_KEYSET': ['quadrupole', 'quadrupoles'], 'SPECIES_KEYSET': ['species', 'atomic_numbers', 'z', 'atom_types', 'atomic_number'], 'STRESS_KEYSET': ['stress', 'stresses', 'virial']}

Built-in key name sets for auto-detection, searched when auto_detect_key is given a hint instead of a keyset.