httk4mdse.httk_reader

Functions

calc_chem_pot(store, stoichiometry)

Compute the total chemical potential contribution for a given defect stoichiometry.

get_chemical_potential(store)

get_defect_formation_energy(store, **query)

Compute defect formation energies from a data store and write the results to MongoDB.

get_defects(store, **query)

Query a defect structure from the HTTK database.

save_defects(defects, defect_folder)

Save a collection of defect structures as CIF files.

save_to_cif(defect, defects_folder)

Save an HTTK structure object to a cif file.

setup_db(db_path)

Initialize an HTTK SQLite-backed database and return a search interface.
httk4mdse.httk_reader.calc_chem_pot(store, stoichiometry)

Compute the total chemical potential contribution for a given defect stoichiometry.

Parameters:

  • store (httk.db.store.SqlStore) – A httk datastore object.

  • stoichiometry (str) – Stoichiometry string of the form “Elem1:-n1_Elem2:-n2 …”, where negative integers indicate added atoms and positive integers removed atoms.

Returns:

The summed chemical potential: \(\sum_i(n_i\mu_i)\), using the database- stored chemical potentials for each involved element.

Return type:

float

Notes

The function:

  • Parses element counts from the stoichiometry string.

  • Queries the datastore for the corresponding elemental chemical potentials.

  • Computes the weighted sum of potentials according to the parsed stoichiometry.

httk4mdse.httk_reader.get_chemical_potential(store)
httk4mdse.httk_reader.get_defect_formation_energy(store, **query)

Compute defect formation energies from a data store and write the results to MongoDB.

Parameters:

  • store (httk.db.store.SqlStore) – A httk datastore object.

  • **query (dict, optional) – Optional filters for the query. Currently supports: - key (str): Restrict results to a specific defect key.

Notes

This function:

  1. Queries all neutral (charge = 0) defect calculations.

  2. Retrieves defect stoichiometry, total energies, spin, and defect type.

  3. Computes chemical potentials using get_chem_pot().

  4. Calculates defect formation energies:

\[E_\mathrm{form} = E_\mathrm{defect} - E_\mathrm{host} + \sum_i n_i \mu_i\]

  1. Stores the resulting data in a MongoDB collection named “DFT data”.

Returns:

Results are written directly to the database.

Return type:

None

httk4mdse.httk_reader.get_defects(store, **query)

Query a defect structure from the HTTK database.

Parameters:

  • search (httk.db.store.SqlStore) – The searcher used to run database queries.

  • query (dict) – Query to filter the output from the database.

Returns:

matches – The retrieved matches for the specified query. If no matching entry is found returns None.

Return type:

list

httk4mdse.httk_reader.save_defects(defects, defect_folder)

Save a collection of defect structures as CIF files.

Each defect in defects is written to the directory specified by defect_folder using save_to_cif(). The function attempts to create the target folder if it does not exist, logging a warning if folder creation fails. It also logs the time taken to perform the conversion.

Parameters:

  • defects (iterable) – A sequence of defect objects to save. Each element must be compatible with save_to_cif().

  • defect_folder (str or Path-like) – Path to the directory where CIF files will be stored.

Returns:

A list of file paths corresponding to the saved CIF files.

Return type:

list of Path

Notes

  • Folder creation errors (e.g., directory already exists) are logged but do not interrupt execution.

  • The function logs the total conversion time at debug level.

httk4mdse.httk_reader.save_to_cif(defect, defects_folder)

Save an HTTK structure object to a cif file.

The function writes the structure to a cif file. HTTK-specific site metadata (Wyckoff symbols and multiplicities) are cleared before export to avoid compatibility issues.

Parameters:

defect (list) – Result from database query as a list of values/objects

Returns:

defect_path – The corresponding path to the cif file, or None if save failed.

Return type:

Path or None

httk4mdse.httk_reader.setup_db(db_path: str)

Initialize an HTTK SQLite-backed database and return a search interface.

Parameters:

db_path (str or Path-like) – Path to the SQLite database file.

Returns:

search – A searcher object that can be used to query the database.

Return type:

httk.db.filteredcollection.FCSqlite