metadatabase module

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

MetaDatabase

Parses a dictionary of arrays (e.g. from a Database) to extract species, positions, forces, and other relevant data, organizing them into structured metadata. Calculates metrics such as force magnitudes, pairwise atomic distances, and simulation box densities to facilitate data searching and visualization.

class MetaDatabase(arr_dict, species_key=None, coordinates_key=None, energies_key=None, forces_key=None, cell_key=None, metadata: dict[str, object] = None, entry_metadata: dict[int, dict[str, object]] = None, populate_metadata=True, pair_dist_hard_max=5.0, peratom=False)

Bases: object

Parse a dictionary of arrays and generate a metadata representation.

This metadata facilitates searching, filtering, and visualization of molecular database contents.

Database keys (species_key, coordinates_key, etc.) can be explicitly provided or auto-detected. See auto_detect_key() for details on auto-detection behavior and supported key names.

Examples >>> # Initialize MetaDatabase with an existing database object >>> from hippynn.databases import metadatabase >>> meta_db = metadatabase.MetaDatabase( >>> arr_dict = db.arr_dict, >>> species_key=’species’, >>> coordinates_key=’coordinates’,

>>> energies_key='energy',
>>> forces_key='forces',
>>> cell_key="cell",
>>> pair_dist_hard_max = 4.0,
>>> metadata={
>>>    "Energy_unit" : 'eV',
>>>    "Mass_unit" : 'grams/mol',
>>>    "Distance_unit" : 'Angstroms',
>>>    "Electronic_Structure_Package" : 'VASP',
>>>    "Electronic_Structure_Package_Version" : '6.4.3',
>>>    "Computer_System" : 'LANL',
>>>    "Input_Procedure" : ''
>>> },
>>> populate_metadata=True,
>>> )
>>>
>>> # Save metadata to files
>>> meta_db.save_metadata_to_json('metadata.json')
>>> meta_db.save_metadata_to_csv('metadata.csv')
>>>
>>> # Generate plots
>>> meta_db.plot_distributions(density_range=(0.1, 1.5), bins=100, alpha=0.5)

>>> # Calculate atom counts and densities
>>> meta_db.species_counts
>>> meta_db.density

>>> # Plot the Force Magnitude Distribution, Density Distribution and Pairwise Distance Distribution
>>> meta_db.plot_distributions(
>>> density_range=(0.1, 1.5),
>>>     max_force_range=(0, 1),
>>>     min_distance_range=(0, 5),
>>>     bins=100,
>>>     alpha=0.5
>>>     )

>>> # Update metadata with a single "Comments" key
>>> meta_db.metadata["Comments"] = ''

>>> # Remove "Input_Procedure" key from metadata
>>> meta_db.metadata.pop("Input_Procedure", None)

>>> # Search for indicies out of all entries containing atleast Carbon
>>> meta_db.search_entries_by_species(['C'], exact_match=False)

>>> # Search for indicies out of all databaseentries containing exactly Hydrogen, Carbon and Oxygen
>>> meta_db.search_entries_by_species(['CHO'], exact_match=True)

>>> # Search for indicies out of all database entries with a calculated maximum atomic force in the range of [0,0.1]
>>> meta_db.search_entries_by_max_force([0.0,0.1])

>>> # Search for indicies out of all database entries with a calculated maximum pairwise atomic distance in the range of [0,0.9]
>>> meta_db.search_entries_by_min_distance([0.0,0.9])

Key Functionalities:

1. Parsing and Metadata Extraction: - Extracts species and coordinate information from the database. - Computes unique atomic numbers and counts of each atom type. - Calculates physical properties like mass and density based on extracted data.

2. Searching Capabilities: - Enables complex queries based on multiple criteria (e.g., density ranges,

   specific atomic compositions).

   • Supports logical operations (AND, OR, NOT) to refine search results.

   • Returns entries that match the specified search parameters.

3. Plotting and Visualization: - Provides methods to visualize database distributions (e.g., pairwise atomic distances, density, force, histograms). - Generates plots for atom counts to understand elemental compositions of database.

exception MetaDatabaseError

Bases: Exception

Custom exception type for MetaDatabase specific errors.

atomic_masses()

calculate_min_distance(periodic=True, batch_size=50)

Calculate minimum pairwise atomic distances for each entry.

Parameters:

• periodic – whether to use periodic boundary conditions if cell is available

• batch_size – batch size for distance calculation (also enables progress bar)

Returns:

tensor of minimum distances for each entry

calculate_range(data, manual_range)

calculate_volume(coordinates, cell=None)

Compute the bounding-box volume, and cell volume if a cell is given, for a single entry.

Parameters:

• coordinates – atomic positions, shape (n_atoms, 3)

• cell – optional cell matrix, shape (3, 3)

Returns:

dict with keys bounding_box_volume and cell_volume (None if cell not given)

count_atoms_by_species(species)

get_density_statistics()

get_energy_statistics()

get_mass_by_species(species)

get_max_force_statistics()

get_min_distance_statistics()

make_json_serializable()

plot_distributions(density_range=None, max_force_range=None, min_distance_range=None, bins=None, alpha=None, figsize=(12, 9))

Plot distribution histograms for density, max force, min distance, and atom counts.

Parameters:

• density_range – manual range for density filtering

• max_force_range – manual range for max force filtering

• min_distance_range – manual range for min distance filtering

• bins – number of bins for histograms

• alpha – transparency for plots

• figsize – figure size as (width, height) in inches

populate_metadata(quiet=False)

save_metadata_to_csv(filename='metadata.csv')

Save metadata to a CSV file.

Parameters:

filename – Output CSV filename

save_metadata_to_json(filename='metadata.json')

Save metadata to a JSON file.

Parameters:

filename – Output JSON filename

search_entries_by_max_force(force_range)

search_entries_by_min_distance(distance_range)

search_entries_by_species(target_species, exact_match=True, use_symbols=True)

Search for entries containing specified atomic species.

Parameters:

• target_species – list of element symbols or atomic numbers to search for

• exact_match – if True, entry must contain exactly these species; if False, at least these species

• use_symbols – if True, interpret input as element symbols; if False, as atomic numbers

Returns:

list of matching entry indices

ATOMIC_NUMBER_TO_SYMBOL = {}

DEFAULT_ALPHA = 0.7

DEFAULT_BINS = 50

property E0_regression

PAIR_DIST_HARD_MAX_DEFAULT = 5.0

SYMBOL_TO_ATOMIC_NUMBER = {}

property density

Density for each entry, computed lazily using vectorized operations.

Computes mass from atomic species and volume from either periodic cells or bounding boxes. Caches both density and volumes for later use.

property max_force

Maximum force magnitude per entry, shape (N,).

property min_distance

Minimum pairwise atomic distance per entry, shape (N,).

property min_force

Minimum force magnitude per entry, shape (N,).

property species_combination_counts

property species_combination_index

property species_counts

Atom counts keyed by atomic number.

property symbols_combination_counts

Species-combination counts keyed by concatenated element symbols, e.g. "CHO".

property symbols_counts

Atom counts keyed by element symbol, e.g. "C".

property unique_species

property volume

Volume for each entry, computed lazily via the density property.