Structure Database Module

Implements StructureDB: a minimalist SQLite database for storing SmactStructure-compatible POSCAR files.

Tools for database interfacing for high throughput IO.

class smact.structure_prediction.database.StructureDB(db: str)

Bases: object

SQLite Structure Database interface.

Acts as a context manager for database interfacing and wraps several useful SQLite commands within methods.

Attributes:

db: The database name. conn: The database connection. Only open when

used as a context manager.

cur: The database connection cursor. Only usable

when class implemented as context manager.

Examples:

Connecting to a database in memory:

>>> DB = StructureDB(":memory:")
>>> with DB as c:
...     _ = c.execute("CREATE TABLE test (id, val)")
...     c.execute("SELECT * FROM test").fetchall()
[]
>>> DB.cur.execute("SELECT * FROM test").fetchall()
Traceback (most recent call last):
    ...
sqlite3.ProgrammingError: Cannot operate on a closed database.

add_mp_icsd(table: str, mp_data: list[dict[str, pmg_Structure | str]] | None = None, mp_api_key: str | None = None) → int

Add a table populated with Materials Project-hosted ICSD structures.

Note:

This is very computationally expensive for large datasets and will not likely run on a laptop. If possible, download a pre-constructed database.

Args:

table (str): The name of the table to add. mp_data: The Materials Project data to parse. If this is None, data

will be downloaded. Downloading data needs mp_api_key to be set.

mp_api_key (str): A Materials Project API key. Only needed if mp_data

is None.

Returns:

The number of structs added.

add_struct(struct: SmactStructure, table: str) → None

Add a SmactStructure to a table.

Args:

struct: The SmactStructure to add. table: The name of the table to add the structure to.

add_structs(structs: Sequence[SmactStructure | None], table: str, commit_after_each: bool = False) → int

Add several SmactStructures to a table.

Args:

structs: Iterable of SmactStructure s to add to table. table: The name of the table to add the structs to. commit_after_each (bool, optional): Whether to commit the addition

after each structure is added. This is useful when adding a large number of structures over a long timeframe, as it ensures some structures are added, even if the program terminates before completion. Defaults to False.

Returns:

The number of structures added.

add_table(table: str) → None

Add a table to the database.

Args:

table: The name of the table to add

get_structs(composition: str, table: str) → list[SmactStructure]

Get SmactStructures for a given composition.

Args:

composition: The composition to search for.

See SmactStructure.composition().

table: The name of the table in which to search.

Returns:

A list of SmactStructure s.

get_with_species(species: list[tuple[str, int]], table: str) → list[SmactStructure]

Get SmactStructures containing given species.

Args:

species: A list of species as tuples, in (element, charge) format. table: The name of the table from which to get the species.

Returns:

A list of SmactStructure s in the table that contain the species.

smact.structure_prediction.database.parse_mprest(data: dict[str, pmg_Structure | str], determine_oxi: str = 'BV') → SmactStructure | None

Parse MPRester query data to generate structures.

Args:

data: A dictionary containing the keys ‘structure’ and

‘material_id’, with the associated values.

determine_oxi (str): The method to determine the assignments oxidation states in the structure.

Options are ‘BV’, ‘comp_ICSD’,’both’ for determining the oxidation states by bond valence, ICSD statistics or trial both sequentially, respectively.

Returns:

An oxidation-state-decorated SmactStructure.