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)

Bases: matador.orm.orm.DataContainer

Class that wraps the MongoDB document, providing useful interfaces for cell manipulation and validation.

elems

list of present elements in the crystal, sorted in alphabetical order.

Type

list of str

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

• voronoi (bool) – whether to compute Voronoi substructure for each site

• network_kwargs (dict) – keywords to pass to the CrystalGraph initialiser

update(data)

Update the underlying self._data dictionary with the passed data.

print_sites()

set_positions(new_positions, fractional=True)

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)

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.

calculate_pdf(**kwargs)

Calculate and set the PDF with the passed parameters.

property pxrd

Returns a PXRD object (powder xray diffraction) containing the XRD pattern for the structure.

calculate_pxrd(**kwargs)

Compute and set PXRD with the passed parameters.

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.

classmethod from_ase(atoms)

classmethod from_pmg(pmg)

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

dict

draw_network(layout=None)

Draw the CrystalGraph network.

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)

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)

Bases: matador.orm.orm.DataContainer

Class that wraps the MongoDB document, providing useful interfaces for cell manipulation and validation.

elems

list of present elements in the crystal, sorted in alphabetical order.

Type

list of str

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

• voronoi (bool) – whether to compute Voronoi substructure for each site

• network_kwargs (dict) – keywords to pass to the CrystalGraph initialiser

update(data)

Update the underlying self._data dictionary with the passed data.

print_sites()

set_positions(new_positions, fractional=True)

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)

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.

calculate_pdf(**kwargs)

Calculate and set the PDF with the passed parameters.

property pxrd

Returns a PXRD object (powder xray diffraction) containing the XRD pattern for the structure.

calculate_pxrd(**kwargs)

Compute and set PXRD with the passed parameters.

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.

classmethod from_ase(atoms)

classmethod from_pmg(pmg)

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

dict

draw_network(layout=None)

Draw the CrystalGraph network.

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)

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.

set_position(position, units)

property coords

property coords_cartesian

property species

property lattice

property occupancy

property coordination

displacement_between_sites(other_site)

distance_between_sites(other_site)

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)

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)

Bases: object

Abstract class for E(V) isothermal equations of state. Used to perform least squares fitting to arbitrary functional form.

E_0

equilbirium lattice energy.

Type

float

V_0

equilibrium lattice volume.

Type

float

popt

fitting parameters for particular EOS.

Type

list of float

p0

initial guess at fitting parameters.

Type

list of float

rrmsd

relative root mean square deviation of fit, as defined by [2].

Type

float

Set up EOS ready for fit.

Parameters

• E_0 (float) – equilibrium energy.

• V_0 (float) – equilibrium volume.

fit(volumes, energies)

Perform a least squares fit on the volumes and energies.

Parameters

• volumes (list of float) – calculated volumes.

• energies (list of float) – calculated energies.

evaluate(V, B, C)

Evaluate the EOS.

Parameters

• V (list of float) – volumes at which to test.

• B (float) – the first fitting parameter defined in [2].

• C (float) – the second fitting parameter defined in [2].

residual(guess, V, E)

Calculate the resdiual of the current fit.

Parameters

• guess (list of float) – interim fitting parameters.

• V (list of float) – volumes at which to test.

• E (list of float) – energies at the volumes V.

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)

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.

Parameters

• E_0 (float) – equilibrium energy.

• V_0 (float) – equilibrium volume.

evaluate(V, B, C)

Evaluate the EOS.

Parameters

• V (list of float) – volumes at which to test.

• B (float) – the first fitting parameter defined in [2].

• C (float) – the second fitting parameter defined in [2].

get_bulk_modulus()

Return the bulk modulus of this particular fit.

class matador.crystal.elastic.PoirerTarantolaEOS(E_0, V_0)

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.

Parameters

• E_0 (float) – equilibrium energy.

• V_0 (float) – equilibrium volume.

evaluate(V, B, C)

Evaluate the EOS.

Parameters

• V (list of float) – volumes at which to test.

• B (float) – the first fitting parameter defined in [2].

• C (float) – the second fitting parameter defined in [2].

get_bulk_modulus()

Return the bulk modulus of this particular fit.

class matador.crystal.elastic.TaitEOS(E_0, V_0)

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.

Parameters

• E_0 (float) – equilibrium energy.

• V_0 (float) – equilibrium volume.

evaluate(V, B, C)

Evaluate the EOS.

Parameters

• V (list of float) – volumes at which to test.

• B (float) – the first fitting parameter defined in [2].

• C (float) – the second fitting parameter defined in [2].

get_bulk_modulus()

Return the bulk modulus of this particular fit.

matador.crystal.elastic.plot_volume_curve(probes_all, labels, curves, volumes, energies, seed)

Plot all fitted EOS curves for this structure and save as a PDF.

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)

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)

Return generator of strongly-connected subgraphs in CrystalGraph format.

get_communities(graph=None, **louvain_kwargs)

Return list of community subgraphs in CrystalGraph format.

remove_directionality(graph=None)

set_unique_subgraphs(method='community')

Filter strongly connected component subgraphs for isomorphism with others inside CrystalGraph. Sets self.unique_subgraph to a set of such subgraphs.

get_bonds_per_atom()

matador.crystal.network.node_match(n1, n2)

matador.crystal.network.get_unique_subgraphs(subgraphs)

Filter strongly connected component subgraphs for isomorphism with others.

Input:

subgraphs: list(CrystalGraph), list of subgraph objects to filter

Returns

set(CrystalGraph), set of unique subgraphs

Return type

unique_subgraphs

matador.crystal.network.are_graphs_the_same(g1, g2, edge_match=None)

matador.crystal.network.draw_network(structure, layout=None, edge_labels=False, node_index=False, curved_edges=True, node_colour='elem', partition=None, ax=None)