pymatgen.util package — pymatgen 2025.6.14 documentation

# pymatgen.util package

The util package implements various utilities that are commonly used by various packages.

## Submodules

## pymatgen.util.coord module

Utilities for manipulating coordinates or list of coordinates, under periodic boundary conditions or otherwise. Many of these are heavily vectorized in numpy for performance.

class Simplex(coords)

  Bases: `MSONable`

  A generalized simplex object. See https://wikipedia.org/wiki/Simplex.

  space_dim

    Dimension of the space. Usually, this is 1 more than the simplex_dim.

    Type:

      int

  simplex_dim

    Dimension of the simplex coordinate space.

    Type:

      int

  Initialize a Simplex from vertex coordinates.

  Parameters:

    coords ([[float]]) – Coords of the vertices of the simplex. e.g. [[1, 2, 3], [2, 4, 5], [6, 7, 8], [8, 9, 10].

  bary_coords(point)
    Parameters:

      point (ArrayLike) – Point coordinates.

    Returns:

      Barycentric coordinations.

  property coords: ndarray

    A copy of the vertex coordinates in the simplex.

  in_simplex(point: Sequence[float], tolerance: float = 1e-08) → bool

    Check if a point is in the simplex using the standard barycentric coordinate system algorithm.

    Taking an arbitrary vertex as an origin, we compute the basis for the simplex from this origin by subtracting all other vertices from the origin. We then project the point into this coordinate system and determine the linear decomposition coefficients in this coordinate system. If the coeffs satisfy all(coeffs >= 0), the composition is in the facet.

    Parameters:

      - point (list[float]) – Point to test

      - tolerance (float) – Tolerance to test if point is in simplex.

  line_intersection(point1: Sequence[float], point2: Sequence[float], tolerance: float = 1e-08)

    Compute the intersection points of a line with a simplex.

    Parameters:

      - point1 (Sequence[float]) – 1st point to determine the line.

      - point2 (Sequence[float]) – 2nd point to determine the line.

      - tolerance (float) – Tolerance for checking if an intersection is in the simplex. Defaults to 1e-8.

    Returns:

      points where the line intersects the simplex (0, 1, or 2).

  point_from_bary_coords(bary_coords: ArrayLike)
    Parameters:

      bary_coords (ArrayLike) – Barycentric coordinates (d+1, d).

    Returns:

      Point in the simplex.

    Return type:

      np.array

  property volume: float

    Volume of the simplex.

all_distances(coords1: ArrayLike, coords2: ArrayLike) → np.ndarray

  Get the distances between two lists of coordinates.

  Parameters:

    - coords1 – First set of Cartesian coordinates.

    - coords2 – Second set of Cartesian coordinates.

  Returns:

    2d array of Cartesian distances. E.g the distance between coords1[i] and coords2[j] is distances[i,j]

barycentric_coords(coords, simplex)

  Convert a list of coordinates to barycentric coordinates, given a simplex with d+1 points. Only works for d >= 2.

  Parameters:

    - coords – list of n coords to transform, shape should be (n,d)

    - simplex – list of coordinates that form the simplex, shape should be (d+1, d)

  Returns:

    a list of barycentric coordinates (even if the original input was 1d)

coord_list_mapping(subset: ArrayLike, superset: ArrayLike, atol: float = 1e-08)

  Get the index mapping from a subset to a superset. Subset and superset cannot contain duplicate rows.

  Parameters:

    - subset (ArrayLike) – List of coords

    - superset (ArrayLike) – List of coords

    - atol (float) – Absolute tolerance. Defaults to 1e-8.

  Returns:

    list of indices such that superset[indices] = subset

coord_list_mapping_pbc(subset, superset, atol: float = 1e-08, pbc: tuple[bool, bool, bool] = (True, True, True))

  Get the index mapping from a subset to a superset. Superset cannot contain duplicate matching rows.

  Parameters:

    - subset (ArrayLike) – List of frac_coords

    - superset (ArrayLike) – List of frac_coords

    - atol (float) – Absolute tolerance. Defaults to 1e-8.

    - pbc (tuple) – A tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    list of indices such that superset[indices] = subset

find_in_coord_list(coord_list, coord, atol: float = 1e-08)

  Find the indices of matches of a particular coord in a coord_list.

  Parameters:

    - coord_list – List of coords to test

    - coord – Specific coordinates

    - atol – Absolute tolerance. Defaults to 1e-8. Accepts both scalar and array.

  Returns:

    Indices of matches, e.g. [0, 1, 2, 3]. Empty list if not found.

find_in_coord_list_pbc(frac_coord_list, frac_coord, atol: float = 1e-08, pbc: tuple[bool, bool, bool] = (True, True, True)) → ndarray

  Get the indices of all points in a fractional coord list that are equal to a fractional coord (with a tolerance), taking into account periodic boundary conditions.

  Parameters:

    - frac_coord_list – List of fractional coords

    - frac_coord – A specific fractional coord to test.

    - atol – Absolute tolerance. Defaults to 1e-8.

    - pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    Indices of matches, e.g. [0, 1, 2, 3]. Empty list if not found.

get_angle(v1: ArrayLike, v2: ArrayLike, units: Literal['degrees', 'radians'] = 'degrees') → float

  Calculate the angle between two vectors.

  Parameters:

    - v1 – Vector 1

    - v2 – Vector 2

    - units – “degrees” or “radians”. Defaults to “degrees”.

  Returns:

    Angle between them in degrees.

get_linear_interpolated_value(x_values: ArrayLike, y_values: ArrayLike, x: float) → float

  Get an interpolated value by linear interpolation between two values. This method is written to avoid dependency on scipy, which causes issues on threading servers.

  Parameters:

    - x_values – Sequence of x values.

    - y_values – Corresponding sequence of y values

    - x – Get value at particular x

  Returns:

    Value at x.

in_coord_list(coord_list, coord, atol: float = 1e-08) → bool

  Test if a particular coord is within a coord_list.

  Parameters:

    - coord_list – List of coords to test

    - coord – Specific coordinates

    - atol – Absolute tolerance. Defaults to 1e-8. Accepts both scalar and array.

  Returns:

    True if coord is in the coord list.

  Return type:

    bool

in_coord_list_pbc(fcoord_list, fcoord, atol: float = 1e-08, pbc: tuple[bool, bool, bool] = (True, True, True)) → bool

  Test if a particular fractional coord is within a fractional coord_list.

  Parameters:

    - fcoord_list – List of fractional coords to test

    - fcoord – A specific fractional coord to test.

    - atol – Absolute tolerance. Defaults to 1e-8.

    - pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    True if coord is in the coord list.

  Return type:

    bool

is_coord_subset(subset: ArrayLike, superset: ArrayLike, atol: float = 1e-08) → bool

  Test if all coords in subset are contained in superset. Doesn’t use periodic boundary conditions.

  Parameters:

    - subset (ArrayLike) – List of coords

    - superset (ArrayLike) – List of coords

    - atol (float) – Absolute tolerance for comparing coordinates. Defaults to 1e-8.

  Returns:

    True if all of subset is in superset.

  Return type:

    bool

is_coord_subset_pbc(subset, superset, atol: float = 1e-08, mask=None, pbc: tuple[bool, bool, bool] = (True, True, True)) → bool

  Test if all fractional coords in subset are contained in superset.

  Parameters:

    - subset (list) – List of fractional coords to test

    - superset (list) – List of fractional coords to test against

    - atol (float or size 3 array) – Tolerance for matching

    - mask (boolean array) – Mask of matches that are not allowed. i.e. if mask[1,2] is True, then subset[1] cannot be matched to superset[2]

    - pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    True if all of subset is in superset.

  Return type:

    bool

lattice_points_in_supercell(supercell_matrix)

  Get the list of points on the original lattice contained in the supercell in fractional coordinates (with the supercell basis). e.g. [[2,0,0],[0,1,0],[0,0,1]] returns [[0,0,0],[0.5,0,0]].

  Parameters:

    supercell_matrix – 3x3 matrix describing the supercell

  Returns:

    numpy array of the fractional coordinates

pbc_diff(frac_coords1: ArrayLike, frac_coords2: ArrayLike, pbc: tuple[bool, bool, bool] = (True, True, True))

  Get the ‘fractional distance’ between two coordinates taking into account periodic boundary conditions.

  Parameters:

    - frac_coords1 – First set of fractional coordinates. e.g. [0.5, 0.6, 0.7] or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. It can be a single coord or any array of coords.

    - frac_coords2 – Second set of fractional coordinates.

    - pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    Fractional distance. Each coordinate must have the property that abs(a) <= 0.5. Examples: pbc_diff([0.1, 0.1, 0.1], [0.3, 0.5, 0.9]) = [-0.2, -0.4, 0.2] pbc_diff([0.9, 0.1, 1.01], [0.3, 0.5, 0.9]) = [-0.4, -0.4, 0.11]

pbc_shortest_vectors(lattice, frac_coords1, frac_coords2, mask=None, return_d2: bool = False)

  Get the shortest vectors between two lists of coordinates taking into account periodic boundary conditions and the lattice.

  Parameters:

    - lattice – lattice to use

    - frac_coords1 – First set of fractional coordinates. e.g. [0.5, 0.6, 0.7] or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. It can be a single coord or any array of coords.

    - frac_coords2 – Second set of fractional coordinates.

    - mask (boolean array) – Mask of matches that are not allowed. i.e. if mask[1,2] is True, then subset[1] cannot be matched to superset[2]

    - return_d2 (bool) – whether to also return the squared distances

  Returns:

    of displacement vectors from frac_coords1 to frac_coords2

      first index is frac_coords1 index, second is frac_coords2 index

  Return type:

    np.ndarray

## pymatgen.util.coord_cython module

Utilities for manipulating coordinates or list of coordinates, under periodic boundary conditions or otherwise.

coord_list_mapping_pbc(subset, superset, atol=1e-08, pbc=(True, True, True))

  Gives the index mapping from a subset to a superset. Superset cannot contain duplicate matching rows.

  Parameters:

    - subset – List of frac_coords.

    - superset – List of frac_coords.

    - pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    list of indices such that superset[indices] = subset

is_coord_subset_pbc(subset, superset, atol, mask, pbc=(True, True, True))

  Tests if all fractional coords in subset are contained in superset. Allows specification of a mask determining pairs that are not allowed to match to each other.

  Parameters:

    - subset – List of fractional coords.

    - superset – List of fractional coords.

    - pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice.

  Returns:

    True if all of subset is in superset.

pbc_shortest_vectors(lattice, fcoords1, fcoords2, mask=None, return_d2=False, lll_frac_tol=None)

  Get the shortest vectors between two lists of coordinates taking into account periodic boundary conditions and the lattice.

  Parameters:

    - lattice – lattice to use

    - fcoords1 – First set of fractional coordinates. e.g., [0.5, 0.6, 0.7] or [[1.1, 1.2, 4.3], [0.5, 0.6, 0.7]]. Must be np.float64

    - fcoords2 – Second set of fractional coordinates.

    - mask (int_ array) – Mask of matches that are not allowed. i.e. if mask[1,2] == True, then subset[1] cannot be matched to superset[2]

    - lll_frac_tol (float_ array of length 3) – Fractional tolerance (per LLL lattice vector) over which the calculation of minimum vectors will be skipped. Can speed up calculation considerably for large structures.

  Returns:

    of displacement vectors from fcoords1 to fcoords2

      first index is fcoords1 index, second is fcoords2 index

  Return type:

    np.array

## pymatgen.util.due module

Stub file for a guaranteed safe import of duecredit constructs: if duecredit is not available.

Then use in your code as

> from .due import due, Doi, BibTeX, Text

See https://github.com/duecredit/duecredit/blob/master/README.md for examples.

Origin: Originally a part of the duecredit Copyright: 2015-2021 DueCredit developers License: BSD-2

BibTeX(*args, **kwargs)

  Perform no good and no bad.

Doi(*args, **kwargs)

  Perform no good and no bad.

class InactiveDueCreditCollector

  Bases: `object`

  Just a stub at the Collector which would not do anything.

  activate(*args, **kwargs)

    Perform no good and no bad.

  active = False
  add(*args, **kwargs)

    Perform no good and no bad.

  cite(*args, **kwargs)

    Perform no good and no bad.

  dcite(*args, **kwargs)

    If I could cite I would.

  dump(*args, **kwargs)

    Perform no good and no bad.

  load(*args, **kwargs)

    Perform no good and no bad.

Text(*args, **kwargs)

  Perform no good and no bad.

Url(*args, **kwargs)

  Perform no good and no bad.

## pymatgen.util.graph_hashing module

Copyright (C) 2004-2022, NetworkX Developers Aric Hagberg <hagberg@lanl.gov> Dan Schult <dschult@colgate.edu> Pieter Swart <swart@lanl.gov> All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

> - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

> - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

> - Neither the name of the NetworkX Developers nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Functions for hashing graphs to strings. Isomorphic graphs should be assigned identical hashes. For now, only Weisfeiler-Lehman hashing is implemented.

weisfeiler_lehman_graph_hash(graph: nx.Graph, edge_attr=None, node_attr=None, iterations=3, digest_size=16)

  Return Weisfeiler Lehman (WL) graph hash.

  The function iteratively aggregates and hashes neighborhoods of each node. After each node’s neighbors are hashed to obtain updated node labels, a hashed histogram of resulting labels is returned as the final hash.

  Hashes are identical for isomorphic graphs and strong guarantees that non-isomorphic graphs will get different hashes. See [1]_ for details.

  If no node or edge attributes are provided, the degree of each node is used as its initial label. Otherwise, node and/or edge labels are used to compute the hash.

  Parameters:

    - graph – nx.Graph The graph to be hashed. Can have node and/or edge attributes. Can also have no attributes.

    - edge_attr – string, default=None The key in edge attribute dictionary to be used for hashing. If None, edge labels are ignored.

    - node_attr – string, default=None The key in node attribute dictionary to be used for hashing. If None, and no edge_attr given, use the degrees of the nodes as labels.

    - iterations – int, default=3 Number of neighbor aggregations to perform. Should be larger for larger graphs.

    - digest_size – int, default=16 Size (in bits) of blake2b hash digest to use for hashing node labels.

  Returns:

    string

      Hexadecimal string corresponding to hash of the input graph.

  Return type:

    h

  Notes

  To return the WL hashes of each subgraph of a graph, use weisfeiler_lehman_subgraph_hashes

  Similarity between hashes does not imply similarity between graphs.

  References

  [1]

  Shervashidze, Nino, Pascal Schweitzer, Erik Jan Van Leeuwen,

  Kurt Mehlhorn, and Karsten M. Borgwardt. Weisfeiler Lehman Graph Kernels. Journal of Machine Learning Research. 2011. https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf

  See also

  weisfeiler_lehman_subgraph_hashes

weisfeiler_lehman_subgraph_hashes(graph, edge_attr=None, node_attr=None, iterations=3, digest_size=16)

  Return a dictionary of subgraph hashes by node.

  The dictionary is keyed by node to a list of hashes in increasingly sized induced subgraphs containing the nodes within 2*k edges of the key node for increasing integer k until all nodes are included.

  The function iteratively aggregates and hashes neighborhoods of each node. This is achieved for each step by replacing for each node its label from the previous iteration with its hashed 1-hop neighborhood aggregate. The new node label is then appended to a list of node labels for each node.

  To aggregate neighborhoods at each step for a node $n$, all labels of nodes adjacent to $n$ are concatenated. If the edge_attr parameter is set, labels for each neighboring node are prefixed with the value of this attribute along the connecting edge from this neighbor to node $n$. The resulting string is then hashed to compress this information into a fixed digest size.

  Thus, at the $i$th iteration nodes within $2i$ distance influence any given hashed node label. We can therefore say that at depth $i$ for node $n$ we have a hash for a subgraph induced by the $2i$-hop neighborhood of $n$.

  Can be used to to create general Weisfeiler-Lehman graph kernels, or generate features for graphs or nodes, for example to generate ‘words’ in a graph as seen in the ‘graph2vec’ algorithm. See [1]_ & [2]_ respectively for details.

  Hashes are identical for isomorphic subgraphs and there exist strong guarantees that non-isomorphic graphs will get different hashes. See [1]_ for details.

  If no node or edge attributes are provided, the degree of each node is used as its initial label. Otherwise, node and/or edge labels are used to compute the hash.

  Parameters:

    - graph – nx.Graph The graph to be hashed. Can have node and/or edge attributes. Can also have no attributes.

    - edge_attr – string, default=None The key in edge attribute dictionary to be used for hashing. If None, edge labels are ignored.

    - node_attr – string, default=None The key in node attribute dictionary to be used for hashing. If None, and no edge_attr given, use the degrees of the nodes as labels.

    - iterations – int, default=3 Number of neighbor aggregations to perform. Should be larger for larger graphs.

    - digest_size – int, default=16 Size (in bits) of blake2b hash digest to use for hashing node labels. The default size is 16 bits

  Returns:

    dict

      A dictionary with each key given by a node in G, and each value given by the subgraph hashes in order of depth from the key node.

  Return type:

    node_subgraph_hashes

  Notes

  To hash the full graph when subgraph hashes are not needed, use weisfeiler_lehman_graph_hash for efficiency.

  Similarity between hashes does not imply similarity between graphs.

  References

  [1]

  Shervashidze, Nino, Pascal Schweitzer, Erik Jan Van Leeuwen,

  Kurt Mehlhorn, and Karsten M. Borgwardt. Weisfeiler Lehman Graph Kernels. Journal of Machine Learning Research. 2011. https://www.jmlr.org/papers/volume12/shervashidze11a/shervashidze11a.pdf .. [2] Annamalai Narayanan, Mahinthan Chandramohan, Rajasekar Venkatesan, Lihui Chen, Yang Liu and Shantanu Jaiswa. graph2vec: Learning Distributed Representations of Graphs. arXiv. 2017 https://arxiv.org/pdf/1707.05005.pdf

  See also

  weisfeiler_lehman_graph_hash

## pymatgen.util.io_utils module

This module provides utility classes for io operations.

clean_lines(string_list: list[str], remove_empty_lines: bool = True, rstrip_only: bool = False) → Iterator[str]

  Remove leading and trailing whitespaces from a list of strings.

  Parameters:

    - string_list (list[str]) – List of strings.

    - remove_empty_lines (bool) – Set to True to skip lines which are empty after stripping.

    - rstrip_only (bool) – Set to True to strip trailing whitespaces only (i.e., to retain leading whitespaces). Defaults to False.

  Yields:

    str – clean string with no leading and trailing whitespaces.

micro_pyawk(filename: str | Path, search: list[tuple[re.Pattern | str, Callable, Callable]], results: Any | None = None, debug: Callable | None = None, postdebug: Callable | None = None) → Any

  Small awk-mimicking search routine.

  This function goes through each line in the file, and if regex matches that line AND test(results, line) is True (OR test is None) we execute run(results, match), where match is the Match object from running Pattern.match.

  Parameters:

    - filename (PathLike) – The file to search through.

    - search (list[tuple[Pattern | str, Callable, Callable]]) – The “search program” of 3 elements, i.e. [(regex, test, run), …]. Here regex is either a Pattern object, or a string that we compile into a Pattern.

    - results – An object to store results. Default as an empty dictionary. Passing a results object let you interact with it via run and test. Hence, in many occasions it is clever to use the instance itself as results.

    - debug (Callable) – Debug run.

    - postdebug (Callable) – Post debug run after debug run.

  Returns:

    The updated results object.

  Return type:

    Any

  Author: Rickard Armiento, Ioannis Petousis

## pymatgen.util.joblib module

This module provides utility functions for getting progress bar with joblib.

set_python_warnings(warnings)

  Context manager to set the PYTHONWARNINGS environment variable to the given value. This is useful for preventing spam when using parallel processing.

tqdm_joblib(tqdm_object: tqdm) → Iterator[None]

  Context manager to patch joblib to report into tqdm progress bar given as argument.

## pymatgen.util.misc module

Other util functions.

is_np_dict_equal(dict1, dict2, /) → bool

  Compare two dict whose value could be NumPy arrays.

  Parameters:

    - dict1 (dict) – The first dict.

    - dict2 (dict) – The second dict.

  Returns:

    Whether these two dicts are equal.

  Return type:

    bool

## pymatgen.util.num module

This module provides utilities for basic math operations.

make_symmetric_matrix_from_upper_tri(val: ArrayLike) → NDArray
  Construct a 3x3 symmetric matrix from its upper triangular

    elements in flat array form: [A_xx, A_yy, A_zz, A_xy, A_xz, A_yz].

  To the full symmetric matrix:
    [[A_xx, A_xy, A_xz],

      [A_xy, A_yy, A_yz], [A_xz, A_yz, A_zz]]

  Parameters:

    val (ArrayLike) – Flattened upper triangular elements.

  Returns:

    The symmetric matrix.

  Return type:

    NDArray

round_to_sigfigs(num: float, sig_figs: int) → float

  Rounds a number to a specific number of significant figures instead of to a specific precision.

  Returns:

    rounded number.

  Return type:

    float

## pymatgen.util.numba module

This module provides a wrapper for numba such that no functionality is lost if numba is not available. Numba is a just-in-time compiler that can significantly accelerate the evaluation of certain functions if installed.

jit(func)

  Replacement for numba.jit when numba is not installed that does nothing.

njit(func)

  Replacement for numba.njit when numba is not installed that does nothing.

## pymatgen.util.plotting module

Utilities for generating nicer plots.

add_fig_kwargs(func)

  Decorator that adds keyword arguments for functions returning matplotlib figures.

  The function should return either a matplotlib figure or None to signal some sort of error/unexpected event. See doc string below for the list of supported options.

format_formula(formula: str) → str

  Convert str of chemical formula into latex format for labelling purposes.

  Parameters:

    formula (str) – Chemical formula

get_ax3d_fig(ax: Axes = None, **kwargs) → tuple[Axes3D, Figure]

  Helper function used in plot functions supporting an optional Axes3D argument. If ax is None, we build the matplotlib figure and create the Axes3D else we return the current active figure.

  Parameters:

    - ax (Axes3D, optional) – Axes3D object. Defaults to None.

    - kwargs – keyword arguments are passed to plt.figure if ax is not None.

  Returns:

    matplotlib Axes3D and corresponding figure objects

  Return type:

    tuple[Axes3D, Figure]

get_ax_fig(ax: Axes = None, **kwargs) → tuple[Axes, Figure]

  Helper function used in plot functions supporting an optional Axes argument. If ax is None, we build the matplotlib figure and create the Axes else we return the current active figure.

  Parameters:

    - ax (Axes, optional) – Axes object. Defaults to None.

    - kwargs – keyword arguments are passed to plt.figure if ax is not None.

  Returns:

    matplotlib Axes object and Figure objects

  Return type:

    tuple[Axes, Figure]

get_axarray_fig_plt(ax_array, nrows=1, ncols=1, sharex: bool = False, sharey: bool = False, squeeze: bool = True, subplot_kw=None, gridspec_kw=None, **fig_kw)

  Helper function used in plot functions that accept an optional array of Axes as argument. If ax_array is None, we build the matplotlib figure and create the array of Axes by calling plt.subplots else we return the current active figure.

  Returns:

    Array of Axes objects figure: matplotlib figure plt: matplotlib pyplot module.

  Return type:

    ax

periodic_table_heatmap(elemental_data=None, cbar_label='', cbar_label_size=14, show_plot: bool = False, cmap='YlOrRd', cmap_range=None, blank_color='grey', edge_color='white', value_format=None, value_fontsize=10, symbol_fontsize=14, max_row: int = 9, readable_fontcolor=False, pymatviz: bool = True, **kwargs)

  A static method that generates a heat map overlaid on a periodic table.

  Parameters:

    - elemental_data (dict) – A dictionary with the element as a key and a value assigned to it, e.g. surface energy and frequency, etc. Elements missing in the elemental_data will be grey by default in the final table elemental_data={“Fe”: 4.2, “O”: 5.0}.

    - cbar_label (str) – Label of the color bar. Default is “”.

    - cbar_label_size (float) – Font size for the color bar label. Default is 14.

    - cmap_range (tuple) – Minimum and maximum value of the color map scale. If None, the color map will automatically scale to the range of the data.

    - show_plot (bool) – Whether to show the heatmap. Default is False.

    - value_format (str) – Formatting string to show values. If None, no value is shown. Example: “%.4f” shows float to four decimals.

    - value_fontsize (float) – Font size for values. Default is 10.

    - symbol_fontsize (float) – Font size for element symbols. Default is 14.

    - cmap (str) – Color scheme of the heatmap. Default is ‘YlOrRd’. Refer to the matplotlib documentation for other options.

    - blank_color (str) – Color assigned for the missing elements in elemental_data. Default is “grey”.

    - edge_color (str) – Color assigned for the edge of elements in the periodic table. Default is “white”.

    - max_row (int) – Maximum number of rows of the periodic table to be shown. Default is 9, which means the periodic table heat map covers the standard 7 rows of the periodic table + 2 rows for the lanthanides and actinides. Use a value of max_row = 7 to exclude the lanthanides and actinides.

    - readable_fontcolor (bool) – Whether to use readable font color depending on background color. Default is False.

    - pymatviz (bool) – Whether to use pymatviz to generate the heatmap. Defaults to True. See https://github.com/janosh/pymatviz.

    - kwargs – Passed to pymatviz.ptable_heatmap_plotly

  Returns:

    matplotlib Axes object

  Return type:

    plt.Axes

pretty_plot(width: float = 8, height: float | None = None, ax: Axes = None, dpi: float | None = None, color_cycle: tuple[str, str] = ('qualitative', 'Set1_9')) → Axes

  Get a publication quality plot, with nice defaults for font sizes etc.

  Parameters:

    - width (float) – Width of plot in inches. Defaults to 8in.

    - height (float) – Height of plot in inches. Defaults to width * golden ratio.

    - ax (Axes) – If ax is supplied, changes will be made to an existing plot. Otherwise, a new plot will be created.

    - dpi (float) – Sets dot per inch for figure. Defaults to 300.

    - color_cycle (tuple) – Set the color cycle for new plots to one of the color sets in palettable. Defaults to a qualitative Set1_9.

  Returns:

    matplotlib axes object with properly sized fonts.

  Return type:

    Axes

pretty_plot_two_axis(x, y1, y2, xlabel=None, y1label=None, y2label=None, width: float = 8, height: float | None = None, dpi=300, **plot_kwargs)

  Variant of pretty_plot that does a dual axis plot. Adapted from matplotlib examples. Makes it easier to create plots with different axes.

  Parameters:

    - x (Sequence[float]) – Data for x-axis.

    - y1 (Sequence[float] | dict[str, Sequence[float]]) – Data for y1 axis (left). If a dict, it will be interpreted as a {label: sequence}.

    - y2 (Sequence[float] | dict[str, Sequence[float]]) – Data for y2 axis (right). If a dict, it will be interpreted as a {label: sequence}.

    - xlabel (str) – If not None, this will be the label for the x-axis.

    - y1label (str) – If not None, this will be the label for the y1-axis.

    - y2label (str) – If not None, this will be the label for the y2-axis.

    - width (float) – Width of plot in inches. Defaults to 8in.

    - height (float) – Height of plot in inches. Defaults to width * golden ratio.

    - dpi (int) – Sets dot per inch for figure. Defaults to 300.

    - plot_kwargs – Passthrough kwargs to matplotlib’s plot method. e.g. linewidth, etc.

  Returns:

    matplotlib axes object with properly sized fonts.

  Return type:

    plt.Axes

pretty_polyfit_plot(x: NDArray, y: NDArray, deg: int = 1, xlabel=None, ylabel=None, **kwargs)

  Convenience method to plot data with trend lines based on polynomial fit.

  Parameters:

    - x – Sequence of x data.

    - y – Sequence of y data.

    - deg (int) – Degree of polynomial. Defaults to 1.

    - xlabel (str) – Label for x-axis.

    - ylabel (str) – Label for y-axis.

    - kwargs – Keyword args passed to pretty_plot.

  Returns:

    plt.Axes

van_arkel_triangle(list_of_materials: Sequence, annotate: bool = True)

  A static method that generates a binary van Arkel-Ketelaar triangle to quantify the ionic, metallic and covalent character of a compound by plotting the electronegativity difference (y) vs average (x). See:

  > A.E. van Arkel, Molecules and Crystals in Inorganic Chemistry,

  >   Interscience, New York (1956)

  and
    J.A.A Ketelaar, Chemical Constitution (2nd edition), An Introduction

      to the Theory of the Chemical Bond, Elsevier, New York (1958).

  Parameters:

    - list_of_materials (list) – A list of computed entries of binary materials or a list of lists containing two elements (str).

    - annotate (bool) – Whether or not to label the points on the triangle with reduced formula (if list of entries) or pair of elements (if list of list of str).

  Returns:

    matplotlib Axes object

  Return type:

    plt.Axes

## pymatgen.util.provenance module

Classes and methods related to the Structure Notation Language (SNL).

class Author(name: str, email: str)

  Bases: `NamedTuple`

  An Author contains two fields: name and email. It is meant to represent the author of a Structure or the author of a code that was applied to a Structure.

  Create new instance of Author(name, email)

  as_dict() → dict[str, str]

    Get MSONable dict.

  email: str

    Alias for field number 1

  classmethod from_dict(dct: dict[str, str]) → Self
    Parameters:

      dct (dict) – Dict representation.

    Returns:

      Author

  name: str

    Alias for field number 0

  classmethod parse_author(author: str | dict[str, str] | tuple[str, str]) → Self

    Parse an Author object from either a String, dict, or tuple.

    Parameters:

      author – in one of the three accepted formats: - A string formatted as “NAME <email@domain.com>”. - A (name, email) tuple. - A dict with name and email as keys.

    Returns:

      An Author object.

class HistoryNode(name: str, url: str, description: str)

  Bases: `NamedTuple`

  A HistoryNode represents a step in the chain of events that lead to a Structure. HistoryNodes leave ‘breadcrumbs’ so that you can trace back how a Structure was created. For example, a HistoryNode might represent pulling a Structure from an external database such as the ICSD or CSD. Or, it might represent the application of a code (e.g. pymatgen) to the Structure, with a custom description of how that code was applied (e.g. a site removal Transformation was applied).

  name

    The name of a code or resource that this Structure encountered in its history.

    Type:

      str

  url

    The URL of that code/resource.

    Type:

      str

  description

    A free-form description of how the code/resource is related to the Structure.

    Type:

      str

  Create new instance of HistoryNode(name, url, description)

  as_dict() → dict[str, str]

    Get MSONable dict.

  description: str

    Alias for field number 2

  classmethod from_dict(dct: dict[str, str]) → Self
    Parameters:

      dct (dict) – Dict representation.

    Returns:

      HistoryNode

  name: str

    Alias for field number 0

  classmethod parse_history_node(h_node) → Self

    Parse a History Node object from either a dict or a tuple.

    Parameters:

      h_node – A dict with name/url/description fields or a 3-element tuple.

    Returns:

      HistoryNode

  url: str

    Alias for field number 1

class StructureNL(struct_or_mol: Structure | Molecule, authors: str | list[dict] | list[str], projects: list[str] | str | None = None, references: str = '', remarks: list[str] | str | None = None, data: dict | None = None, history: list[dict] | None = None, created_at: datetime | None = None)

  Bases: `object`

  The Structure Notation Language (SNL, pronounced “snail”) is a container for a pymatgen Structure/Molecule object with some additional fields for enhanced provenance.

  It is meant to be imported/exported in a JSON file format with the following structure:

    - sites

    - lattice (optional)

    - about

        - created_at

        - authors

        - projects

        - references

        - remarks

        - data

        - history

  Parameters:

    - struct_or_mol – A pymatgen Structure/Molecule object

    - authors (list | str) –

      - List of {“name”:””, “email”:””} dicts.

      - List of strings as “John Doe <johndoe@gmail.com>”.

      - A single String with commas separating authors.

    - projects (list[str] | str) – e.g. [“Project A”, “Project B”]

    - references (str) – A string in BibTeX format

    - remarks (list[str]) – e.g. [“Remark A”, “Remark B”]

    - data (dict) – A free form dict. Namespaced at the root level with an underscore, e.g. {“_materialsproject”: <custom data>}

    - history (list[dict]) – e.g. [{“name”:””, “url”:””, “description”:{}}]

    - created_at (datetime) – Creation date.

  as_dict() → dict[str, Any]

    Get MSONable dict.

  classmethod from_dict(dct: dict[str, Any]) → Self
    Parameters:

      dct (dict) – Dict representation.

    Returns:

      Class

  classmethod from_structures(structures: Sequence[Structure], authors, projects: list[str] | None = None, references: str = '', remarks: list[str] | None = None, data: list[dict] | None = None, histories: list[list[dict]] | None = None, created_at: datetime | None = None) → list[Self]

    A convenience method for getting a list of StructureNL objects by specifying structures and metadata separately. Some of the metadata is applied to all of the structures for ease of use.

    Parameters:

      - structures (Sequence[Structure]) – Structure objects

      - authors – List of {“name”:’’, “email”:’’} dicts, list of Strings as ‘John Doe <johndoe@gmail.com>’, or a single String with commas separating authors

      - projects (list[str]) – e.g. [“Project A”, “Project B”]. This applies to all structures.

      - references (str) – A String in BibTeX format. This applies to all structures.

      - remarks (list[str]) – e.g. [“Remark A”, “Remark B”].

      - data (list[dict]) – Free form dicts. Namespaced at the root level with an underscore, e.g. {“_materialsproject”:<custom data>} . The length of data should be the same as the list of structures if not None.

      - histories (list[list[dict]]) – e.g. [[{“name”:””, “url”:””, “description”:{}}], …] The length of histories should be the same as the list of structures if not None.

      - created_at (datetime) – Creation date.

is_valid_bibtex(reference: str) → bool

  Validate that a reference is in proper BibTeX format.

  Parameters:

    reference (str) – Reference in BibTeX format.

  Returns:

    True if reference is valid BibTeX.

  Return type:

    bool

## pymatgen.util.string module

This module provides utility classes for string operations.

TODO: make standalone functions in this module use the same implementation as Stringify Note: previous deprecations of standalone functions in this module were removed due to a community need.

class Stringify

  Bases: `object`

  Mix-in class for string formatting, e.g. superscripting numbers and symbols or superscripting.

  STRING_MODE = 'SUBSCRIPT'
  to_html_string() → str

    Generate a HTML formatted string. This uses the output from to_latex_string to generate a HTML output.

    Returns:

      HTML formatted string.

  to_latex_string() → str

    Generate a LaTeX formatted string. The mode is set by the class variable STRING_MODE, which defaults to “SUBSCRIPT”. e.g. Fe2O3 is transformed to Fe$_{2}$O$_{3}$. Setting STRING_MODE to “SUPERSCRIPT” creates superscript, e.g. Fe2+ becomes Fe^{2+}. The initial string is obtained from the class’s __str__ method.

    Returns:

      for LaTeX display with proper sub-/superscripts.

    Return type:

      str

  to_pretty_string() → str

    A pretty string representation. By default, the __str__ output is used, but this method can be overridden if a different representation from default is desired.

  to_unicode_string() → str

    Unicode string with proper sub and superscripts. Note that this works only with systems where the sub and superscripts are pure integers.

charge_string(charge: float, brackets: bool = True, explicit_one: bool = True) → str

  Get a string representing the charge of an Ion. By default, the charge is placed in brackets with the sign preceding the magnitude, e.g. ‘[+2]’. For uncharged species, the string returned is ‘(aq)’.

  Parameters:

    - charge (float) – The charge of the ion.

    - brackets (bool) – Whether to enclose the charge in brackets, e.g. [+2]. Default is True.

    - explicit_one (bool) – whether to include the number one for monovalent ions, e.g. “+1” rather than “+”. Default is True.

disordered_formula(disordered_struct: Structure, symbols: Sequence[str] = ('x', 'y', 'z'), fmt: Literal['plain', 'HTML', 'LaTex'] = 'plain') → str

  Get a formula of a form like AxB1-x (x=0.5) for disordered structures. Will only return a formula for disordered structures with one kind of disordered site at present.

  Parameters:

    - disordered_struct (Structure) – a disordered structure.

    - symbols (Sequence[str]) – Characters to use for subscripts, by default this is (‘x’, ‘y’, ‘z’) but if you have more than three disordered species more symbols will need to be added.

    - fmt (str) – ‘plain’, ‘HTML’ or ‘LaTeX’,

  Returns:

    a disordered formula string

  Return type:

    str

formula_double_format(afloat: float, ignore_ones: bool = True, tol: float = 1e-08) → float | Literal['']

  Format a float for pretty formulas. E.g. “Li1.0 Fe1.0 P1.0 O4.0” -> “LiFePO4”.

  Parameters:

    - afloat (float) – The float to be formatted.

    - ignore_ones (bool) – if true, floats of 1.0 are ignored.

    - tol (float) – Absolute tolerance to round to nearest int. i.e. (2 + 1E-9) -> 2.

  Returns:

    Formatted float for formulas.

  Return type:

    float | “”

htmlify(formula: str) → str

  Generate a HTML formatted formula, e.g. Fe2O3 is transformed to Fe<sub>2</sub>O</sub>3</sub>.

  Note that Composition now has a to_html_string() method that may be used instead.

  Parameters:

    formula (str) – The string to format.

latexify(formula: str, bold: bool = False) → str

  Generate a LaTeX formatted formula. e.g. Fe2O3 is transformed to Fe$_{2}$O$_{3}$.

  Note that Composition now has to_latex_string method that may be used instead.

  Parameters:

    - formula (str) – Input formula.

    - bold (bool) – Whether to make the subscripts bold. Defaults to False.

  Returns:

    Formula suitable for display as in LaTeX with proper subscripts.

  Return type:

    str

latexify_spacegroup(spacegroup_symbol: str) → str

  Generate a latex formatted spacegroup. e.g. P2_1/c is converted to P2$_{1}$/c and P-1 is converted to P$\overline{1}$.

  Note that SymmetryGroup now has a to_latex_string() method that may be called instead.

  Parameters:

    spacegroup_symbol (str) – A spacegroup symbol

  Returns:

    A latex formatted spacegroup with proper subscripts and overlines.

  Return type:

    str

str_delimited(results: Sequence[Sequence[Any]], header: Sequence[str] | None = None, delimiter: str = '\t') → str

  Given a tuple of tuples, generate a delimited string form. >>> results = ((“a”, “b”, “c”), (“d”, “e”, “f”), (1, 2, 3)) >>> str_delimited(results, delimiter=”,”) a,b,c d,e,f 1,2,3.

  Parameters:

    - results (Sequence[Sequence[Any]]) – 2D sequence of arbitrary types.

    - header (Sequence[str]) – optional headers.

    - delimiter (str) – Defaults to “t” for tab-delimited output.

  Returns:

    Aligned string output in a table-like format.

  Return type:

    str

stream_has_colors(stream: TextIO) → bool

  True if stream supports colors. Python cookbook, #475186.

transformation_to_string(matrix: ArrayLike, translation_vec: ArrayLike = (0, 0, 0), components: tuple[str, str, str] = ('x', 'y', 'z'), c: str = '', delim: str = ',') → str

  Convenience method. Given matrix returns string, e.g. x+2y+1/4.

  Parameters:

    - matrix (ArrayLike) – A 3x3 matrix.

    - translation_vec (tuple[float, float, float]) – The translation vector. Defaults to (0, 0, 0).

    - components (tuple[str, str, str]) – The components. Either (‘x’, ‘y’, ‘z’) or (‘a’, ‘b’, ‘c’). Defaults to (‘x’, ‘y’, ‘z’).

    - c (str) – An optional additional character to print (used for magmoms). Defaults to “”.

    - delim (str) – A delimiter. Defaults to “,”.

  Returns:

    xyz string.

  Return type:

    str

unicodeify(formula: str) → str

  Generate a formula with unicode subscripts, e.g. Fe2O3 is transformed to Fe₂O₃. Does not support formulae with decimal points.

  Note that Composition now has a to_unicode_string() method that may be used instead.

  Parameters:

    formula (str) – The string to format.

unicodeify_spacegroup(spacegroup_symbol: str) → str

  Generate a unicode formatted spacegroup. e.g. P2$_{1}$/c is converted to P2₁/c and P$\overline{1}$ is converted to P̅1.

  Note that SymmetryGroup now has a to_unicode_string() method that may be called instead.

  Parameters:

    spacegroup_symbol (str) – A spacegroup symbol as LaTeX.

  Returns:

    A unicode spacegroup with proper subscripts and overlines.

  Return type:

    str

unicodeify_species(specie_string: str) → str

  Generate a unicode formatted species string, with appropriate superscripts for oxidation states.

  Note that Species now has to_unicode_string method that may be used instead.

  Parameters:

    specie_string (str) – Species string, e.g. “O2-”

  Returns:

    Species string, e.g. “O²⁻”

  Return type:

    str

## pymatgen.util.testing module

This module implements testing utilities for materials science codes.

While the primary use is within pymatgen, the functionality is meant to be useful for external materials science codes as well. For instance, obtaining example crystal structures to perform tests, specialized assert methods for materials science, etc.

class MatSciTest

  Bases: `object`

  pytest based test framework extended to facilitate testing with the following methods: - tmp_path (attribute): Temporary directory. - get_structure: Load a Structure from util.structures with its name. - assert_str_content_equal: Check if two strings are equal (ignore whitespaces). - serialize_with_pickle: Test whether object(s) can be (de)serialized with pickle. - assert_msonable: Test if obj is MSONable and return its serialized string.

  TEST_STRUCTURES: ClassVar[dict[PathLike, Structure | None]] = {PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/BaNiO3.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/CsCl.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Graphite.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/He_BCC.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/K2O2.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/La2CoO4F.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li10GeP2S12.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li2O.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li2O2.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Li3V2(PO4)3.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/LiFePO4.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/NaFePO4.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Pb2TiZrO6.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Si.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/SiO2.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Si_SiO2_Interface.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/Sn.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/SrTiO3.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/TiO2.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/TlBiSe2.json'): None, PosixPath('/Users/shyue/repos/pymatgen/src/pymatgen/util/structures/VO2.json'): None}
  static assert_msonable(obj: Any, test_is_subclass: bool = True) → str

    Test if an object is MSONable and verify the contract is fulfilled, and return the serialized object.

    By default, the method tests whether obj is an instance of MSONable. This check can be deactivated by setting test_is_subclass to False.

    Parameters:

      - obj (Any) – The object to be checked.

      - test_is_subclass (bool) – Check if object is an instance of MSONable or its subclasses.

    Returns:

      Serialized object.

    Return type:

      str

  static assert_str_content_equal(actual: str, expected: str) → None

    Test if two strings are equal, ignoring whitespaces.

    Parameters:

      - actual (str) – The string to be checked.

      - expected (str) – The reference string.

    Raises:

      AssertionError – When two strings are not equal.

  classmethod get_structure(name: str) → Structure

    Load a structure from pymatgen.util.structures.

    Parameters:

      name (str) – Name of the structure file, for example “LiFePO4”.

    Returns:

      Structure

  serialize_with_pickle(objects: Any, protocols: Sequence[int] | None = None, test_eq: bool = True) → list

    Test whether the object(s) can be serialized and deserialized with pickle. This method tries to serialize the objects with pickle and the protocols specified in input. Then it deserializes the pickled format and compares the two objects with the == operator if test_eq.

    Parameters:

      - objects (Any) – Object or list of objects.

      - protocols (Sequence[int]) – List of pickle protocols to test. If protocols is None, HIGHEST_PROTOCOL is tested.

      - test_eq (bool) – If True, the deserialized object is compared with the original object using the __eq__ method.

    Returns:

      Objects deserialized with the specified protocols.

    Return type:

      list[Any]

class PymatgenTest(methodName='runTest')

  Bases: `TestCase`, `MatSciTest`

  Extends unittest.TestCase with several assert methods for array and str comparison.

  Deprecated: please use MatSciTest instead (migrate from unittest to pytest).

  Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.

## pymatgen.util.typing module

This module defines convenience types for type hinting purposes. Type hinting is new to pymatgen, so this module is subject to change until best practices are established.