mdse.utils

Utility functions for post-processing and data management.

This module provides helper functions for tasks such as calculating defect formation energies from simulation results and transferring data between different database sources (e.g., from an HTTK SQLite DB to MongoDB).

Functions

calc_formation_energy(host_energy, ...[, ...])

Calculates the formation energy for a given defect.

defect_formation_energy(db)

Calculates defect formation energies and stores them in the database.

get_nelements(stoichiometry)

Parses a stoichiometry string into a dictionary of element counts.

transfer_chemical_potential(sqlite_path, ...)

Transfers chemical potential data from an SQLite DB to MongoDB.

transfer_defect_formation_energy(...)

Transfers DFT defect formation energy data from an SQLite DB to MongoDB.
mdse.utils.calc_formation_energy(host_energy, element_counts, db, defect_energy=0)

Calculates the formation energy for a given defect.

The formation energy is calculated using the formula:

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

where \(E_\mathrm{defect}\) is the energy of the defect system, \(E_\mathrm{Host}\) is the energy of the pristine host system, \(n_i\) is the number of atoms of element i added or removed, and \(\mu_i\) is the chemical potential of element i.

Parameters:

  • host_energy (float) – The total energy of the host material.

  • element_counts (dict[str, int]) – A dictionary mapping element symbols to the number of atoms of that type added (positive) or removed (negative).

  • db (DBManager) – The database manager used to query for chemical potentials.

  • defect_energy (float, optional) – The total energy of the system containing the defect. Defaults to 0.

Returns:

A tuple containing the calculated formation energy and the total chemical potential contribution.

Return type:

tuple[float, float]

mdse.utils.defect_formation_energy(db)

Calculates defect formation energies and stores them in the database.

This function reads defect simulation results and the corresponding host material energy from a MongoDB database. It then calculates the formation energy for each defect and writes the results (including the formation energy and total chemical potential) back into a new collection named ‘MACE_results’.

Note

This function will clear the ‘MACE_results’ collection before writing new data.

Parameters:

db (DBManager) – An active DBManager instance connected to the database.

mdse.utils.get_nelements(stoichiometry)

Parses a stoichiometry string into a dictionary of element counts.

The function uses a regular expression to find all element-count pairs in the input string.

Parameters:

stoichiometry (str) – A string representing the change in stoichiometry, e.g., “C:-1,Si:1”.

Returns:

A dictionary mapping element symbols to their counts.

Return type:

dict[str, int]

mdse.utils.transfer_chemical_potential(sqlite_path, mongodb_adress)

Transfers chemical potential data from an SQLite DB to MongoDB.

This function connects to an HTTK-formatted SQLite database, retrieves chemical potential data, and writes it to a specified MongoDB instance. The target collection ‘Chemical_potential’ in MongoDB is cleared before the new data is inserted.

Parameters:

  • sqlite_path (str) – The file path to the source SQLite database.

  • mongodb_adress (str) – The connection address for the target MongoDB server.

mdse.utils.transfer_defect_formation_energy(sqlite_path, mongodb_adress)

Transfers DFT defect formation energy data from an SQLite DB to MongoDB.

This function connects to an HTTK-formatted SQLite database, retrieves defect formation energy data, and writes it to a specified MongoDB instance. The target collection ‘DFT_data’ in MongoDB is cleared before the new data is inserted.

Parameters:

  • sqlite_path (str) – The file path to the source SQLite database.

  • mongodb_adress (str) – The connection address for the target MongoDB server.