Structure Module

Structure Module#

Contains a minimalist SmactStructure class for simple crystal structure and chemical composition representation and manipulation.

Minimalist structure representation for comprehensible manipulation.

class smact.structure_prediction.structure.SmactStructure(species: Sequence[tuple[str, int, int] | tuple[smact.Species, int]], lattice_mat: np.ndarray, sites: dict[str, list[list[float]]], lattice_param: float | None = 1.0, sanitise_species: bool | None = True)[source]#

Bases: object

SMACT implementation inspired by pymatgen Structure class.

Handles basic structural and compositional information for a compound. Includes a lossless POSCAR-style specification for storing structures, allowing structures to be stored in files or databases, or to be pulled from the Materials Project.

Attributes:#

species: A list of tuples describing the composition of the structure,

stored as (element, oxidation, stoichiometry). The list is sorted alphabetically based on element symbol, and identical elements are sorted with highest charge first.

lattice_mat: A numpy 3x3 array containing the lattice vectors. sites: A dictionary of {species: coords}, where species is a string

representation of the species and coords is a list of position vectors, given as lists of length 3. For example:

>>> s = SmactStructure.from_file("tests/files/NaCl.txt")
>>> s.sites
{'Cl1-': [[2.323624165, 1.643050405, 4.02463512]], 'Na1+': [[0.0, 0.0, 0.0]]}

lattice_param: The lattice parameter.

as_poscar() → str[source]#

Represent the structure as a POSCAR file compatible with VASP5.

The POSCAR format adopted is as follows:

Line 1: species strings (e.g. “Na1+ Cl1-“), whitespace-separated. Line 2: lattice parameter (scaling factor). Lines 3-5: lattice matrix, one vector per line. Line 6: element symbols, whitespace-separated. If more than one oxidation state exists for an element, the element appears multiple times; once for each oxidation state. Line 7: number of atoms per species, whitespace-separated. Line 8: the string ‘Cartesian’. Lines 9+: Cartesian coordinates of each site, with the species string appended at the end of each line.

For examples of this format, see the text files under tests/files.

Returns:#

str: POSCAR-style representation of the structure.

as_py_struct() → pymatgen.core.Structure[source]#

Represent the structure as a pymatgen Structure object.

Returns:#

pmg_Structure: pymatgen Structure object.

composition() → str[source]#

Generate a key that describes the composition.

Key format is ‘{element}_{stoichiometry}_{charge}{sign}’ with no delimiter, sans brackets. Species are ordered as stored within the structure, see SmactStructure.

Returns:#

Key describing constituent species.

Examples:#

>>> s = SmactStructure.from_file("tests/files/CaTiO3.txt")
>>> print(s.composition())
Ca_1_2+O_3_2-Ti_1_4+
static from_file(fname: str) → SmactStructure[source]#

Create SmactStructure from a POSCAR file.

Args:#

fname: The name of the POSCAR file.

See as_poscar() for format specification.

Returns:#

static from_mp(species: Sequence[tuple[str, int, int] | tuple[smact.Species, int]], api_key: str | None = None, determine_oxi: str = 'BV') → SmactStructure[source]#

Create a SmactStructure using the first Materials Project entry for a composition.

Args:#

species: See __init__(). 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.

api_key (str| None): A www.materialsproject.org API key.

Returns:#

static from_poscar(poscar: str) → SmactStructure[source]#

Create SmactStructure from a POSCAR string.

Args:#

poscar: A SMACT-formatted POSCAR string.

See as_poscar() for format specification.

Returns:#

static from_py_struct(structure: pymatgen.core.Structure, determine_oxi: str = 'BV') → SmactStructure[source]#

Create a SmactStructure from a pymatgen Structure object.

Args:#

structure: A pymatgen Structure. 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:#

get_spec_strs() → list[str][source]#

Get string representations of the constituent species.

Returns:#

A list of strings, formatted as ‘{element}{charge}{sign}’.

Examples:#

>>> s = SmactStructure.from_file("tests/files/CaTiO3.txt")
>>> s.get_spec_strs()
['Ca2+', 'O2-', 'Ti4+']
has_species(species: tuple[str, int]) → bool[source]#

Determine whether a given species is in the structure.

reduced_formula() → str[source]#

Generate a reduced formula for the structure.

Returns:#

str: Reduced formula of the structure.

Examples:#

>>> s = SmactStructure.from_file("tests/files/CaTiO3.txt")
>>> print(s.reduced_formula())
CaTiO3