matador.utils package

This module contains various utility functions that are used liberally throughout matador.

Submodules

matador.utils.ase_utils module

This file implements some light wrappers to the Atomic Simulation Environment (ASE).

matador.utils.ase_utils.ase2dict(atoms, as_model=False) → Union[dict, Crystal]

Return a matador document (dictionary or Crystal) from an ase.Atoms object.

Parameters:

atoms (ase.Atoms) – input structure.

Keyword Arguments:

as_model (bool) – if True, return a Crystal instead of a dictionary.

Returns:

matador output.

Return type:

Union[dict, Crystal]

matador.utils.ase_utils.doc2ase(doc: Union[dict, Crystal], add_keys_to_info=True)

Convert matador document to simple ASE object.

Parameters:

doc (dict/Crystal) – matador document or Crystal containing the structure.

Keyword Arguments:

add_keys_to_info (bool) – whether or not to add the keys from the matador document to the info section of the Atoms object.

matador.utils.castep_help_utils module

This submodule is essentially a script to scrape CASTEP help strings for all possible CASTEP parameters.

matador.utils.castep_help_utils.scrape_castep_params(executable)

Scan CASTEP help system for parameter file keywords.

Parameters:

executable (str) – name of CASTEP executable

Returns:

list of cell keyword strings list: list of cell blocks names list: list of param keyword strings str: castep version number used

Return type:

list

matador.utils.castep_help_utils.update_castep_param_list(executable)

Update the castep_params.py file.

Parameters:

executable (str) – name of CASTEP executable

matador.utils.castep_params module

This file contains a Python list of all CASTEP parameters, automatically generated with file_utils.scrape_castep_params().

matador.utils.cell_utils module

This submodule implements some useful functions for real/reciprocal cell manipulation, symmetry checking and sampling (e.g. grids and paths.)

matador.utils.cell_utils.abc2cart(lattice_abc: List[List[float]]) → List[List[float]]

Converts lattice parameters into Cartesian lattice vectors.

Parameters:

lattice_abc – The lattice parameters [[a, b, c], [alpha, beta, gamma]]

Returns:

Cartesian lattice vectors.

matador.utils.cell_utils.cart2abcstar(lattice_cart: List[List[float]]) → ndarray

Convert Cartesian lattice vectors to the reciprocal of the lattice vectors, NOT the reciprocal lattice vectors (useful when writing PDB files).

Parameters:

lattice_cart – Cartesian lattice vectors.

Returns:

Reciprocal of the lattice vectors.

matador.utils.cell_utils.cart2volume(lattice_cart: List[List[float]]) → float

Convert lattice_cart to cell volume.

Parameters:

lattice_cart – Cartesian lattice vectors.

Returns:

Cell volume in the same unit as the lattice vectors (cubed).

matador.utils.cell_utils.cart2abc(lattice_cart: List[List[float]]) → List[List[float]]

Convert Cartesian lattice vectors to lattice parametres.

Parameters:

lattice_cart – Cartesian lattice vectors.

Returns:

The lattice parameters \([(a, b, c), (\alpha, \beta, \gamma)]\).

matador.utils.cell_utils.frac2cart(lattice_cart: List[List[float]], positions_frac: List[List[float]]) → List[List[float]]

Convert positions_frac block into positions_abs.

Parameters:

• lattice_cart – Cartesian lattice vectors.

• positions_frac – List of fractional position vectors.

Returns:

List of absolute position vectors.

matador.utils.cell_utils.wrap_frac_coords(positions: Union[List[List[float]], List[float]], remove: bool = False) → Union[List[List[float]], List[float]]

Wrap the given fractional coordinates back into the cell.

Parameters:

positions – list of fractional position vectors, or a single position.

Keyword Arguments:

remove – if True, removes points exterior to the cell.

Returns:

List of wrapped fractional position vectors.

matador.utils.cell_utils.switch_coords(lattice: ndarray, pos: ndarray, norm: Optional[float] = None) → ndarray

Act on coordinates with the relevant lattice vectors to switch from fractional to absolute coordinates.

Parameters:

• lattice – either lattice_cart or reciprocal lattice_cart (3x3 array)

• pos – input positions to convert (3xN array for N atoms).

Keyword Arguments:

norm (float) – divide final coordinates by normalisation factor, e.g. \(2 \pi\) when lattice is recip and positions are cartesian.

Returns:

3xN array of converted positions.

matador.utils.cell_utils.cart2frac(lattice_cart: List[List[float]], positions_abs: List[List[float]]) → List[List[float]]

Convert positions_abs block into positions_frac (and equivalent in reciprocal space).

Parameters:

• lattice_cart – Cartesian lattice vectors.

• positions_abs – list of absolute position vectors.

Returns:

List of fractional position vectors with the same shape

as the input list.

matador.utils.cell_utils.real2recip(real_lat: List[List[float]]) → List[List[float]]

Convert the real lattice in Cartesian basis to the reciprocal space lattice.

Parameters:

real_lat – Cartesian lattice vectors.

Returns:

Cartesian lattice vectors of reciprocal lattice.

matador.utils.cell_utils.calc_mp_grid(lattice_cart: List[List[float]], spacing: float) → Tuple[int, int, int]

Return the Monkhorst-Pack grid based on lattice vectors and desired spacing.

Parameters:

• lattice_cart – Cartesian lattice vectors.

• spacing – desired maximum grid spacing.

Returns:

List of 3 integers defining the MP grid.

matador.utils.cell_utils.shift_to_include_gamma(mp_grid: Tuple[int, int, int]) → Tuple[float, float, float]

Calculate the shift required to include the \(\Gamma\)-point in the Monkhorst-Pack grid.

Parameters:

mp_grid – number of grid points in each reciprocal space direction.

Returns:

The shift required to include the \(\Gamma\).

matador.utils.cell_utils.shift_to_exclude_gamma(mp_grid: Tuple[int, int, int]) → Tuple[float, float, float]

Calculate the shift required to exclude the \(\Gamma\)-point in the Monkhorst-Pack grid. Returns the “minimal shift”, i.e. only one direction will be shifted.

Parameters:

mp_grid – number of grid points in each reciprocal space direction.

Returns:

The shift required to exclude \(\Gamma\).

matador.utils.cell_utils.get_best_mp_offset_for_cell(doc: Union[Dict[str, Any], Crystal]) → List[float]

Calculates the “best” kpoint_mp_offset to use for the passed cell. If the crystal has a hexagonal space group, then the offset returned will shift the grid to include \(\Gamma\)-point, and vice versa for non-hexagonal cells.

Parameters:

doc – matador document/Crystal to consider, containing structural information and a “kpoints_mp_spacing” key.

Returns:

The desired kpoint_mp_offset.

matador.utils.cell_utils.calc_mp_spacing(real_lat: List[List[float]], mp_grid: Tuple[int, int, int], prec: int = 3) → float

Convert real lattice in Cartesian basis and the CASTEP kpoint_mp_grid into a CASTEP grid spacing.

Parameters:

• real_lat – Cartesian lattice vectors.

• mp_grid – 3 integers defining the MP grid.

Keyword Arguments:

prec – desired decimal precision of output.

Returns:

kpoint_mp_spacing rounded to prec decimal places.

matador.utils.cell_utils.get_seekpath_kpoint_path(doc: Union[Dict[str, Any], Tuple], standardize: bool = True, explicit: bool = True, spacing: float = 0.01, threshold: float = 1e-07, debug: bool = False, symmetry_tol: Optional[float] = None) → Tuple[Dict[str, Any], List[List[float]], Dict[str, Any]]

Return the conventional kpoint path of the relevant crystal system according to the definitions by “HKPOT” in Comp. Mat. Sci. 128, 2017:

http://dx.doi.org/10.1016/j.commatsci.2016.10.015

Parameters:

doc – matador doc or spglib tuple to find kpoint path for.

Keyword Arguments:

• spacing – desired kpoint spacing

• threshold – internal seekpath threshold

• symmetry_tol – spglib symmetry tolerance

Returns:

standardized version of input doc list: list of kpoint positions dict: full dictionary of all seekpath results

Return type:

dict

matador.utils.cell_utils.doc2spg(doc: Union[Dict[str, Any], 'Crystal'], check_occ: bool = True) → Tuple[List[List[float]], List[List[float]], List[int]]

Return an spglib input tuple from a matador doc.

Parameters:

doc – matador document or Crystal object.

Keyword Arguments:

check_occ – check for partial occupancy and raise an error if present.

Returns:

spglib-style tuple of lattice, positions and types.

Return type:

tuple

matador.utils.cell_utils.get_space_group_label_latex(label: str) → str

Return the LaTeX format of the passed space group label. Takes any string, leaves the first character upright, italicses the rest, handles subscripts and bars over numbers.

Parameters:

• label – a given space group in “standard” plain text format,

• '$Pbar{6}3m$'. (e.g. P-63m to convert to) –

Returns:

The best attempt to convert the label to LaTeX format.

matador.utils.cell_utils.standardize_doc_cell(doc: Union['Crystal', Dict[str, Any]], primitive: bool = True, symprec: float = 0.01) → Union['Crystal', Dict[str, Any]]

Return standardized cell data from matador doc.

Parameters:

doc – matador document or Crystal object to standardize.

Keyword Arguments:

• primitive – whether to reduce cell to primitive.

• symprec – spglib symmetry tolerance.

Returns:

A matador document/Crystal containing standardized cell.

matador.utils.cell_utils.get_spacegroup_spg(doc: Union[Dict[str, Any], Crystal], symprec: float = 0.01, check_occ: bool = True)

Return spglib spacegroup for a cell.

Parameters:

doc – matador document or Crystal object.

Keyword Arguments:

symprec – spglib symmetry tolerance.

Returns:

The H-M space group symbol of structure.

matador.utils.cell_utils.get_compatible_spacegroups(doc: Union[Dict[str, Any], Crystal], symprec_range=(-5, 0)) → Dict[float, str]

Return the space group of a given crystal for the range of symprecs.

Parameters:

• doc – The crystal to analyse.

• symprec_range – The range of symprecs to test (log space).

Returns:

A mapping from symprec to space group symbol.

matador.utils.cell_utils.add_noise(doc: Dict[str, Any], amplitude: float = 0.1) → Dict[str, Any]

Add random noise to the positions of structure contained in doc. Useful for force convergence tests.

Parameters:

doc – dictionary containing matador structure.

Keyword Arguments:

amplitude – maximum amplitude of noise vector.

Raises:

KeyError if (lattice_cart and positions_frac) or positions_abs – are missing.

Returns:

The randomised structure.

matador.utils.cell_utils.calc_pairwise_distances_pbc(poscart, images, lattice, rmax, poscart_b=None, compress=False, debug=False, filter_zero=False, per_image=False)

Calculate PBC distances with SciPy’s cdist, given the image cell vectors.

Parameters:

• poscart (numpy.ndarray) – list or array of absolute atomic coordinates.

• images – iterable of lattice vector multiples (e.g. [2, -1, 3]) required to obtain the translation to desired image cells.

• lattice (list if list) – list of lattice vectors of the real cell.

• rmax (float) – maximum value after which to mask the array.

Keyword Arguments:

• poscart_b (numpy.ndarray) – absolute positions of another type of atom, where only A-B distances will be calculated.

• debug (bool) – print timing data and how many distances were masked.

• compress (bool) – whether or not to compressed the output array, useful when e.g. creating PDFs but not when atom ID is important.

• filter_zero (bool) – whether or not to filter out the “self-interaction” zero distances.

• per_image (bool) – return a list of distances per image, as opposed to one large flat. This preserves atom IDs for use elsewhere.

Returns:

pairwise 2-D d_ij masked array with values

or stripped 1-D array containing just the distances, or a list of numpy arrays if per_image is True.

Return type:

distances (numpy.ndarray)

matador.utils.cell_utils.create_simple_supercell(doc: Union[Dict[str, Any], 'Crystal'], extension: Tuple[int, int, int], standardize: bool = False, symmetric: bool = False) → Union[Dict[str, Any], 'Crystal']

Return a document with new supercell, given extension vector.

Parameters:

• doc – matador doc to construct cell from.

• extension – multiplicity of each lattice vector, e.g. (2,2,1).

Keyword Arguments:

• standardize – whether or not to use spglib to standardize the cell first.

• symmetric – whether or not centre the new cell on the origin.

Returns:

The supercell, either as a Crystal or as a dictionary, depending on the input type.

matador.utils.cell_utils.create_supercell_with_minimum_side_length(doc: Union[Dict[str, Any], 'Crystal'], target: float)

Pad the cell such that the minimum side length is greater than the target length.

Parameters:

• doc – The crystal structure to pad.

• target – The target minimum side length.

Returns:

The supercell.

matador.utils.chem_utils module

This submodule defines some useful chemical functions and constants, with a focus on battery materials.

matador.utils.chem_utils.get_iupac_ordered_elements(elements: List[str]) → List[str]

Returns the list of elements in IUPAC order, i.e., that specified in Table VI of the IUPAC Red Book:

Nomenclature of Inorganic Chemistry, IUPAC Recommendations 2005, IUPAC Red Book, RSC Publishing, 2005 [ISBN 0 85404 438 8]

Returns:

List of elements in the IUPAC order.

matador.utils.chem_utils.get_periodic_table()

Return some periodic table macros.

matador.utils.chem_utils.get_molar_mass(elem)

Returns molar mass of chosen element.

matador.utils.chem_utils.get_atomic_number(elem)

Returns atomic number of chosen element.

matador.utils.chem_utils.get_atomic_symbol(atomic_number)

Returns elemental symbol from atomic number.

matador.utils.chem_utils.get_concentration(doc, elements, include_end=False)

Returns x for A_x B_{1-x} or x,y for A_x B_y C_z, (x+y+z=1).

Parameters:

• doc (list/dict) – structure to evaluate OR matador-style stoichiometry.

• elements (list) – list of element symbols to enforce ordering.

Keyword Arguments:

include_end (bool) – whether or not to return the final value, i.e. [x, y, z] rather than [x, y] in the above.

Returns:

concentrations of elements in given order.

Return type:

list of float

matador.utils.chem_utils.get_subscripted_formula(formula: str) → str

Subscripts numbers in a chemical formula, returning unicode subscripts.

matador.utils.chem_utils.get_subscripted_formula_tex(formula: str) → str

Subscripts numbers in a chemical formula, returning LaTeX math subscripts.

matador.utils.chem_utils.get_num_intercalated(cursor)

Return array of the number of intercalated atoms per host atom from a list of structures, of type defined by the first entry in the structures’ concentration vectors.

Parameters:

cursor (list of dict) – structures to evaluate.

Returns:

number of intercalated ions in each structure.

Return type:

ndarray

matador.utils.chem_utils.get_binary_grav_capacities(x, m_B)

Returns capacity in mAh/g from x/y in A_x B_y and m_B in a.m.u.

matador.utils.chem_utils.get_generic_grav_capacity(concs, elements)

Returns gravimetric capacity of <elements[0]> in mAh/g of matador doc.

matador.utils.chem_utils.get_binary_volumetric_capacity(initial_doc, final_doc)

For initial (delithiated/sodiated) (single element) structure and final (maximally charged) binary structure, calculate the volumetric capacity.

Parameters:

• initial_doc (dict) – matador doc of delithiated phase

• final_doc (dict) – matador doc of maximally lithiated phase

Returns:

capacity in mAh/cm^3.

Return type:

volumetric_capacity (float)

matador.utils.chem_utils.get_atoms_per_fu(doc)

Calculate and return the number of atoms per formula unit.

Parameters:

doc (list/dict) – structure to evaluate OR matador-style stoichiometry.

matador.utils.chem_utils.get_formation_energy(chempots, doc, energy_key='enthalpy_per_atom')

From given chemical potentials, calculate the simplest formation energy per atom of the desired document.

Note

recursive_get(doc, energy_key) MUST return an energy per atom for the target doc and the chemical potentials.

Parameters:

• chempots (list of dict) – list of chempot structures, must be unique.

• doc (dict) – structure to evaluate.

Keyword Arguments:

energy_key (str or list) – name of energy field to use to calculate formation energy. Can use a list of keys/subkeys/indices to query nested dicts with matador.utils.cursor_utils.recursive_get.

Returns:

formation energy per atom.

Return type:

float

matador.utils.chem_utils.get_number_of_chempots(stoich, chempot_stoichs, precision=5)

Return the required number of each (arbitrary) chemical potentials to construct one formula unit of the input stoichiometry. Uses least-squares as implemented by numpy.linalg.lstsq and rounds the output precision based on the precision kwarg.

Parameters:

• stoich (list/dict) – matador-style stoichiometry, e.g. [[‘Li’, 3], [‘P’, 1]], or the full document.

• chempot_stoichs (list/dict) – list of stoichiometries of the input chemical potentials, or the full documents.

Keyword Arguments:

precision (int/None) – number of decimal places to round answer to. None maintains the precision from numpy.linalg.lstsq.

Returns:

number of each chemical potential required to create

1 formula unit.

Return type:

list

Raises:

RuntimeError – if the stoichiometry provided cannot be created with the given chemical potentials.

matador.utils.chem_utils.get_stoich(atom_types)

Return integer stoichiometry from atom_types list.

Parameters:

atom_types (list) – list of element symbols of each atom.

Returns:

matador-style stoichiometry, e.g. [[‘Li’, 1], [‘P’, 2]].

Return type:

list

matador.utils.chem_utils.get_padded_composition(stoichiometry, elements)

Return a list that contains how many of each species in elements exists in the given stoichiometry. e.g. for [[‘Li’, 2], [‘O’, 1]] with elements [‘O’, ‘Li’, ‘Ba’], this function will return [1, 2, 0].

Parameters:

• stoichiometry (list) – matador-style stoichiometry, as above.

• elements (list) – order of element labels to pick out.

matador.utils.chem_utils.get_ratios_from_stoichiometry(stoichiometry)

Get a dictionary of pairwise atomic ratios.

Parameters:

stoichiometry (list) – matador-style stoichiometry.

Returns:

dictionary of pairwise ratios, e.g. for K8SnP4,

ratio_dict = {‘KSn’: 8, ‘KP’: 2, ‘SnP’: 0.25,

’SnK’: 0.125, ‘PSn’: 4, ‘PK’: 0.5}.

Return type:

dict

matador.utils.chem_utils.get_stoich_from_formula(formula: str, sort=True)

Convert formula string, e.g. Li2TiP4 into a matador-style stoichiometry, e.g. [[‘Li’, 2], [‘Ti’, 1], [‘P’, 4]].

Parameters:

formula (str) – chemical formula of compound

Returns:

sorted matador-style stoichiometry.

Return type:

list

matador.utils.chem_utils.parse_element_string(elements_str, stoich=False)

Parse element query string with macros. Has to parse braces too, and throw an error if brackets are unmatched.

e.g.

Parameters: ‘[VII][Fe,Ru,Os][I]’ Returns: [‘[VII]’, ‘[Fe,Ru,Os]’, ‘[I]’]

e.g.2

Parameters: ‘[VII]2[Fe,Ru,Os][I]’ Returns: [‘[VII]2’, ‘[Fe,Ru,Os]’, ‘[I]’]

Parameters:

elements_str – str, chemical formula, including macros.

Keyword Arguments:

stoich – bool, parse as a stoichiometry, i.e. check for numbers

Raises:

RuntimeError – if the composition contains unmatched brackets.

Returns:

split list of elements contained in input

Return type:

list

matador.utils.chem_utils.get_root_source(source)

Get the main file source from a doc’s source list.

Parameters:

source (str/list/dict) – contents of doc[‘source’] or the doc itself.

Returns:

“root” filename, e.g. if source = [‘KP.cell’, ‘KP.param’,

’KP_specific_structure.res’] then root = ‘KP_specific_structure’.

Return type:

str

matador.utils.chem_utils.get_formula_from_stoich(stoich, elements=None, tex=False, sort=True, unicode_sub=False, latex_sub_style='')

Get the chemical formula of a structure from its matador stoichiometry.

Parameters:

stoich (list) – matador-style stoichiometry.

Keyword Arguments:

• elements (list) – list of element symbols to enforce order.

• tex (bool) – whether to print a LaTeX-compatibile string.

• unicode_sub (bool) – use unicode subscripts

• latex_sub_style (str) – a string to wrap subscripts in, e.g. r”mathrm” or r”text” (default is blank).

Returns:

the string representation of the chemical formula.

Return type:

str

matador.utils.chem_utils.magres_reference_shifts(magres: Dict[str, Any], reference: Dict[str, Tuple[float, float]])

Set chemical shifts inside a matador document from shieldings and a given reference.

Parameters:

magres: A matador document containing the structure and magres shielding data. reference: Reference values in the form {element: [gradient, constant]}.

Returns:

The input dictionary with the chemical_shift_isos key set to the referenced shifts.

matador.utils.cursor_utils module

This submodule defines some useful generic cursor methods for displaying, extracting and refining results from a Mongo cursor/list.

matador.utils.cursor_utils.recursive_get(data, keys, _top=True)

Recursively slice a nested dictionary by a list of keys.

Parameters:

• data (dict) – nested dictionary to get from.

• keys (list) – list of keys/indices to delve into.

Raises:

• KeyError – if any in chain keys are missing,

• IndexError – if any element of a sublist is missing.

matador.utils.cursor_utils.recursive_set(data, keys, value)

Recursively slice a nested dictionary by a list of keys and set the value.

Parameters:

• data (dict) – nested dictionary to get from.

• keys (list) – list of keys/indices to delve into.

• value – value to store under key.

Raises:

KeyError – if any intermediate keys are missing.

matador.utils.cursor_utils.display_results(cursor, energy_key='enthalpy_per_atom', summary=False, args=None, argstr=None, additions=None, deletions=None, sort=True, hull=False, markdown=False, latex=False, colour=True, return_str=False, use_source=True, details=False, per_atom=False, eform=False, source=False, **kwargs)

Print query results in a table, with many options for customisability.

TODO: this function has gotten out of control and should be rewritten.

Parameters:

cursor (list of dict or pm.cursor.Cursor) – list of matador documents

Keyword Arguments:

• summary (bool) – print a summary per stoichiometry, that uses the lowest energy phase (requires sort=True).

• argstr (str) – string to store matador initialisation command

• eform (bool) – prepend energy key with “formation_”.

• sort (bool) – sort input cursor by the value of energy key.

• return_str (bool) – return string instead of printing.

• details (bool) – print extra details as an extra line per structure.

• per_atom (bool) – print quantities per atom, rather than per fu.

• source (bool) – print all source files associated with the structure.

• use_source (bool) – use the source instead of the text id when displaying a structure.

• hull (bool) – whether or not to print hull-style (True) or query-style

• energy_key (str or list) – key (or recursive key) to print as energy (per atom)

• markdown (bool) – whether or not to write a markdown file containing results

• latex (bool) – whether or not to create a LaTeX table

• colour (bool) – colour on-hull structures

• additions (list) – list of string text_ids to be coloured green with a (+) or, list of indices referring to those structures in the cursor.

• deletions (list) – list of string text_ids to be coloured red with a (-) or, list of indices referring to those structures in the cursor.

• kwargs (dict) – any extra args are ignored.

Returns:

markdown or latex string, if markdown or latex is True, else None.

Return type:

str or None

matador.utils.cursor_utils.loading_bar(iterable, width=80, verbosity=0)

Checks if tqdm exists and makes a loading bar, otherwise just returns initial iterable.

Parameters:

iterable (iterable) – the thing to be iterated over.

Keyword Arguments:

width (int) – maximum number of columns to use on screen.

Returns:

the decorated iterator.

Return type:

iterable

matador.utils.cursor_utils.set_cursor_from_array(cursor, array, key)

Updates the key-value pair for documents in internal cursor from a numpy array.

matador.utils.cursor_utils.get_array_from_cursor(cursor, key, pad_missing=False)

Returns a numpy array of the values of a key in a cursor, where the key can be defined as list of keys to use with recursive_get.

Parameters:

• cursor (list) – list of matador dictionaries.

• key (str or list) – the key to extract, or list of keys/subkeys/indices to extract with recursive_get.

Keyword Arguments:

pad_missing (bool) – whether to fill array with NaN’s where data is missing.

Raises:

KeyError – if any document is missing that key, unless pad_missing is True.

Returns:

numpy array containing results, padded

with np.nan if key is missing and pad_missing is True.

Return type:

np.ndarray

matador.utils.cursor_utils.get_guess_doc_provenance(sources, icsd=None)

Returns a guess at the provenance of a structure from its source list.

Return possiblities are ‘ICSD’, ‘SWAP’, ‘OQMD’ or ‘AIRSS’, ‘MP’ or ‘PF’.

matador.utils.cursor_utils.filter_unique_structures(cursor, quiet=False, **kwargs)

Wrapper for matador.fingerprints.similarity.get_uniq_cursor that displays the results and returns the filtered cursor.

matador.utils.cursor_utils.filter_cursor(cursor, key, vals, verbosity=0)

Returns a cursor obeying the filter on the given key. Any documents that are missing the key will not be returned. Any documents with values that cannot be compared to floats will also not be returned.

Parameters:

• cursor (list) – list of dictionaries to filter.

• key (str) – key to filter.

• vals (list) – either 1 value to 2 values to use as a range. The values are interpreted as floats for comparison.

Returns:

list of dictionaries that pass the filter.

Return type:

list

matador.utils.cursor_utils.filter_cursor_by_chempots(species, cursor)

For the desired chemical potentials, remove any incompatible structures from cursor.

Parameters:

• species (list) – list of chemical potential formulae.

• cursor (list) – list of matador documents to filter.

Returns:

the filtered cursor.

Return type:

list

matador.utils.cursor_utils.index_cursors_by_structure(cursors, structure_labeller=<function get_root_source>)

For a dictionary of lists of structures, reindex the list by the root source of each structure.

Parameters:

• cursors – A dictionary of input cursors. Keys will be used as labels in the output dictionary.

• structure_labeller – A function called on each structure, the result of which will be that structure’s key in the output dictionary.

Returns:

A dictionary with one key per structure, with subkeys corresponding to the elements of the initial cursors, under which structures are stored from each cursor.

matador.utils.cursor_utils.compare_structures(structures, order, fields=None)

Compare structures across various specified or default fields.

Intended use is to compare crystal structures/energies of the “same” crystal when relaxed with different parameters.

Parameters:

• structures – A dictionary containing the structures to compare. Keys will be used to label the output.

• order – The order of the input keys to use, the first of which will be treated as the ‘benchmark’ structure.

• fields – A list of fields to compare. If None, defaults to comparing the lattice parameters, cell volumes and stabilities (hull distance, formation energy).

Returns:

A dictionary summarising the differences.

matador.utils.cursor_utils.compare_structure_cursor(cursor, order, fields=None)

Compare the “same” structures across different accuracies.

Parameters:

• cursor – A dict of dicts keyed by structure ID storing data for each structure at different accuracies.

• order – An ordered list of the subkeys for each structure; the first will be used as the benchmark.

• fields – A list of fields to compare. If None, defaults to comparing the lattice parameters, cell volumes and stabilities (hull distance, formation energy).

Returns:

A dictionary of dictionaries summarising the differences.

matador.utils.db_utils module

matador.utils.errors module

This submodule module implements some useful exception types, mostly for use in the compute and calculator submodules.

exception matador.utils.errors.CalculationError

Bases: Exception

Raised when a particular calculation fails, for non-fatal reasons.

exception matador.utils.errors.MaxMemoryEstimateExceeded

Bases: Exception

Raised when a structure is estimated to exceed the max memory.

exception matador.utils.errors.CriticalError

Bases: RuntimeError

Raise this when you don’t want any more jobs to run because something uncorrectable has happened! Plays more nicely with multiprocessing than SystemExit.

exception matador.utils.errors.InputError

Bases: RuntimeError

Raise this when there is an issue with the input files.

exception matador.utils.errors.WalltimeError

Bases: RuntimeError

Raise this when you don’t want any more jobs to run because they’re about to exceed the max walltime.

exception matador.utils.errors.NodeCollisionError

Bases: CalculationError

Dummy exception to raise when one node has tried to run a calculation that another node is performing.

matador.utils.hull_utils module

This file implements some useful geometric functions for the construction and manipulation of convex hulls.

matador.utils.hull_utils.vertices2plane(points)

Convert points (xi, yi, zi) for i=1,..,3 into the equation of the plane spanned by the vectors v12, v13. For unit vectors e(i):

v12 x v13 = n = i*e(1) + j*e(2) + k*e(3)

and so the equation of the plane is

i*x + j*y + k*z + d = 0.

Parameters:

points (list of np.ndarray) – list of 3 3D numpy arrays containing the points comprising the vertex.

Returns:

a function which will return the vertical distance between

the point and the plane:

Return type:

callable

matador.utils.hull_utils.vertices2line(points)

Perform a simple linear interpolation on two points.

Parameters:

points (list of np.ndarray) – list of two 2D numpy arrays. of form [[x1, E1], [x2, E2]].

Returns:

a tuple containing the gradient and

intercept of the line intersecting the two points.

Return type:

(float, float)

matador.utils.hull_utils.is_point_in_triangle(point, triangle, preprocessed_triangle=False)

Check whether a point is inside a triangle.

Parameters:

• point (np.ndarray) – 3x1 array containing the coordinates of the point.

• triangle (np.ndarray) – 3x3 array specifying the coordinates of the triangle vertices.

Keyword Arguments:

preprocessed_triangle (bool) – if True, treat the input triangle as already processed, i.e. the array contains the inverse of the barycentric coordinate array.

Returns:

whether or not the point is found to lie inside the

triangle. If all vertices of the triangle lie on the same line, return False.

Return type:

bool

matador.utils.hull_utils.barycentric2cart(structures)

Convert ternary (x, y) in A_x B_y C_{1-x-y} to positions projected onto 2D plane.

Input structures array is of the form:

[

[l(1)_0, l(2)_0, Eform_0], [l(1)_n, l(2)_n, Eform_n]

]

where l3 = 1 - l2 - l1 are the barycentric coordinates of the point in the triangle defined by the chemical potentials.

Parameters:

structures (list of np.ndarray) – list of 3D numpy arrays containing input points.

Returns:

list of numpy arrays containing converted

coordinates.

Return type:

list of np.ndarray

class matador.utils.hull_utils.FakeHull

Bases: object

Implements a thin class to mimic a ConvexHull object that would otherwise be undefined for two points.

Define the used hull properties.

matador.utils.optimade_utils module

This submodule implements some convenience functions for working with OPTIMADE structures.

matador.utils.optimade_utils.optimade2dict_from_url(url: str) → Union[Crystal, List[Crystal]]

Queries the provided OPTIMADE URL and returns a Crystal of list of crystals for the corresponding structures.

Parameters:

url – The URL of a single or multiple OPTIMADE structure entries.

Returns:

The crystal or list of crystals.

matador.utils.optimade_utils.optimade2dict(structure: Dict[str, Any]) → Crystal

This function takes an OPTIMADE structure and converts it into a matador Crystal.

matador.utils.pmg_utils module

This file implements some light wrappers to the pymatgen, via ASE.

matador.utils.pmg_utils.get_chemsys(elements, dumpfile=None)

Scrape the Materials Project for the chemical system specified by elements, e.g. for elements ['A', 'B', 'C'] the query performed is chemsys='A-B-C' & nelements=3. Requires interactive user input of their MP API key (unless set by environment variable $PMG_MAPI_KEY).

Parameters:

elements (list) – list of chemical symbols.

Keyword Arguments:

dumpfile (str) – optional filename to dump the pickled response after conversion to matador documents.

matador.utils.pmg_utils.doc2pmg(doc: Union[dict, Crystal])

Converts matador document/Crystal to a pymatgen structure, via ASE.

matador.utils.pmg_utils.pmg2dict(pmg: Structure, as_model=False) → Union[dict, Crystal]

Converts a pymatgen.Structure to a matador document/Crystal.

Parameters:

pmg (pymatgen.Structure) – the structure to convert.

Keyword Arguments:

as_model (bool) – if True, return a Crystal instead of a dict.

Returns:

the converted structure.

Return type:

Union[dict, Crystal]

matador.utils.pmg_utils.mp2dict(response)

Convert a response from pymatgen.MPRester into a matador document, via an ASE atoms object. Expects certain properties to be requested in order to construct a full matador document, e.g. structure & input.

Parameters:

response (dict) – containing one item of the MPRester response.

matador.utils.print_utils module

This file implements some useful wrappers to the print function for writing errors and warnings to stderr.

matador.utils.print_utils.print_warning(string)

Print but angry.

matador.utils.print_utils.print_failure(string)

Print but sad.

matador.utils.print_utils.print_success(string)

Print but happy.

matador.utils.print_utils.print_notify(string)

Print but aloof.

matador.utils.print_utils.dumps(obj, **kwargs)

Mirrors json.dumps whilst handling numpy arrays.

class matador.utils.print_utils.NumpyEncoder(*, skipkeys=False, ensure_ascii=True, check_circular=True, allow_nan=True, sort_keys=False, indent=None, separators=None, default=None)

Bases: JSONEncoder

This encoder handles NumPy arrays in JSON, and was taken from StackOverflow (where else) (https://stackoverflow.com/a/47626762).

Constructor for JSONEncoder, with sensible defaults.

If skipkeys is false, then it is a TypeError to attempt encoding of keys that are not str, int, float or None. If skipkeys is True, such items are simply skipped.

If ensure_ascii is true, the output is guaranteed to be str objects with all incoming non-ASCII characters escaped. If ensure_ascii is false, the output can contain non-ASCII characters.

If check_circular is true, then lists, dicts, and custom encoded objects will be checked for circular references during encoding to prevent an infinite recursion (which would cause an RecursionError). Otherwise, no such check takes place.

If allow_nan is true, then NaN, Infinity, and -Infinity will be encoded as such. This behavior is not JSON specification compliant, but is consistent with most JavaScript based encoders and decoders. Otherwise, it will be a ValueError to encode such floats.

If sort_keys is true, then the output of dictionaries will be sorted by key; this is useful for regression tests to ensure that JSON serializations can be compared on a day-to-day basis.

If indent is a non-negative integer, then JSON array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. None is the most compact representation.

If specified, separators should be an (item_separator, key_separator) tuple. The default is (’, ‘, ‘: ‘) if indent is None and (‘,’, ‘: ‘) otherwise. To get the most compact JSON representation, you should specify (‘,’, ‘:’) to eliminate whitespace.

If specified, default is a function that gets called for objects that can’t otherwise be serialized. It should return a JSON encodable version of the object or raise a TypeError.

default(obj)

Implement this method in a subclass such that it returns a serializable object for o, or calls the base implementation (to raise a TypeError).

For example, to support arbitrary iterators, you could implement default like this:

def default(self, o):
    try:
        iterable = iter(o)
    except TypeError:
        pass
    else:
        return list(iterable)
    # Let the base class default method raise the TypeError
    return JSONEncoder.default(self, o)

matador.utils.viz_utils module

This submodule contains a dirty wrapper of ase-gui for quick visualisation, and nglview wrapper for JupyterNotebook visualisation, and some colour definitions scraped from VESTA configs.

matador.utils.viz_utils.viz(doc)

Quick and dirty ase-gui visualisation from matador doc.

matador.utils.viz_utils.get_element_colours() → Dict[str, List[float]]

Return RGB element colours from VESTA file.

The colours file can be specified in the matadorrc. If unspecified, the default ../config/vesta_elements.ini will be used.

matador.utils.viz_utils.get_element_radii()

Read element radii from VESTA config file. The colours file can be specified in the matadorrc. If unspecified, the default ../config/vesta_elements.ini (relative to this file) will be used.

matador.utils.viz_utils.nb_viz(doc, repeat=1, bonds=None)

Return an ipywidget for nglview visualisation in a Jupyter notebook or otherwise.

Parameters:

doc (matador.crystal.Crystal / dict) – matador document to show.

Keyword Arguments:

• repeat (int) – number of periodic images to include.

• bonds (str) – custom bond selection.

matador.utils.viz_utils.fresnel_view(doc: Crystal, standardize: Union[bool, float] = True, extension: Optional[Tuple[int, int, int]] = None, show_bonds: bool = True, show_cell: bool = True, show_compass: bool = True, bond_dict: Optional[Dict[Tuple[str, str], float]] = None, images: Union[bool, float] = True, pad_cell: bool = True, lights: Optional[Callable] = None, **camera_kwargs) → fresnel.Scene

Return a fresnel scene visualising the input crystal.

The scene can then be rendered/ray-traced with fresnel.pathtrace or fresnel.preview.

Notes

Periodic images of sites will be included in the visualisation if they are within the desired distance tolerance of another site in the crystal, and are only rendered if they are bonded within the definitions of the bond_dict. This process requires the construction of two kd-trees, so disabling the images flag will yield a significant speed-up for large crystal structures.

Parameters:

• doc – The crystal to visualize.

• standardize – Whether to standardize the crystal before visualising. If a float is provided, this will be used for the symmetry tolerance.

• extension – Visualize a supercell with this lattice extension.

• show_bonds – Whether to show bonds in the visualisation.

• show_cell – Whether to show the unit cell in the visualisation.

• show_compass – Whether to show a compass in the visualisation.

• bond_dict – A dictionary of bond lengths to override the default bonds, e.g., {('C', 'C'): 1.5, ('C', 'H'): 1.0}.

• images – Whether to show periodic images in the visualisation (if given a float, this will be used as the clipping distance).

• pad_cell – Size to aim for all directions to be visualised, e.g. a supercell with minimum side length pad_cell will be constructed.

• lights – An optional callable that sets the lights for the scene.

Returns:

The fresnel scene to render.

matador.utils.viz_utils.rerender_scenes_to_axes(scenes, axes, renderer=None)

(Re)render the scenes to the axes.

Parameters:

• scenes – List of fresnel scenes to render.

• axes – List or grid of matplolib axes to render to.

• renderer – The renderer to use (default pathtrace).

matador.utils.viz_utils.fit_orthographic_camera(scene: fresnel.Scene, scale=1.1, margin=0.05, view='isometric', vectors=None) → None

Alternative orthographic camera fitting, based on the equivalent fresnel function.

Parameters:

• scene – The fresnel scene to visualize.

• scale – The scale of the camera.

• margin – The margin around the viewbox.

• view – Either ‘front’, ‘isometric’, ‘a’, ‘b’, ‘c’, ‘vector’ or an actual vector.

• vectors – A custom dictionary of vectors with keys ‘v’, ‘up’ and ‘right’ that defines the camera basis.

matador.utils.viz_utils.get_image_atoms_near_cell_boundaries(doc: Crystal, tolerance: float, bond_dict: Optional[Dict[Tuple[str, str], float]] = None) → Tuple[List[str], List[Tuple[float, float, float]]]

Returns a list of atom positions and species that are within the distance tolerance of the non-image atoms.

Parameters:

• doc – The crystal object to consider.

• tolerance – The distance tolerance in Å.

• bond_dict – If provided, use asspecies-specific tolerances.

Returns:

A list of species and a list of positions in Cartesian coordinates.

matador.utils.viz_utils.fresnel_plot(structures: Union[Crystal, List[Crystal]], figsize: Optional[Tuple[float, float]] = None, fig_cols: Optional[int] = None, fig_rows: Optional[int] = None, labels: Union[bool, List[str]] = True, renderer: Optional[Callable] = None, camera_patches: Optional[List[Optional[Dict]]] = None, **fresnel_view_kwargs)

Visualize a series of structures as a grid of matplotlib plots.

Parameters:

• structures – A list or single structure to visualize.

• figsize – The size of the figure (defaults to a 3x4 box for each structure).

• fig_cols – The number of columns in the figure.

• fig_rows – The number of rows in the figure.

• labels – If true, label structures by formula, otherwise label by the passed list of strings.

• renderer – A callable to use instead of the default fresnel.pathtrace. A useful alternative could be fresnel.preview. Can also be used to parameterise the fresnel rendering with e.g., partial(fresnel.pathtrace, samples=64).

• fresnel_view_kwargs – Any additional kwargs will be passed down to matador.utils.viz_utils.fresnel_view to control e.g., camera angles. The contents of any keywords containing lists with the same length as the passed structures will be applied to each structure individually.

Returns:

The matplotlib figures, axis grid and a list of fresnel scenes.

matador.utils.viz_utils.formula_to_colour(formula: str) → List[float]

Return an RGBA colour for the given chemical formula, provided the formula has 3 or fewer species.

matador.utils.viz_utils.colour_from_ternary_concentration(conc: Union[Tuple[float, float], Tuple[float, float, float]], species: List[str], alpha: float = 1) → List[float]

Returns a colour for a ternary composition of the given species, mixing the configured VESTA colours.

Returns:

RGBA array.