matador.crystal package¶
This module contains functionality for wrapping matador
data dictionaries as Crystal
objects, which possess
several convenience methods.
-
class
matador.crystal.
Crystal
(doc, voronoi=False, network_kwargs=None)[source]¶ Bases:
matador.orm.orm.DataContainer
Class that wraps the MongoDB document, providing useful interfaces for cell manipulation and validation.
-
cell
¶ the unit cell constructed from lattice vectors.
- Type
UnitCell
Initialise Crystal object from matador document with Site list and any additional abstractions, e.g. voronoi or CrystalGraph.
- Parameters
doc (dict) – document containing structural information, minimal requirement is for atom_types, one of lattice_abc or lattice_cart, and one of positions_frac or positions_abs to be present.
- Keyword Arguments
-
property
atom_types
¶ Return list of atom types.
-
property
num_atoms
¶ Return number of atoms in structure.
-
property
num_elements
¶ Return number of species in the structure.
-
property
positions_frac
¶ Return list of fractional positions.
-
property
positions_abs
¶ Return list of absolute Cartesian positions.
-
property
site_occupancies
¶ Return a list of site occupancies.
-
property
stoichiometry
¶ Return stoichiometry in matador format: a list of two-member lists containing element symbol and number of atoms per formula unit, sorted in alphabetical order by element symbol).
-
property
concentration
¶ Return concentration of each species in stoichiometry.
-
property
formula
¶ Returns chemical formula of structure.
-
property
formula_tex
¶ Returns chemical formula of structure in LaTeX format.
-
property
cell_volume
¶ Returns cell volume in ų.
-
property
lattice_cart
¶ The Cartesian lattice vectors as a tuple.
-
property
lattice_abc
¶ Lattice parameters as a tuple.
-
property
bond_lengths
¶ Returns a list of ((species_A, species_B), bond_length)), sorted by bond length, computed from the network structure of the crystal (i.e. first coordination sphere).
-
property
voronoi_substructure
¶ Returns, or calculates if not present, the Voronoi substructure of crystal.
-
property
space_group
¶ Return the space group symbol at the last-used symprec.
-
get_space_group
(symprec=0.01)[source]¶ Return the space group of the structure at the desired symprec. Stores the space group in a dictionary self._space_group under symprec keys. Updates self._data[‘space_group’] and self._data[‘symprec’] with the last value calculated.
- Keyword Arguments
symprec (float) – spglib symmetry tolerance.
-
property
pdf
¶ Returns a PDF object (pair distribution function) for the structure, calculated with default PDF settings.
-
property
pxrd
¶ Returns a PXRD object (powder xray diffraction) containing the XRD pattern for the structure.
-
property
coordination_stats
¶ Returns stastistics on the coordination of each site, as computed from Voronoi decomposition.
-
property
ase_atoms
¶ Returns an ASE Atoms representation of the crystal.
-
property
pmg_structure
¶ Returns the pymatgen structure representation of the crystal.
-
property
coordination_lists
¶ Returns a dictionary containing pairs of elements and the list of coordination numbers per site.
-
property
unique_sites
¶ Return unique sites using Voronoi decomposition.
-
property
network
¶ Returns/constructs a CrystalGraph object of the structure.
-
property
network_stats
¶ Return network-calculated coordnation stats.
-
property
bonding_stats
¶ Return network-calculated bonding stats.
- Returns
- sorted dictionary with root atom as keys and bond
information as values.
- Return type
-
Submodules¶
matador.crystal.crystal module¶
This submodule implements the Crystal class, a wrapper to the raw dictionary stored in MongoDB that allows for validation, manipulation and analysis of the lattice.
-
class
matador.crystal.crystal.
UnitCell
(lattice)[source]¶ Bases:
object
This class describes a 3D periodic unit cell by its Cartesian lattice vectors or lattice parameters, in Å.
Initialise the cell from either Cartesian lattice vectors [[x1, y1, z1], [x2, y2, z2], [x3, y3, z3]], or lattice parameters [[a, b, c], [alpha, beta, gamma]].
- Parameters
lattice (
list
or numpy.ndarray) – either Cartesian lattice vectors or lattice parameters, stored as lists or a numpy arrays.
-
property
lattice_cart
¶ The Cartesian lattice vectors as a tuple.
-
property
lattice_abc
¶ Lattice parameters as a tuple.
-
property
lengths
¶ Lattice vector lengths.
-
property
recip_lattice_cart
¶
-
property
angles
¶ Lattice vector angles.
-
property
volume
¶ The cell volume in ų.
-
class
matador.crystal.crystal.
Crystal
(doc, voronoi=False, network_kwargs=None)[source]¶ Bases:
matador.orm.orm.DataContainer
Class that wraps the MongoDB document, providing useful interfaces for cell manipulation and validation.
Initialise Crystal object from matador document with Site list and any additional abstractions, e.g. voronoi or CrystalGraph.
- Parameters
doc (dict) – document containing structural information, minimal requirement is for atom_types, one of lattice_abc or lattice_cart, and one of positions_frac or positions_abs to be present.
- Keyword Arguments
-
property
atom_types
¶ Return list of atom types.
-
property
num_atoms
¶ Return number of atoms in structure.
-
property
num_elements
¶ Return number of species in the structure.
-
property
positions_frac
¶ Return list of fractional positions.
-
property
positions_abs
¶ Return list of absolute Cartesian positions.
-
property
site_occupancies
¶ Return a list of site occupancies.
-
property
stoichiometry
¶ Return stoichiometry in matador format: a list of two-member lists containing element symbol and number of atoms per formula unit, sorted in alphabetical order by element symbol).
-
property
concentration
¶ Return concentration of each species in stoichiometry.
-
property
formula
¶ Returns chemical formula of structure.
-
property
formula_tex
¶ Returns chemical formula of structure in LaTeX format.
-
property
cell_volume
¶ Returns cell volume in ų.
-
property
lattice_cart
¶ The Cartesian lattice vectors as a tuple.
-
property
lattice_abc
¶ Lattice parameters as a tuple.
-
property
bond_lengths
¶ Returns a list of ((species_A, species_B), bond_length)), sorted by bond length, computed from the network structure of the crystal (i.e. first coordination sphere).
-
property
voronoi_substructure
¶ Returns, or calculates if not present, the Voronoi substructure of crystal.
-
property
space_group
¶ Return the space group symbol at the last-used symprec.
-
get_space_group
(symprec=0.01)[source]¶ Return the space group of the structure at the desired symprec. Stores the space group in a dictionary self._space_group under symprec keys. Updates self._data[‘space_group’] and self._data[‘symprec’] with the last value calculated.
- Keyword Arguments
symprec (float) – spglib symmetry tolerance.
-
property
pdf
¶ Returns a PDF object (pair distribution function) for the structure, calculated with default PDF settings.
-
property
pxrd
¶ Returns a PXRD object (powder xray diffraction) containing the XRD pattern for the structure.
-
property
coordination_stats
¶ Returns stastistics on the coordination of each site, as computed from Voronoi decomposition.
-
property
ase_atoms
¶ Returns an ASE Atoms representation of the crystal.
-
property
pmg_structure
¶ Returns the pymatgen structure representation of the crystal.
-
property
coordination_lists
¶ Returns a dictionary containing pairs of elements and the list of coordination numbers per site.
-
property
unique_sites
¶ Return unique sites using Voronoi decomposition.
-
property
network
¶ Returns/constructs a CrystalGraph object of the structure.
-
property
network_stats
¶ Return network-calculated coordnation stats.
-
property
bonding_stats
¶ Return network-calculated bonding stats.
- Returns
- sorted dictionary with root atom as keys and bond
information as values.
- Return type
matador.crystal.crystal_site module¶
This submodule implements the Site class for handling atomic sites.
-
class
matador.crystal.crystal_site.
Site
(species: str, position: list, lattice, position_unit='fractional', **site_data)[source]¶ Bases:
matador.orm.orm.DataContainer
The Site class contains a description of an individual site within a 3D periodic Crystal.
Initialise a Site object from its species, position and a reference to the lattice it exists in. Any other keys will be made available as site-level values.
-
property
coords
¶
-
property
coords_cartesian
¶
-
property
species
¶
-
property
lattice
¶
-
property
occupancy
¶
-
property
coordination
¶
-
property
matador.crystal.elastic module¶
This submodule contains functionality to fit E(V) equations of state to ab initio data, primarily to calculate bulk moduli.
-
matador.crystal.elastic.
get_equation_of_state
(seed, plot=False)[source]¶ Extract E(V) data from CASTEP files and perform fits for the equation of state and bulk moduli.
- Parameters
seed (str/dict) – filename or scraped dictionary to fit.
- Keyword Arguments
plot (bool) – plot the fitted EoS.
-
class
matador.crystal.elastic.
EquationOfState
(E_0, V_0)[source]¶ Bases:
object
Abstract class for E(V) isothermal equations of state. Used to perform least squares fitting to arbitrary functional form.
Set up EOS ready for fit.
-
property
bulk_modulus
¶ Returns the bulk modulus predicted by the fit.
-
property
bulk_modulus_err
¶ Returns the estimated error on the bulk modulus.
-
property
fit_parameters
¶ Return list of final fitting parameters.
-
property
-
class
matador.crystal.elastic.
BirchMurnaghanEulerianEOS
(E_0, V_0)[source]¶ Bases:
matador.crystal.elastic.EquationOfState
Implements the 3rd order Birch-Murnaghan EOS [1] for given data, as provided by Ref. [2] in the Eulerian frame.
- [1]. Francis Birch, Phys. Rev. 71 809 (1947)
DOI: 10.1103/PhysRev.71.809.
- [2]. K. Latimer, S. Dwaraknath, K. Mathew, D. Winston, K. A. Persson,
npj Comput. Mater. 2018 41 2018, 4, 40. DOI: 10.1038/s41524-018-0091-x.
Set up EOS ready for fit.
-
class
matador.crystal.elastic.
PoirerTarantolaEOS
(E_0, V_0)[source]¶ Bases:
matador.crystal.elastic.EquationOfState
Implements the logarithmic Poirer-Tarantola [3] for given data, as provided by Ref. [2].
- [2]. K. Latimer, S. Dwaraknath, K. Mathew, D. Winston, K. A. Persson,
npj Comput. Mater. 2018 41 2018, 4, 40. DOI: 10.1038/s41524-018-0091-x.
[3]. J. Poirer, A. Tarantola, Phys. Earth Planet. Inter. 109 1-8 (1998).
Set up EOS ready for fit.
-
class
matador.crystal.elastic.
TaitEOS
(E_0, V_0)[source]¶ Bases:
matador.crystal.elastic.EquationOfState
Implements the exponential Tait EOS [4] for given data, as provided by Ref. [2].
- [2]. K. Latimer, S. Dwaraknath, K. Mathew, D. Winston, K. A. Persson,
npj Comput. Mater. 2018 41 2018, 4, 40. DOI: 10.1038/s41524-018-0091-x.
[4]. J. H. Dymond, R. Malhotra, Int. J. Thermophys. 9 941-951 (1988).
Set up EOS ready for fit.
matador.crystal.network module¶
This file implements turning matador Crystal objects into CrystalGraph objects.
-
class
matador.crystal.network.
CrystalGraph
(structure=None, graph=None, coordination_cutoff=1.1, bond_tolerance=1e+20, num_images=1, debug=False, separate_images=False, delete_one_way_bonds=False, max_bond_length=5)[source]¶ Bases:
networkx.classes.multidigraph.MultiDiGraph
Create networkx.MultiDiGraph object with extra functionality for atomic networks.
- Keyword Arguments
structure (matador.Crystal) – crystal structure to network-ify
graph (nx.MultiDiGraph) – initialise from graph
coordination_cutoff (float) – max multiplier of first coordination sphere for edge drawing
num_images (int) – number of periodic images to include in each direction
separate_images (bool) – whether or not to include image atoms as new nodes
-
get_strongly_connected_component_subgraphs
(delete_one_way_bonds=True)[source]¶ Return generator of strongly-connected subgraphs in CrystalGraph format.
-
get_communities
(graph=None, **louvain_kwargs)[source]¶ Return list of community subgraphs in CrystalGraph format.