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.

Note

The 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_embedding(distance: str, **kwargs) → tuple[tuple[str, int]] | tuple[int, tuple[str]] | list[float] | ndarray[float32 | float64] | str | tuple[str, ndarray[float32 | float64]]View on GitHub

Get the embedding of the crystal based on the specified distance metric.

Parameters:

  • distance (str) – The distance metric to use.

  • **kwargs – Additional arguments for embedding methods if needed.

Returns:

The embedding corresponding to the specified distance metric.

Return type:

TYPE_EMB_ALL

Raises:

ValueError – If an unsupported distance metric is provided.

Note

For “smat” distance, the embedding is the Crystal object itself.

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