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¶
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.
- 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.