xtalmet.crystal module

This module defines the Crystal class to store information about a single crystal.

class xtalmet.crystal.Crystal(lattice: Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | Lattice, species: Sequence[str | Element | Species | DummySpecies | dict | Composition], coords: Sequence[Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]], charge: float | None = None, validate_proximity: bool = False, to_unit_cell: bool = False, coords_are_cartesian: bool = False, site_properties: dict | None = None, labels: Sequence[str | None] | None = None, properties: dict | None = None)View on GitHub

Bases: Structure

Container for a single crystal structure.

Initialize a Crystal object.

The parameters are the same as those used in the __init__() method of the pymatgen.core.Structure class.

Parameters:

• lattice (Lattice/3x3 array) – The lattice, either as a pymatgen.core.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. e.g. [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].

• species ([Species]) –

  Sequence of species on each site. Can take in flexible input, including:

  1. A sequence of element / species specified either as string

     symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g. (3, 56, …) or actual Element or Species objects.

  2. List of dict of elements/species and occupancies, e.g.

     [{“Fe” : 0.5, “Mn”:0.5}, …]. This allows the setup of disordered structures.

• coords (Nx3 array) – list of fractional/Cartesian coordinates of each species.

• charge (int) – overall charge of the structure. Defaults to behavior in SiteCollection where total charge is the sum of the oxidation states.

• validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.

• to_unit_cell (bool) – Whether to map all sites into the unit cell, i.e. fractional coords between 0 and 1. Defaults to False.

• coords_are_cartesian (bool) – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.

• site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g. {“magmom”:[5, 5, 5, 5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.

• labels (list[str]) – Labels associated with the sites as a list of strings, e.g. [‘Li1’, ‘Li2’]. Must have the same length as the species and fractional coords. Defaults to None for no labels.

• properties (dict) – Properties associated with the whole structure. Will be serialized when writing the structure to JSON or YAML but is lost when converting to other formats.

Returns:

None

Note

descriptions for args are copied from pymatgen.core.Structure class.

classmethod from_Structure(structure: Structure) → CrystalView on GitHub

Create a Crystal object from a pymatgen Structure object.

Parameters:

structure (Structure) – A pymatgen Structure object.

Returns:

A Crystal object created from the Structure.

Return type:

Crystal

get_composition_tuple() → tuple[tuple[str, int]]View on GitHub

Get the composition of the crystal as a tuple of (element, count).

Embedding for d_comp.

Returns:

A tuple containing elements and their counts (divided by gcd).

Return type:

tuple

get_wyckoff() → tuple[int, tuple[str]] | ExceptionView on GitHub

Get the Wyckoff representation of the crystal.

Embedding for d_wyckoff.

Returns:

A tuple containing the space group number and a tuple of Wyckoff letters, or an Exception from SpacegroupAnalyzer.

Return type:

tuple | Exception

get_magpie() → list[float]View on GitHub

Get the magpie embedding of the crystal.

Embedding for d_magpie. Not influenced by oxidation states.

Returns:

Magpie feature vector of the crystal.

Return type:

list[float]

References

• Ward et al., (2016). A general-purpose machine learning framework for predicting properties of inorganic materials. npj Computational Materials, 2(1), 1-7. https://doi.org/10.1038/npjcompumats.2016.28

get_PDD(k: int = 100, **kwargs) → ndarray[float32 | float64] | ExceptionView on GitHub

Get the pointwise distance distribution (PDD) of the crystal.

Embedding for d_ppd.

Parameters:

• k (int) – Number of nearest neighbors to consider.

• **kwargs – Additional arguments for amd.PDD, except k.

Returns:

PDD or an Exception from periodicset_from_pymatgen_structure

Return type:

np.ndarray[np.float32 | np.float64] | Exception

References

• Widdowson et al., (2022). Resolving the data ambiguity for periodic crystals. Advances in Neural Information Processing Systems, 35, 24625–24638. https://openreview.net/forum?id=4wrB7Mo9_OQ

get_AMD(k: int = 100) → ndarray[float32 | float64] | ExceptionView on GitHub

Get the average minimum distance (AMD) of the crystal.

Embedding for d_amd.

Parameters:

k (int) – Number of nearest neighbors to consider. Also the embedding length.

Returns:

AMD or an Exception from periodicset_from_pymatgen_structure

Return type:

np.ndarray[np.float32 | np.float64] | Exception

References

• Widdson et al., (2022). Average Minimum Distances of periodic point sets - foundational invariants for mapping periodic crystals. MATCH Communications in Mathematical and in Computer Chemistry, 87(3), 529-559, https://doi.org/10.46793/match.87-3.529W

get_composition_pymatgen() → CompositionView on GitHub

Get the pymatgen composition of the crystal.

Called when screening using SMACT or E_hull.

Returns:

Pymatgen Composition object.

Return type:

Composition

get_ase_atoms() → AtomsView on GitHub

Get the ASE Atoms object of the crystal.

Called when screening using E_hull. Not influenced by oxidation states.

Returns:

ASE Atoms object.

Return type:

Atoms