pymatgen.core package

This package contains core modules and classes for representing structures and operations on them.

Submodules

pymatgen.core.bonds module

This class implements definitions for various kinds of bonds. Typically used in Molecule analysis.

class CovalentBond(site1: Site, site2: Site)[source]

Bases: object

Defines a covalent bond between two sites.

Initializes a covalent bond between two sites.

Parameters:
  • site1 (Site) – First site.

  • site2 (Site) – Second site.

get_bond_order(tol: float = 0.2, default_bl: float | None = None) float[source]

The bond order according the distance between the two sites.

Parameters:
  • tol (float) – Relative tolerance to test. (1 + tol) * the longest bond distance is considered to be the threshold length for a bond to exist. (1 - tol) * the shortest bond distance is considered to be the shortest possible bond length Defaults to 0.2.

  • default_bl – If a particular type of bond does not exist, use this bond length as a default value (bond order = 1). If None, a ValueError will be thrown.

Returns:

Float value of bond order. For example, for C-C bond in benzene, return 1.7.

static is_bonded(site1, site2, tol: float = 0.2, bond_order: float | None = None, default_bl: float | None = None)[source]

Test if two sites are bonded, up to a certain limit.

Parameters:
  • site1 (Site) – First site

  • site2 (Site) – Second site

  • tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is less than (1 + tol) * typical bond distances. Defaults to 0.2, i.e., 20% longer.

  • bond_order – Bond order to test. If None, the code simply checks against all possible bond data. Defaults to None.

  • default_bl – If a particular type of bond does not exist, use this bond length. If None, a ValueError will be thrown.

Returns:

Boolean indicating whether two sites are bonded.

property length: float[source]

Length of the bond.

get_bond_length(sp1: SpeciesLike, sp2: SpeciesLike, bond_order: float = 1) float[source]

Get the bond length between two species.

Parameters:
  • sp1 (Species) – First specie.

  • sp2 (Species) – Second specie.

  • bond_order – For species with different possible bond orders, this allows one to obtain the bond length for a particular bond order. For example, to get the C=C bond length instead of the C-C bond length, this should be set to 2. Defaults to 1.

Returns:

Bond length in Angstrom. If no data is available, the sum of the atomic radius is used.

get_bond_order(sp1, sp2, dist: float, tol: float = 0.2, default_bl: float | None = None)[source]

Calculate the bond order given the distance of 2 species.

Parameters:
  • sp1 (Species) – First specie.

  • sp2 (Species) – Second specie.

  • dist – Their distance in angstrom

  • tol (float) – Relative tolerance to test. Basically, the code checks if the distance between the sites is larger than (1 + tol) * the longest bond distance or smaller than (1 - tol) * the shortest bond distance to determine if they are bonded or the distance is too short. Defaults to 0.2.

  • default_bl – If a particular type of bond does not exist, use this bond length (bond order = 1). If None, a ValueError will be thrown.

Returns:

Float value of bond order. For example, for C-C bond in benzene, return 1.7.

obtain_all_bond_lengths(sp1, sp2, default_bl: float | None = None)[source]

Obtain bond lengths for all bond orders from bond length database.

Parameters:
  • sp1 (Species) – First specie.

  • sp2 (Species) – Second specie.

  • default_bl – If a particular type of bond does not exist, use this bond length as a default value (bond order = 1). If None, a ValueError will be thrown.

Returns:

A dict mapping bond order to bond length in angstrom

pymatgen.core.composition module

This module implements a Composition class to represent compositions, and a ChemicalPotential class to represent potentials.

class ChemicalPotential(*args, **kwargs)[source]

Bases: dict, MSONable

Class to represent set of chemical potentials. Can be: multiplied/divided by a Number multiplied by a Composition (returns an energy) added/subtracted with other ChemicalPotentials.

Parameters:
  • *args – any valid dict init arguments

  • **kwargs – any valid dict init arguments.

get_energy(composition: Composition, strict: bool = True) float[source]

Calculates the energy of a composition.

Parameters:
  • composition (Composition) – input composition

  • strict (bool) – Whether all potentials must be specified

class Composition(*args, strict: bool = False, **kwargs)[source]

Bases: Hashable, Mapping, MSONable, Stringify

Represents a Composition, which is essentially a {element:amount} mapping type. Composition is written to be immutable and hashable, unlike a standard Python dict.

Note that the key can be either an Element or a Species. Elements and Species are treated differently. i.e., a Fe2+ is not the same as a Fe3+ Species and would be put in separate keys. This differentiation is deliberate to support using Composition to determine the fraction of a particular Species.

Works almost completely like a standard python dictionary, except that __getitem__ is overridden to return 0 when an element is not found. (somewhat like a defaultdict, except it is immutable).

Also adds more convenience methods relevant to compositions, e.g., get_fraction.

It should also be noted that many Composition related functionality takes in a standard string as a convenient input. For example, even though the internal representation of a Fe2O3 composition is {Element(“Fe”): 2, Element(“O”): 3}, you can obtain the amount of Fe simply by comp[“Fe”] instead of the more verbose comp[Element(“Fe”)].

>>> comp = Composition("LiFePO4")
>>> comp.get_atomic_fraction(Element("Li"))
0.14285714285714285
>>> comp.num_atoms
7.0
>>> comp.reduced_formula
'LiFePO4'
>>> comp.formula
'Li1 Fe1 P1 O4'
>>> comp.get_wt_fraction(Element("Li"))
0.04399794666951898
>>> comp.num_atoms
7.0

Very flexible Composition construction, similar to the built-in Python dict(). Also extended to allow simple string init.

Takes any inputs supported by the Python built-in dict function.

  1. A dict of either {Element/Species: amount},

    {string symbol:amount}, or {atomic number:amount} or any mixture of these. E.g., {Element(“Li”): 2, Element(“O”): 1}, {“Li”:2, “O”:1}, {3: 2, 8: 1} all result in a Li2O composition.

  2. Keyword arg initialization, similar to a dict, e.g.,

    Composition(Li = 2, O = 1)

In addition, the Composition constructor also allows a single string as an input formula. E.g., Composition(“Li2O”).

Parameters:
  • *args – Any number of 2-tuples as key-value pairs.

  • strict (bool) – Only allow valid Elements and Species in the Composition. Defaults to False.

  • allow_negative (bool) – Whether to allow negative compositions. Defaults to False.

  • **kwargs – Additional kwargs supported by the dict() constructor.

add_charges_from_oxi_state_guesses(oxi_states_override: dict | None = None, target_charge: float = 0, all_oxi_states: bool = False, max_sites: int | None = None) Composition[source]

Assign oxidation states based on guessed oxidation states.

See oxi_state_guesses for an explanation of how oxidation states are guessed. This operation uses the set of oxidation states for each site that were determined to be most likely from the oxidation state guessing routine.

Parameters:
  • oxi_states_override (dict) – dict of str->list to override an element’s common oxidation states, e.g. {“V”: [2,3,4,5]}

  • target_charge (int) – the desired total charge on the structure. Default is 0 signifying charge balance.

  • all_oxi_states (bool) – if True, an element defaults to all oxidation states in pymatgen Element.icsd_oxidation_states. Otherwise, default is Element.common_oxidation_states. Note that the full oxidation state list is very inclusive and can produce nonsensical results.

  • max_sites (int) – if possible, will reduce Compositions to at most this many sites to speed up oxidation state guesses. If the composition cannot be reduced to this many sites a ValueError will be raised. Set to -1 to just reduce fully. If set to a number less than -1, the formula will be fully reduced but a ValueError will be thrown if the number of atoms in the reduced formula is greater than abs(max_sites).

Returns:

Composition, where the elements are assigned oxidation states based on the results form guessing oxidation states. If no oxidation state is possible, returns a Composition where all oxidation states are 0.

almost_equals(other: Composition, rtol: float = 0.1, atol: float = 1e-08) bool[source]

Returns true if compositions are equal within a tolerance.

Parameters:
  • other (Composition) – Other composition to check

  • rtol (float) – Relative tolerance

  • atol (float) – Absolute tolerance

property alphabetical_formula: str[source]

Returns a formula string, with elements sorted by alphabetically e.g., Fe4 Li4 O16 P4.

amount_tolerance = 1e-08[source]
property anonymized_formula: str[source]

An anonymized formula. Unique species are arranged in ordering of increasing amounts and assigned ascending alphabets. Useful for prototyping formulas. For example, all stoichiometric perovskites have anonymized_formula ABC3.

as_dict() dict[str, float][source]

Subtly different from get_el_amt_dict in that they keys here are str(Element) instead of Element.symbol.

Returns:

element symbol and (unreduced) amount. E.g.

{“Fe”: 4.0, “O”:6.0} or {“Fe3+”: 4.0, “O2-“:6.0}

Return type:

dict[str, float]

property average_electroneg: float[source]

Average electronegativity of the composition.

property chemical_system: str[source]

Get the chemical system of a Composition, for example “O-Si” for SiO2. Chemical system is a string of a list of elements sorted alphabetically and joined by dashes, by convention for use in database keys.

contains_element_type(category: str) bool[source]

Check if Composition contains any elements matching a given category.

Parameters:

category (str) – one of “noble_gas”, “transition_metal”, “post_transition_metal”, “rare_earth_metal”, “metal”, “metalloid”, “alkali”, “alkaline”, “halogen”, “chalcogen”, “lanthanoid”, “actinoid”, “quadrupolar”, “s-block”, “p-block”, “d-block”, “f-block”

Returns:

True if any elements in Composition match category, otherwise False

Return type:

bool

copy() Composition[source]

A copy of the composition.

property element_composition: Composition[source]

Returns the composition replacing any species by the corresponding element.

property elements: list[Element | Species | DummySpecies][source]

Returns list of elements in Composition.

property formula: str[source]

Returns a formula string, with elements sorted by electronegativity, e.g., Li4 Fe4 P4 O16.

property fractional_composition: Composition[source]

Returns the normalized composition in which the amounts of each species sum to 1. E.g. “Fe2 O3”.fractional_composition = “Fe0.4 O0.6”.

classmethod from_dict(d) Composition[source]

Creates a composition from a dict generated by as_dict(). Strictly not necessary given that the standard constructor already takes in such an input, but this method preserves the standard pymatgen API of having from_dict methods to reconstitute objects generated by as_dict(). Allows for easier introspection.

Parameters:

d (dict) – {symbol: amount} dict.

classmethod from_weight_dict(weight_dict) Composition[source]

Creates a Composition based on a dict of atomic fractions calculated from a dict of weight fractions. Allows for quick creation of the class from weight-based notations commonly used in the industry, such as Ti6V4Al and Ni60Ti40.

Parameters:

weight_dict (dict) – {symbol: weight_fraction} dict.

Returns:

Composition

get_atomic_fraction(el: str | Element | Species | DummySpecies) float[source]

Calculate atomic fraction of an Element or Species.

Parameters:

el (Element/Species) – Element or Species to get fraction for.

Returns:

Atomic fraction for element el in Composition

get_el_amt_dict() dict[str, float][source]
Returns:

element symbol and (unreduced) amount. E.g. {“Fe”: 4.0, “O”:6.0} or {“Fe3+”: 4.0, “O2-“:6.0}.

Return type:

dict[str, float]

get_integer_formula_and_factor(max_denominator: int = 10000, iupac_ordering: bool = False) tuple[str, float][source]

Calculates an integer formula and factor.

Parameters:
  • max_denominator (int) – all amounts in the el:amt dict are first converted to a Fraction with this maximum denominator

  • iupac_ordering (bool, optional) – Whether to order the formula by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

A pretty normalized formula and a multiplicative factor, i.e., Li0.5O0.25 returns (Li2O, 0.25). O0.25 returns (O2, 0.125)

get_reduced_composition_and_factor() tuple[Composition, float][source]

Calculates a reduced composition and factor.

Returns:

A normalized composition and a multiplicative factor, i.e., Li4Fe4P4O16 returns (Composition(“LiFePO4”), 4).

get_reduced_formula_and_factor(iupac_ordering: bool = False) tuple[str, float][source]

Calculates a reduced formula and factor.

Parameters:

iupac_ordering (bool, optional) – Whether to order the formula by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

A pretty normalized formula and a multiplicative factor, i.e., Li4Fe4P4O16 returns (LiFePO4, 4).

get_wt_fraction(el: str | Element | Species | DummySpecies) float[source]

Calculate weight fraction of an Element or Species.

Parameters:

el (Element | Species) – Element or Species to get fraction for.

Returns:

Weight fraction for element el in Composition.

Return type:

float

property hill_formula: str[source]

The Hill system (or Hill notation) is a system of writing empirical chemical formulas, molecular chemical formulas and components of a condensed formula such that the number of carbon atoms in a molecule is indicated first, the number of hydrogen atoms next, and then the number of all other chemical elements subsequently, in alphabetical order of the chemical symbols. When the formula contains no carbon, all the elements, including hydrogen, are listed alphabetically.

property is_element: bool[source]

True if composition is an element.

property iupac_formula: str[source]

Returns a formula string, with elements sorted by the iupac electronegativity ordering defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Polyanions are still determined based on the true electronegativity of the elements. e.g. CH2(SO4)2.

property num_atoms: float[source]

Total number of atoms in Composition. For negative amounts, sum of absolute values.

oxi_prob = None[source]
oxi_state_guesses(oxi_states_override: dict | None = None, target_charge: float = 0, all_oxi_states: bool = False, max_sites: int | None = None) tuple[dict[str, float]][source]

Checks if the composition is charge-balanced and returns back all charge-balanced oxidation state combinations. Composition must have integer values. Note that more num_atoms in the composition gives more degrees of freedom. e.g., if possible oxidation states of element X are [2,4] and Y are [-3], then XY is not charge balanced but X2Y2 is. Results are returned from most to least probable based on ICSD statistics. Use max_sites to improve performance if needed.

Parameters:
  • oxi_states_override (dict) – dict of str->list to override an element’s common oxidation states, e.g. {“V”: [2,3,4,5]}

  • target_charge (int) – the desired total charge on the structure. Default is 0 signifying charge balance.

  • all_oxi_states (bool) – if True, an element defaults to all oxidation states in pymatgen Element.icsd_oxidation_states. Otherwise, default is Element.common_oxidation_states. Note that the full oxidation state list is very inclusive and can produce nonsensical results.

  • max_sites (int) – if possible, will reduce Compositions to at most this many sites to speed up oxidation state guesses. If the composition cannot be reduced to this many sites a ValueError will be raised. Set to -1 to just reduce fully. If set to a number less than -1, the formula will be fully reduced but a ValueError will be thrown if the number of atoms in the reduced formula is greater than abs(max_sites).

Returns:

each dict reports an element symbol and average

oxidation state across all sites in that composition. If the composition is not charge balanced, an empty list is returned.

Return type:

list[dict]

static ranked_compositions_from_indeterminate_formula(fuzzy_formula: str, lock_if_strict: bool = True) list[Composition][source]

Takes in a formula where capitalization might not be correctly entered, and suggests a ranked list of potential Composition matches. Author: Anubhav Jain.

Parameters:
  • fuzzy_formula (str) – A formula string, such as “co2o3” or “MN”, that may or may not have multiple interpretations

  • lock_if_strict (bool) – If true, a properly entered formula will only return the one correct interpretation. For example, “Co1” will only return “Co1” if true, but will return both “Co1” and “C1 O1” if false.

Returns:

A ranked list of potential Composition matches

property reduced_composition: Composition[source]

Returns the reduced composition, i.e. amounts normalized by greatest common denominator. E.g. “Fe4 P4 O16”.reduced_composition = “Fe P O4”.

property reduced_formula: str[source]

Returns a pretty normalized formula, i.e., LiFePO4 instead of Li4Fe4P4O16.

remove_charges() Composition[source]

Returns a new Composition with charges from each Species removed.

Returns:

Composition object without charge decoration, for example {“Fe3+”: 2.0, “O2-“:3.0} becomes {“Fe”: 2.0, “O”:3.0}

replace(elem_map: dict[str, str | dict[str, float]]) Composition[source]

Replace elements in a composition. Returns a new Composition, leaving the old one unchanged.

Parameters:

elem_map (dict[str, str | dict[str, float]]) – dict of elements or species to swap. E.g. {“Li”: “Na”} performs a Li for Na substitution. The target can be a {species: factor} dict. For example, in Fe2O3 you could map {“Fe”: {“Mg”: 0.5, “Cu”:0.5}} to obtain MgCuO3.

Returns:

New object with elements remapped according to elem_map.

Return type:

Composition

special_formulas = {'Cl': 'Cl2', 'CsO': 'Cs2O2', 'F': 'F2', 'H': 'H2', 'HO': 'H2O2', 'KO': 'K2O2', 'LiO': 'Li2O2', 'N': 'N2', 'NaO': 'Na2O2', 'O': 'O2', 'RbO': 'Rb2O2'}[source]
property to_data_dict: dict[source]

Returns: A dict with many keys and values relating to Composition/Formula, including reduced_cell_composition, unit_cell_composition, reduced_cell_formula, elements and nelements.

to_pretty_string() str[source]
Returns:

Same output as __str__() but without spaces.

Return type:

str

property to_reduced_dict: dict[str, float][source]

Returns: dict[str, float]: element symbols mapped to reduced amount e.g. {“Fe”: 2.0, “O”:3.0}.

property to_weight_dict: dict[str, float][source]

Returns: dict[str, float] with weight fraction of each component {“Ti”: 0.90, “V”: 0.06, “Al”: 0.04}.

property total_electrons: float[source]

Total number of electrons in composition.

property valid: bool[source]

Returns True if Composition contains valid elements or species and False if the Composition contains any dummy species.

property weight: float[source]

Total molecular weight of Composition.

exception CompositionError[source]

Bases: Exception

Exception class for composition errors.

reduce_formula(sym_amt, iupac_ordering: bool = False) tuple[str, float][source]

Helper method to reduce a sym_amt dict to a reduced formula and factor.

Parameters:
  • sym_amt (dict) – {symbol: amount}.

  • iupac_ordering (bool, optional) – Whether to order the formula by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

Returns:

(reduced_formula, factor).

pymatgen.core.interface module

This module provides classes to store, generate, and manipulate material interfaces.

class Interface(lattice, species, coords, site_properties, validate_proximity=False, to_unit_cell=False, coords_are_cartesian=False, in_plane_offset: tuple[float, float] = (0, 0), gap: float = 0, vacuum_over_film: float = 0, interface_properties: dict | None = None)[source]

Bases: Structure

This class stores data for defining an interface between two structures. It is a subclass of pymatgen.core.structure.Structure.

Makes an interface structure, a structure object with additional information and methods pertaining to interfaces.

Parameters:
  • lattice (Lattice/3x3 array) – The lattice, either as a pymatgen.core.Lattice or simply as any 2D array. Each row should correspond to a lattice vector. E.g., [[10,0,0], [20,10,0], [0,0,30]] specifies a lattice with lattice vectors [10,0,0], [20,10,0] and [0,0,30].

  • species ([Species]) –

    Sequence of species on each site. Can take in flexible input, including:

    1. A sequence of element / species specified either as string symbols, e.g. [“Li”, “Fe2+”, “P”, …] or atomic numbers, e.g., (3, 56, …) or actual Element or Species objects.

    2. List of dict of elements/species and occupancies, e.g., [{“Fe” : 0.5, “Mn”:0.5}, …]. This allows the setup of disordered structures.

  • coords (Nx3 array) – list of fractional/cartesian coordinates of each species.

  • validate_proximity (bool) – Whether to check if there are sites that are less than 0.01 Ang apart. Defaults to False.

  • to_unit_cell (bool) – Whether to translate sites into the unit cell. Defaults to False.

  • coords_are_cartesian (bool) – Set to True if you are providing coordinates in Cartesian coordinates. Defaults to False.

  • site_properties (dict) – Properties associated with the sites as a dict of sequences, e.g., {“magmom”:[5,5,5,5]}. The sequences have to be the same length as the atomic species and fractional_coords. Defaults to None for no properties.

  • in_plane_offset – fractional shift in plane for the film with respect to the substrate

  • gap – gap between substrate and film in Angstroms; zero corresponds to the original distance between substrate and film sites

  • vacuum_over_film – vacuum space above the film in Angstroms. Defaults to 0.

  • interface_properties – properties associated with the interface. Defaults to None.

as_dict()[source]

MSONable dict.

copy()[source]
Returns:

A copy of the Interface.

Return type:

Interface

property film: Structure[source]

A pymatgen Structure for just the film.

property film_indices: list[int][source]

Site indices of the film sites.

property film_layers: int[source]

Number of layers of the minimum element in the film composition.

property film_sites: list[Site][source]

Return the film sites of the interface.

property film_termination: str[source]

Label for the film termination chemistry.

classmethod from_dict(d)[source]
Parameters:

d – dict

Returns:

Creates slab from dict.

classmethod from_slabs(substrate_slab: Slab, film_slab: Slab, in_plane_offset: tuple[float, float] = (0, 0), gap: float = 1.6, vacuum_over_film: float = 0, interface_properties: dict | None = None, center_slab: bool = True) Interface[source]

Makes an interface structure by merging a substrate and film slabs The film a- and b-vectors will be forced to be the substrate slab’s a- and b-vectors.

For now, it’s suggested to use a factory method that will ensure the appropriate interface structure is already met.

Parameters:
  • substrate_slab (Slab) – slab for the substrate

  • film_slab (Slab) – slab for the film

  • in_plane_offset (tuple) – fractional shift in plane for the film with respect to the substrate. For example, (0.5, 0.5) will shift the film by half the substrate’s a- and b-vectors. Defaults to (0, 0).

  • gap (float) – gap between substrate and film in Angstroms. Defaults to 1.6.

  • vacuum_over_film (float) – vacuum space above the film in Angstroms. Defaults to 0.

  • interface_properties (dict) – misc properties to assign to the interface. Defaults to None.

  • center_slab (bool) – center the slab. Defaults to True.

property gap: float[source]

The gap in Cartesian units between the film and the substrate.

get_shifts_based_on_adsorbate_sites(tolerance: float = 0.1) list[tuple[float, float]][source]

Computes possible in-plane shifts based on an adsorbate site algorithm.

Parameters:

tolerance – tolerance for “uniqueness” for shifts in Cartesian unit This is usually Angstroms.

get_sorted_structure(key=None, reverse=False) Structure[source]

Get a sorted structure for the interface. The parameters have the same meaning as in list.sort. By default, sites are sorted by the electronegativity of the species.

Parameters:
  • key – Specifies a function of one argument that is used to extract a comparison key from each list element: key=str.lower. The default value is None (compare the elements directly).

  • reverse (bool) – If set to True, then the list elements are sorted as if each comparison were reversed.

property in_plane_offset: ndarray[source]

The shift between the film and substrate in fractional coordinates.

property substrate: Structure[source]

A pymatgen Structure for just the substrate.

property substrate_indices: list[int][source]

Site indices for the substrate atoms.

property substrate_layers: int[source]

Number of layers of the minimum element in the substrate composition.

property substrate_sites: list[Site][source]

The site objects in the substrate.

property substrate_termination: str[source]

Label for the substrate termination chemistry.

property vacuum_over_film: float[source]

The vacuum space over the film in Cartesian units.

count_layers(struct: Structure, el=None) int[source]

Counts the number of ‘layers’ along the c-axis.

label_termination(slab: Structure) str[source]

Labels the slab surface termination.

pymatgen.core.ion module

Module containing class to create an ion.

class Ion(composition, charge=0.0, _properties=None)[source]

Bases: Composition, MSONable, Stringify

Ion object. Just a Composition object with an additional variable to store charge.

The net charge can either be represented as Mn++, Mn+2, Mn[2+], Mn[++], or Mn[+2]. Note the order of the sign and magnitude in each representation.

Flexible Ion construction, similar to Composition. For more information, please see pymatgen.core.Composition.

property alphabetical_formula: str[source]

Returns a formula string, with elements sorted by alphabetically and appended charge.

property anonymized_formula: str[source]

An anonymized formula. Appends charge to the end of anonymized composition.

as_dict() dict[str, float][source]
Returns:

dict with composition, as well as charge.

property charge: float[source]

Charge of the ion.

property composition: Composition[source]

Composition of ion.

property formula: str[source]

Returns a formula string with appended charge. The charge is written with the sign preceding the magnitude, e.g., ‘Ca1 +2’. Uncharged species have “(aq)” appended, e.g. “O2 (aq)”.

classmethod from_dict(dct) Ion[source]

Generates an ion object from a dict created by as_dict().

Parameters:

dct – {symbol: amount} dict.

classmethod from_formula(formula: str) Ion[source]

Creates Ion from formula. The net charge can either be represented as Mn++, Mn+2, Mn[2+], Mn[++], or Mn[+2]. Note the order of the sign and magnitude in each representation.

Also note that (aq) can be included in the formula, e.g. “NaOH (aq)”.

Parameters:

formula

Returns:

Ion

get_reduced_formula_and_factor(iupac_ordering: bool = False, hydrates: bool = False) tuple[str, float][source]

Calculates a reduced formula and factor.

Similar to Composition.get_reduced_formula_and_factor except that O-H formulas receive special handling to differentiate between hydrogen peroxide and OH-. Formulas containing HO are written with oxygen first (e.g. ‘Fe(OH)2’ rather than ‘Fe(HO)2’), and special formulas that apply to solids (e.g. Li2O2 instead of LiO) are not used.

Note that the formula returned by this method does not contain a charge. To include charge, use formula or reduced_formula instead.

Parameters:
  • iupac_ordering (bool, optional) – Whether to order the formula by the iupac “electronegativity” series, defined in Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen. Note that polyanions will still be determined based on the true electronegativity of the elements.

  • hydrates – If True (default), attempt to recognize hydrated metal complexes and separate out the H2O in the reduced formula. For example, Zr(OH)4 becomes ZrO2.2H2O. Applies only to Ions containing metals.

Returns:

A pretty normalized formula and a multiplicative factor, i.e., H4O4 returns (‘H2O2’, 2.0).

oxi_state_guesses(oxi_states_override: dict | None = None, all_oxi_states: bool = False, max_sites: int | None = None) list[dict[str, float]][source]

Checks if the composition is charge-balanced and returns back all charge-balanced oxidation state combinations. Composition must have integer values. Note that more num_atoms in the composition gives more degrees of freedom. e.g., if possible oxidation states of element X are [2,4] and Y are [-3], then XY is not charge balanced but X2Y2 is. Results are returned from most to least probable based on ICSD statistics. Use max_sites to improve performance if needed.

Parameters:
  • oxi_states_override (dict) – dict of str->list to override an element’s common oxidation states, e.g. {“V”: [2,3,4,5]}

  • all_oxi_states (bool) – if True, an element defaults to all oxidation states in pymatgen Element.icsd_oxidation_states. Otherwise, default is Element.common_oxidation_states. Note that the full oxidation state list is very inclusive and can produce nonsensical results.

  • max_sites (int) – if possible, will reduce Compositions to at most this many sites to speed up oxidation state guesses. If the composition cannot be reduced to this many sites a ValueError will be raised. Set to -1 to just reduce fully. If set to a number less than -1, the formula will be fully reduced but a ValueError will be thrown if the number of atoms in the reduced formula is greater than abs(max_sites).

Returns:

A list of dicts - each dict reports an element symbol and average

oxidation state across all sites in that composition. If the composition is not charge balanced, an empty list is returned.

property reduced_formula: str[source]

Returns a reduced formula string with appended charge. The charge is placed in brackets with the sign preceding the magnitude, e.g., ‘Ca[+2]’. Uncharged species have “(aq)” appended, e.g. “O2(aq)”.

to_pretty_string() str[source]

Pretty string with proper superscripts.

property to_reduced_dict: dict[source]
Returns:

dict with element symbol and reduced amount e.g.,

{“Fe”: 2.0, “O”:3.0}.

pymatgen.core.lattice module

Defines the classes relating to 3D lattices.

class Lattice(matrix: ArrayLike, pbc: tuple[bool, bool, bool] = (True, True, True))[source]

Bases: MSONable

A lattice object. Essentially a matrix with conversion matrices. In general, it is assumed that length units are in Angstroms and angles are in degrees unless otherwise stated.

Create a lattice from any sequence of 9 numbers. Note that the sequence is assumed to be read one row at a time. Each row represents one lattice vector.

Parameters:
  • matrix – Sequence of numbers in any form. Examples of acceptable input. i) An actual numpy array. ii) [[1, 0, 0], [0, 1, 0], [0, 0, 1]] iii) [1, 0, 0 , 0, 1, 0, 0, 0, 1] iv) (1, 0, 0, 0, 1, 0, 0, 0, 1) Each row should correspond to a lattice vector. E.g., [[10, 0, 0], [20, 10, 0], [0, 0, 30]] specifies a lattice with lattice vectors [10, 0, 0], [20, 10, 0] and [0, 0, 30].

  • pbc – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

property a: float[source]

a lattice parameter.

property abc: Vector3D[source]

Lengths of the lattice vectors, i.e. (a, b, c).

property alpha: float[source]

Angle alpha of lattice in degrees.

property angles: Vector3D[source]

Lattice angles.

Returns:

The angles (alpha, beta, gamma) of the lattice.

as_dict(verbosity: int = 0) dict[source]

MSONable dict representation of the Lattice.

Parameters:

verbosity (int) – Default of 0 only includes the matrix representation. Set to 1 to include the lattice parameters.

property b: float[source]

b lattice parameter.

property beta: float[source]

Angle beta of lattice in degrees.

property c: float[source]

c lattice parameter.

copy()[source]

Deep copy of self.

static cubic(a: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for a cubic lattice.

Parameters:
  • a (float) – The a lattice parameter of the cubic cell.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Cubic lattice of dimensions a x a x a.

d_hkl(miller_index: ArrayLike) float[source]

Returns the distance between the hkl plane and the origin.

Parameters:

miller_index ([h,k,l]) – Miller index of plane

Returns:

d_hkl (float)

dot(coords_a: ArrayLike, coords_b: ArrayLike, frac_coords: bool = False) np.ndarray[source]

Compute the scalar product of vector(s).

Parameters:
  • coords_a – Array-like coordinates.

  • coords_b – Array-like coordinates.

  • frac_coords (bool) – Boolean stating whether the vector corresponds to fractional or Cartesian coordinates.

Returns:

one-dimensional numpy array.

find_all_mappings(other_lattice: Lattice, ltol: float = 1e-05, atol: float = 1, skip_rotation_matrix: bool = False) Iterator[tuple[Lattice, np.ndarray | None, np.ndarray]][source]

Finds all mappings between current lattice and another lattice.

Parameters:
  • other_lattice (Lattice) – Another lattice that is equivalent to this one.

  • ltol (float) – Tolerance for matching lengths. Defaults to 1e-5.

  • atol (float) – Tolerance for matching angles. Defaults to 1.

  • skip_rotation_matrix (bool) – Whether to skip calculation of the rotation matrix

Yields:

(aligned_lattice, rotation_matrix, scale_matrix) if a mapping is found. aligned_lattice is a rotated version of other_lattice that has the same lattice parameters, but which is aligned in the coordinate system of this lattice so that translational points match up in 3D. rotation_matrix is the rotation that has to be applied to other_lattice to obtain aligned_lattice, i.e., aligned_matrix = np.inner(other_lattice, rotation_matrix) and op = SymmOp.from_rotation_and_translation(rotation_matrix) aligned_matrix = op.operate_multi(latt.matrix) Finally, scale_matrix is the integer matrix that expresses aligned_matrix as a linear combination of this lattice, i.e., aligned_matrix = np.dot(scale_matrix, self.matrix)

None is returned if no matches are found.

find_mapping(other_lattice: Lattice, ltol: float = 1e-05, atol: float = 1, skip_rotation_matrix: bool = False) tuple[Lattice, ndarray | None, ndarray] | None[source]

Finds a mapping between current lattice and another lattice. There are an infinite number of choices of basis vectors for two entirely equivalent lattices. This method returns a mapping that maps other_lattice to this lattice.

Parameters:
  • other_lattice (Lattice) – Another lattice that is equivalent to this one.

  • ltol (float) – Tolerance for matching lengths. Defaults to 1e-5.

  • atol (float) – Tolerance for matching angles. Defaults to 1.

  • skip_rotation_matrix (bool) – Whether to skip calculation of the rotation matrix. Defaults to False.

Returns:

(aligned_lattice, rotation_matrix, scale_matrix) if a mapping is found. aligned_lattice is a rotated version of other_lattice that has the same lattice parameters, but which is aligned in the coordinate system of this lattice so that translational points match up in 3D. rotation_matrix is the rotation that has to be applied to other_lattice to obtain aligned_lattice, i.e., aligned_matrix = np.inner(other_lattice, rotation_matrix) and op = SymmOp.from_rotation_and_translation(rotation_matrix) aligned_matrix = op.operate_multi(latt.matrix) Finally, scale_matrix is the integer matrix that expresses aligned_matrix as a linear combination of this lattice, i.e., aligned_matrix = np.dot(scale_matrix, self.matrix)

None is returned if no matches are found.

classmethod from_dict(d: dict, fmt: str | None = None, **kwargs)[source]

Create a Lattice from a dictionary containing the a, b, c, alpha, beta, and gamma parameters if fmt is None.

If fmt == “abivars”, the function build a Lattice object from a dictionary with the Abinit variables acell and rprim in Bohr. If acell is not given, the Abinit default is used i.e. [1,1,1] Bohr

Example

Lattice.from_dict(fmt=”abivars”, acell=3*[10], rprim=np.eye(3))

classmethod from_parameters(a: float, b: float, c: float, alpha: float, beta: float, gamma: float, vesta: bool = False, pbc: tuple[bool, bool, bool] = (True, True, True))[source]

Create a Lattice using unit cell lengths (in Angstrom) and angles (in degrees).

Parameters:
  • a (float) – a lattice parameter.

  • b (float) – b lattice parameter.

  • c (float) – c lattice parameter.

  • alpha (float) – alpha angle in degrees.

  • beta (float) – beta angle in degrees.

  • gamma (float) – gamma angle in degrees.

  • vesta – True if you import Cartesian coordinates from VESTA.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Lattice with the specified lattice parameters.

property gamma: float[source]

Angle gamma of lattice in degrees.

get_all_distances(fcoords1: ArrayLike, fcoords2: ArrayLike) np.ndarray[source]

Returns the distances between two lists of coordinates taking into account periodic boundary conditions and the lattice. Note that this computes an MxN array of distances (i.e. the distance between each point in fcoords1 and every coordinate in fcoords2). This is different functionality from pbc_diff.

Parameters:
  • 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]]. It can be a single coord or any array of coords.

  • fcoords2 – Second set of fractional coordinates.

Returns:

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

get_brillouin_zone() list[list[ndarray]][source]

Returns the Wigner-Seitz cell for the reciprocal lattice, aka the Brillouin Zone.

Returns:

A list of list of coordinates. Each element in the list is a “facet” of the boundary of the Brillouin Zone. For instance, a list of four coordinates will represent a square facet.

get_cartesian_coords(fractional_coords: ArrayLike) np.ndarray[source]

Returns the Cartesian coordinates given fractional coordinates.

Parameters:

fractional_coords (3x1 array) – Fractional coords.

Returns:

Cartesian coordinates

get_distance_and_image(frac_coords1: ArrayLike, frac_coords2: ArrayLike, jimage: ArrayLike | None = None) tuple[float, np.ndarray][source]

Gets distance between two frac_coords assuming periodic boundary conditions. If the index jimage is not specified it selects the j image nearest to the i atom and returns the distance and jimage indices in terms of lattice vector translations. If the index jimage is specified it returns the distance between the frac_coords1 and the specified jimage of frac_coords2, and the given jimage is also returned.

Parameters:
  • frac_coords1 (3x1 array) – Reference fcoords to get distance from.

  • frac_coords2 (3x1 array) – fcoords to get distance from.

  • jimage (3x1 array) – Specific periodic image in terms of lattice translations, e.g., [1,0,0] implies to take periodic image that is one a-lattice vector away. If jimage is None, the image that is nearest to the site is found.

Returns:

distance and periodic lattice translations of the other site for which the distance applies. This means that the distance between frac_coords1 and (jimage + frac_coords2) is equal to distance.

Return type:

(distance, jimage)

get_frac_coords_from_lll(lll_frac_coords: ArrayLike) np.ndarray[source]

Given fractional coordinates in the lll basis, returns corresponding fractional coordinates in the lattice basis.

get_fractional_coords(cart_coords: ArrayLike) np.ndarray[source]

Returns the fractional coordinates given Cartesian coordinates.

Parameters:

cart_coords (3x1 array) – Cartesian coords.

Returns:

Fractional coordinates.

get_lll_frac_coords(frac_coords: ArrayLike) np.ndarray[source]

Given fractional coordinates in the lattice basis, returns corresponding fractional coordinates in the lll basis.

get_lll_reduced_lattice(delta: float = 0.75) Lattice[source]
Parameters:

delta – Delta parameter.

Returns:

LLL reduced Lattice.

get_miller_index_from_coords(coords: ArrayLike, coords_are_cartesian: bool = True, round_dp: int = 4, verbose: bool = True) tuple[int, int, int][source]

Get the Miller index of a plane from a list of site coordinates.

A minimum of 3 sets of coordinates are required. If more than 3 sets of coordinates are given, the best plane that minimises the distance to all points will be calculated.

Parameters:
  • coords (iterable) – A list or numpy array of coordinates. Can be Cartesian or fractional coordinates. If more than three sets of coordinates are provided, the best plane that minimises the distance to all sites will be calculated.

  • coords_are_cartesian (bool, optional) – Whether the coordinates are in Cartesian space. If using fractional coordinates set to False.

  • round_dp (int, optional) – The number of decimal places to round the miller index to.

  • verbose (bool, optional) – Whether to print warnings.

Returns:

The Miller index.

Return type:

(tuple)

get_niggli_reduced_lattice(tol: float = 1e-05) Lattice[source]

Get the Niggli reduced lattice using the numerically stable algo proposed by R. W. Grosse-Kunstleve, N. K. Sauter, & P. D. Adams, Acta Crystallographica Section A Foundations of Crystallography, 2003, 60(1), 1-6. doi:10.1107/S010876730302186X.

Parameters:

tol (float) – The numerical tolerance. The default of 1e-5 should result in stable behavior for most cases.

Returns:

Niggli-reduced lattice.

Return type:

Lattice

get_points_in_sphere(frac_points: ArrayLike, center: ArrayLike, r: float, zip_results=True) list[tuple[np.ndarray, float, int, np.ndarray]] | list[np.ndarray] | list[source]

Find all points within a sphere from the point taking into account periodic boundary conditions. This includes sites in other periodic images.

Algorithm:

  1. place sphere of radius r in crystal and determine minimum supercell (parallelepiped) which would contain a sphere of radius r. for this we need the projection of a_1 on a unit vector perpendicular to a_2 & a_3 (i.e. the unit vector in the direction b_1) to determine how many a_1”s it will take to contain the sphere.

    Nxmax = r * length_of_b_1 / (2 Pi)

  2. keep points falling within r.

Parameters:
  • frac_points – All points in the lattice in fractional coordinates.

  • center – Cartesian coordinates of center of sphere.

  • r – radius of sphere.

  • zip_results (bool) – Whether to zip the results together to group by point, or return the raw fcoord, dist, index arrays

Returns:

[(fcoord, dist, index, supercell_image) …] since most of the time, subsequent

processing requires the distance, index number of the atom, or index of the image

else:

fcoords, dists, inds, image

Return type:

if zip_results

get_points_in_sphere_old(**kwargs)[source]
get_points_in_sphere_py(frac_points: ArrayLike, center: ArrayLike, r: float, zip_results=True) list[tuple[np.ndarray, float, int, np.ndarray]] | list[np.ndarray][source]

Find all points within a sphere from the point taking into account periodic boundary conditions. This includes sites in other periodic images.

Algorithm:

  1. place sphere of radius r in crystal and determine minimum supercell (parallelepiped) which would contain a sphere of radius r. for this we need the projection of a_1 on a unit vector perpendicular to a_2 & a_3 (i.e. the unit vector in the direction b_1) to determine how many a_1”s it will take to contain the sphere.

    Nxmax = r * length_of_b_1 / (2 Pi)

  2. keep points falling within r.

Parameters:
  • frac_points – All points in the lattice in fractional coordinates.

  • center – Cartesian coordinates of center of sphere.

  • r – radius of sphere.

  • zip_results (bool) – Whether to zip the results together to group by point, or return the raw fcoord, dist, index arrays

Returns:

[(fcoord, dist, index, supercell_image) …] since most of the time, subsequent

processing requires the distance, index number of the atom, or index of the image

else:

fcoords, dists, inds, image

Return type:

if zip_results

get_recp_symmetry_operation(symprec: float = 0.01) list[source]

Find the symmetric operations of the reciprocal lattice, to be used for hkl transformations.

Parameters:

symprec – default is 0.001.

get_vector_along_lattice_directions(cart_coords: ArrayLike) np.ndarray[source]

Returns the coordinates along lattice directions given Cartesian coordinates.

Note, this is different than a projection of the Cartesian vector along the lattice parameters. It is simply the fractional coordinates multiplied by the lattice vector magnitudes.

For example, this method is helpful when analyzing the dipole moment (in units of electron Angstroms) of a ferroelectric crystal. See the Polarization class in pymatgen.analysis.ferroelectricity.polarization.

Parameters:

cart_coords (3x1 array) – Cartesian coords.

Returns:

Lattice coordinates.

get_wigner_seitz_cell() list[list[ndarray]][source]

Returns the Wigner-Seitz cell for the given lattice.

Returns:

A list of list of coordinates. Each element in the list is a “facet” of the boundary of the Wigner Seitz cell. For instance, a list of four coordinates will represent a square facet.

static hexagonal(a: float, c: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for a hexagonal lattice.

Parameters:
  • a (float) – a lattice parameter of the hexagonal cell.

  • c (float) – c lattice parameter of the hexagonal cell.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Hexagonal lattice of dimensions a x a x c.

property inv_matrix: ndarray[source]

Inverse of lattice matrix.

property is_3d_periodic: bool[source]

True if the Lattice is periodic in all directions.

is_hexagonal(hex_angle_tol: float = 5, hex_length_tol: float = 0.01) bool[source]
Parameters:
  • hex_angle_tol – Angle tolerance

  • hex_length_tol – Length tolerance

Returns:

Whether lattice corresponds to hexagonal lattice.

property is_orthogonal: bool[source]

Whether all angles are 90 degrees.

property lengths: Vector3D[source]

Lattice lengths.

Returns:

The lengths (a, b, c) of the lattice.

property lll_inverse: ndarray[source]

Inverse of self.lll_mapping.

property lll_mapping: ndarray[source]

The mapping between the LLL reduced lattice and the original lattice.

property lll_matrix: ndarray[source]

The matrix for LLL reduction.

property matrix: ndarray[source]

Copy of matrix representing the Lattice.

property metric_tensor: ndarray[source]

The metric tensor of the lattice.

static monoclinic(a: float, b: float, c: float, beta: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for a monoclinic lattice.

Parameters:
  • a (float) – a lattice parameter of the monoclinc cell.

  • b (float) – b lattice parameter of the monoclinc cell.

  • c (float) – c lattice parameter of the monoclinc cell.

  • beta (float) – beta angle between lattice vectors b and c in degrees.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Monoclinic lattice of dimensions a x b x c with non right-angle beta between lattice vectors a and c.

norm(coords: ArrayLike, frac_coords: bool = True) np.ndarray[source]

Compute the norm of vector(s).

Parameters:
  • coords – Array-like object with the coordinates.

  • frac_coords – Boolean stating whether the vector corresponds to fractional or Cartesian coordinates.

Returns:

one-dimensional numpy array.

static orthorhombic(a: float, b: float, c: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for an orthorhombic lattice.

Parameters:
  • a (float) – a lattice parameter of the orthorhombic cell.

  • b (float) – b lattice parameter of the orthorhombic cell.

  • c (float) – c lattice parameter of the orthorhombic cell.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Orthorhombic lattice of dimensions a x b x c.

property parameters: tuple[float, float, float, float, float, float][source]

Returns (a, b, c, alpha, beta, gamma).

property params_dict: dict[str, float][source]

Dictionary of lattice parameters.

property pbc: tuple[bool, bool, bool][source]

Tuple defining the periodicity of the Lattice.

property reciprocal_lattice: Lattice[source]

Return the reciprocal lattice. Note that this is the standard reciprocal lattice used for solid state physics with a factor of 2 * pi. If you are looking for the crystallographic reciprocal lattice, use the reciprocal_lattice_crystallographic property. The property is lazily generated for efficiency.

property reciprocal_lattice_crystallographic: Lattice[source]

Returns the crystallographic reciprocal lattice, i.e. no factor of 2 * pi.

static rhombohedral(a: float, alpha: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for a rhombohedral lattice.

Parameters:
  • a (float) – a lattice parameter of the rhombohedral cell.

  • alpha (float) – Angle for the rhombohedral lattice in degrees.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Rhombohedral lattice of dimensions a x a x a.

scale(new_volume: float) Lattice[source]

Return a new Lattice with volume new_volume by performing a scaling of the lattice vectors so that length proportions and angles are preserved.

Parameters:

new_volume – New volume to scale to.

Returns:

New lattice with desired volume.

selling_dist(other)[source]

Returns the minimum Selling distance between two lattices.

property selling_vector: ndarray[source]

Returns the (1,6) array of Selling Scalars.

static tetragonal(a: float, c: float, pbc: tuple[bool, bool, bool] = (True, True, True)) Lattice[source]

Convenience constructor for a tetragonal lattice.

Parameters:
  • a (float) – a lattice parameter of the tetragonal cell.

  • c (float) – c lattice parameter of the tetragonal cell.

  • pbc (tuple) – a tuple defining the periodic boundary conditions along the three axis of the lattice. If None periodic in all directions.

Returns:

Tetragonal lattice of dimensions a x a x c.

property volume: float[source]

Volume of the unit cell in Angstrom^3.

find_neighbors(label: ndarray, nx: int, ny: int, nz: int) list[ndarray][source]

Given a cube index, find the neighbor cube indices.

Parameters:
  • label – (array) (n,) or (n x 3) indice array

  • nx – (int) number of cells in y direction

  • ny – (int) number of cells in y direction

  • nz – (int) number of cells in z direction

Returns:

Neighbor cell indices.

get_integer_index(miller_index: Sequence[float], round_dp: int = 4, verbose: bool = True) tuple[int, int, int][source]

Attempt to convert a vector of floats to whole numbers.

Parameters:
  • miller_index (list of float) – A list miller indexes.

  • round_dp (int, optional) – The number of decimal places to round the miller index to.

  • verbose (bool, optional) – Whether to print warnings.

Returns:

The Miller index.

Return type:

(tuple)

get_points_in_spheres(all_coords: ndarray, center_coords: ndarray, r: float, pbc: bool | list[bool] | tuple[bool, bool, bool] = True, numerical_tol: float = 1e-08, lattice: Lattice | None = None, return_fcoords: bool = False) list[list[tuple[ndarray, float, int, ndarray]]][source]

For each point in center_coords, get all the neighboring points in all_coords that are within the cutoff radius r.

Parameters:
  • all_coords – (list of Cartesian coordinates) all available points

  • center_coords – (list of Cartesian coordinates) all centering points

  • r – (float) cutoff radius

  • pbc – (bool or a list of bool) whether to set periodic boundaries

  • numerical_tol – (float) numerical tolerance

  • lattice – (Lattice) lattice to consider when PBC is enabled

  • return_fcoords – (bool) whether to return fractional coords when pbc is set.

Returns:

List[List[Tuple[coords, distance, index, image]]]

pymatgen.core.libxcfunc module

Enumerator with the libxc identifiers. This is a low level object, client code should not interact with LibxcFunc directly but use the API provided by the Xcfunc object defined in core.xcfunc.py. Part of this module is automatically generated so be careful when refactoring stuff. Use the script ~pymatgen/dev_scripts/regen_libxcfunc.py to regenerate the enum values.

class LibxcFunc(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enumerator with the identifiers. This object is used by Xcfunc declared in xcfunc.py to create an internal representation of the XC functional. This is a low level object, client code should not interact with LibxcFunc directly but use the API provided by Xcfunc.

Parameters:

num – Number for the xc.

GGA_C_AM05 = 135[source]
GGA_C_APBE = 186[source]
GGA_C_BGCP = 39[source]
GGA_C_FT97 = 88[source]
GGA_C_GAM = 33[source]
GGA_C_HCTH_A = 97[source]
GGA_C_LM = 137[source]
GGA_C_LYP = 131[source]
GGA_C_N12 = 80[source]
GGA_C_N12_SX = 79[source]
GGA_C_OPTC = 200[source]
GGA_C_OP_B88 = 87[source]
GGA_C_OP_G96 = 85[source]
GGA_C_OP_PBE = 86[source]
GGA_C_OP_PW91 = 262[source]
GGA_C_OP_XALPHA = 84[source]
GGA_C_P86 = 132[source]
GGA_C_PBE = 130[source]
GGA_C_PBEFE = 258[source]
GGA_C_PBEINT = 62[source]
GGA_C_PBELOC = 246[source]
GGA_C_PBE_JRGX = 138[source]
GGA_C_PBE_SOL = 133[source]
GGA_C_PW91 = 134[source]
GGA_C_Q2D = 47[source]
GGA_C_REGTPSS = 83[source]
GGA_C_REVTCA = 99[source]
GGA_C_RGE2 = 143[source]
GGA_C_SOGGA11 = 152[source]
GGA_C_SOGGA11_X = 159[source]
GGA_C_SPBE = 89[source]
GGA_C_TCA = 100[source]
GGA_C_WI = 148[source]
GGA_C_WI0 = 153[source]
GGA_C_WL = 147[source]
GGA_C_XPBE = 136[source]
GGA_C_ZPBEINT = 61[source]
GGA_C_ZPBESOL = 63[source]
GGA_K_ABSP1 = 506[source]
GGA_K_ABSP2 = 507[source]
GGA_K_APBE = 185[source]
GGA_K_APBEINT = 54[source]
GGA_K_BALTIN = 504[source]
GGA_K_DK = 516[source]
GGA_K_ERNZERHOF = 520[source]
GGA_K_FR_B88 = 514[source]
GGA_K_FR_PW86 = 515[source]
GGA_K_GE2 = 501[source]
GGA_K_GOLDEN = 502[source]
GGA_K_GP85 = 510[source]
GGA_K_GR = 508[source]
GGA_K_LC94 = 521[source]
GGA_K_LIEB = 505[source]
GGA_K_LLP = 522[source]
GGA_K_LUDENA = 509[source]
GGA_K_MEYER = 57[source]
GGA_K_OL1 = 512[source]
GGA_K_OL2 = 513[source]
GGA_K_PEARSON = 511[source]
GGA_K_PERDEW = 517[source]
GGA_K_REVAPBE = 55[source]
GGA_K_REVAPBEINT = 53[source]
GGA_K_TFVW = 52[source]
GGA_K_THAKKAR = 523[source]
GGA_K_TW1 = 187[source]
GGA_K_TW2 = 188[source]
GGA_K_TW3 = 189[source]
GGA_K_TW4 = 190[source]
GGA_K_VJKS = 519[source]
GGA_K_VSK = 518[source]
GGA_K_VW = 500[source]
GGA_K_YT65 = 503[source]
GGA_XC_B97_D = 170[source]
GGA_XC_B97_GGA1 = 96[source]
GGA_XC_EDF1 = 165[source]
GGA_XC_HCTH_120 = 162[source]
GGA_XC_HCTH_147 = 163[source]
GGA_XC_HCTH_407 = 164[source]
GGA_XC_HCTH_407P = 93[source]
GGA_XC_HCTH_93 = 161[source]
GGA_XC_HCTH_P14 = 95[source]
GGA_XC_HCTH_P76 = 94[source]
GGA_XC_KT2 = 146[source]
GGA_XC_MOHLYP = 194[source]
GGA_XC_MOHLYP2 = 195[source]
GGA_XC_MPWLYP1W = 174[source]
GGA_XC_OBLYP_D = 67[source]
GGA_XC_OPBE_D = 65[source]
GGA_XC_OPWLYP_D = 66[source]
GGA_XC_PBE1W = 173[source]
GGA_XC_PBELYP1W = 175[source]
GGA_XC_TH1 = 154[source]
GGA_XC_TH2 = 155[source]
GGA_XC_TH3 = 156[source]
GGA_XC_TH4 = 157[source]
GGA_XC_TH_FC = 197[source]
GGA_XC_TH_FCFO = 198[source]
GGA_XC_TH_FCO = 199[source]
GGA_XC_TH_FL = 196[source]
GGA_XC_VV10 = 255[source]
GGA_XC_XLYP = 166[source]
GGA_X_2D_B86 = 128[source]
GGA_X_2D_B86_MGC = 124[source]
GGA_X_2D_B88 = 127[source]
GGA_X_2D_PBE = 129[source]
GGA_X_AIRY = 192[source]
GGA_X_AK13 = 56[source]
GGA_X_AM05 = 120[source]
GGA_X_APBE = 184[source]
GGA_X_B86 = 103[source]
GGA_X_B86_MGC = 105[source]
GGA_X_B86_R = 41[source]
GGA_X_B88 = 106[source]
GGA_X_BAYESIAN = 125[source]
GGA_X_BGCP = 38[source]
GGA_X_BPCCAC = 98[source]
GGA_X_C09X = 158[source]
GGA_X_CAP = 270[source]
GGA_X_DK87_R1 = 111[source]
GGA_X_DK87_R2 = 112[source]
GGA_X_EV93 = 35[source]
GGA_X_FT97_A = 114[source]
GGA_X_FT97_B = 115[source]
GGA_X_G96 = 107[source]
GGA_X_GAM = 32[source]
GGA_X_HCTH_A = 34[source]
GGA_X_HERMAN = 104[source]
GGA_X_HJS_B88 = 527[source]
GGA_X_HJS_B88_V2 = 46[source]
GGA_X_HJS_B97X = 528[source]
GGA_X_HJS_PBE = 525[source]
GGA_X_HJS_PBE_SOL = 526[source]
GGA_X_HTBS = 191[source]
GGA_X_ITYH = 529[source]
GGA_X_KT1 = 145[source]
GGA_X_LAG = 193[source]
GGA_X_LAMBDA_CH_N = 44[source]
GGA_X_LAMBDA_LO_N = 45[source]
GGA_X_LAMBDA_OC2_N = 40[source]
GGA_X_LB = 160[source]
GGA_X_LBM = 182[source]
GGA_X_LG93 = 113[source]
GGA_X_LV_RPW86 = 58[source]
GGA_X_MB88 = 149[source]
GGA_X_MPBE = 122[source]
GGA_X_MPW91 = 119[source]
GGA_X_N12 = 82[source]
GGA_X_OL2 = 183[source]
GGA_X_OPTB88_VDW = 139[source]
GGA_X_OPTPBE_VDW = 141[source]
GGA_X_OPTX = 110[source]
GGA_X_PBE = 101[source]
GGA_X_PBEA = 121[source]
GGA_X_PBEFE = 265[source]
GGA_X_PBEINT = 60[source]
GGA_X_PBEK1_VDW = 140[source]
GGA_X_PBE_JSJR = 126[source]
GGA_X_PBE_MOL = 49[source]
GGA_X_PBE_R = 102[source]
GGA_X_PBE_SOL = 116[source]
GGA_X_PBE_TCA = 59[source]
GGA_X_PW86 = 108[source]
GGA_X_PW91 = 109[source]
GGA_X_Q2D = 48[source]
GGA_X_RGE2 = 142[source]
GGA_X_RPBE = 117[source]
GGA_X_RPW86 = 144[source]
GGA_X_SFAT = 530[source]
GGA_X_SOGGA = 150[source]
GGA_X_SOGGA11 = 151[source]
GGA_X_SSB = 91[source]
GGA_X_SSB_D = 92[source]
GGA_X_SSB_SW = 90[source]
GGA_X_VMT84_GE = 68[source]
GGA_X_VMT84_PBE = 69[source]
GGA_X_VMT_GE = 70[source]
GGA_X_VMT_PBE = 71[source]
GGA_X_WC = 118[source]
GGA_X_WPBEH = 524[source]
GGA_X_XPBE = 123[source]
HYB_GGA_XC_B1LYP = 416[source]
HYB_GGA_XC_B1PW91 = 417[source]
HYB_GGA_XC_B1WC = 412[source]
HYB_GGA_XC_B3LYP = 402[source]
HYB_GGA_XC_B3LYP5 = 475[source]
HYB_GGA_XC_B3LYPs = 459[source]
HYB_GGA_XC_B3P86 = 403[source]
HYB_GGA_XC_B3PW91 = 401[source]
HYB_GGA_XC_B97 = 407[source]
HYB_GGA_XC_B97_1 = 408[source]
HYB_GGA_XC_B97_1p = 266[source]
HYB_GGA_XC_B97_2 = 410[source]
HYB_GGA_XC_B97_3 = 414[source]
HYB_GGA_XC_B97_K = 413[source]
HYB_GGA_XC_BHANDH = 435[source]
HYB_GGA_XC_BHANDHLYP = 436[source]
HYB_GGA_XC_CAMY_B3LYP = 470[source]
HYB_GGA_XC_CAMY_BLYP = 455[source]
HYB_GGA_XC_CAM_B3LYP = 433[source]
HYB_GGA_XC_CAP0 = 477[source]
HYB_GGA_XC_EDF2 = 476[source]
HYB_GGA_XC_HJS_B88 = 431[source]
HYB_GGA_XC_HJS_B97X = 432[source]
HYB_GGA_XC_HJS_PBE = 429[source]
HYB_GGA_XC_HJS_PBE_SOL = 430[source]
HYB_GGA_XC_HPBEINT = 472[source]
HYB_GGA_XC_HSE03 = 427[source]
HYB_GGA_XC_HSE06 = 428[source]
HYB_GGA_XC_LCY_BLYP = 468[source]
HYB_GGA_XC_LCY_PBE = 467[source]
HYB_GGA_XC_LC_VV10 = 469[source]
HYB_GGA_XC_LRC_WPBE = 473[source]
HYB_GGA_XC_LRC_WPBEH = 465[source]
HYB_GGA_XC_MB3LYP_RC04 = 437[source]
HYB_GGA_XC_MPW3LYP = 419[source]
HYB_GGA_XC_MPW3PW = 415[source]
HYB_GGA_XC_MPWLYP1M = 453[source]
HYB_GGA_XC_O3LYP = 404[source]
HYB_GGA_XC_PBE0_13 = 456[source]
HYB_GGA_XC_PBEH = 406[source]
HYB_GGA_XC_REVB3LYP = 454[source]
HYB_GGA_XC_SB98_1a = 420[source]
HYB_GGA_XC_SB98_1b = 421[source]
HYB_GGA_XC_SB98_1c = 422[source]
HYB_GGA_XC_SB98_2a = 423[source]
HYB_GGA_XC_SB98_2b = 424[source]
HYB_GGA_XC_SB98_2c = 425[source]
HYB_GGA_XC_TUNED_CAM_B3LYP = 434[source]
HYB_GGA_XC_WB97 = 463[source]
HYB_GGA_XC_WB97X = 464[source]
HYB_GGA_XC_WB97X_D = 471[source]
HYB_GGA_XC_WB97X_V = 466[source]
HYB_GGA_XC_X3LYP = 411[source]
HYB_GGA_XC_mPW1K = 405[source]
HYB_GGA_XC_mPW1PW = 418[source]
HYB_GGA_X_N12_SX = 81[source]
HYB_GGA_X_SOGGA11_X = 426[source]
HYB_MGGA_XC_B86B95 = 441[source]
HYB_MGGA_XC_B88B95 = 440[source]
HYB_MGGA_XC_BB1K = 443[source]
HYB_MGGA_XC_M05 = 438[source]
HYB_MGGA_XC_M05_2X = 439[source]
HYB_MGGA_XC_M06 = 449[source]
HYB_MGGA_XC_M06_2X = 450[source]
HYB_MGGA_XC_M06_HF = 444[source]
HYB_MGGA_XC_M08_HX = 460[source]
HYB_MGGA_XC_M08_SO = 461[source]
HYB_MGGA_XC_M11 = 462[source]
HYB_MGGA_XC_MPW1B95 = 445[source]
HYB_MGGA_XC_MPWB1K = 446[source]
HYB_MGGA_XC_PW6B95 = 451[source]
HYB_MGGA_XC_PW86B95 = 442[source]
HYB_MGGA_XC_PWB6K = 452[source]
HYB_MGGA_XC_REVTPSSH = 458[source]
HYB_MGGA_XC_TPSSH = 457[source]
HYB_MGGA_XC_WB97M_V = 531[source]
HYB_MGGA_XC_X1B95 = 447[source]
HYB_MGGA_XC_XB1K = 448[source]
HYB_MGGA_X_DLDF = 36[source]
HYB_MGGA_X_MN12_SX = 248[source]
HYB_MGGA_X_MN15 = 268[source]
HYB_MGGA_X_MS2H = 224[source]
HYB_MGGA_X_MVSH = 474[source]
HYB_MGGA_X_SCAN0 = 264[source]
LDA_C_1D_CSC = 18[source]
LDA_C_1D_LOOS = 26[source]
LDA_C_2D_AMGB = 15[source]
LDA_C_2D_PRM = 16[source]
LDA_C_GL = 5[source]
LDA_C_GOMBAS = 24[source]
LDA_C_HL = 4[source]
LDA_C_ML1 = 22[source]
LDA_C_ML2 = 23[source]
LDA_C_OB_PW = 14[source]
LDA_C_OB_PZ = 11[source]
LDA_C_PW = 12[source]
LDA_C_PW_MOD = 13[source]
LDA_C_PW_RPA = 25[source]
LDA_C_PZ = 9[source]
LDA_C_PZ_MOD = 10[source]
LDA_C_RC04 = 27[source]
LDA_C_RPA = 3[source]
LDA_C_VWN = 7[source]
LDA_C_VWN_1 = 28[source]
LDA_C_VWN_2 = 29[source]
LDA_C_VWN_3 = 30[source]
LDA_C_VWN_4 = 31[source]
LDA_C_VWN_RPA = 8[source]
LDA_C_WIGNER = 2[source]
LDA_C_XALPHA = 6[source]
LDA_C_vBH = 17[source]
LDA_K_LP = 51[source]
LDA_K_TF = 50[source]
LDA_X = 1[source]
LDA_XC_KSDT = 259[source]
LDA_XC_TETER93 = 20[source]
LDA_XC_ZLP = 43[source]
LDA_X_1D = 21[source]
LDA_X_2D = 19[source]
MGGA_C_BC95 = 240[source]
MGGA_C_CC06 = 229[source]
MGGA_C_CS = 72[source]
MGGA_C_DLDF = 37[source]
MGGA_C_M05 = 237[source]
MGGA_C_M05_2X = 238[source]
MGGA_C_M06 = 235[source]
MGGA_C_M06_2X = 236[source]
MGGA_C_M06_HF = 234[source]
MGGA_C_M06_L = 233[source]
MGGA_C_M08_HX = 78[source]
MGGA_C_M08_SO = 77[source]
MGGA_C_M11 = 76[source]
MGGA_C_M11_L = 75[source]
MGGA_C_MN12_L = 74[source]
MGGA_C_MN12_SX = 73[source]
MGGA_C_MN15 = 269[source]
MGGA_C_MN15_L = 261[source]
MGGA_C_PKZB = 239[source]
MGGA_C_REVTPSS = 241[source]
MGGA_C_SCAN = 267[source]
MGGA_C_TPSS = 231[source]
MGGA_C_TPSSLOC = 247[source]
MGGA_C_VSXC = 232[source]
MGGA_XC_B97M_V = 254[source]
MGGA_XC_OTPSS_D = 64[source]
MGGA_XC_TPSSLYP1W = 242[source]
MGGA_XC_ZLP = 42[source]
MGGA_X_2D_PRHG07 = 210[source]
MGGA_X_2D_PRHG07_PRP10 = 211[source]
MGGA_X_BJ06 = 207[source]
MGGA_X_BLOC = 244[source]
MGGA_X_BR89 = 206[source]
MGGA_X_GVT4 = 204[source]
MGGA_X_LTA = 201[source]
MGGA_X_M05 = 214[source]
MGGA_X_M05_2X = 215[source]
MGGA_X_M06 = 217[source]
MGGA_X_M06_2X = 218[source]
MGGA_X_M06_HF = 216[source]
MGGA_X_M06_L = 203[source]
MGGA_X_M08_HX = 219[source]
MGGA_X_M08_SO = 220[source]
MGGA_X_M11 = 225[source]
MGGA_X_M11_L = 226[source]
MGGA_X_MBEEF = 249[source]
MGGA_X_MBEEFVDW = 250[source]
MGGA_X_MK00 = 230[source]
MGGA_X_MK00B = 243[source]
MGGA_X_MN12_L = 227[source]
MGGA_X_MN15_L = 260[source]
MGGA_X_MODTPSS = 245[source]
MGGA_X_MS0 = 221[source]
MGGA_X_MS1 = 222[source]
MGGA_X_MS2 = 223[source]
MGGA_X_MVS = 257[source]
MGGA_X_PKZB = 213[source]
MGGA_X_REVTPSS = 212[source]
MGGA_X_RPP09 = 209[source]
MGGA_X_SCAN = 263[source]
MGGA_X_TAU_HCTH = 205[source]
MGGA_X_TB09 = 208[source]
MGGA_X_TPSS = 202[source]
static all_families()[source]

List of strings with the libxc families. Note that XC_FAMILY if removed from the string e.g. XC_FAMILY_LDA becomes LDA.

static all_kinds()[source]

List of strings with the libxc kinds. Also in this case, the string is obtained by remove the XC_ prefix. XC_CORRELATION –> CORRELATION.

as_dict()[source]

Makes LibxcFunc obey the general json interface used in pymatgen for easier serialization.

classmethod from_dict(dct)[source]

Makes LibxcFunc obey the general json interface used in pymatgen for easier serialization.

property info_dict[source]

Dictionary with metadata. see libxc_docs.json.

property is_c_kind: bool[source]

True if this is a correlation-only functional.

property is_gga_family: bool[source]

True if this functional belongs to the GGA family.

property is_hyb_gga_family: bool[source]

True if this functional belongs to the hybrid + GGA family.

property is_hyb_mgga_family: bool[source]

True if this functional belongs to the hybrid + meta-GGA family.

property is_k_kind: bool[source]

True if this is a kinetic functional.

property is_lda_family: bool[source]

True if this functional belongs to the LDA family.

property is_mgga_family: bool[source]

True if this functional belongs to the meta-GGA family.

property is_x_kind: bool[source]

True if this is an exchange-only functional.

property is_xc_kind: bool[source]

True if this is a exchange+correlation functional.

to_json()[source]

Returns a json string representation of the MSONable object.

pymatgen.core.molecular_orbitals module

This module implements a MolecularOrbital class to represent band character in solids. Useful for predicting PDOS character from structural information.

class MolecularOrbitals(formula)[source]

Bases: object

Represents the character of bands in a solid. The input is a chemical formula, since no structural characteristics are taken into account.

The band character of a crystal emerges from the atomic orbitals of the constituent ions, hybridization/covalent bonds, and the spin-orbit interaction (ex: Fe2O3). Right now the orbitals are only built from the uncharged atomic species. Functionality can be improved by: 1) calculate charged ion orbital energies 2) incorporate the coordination environment to account for covalent bonds

The atomic orbital energies are stored in pymatgen.core.periodic_table.JSON

MOs = MolecularOrbitals(‘SrTiO3’) MOs.band_edges # gives {‘HOMO’:[‘O’,’2p’,-0.338381], ‘LUMO’:[‘Ti’,’3d’,-0.17001], ‘metal’:False}

Parameters:

formula (str) – Chemical formula. Must have integer subscripts. Ex: ‘SrTiO3’.

composition[source]

the composition as a dictionary. Ex: {‘Sr’: 1, ‘Ti’: 1, ‘O’, 3}

elements[source]

the dictionary keys for the composition

elec_neg[source]

the maximum pairwise electronegativity difference

aos[source]

the constituent atomic orbitals for each element as a dictionary

band_edges[source]

dictionary containing the highest occupied molecular orbital (HOMO), lowest unoccupied molecular orbital (LUMO), and whether the material is predicted to be a metal

aos_as_list()[source]

The orbitals energies in eV are represented as [[‘O’, ‘1s’, -18.758245], [‘O’, ‘2s’, -0.871362], [‘O’, ‘2p’, -0.338381]] Data is obtained from https://www.nist.gov/pml/data/atomic-reference-data-electronic-structure-calculations.

Returns:

A list of atomic orbitals, sorted from lowest to highest energy.

max_electronegativity()[source]
Returns:

The maximum pairwise electronegativity difference.

obtain_band_edges()[source]

Fill up the atomic orbitals with available electrons.

Returns:

HOMO, LUMO, and whether it’s a metal.

pymatgen.core.operations module

This module provides classes that operate on points or vectors in 3D space.

class MagSymmOp(affine_transformation_matrix: ArrayLike, time_reversal: int, tol: float = 0.01)[source]

Bases: SymmOp

Thin wrapper around SymmOp to extend it to support magnetic symmetry by including a time reversal operator. Magnetic symmetry is similar to conventional crystal symmetry, except symmetry is reduced by the addition of a time reversal operator which acts on an atom’s magnetic moment.

Initializes the MagSymmOp from a 4x4 affine transformation matrix and time reversal operator. In general, this constructor should not be used unless you are transferring rotations. Use the static constructors instead to generate a SymmOp from proper rotations and translation.

Parameters:
  • affine_transformation_matrix (4x4 array) – Representing an affine transformation.

  • time_reversal (int) – 1 or -1

  • tol (float) – Tolerance for determining if matrices are equal.

as_dict() dict[str, Any][source]

MSONable dict.

as_xyzt_str() str[source]

Returns a string of the form ‘x, y, z, +1’, ‘-x, -y, z, -1’, ‘-y+1/2, x+1/2, z+1/2, +1’, etc. Only works for integer rotation matrices.

as_xyzt_string(*args, **kwargs)[source]

as_xyzt_string is deprecated! Use as_xyzt_str instead

classmethod from_dict(d: dict) MagSymmOp[source]
Parameters:

d – dict

Returns:

MagneticSymmOp from dict representation.

static from_rotation_and_translation_and_time_reversal(rotation_matrix: ArrayLike = ((1, 0, 0), (0, 1, 0), (0, 0, 1)), translation_vec: ArrayLike = (0, 0, 0), time_reversal: int = 1, tol: float = 0.1) MagSymmOp[source]

Creates a symmetry operation from a rotation matrix, translation vector and time reversal operator.

Parameters:
  • rotation_matrix (3x3 array) – Rotation matrix.

  • translation_vec (3x1 array) – Translation vector.

  • time_reversal (int) – Time reversal operator, +1 or -1.

  • tol (float) – Tolerance to determine if rotation matrix is valid.

Returns:

MagSymmOp object

classmethod from_symmop(symmop: SymmOp, time_reversal) MagSymmOp[source]

Initialize a MagSymmOp from a SymmOp and time reversal operator.

Parameters:
  • symmop (SymmOp) – SymmOp

  • time_reversal (int) – Time reversal operator, +1 or -1.

Returns:

MagSymmOp object

classmethod from_xyzt_str(xyzt_string: str) MagSymmOp[source]
Parameters:

xyzt_string (str) – of the form ‘x, y, z, +1’, ‘-x, -y, z, -1’, ‘-2y+1/2, 3x+1/2, z-y+1/2, +1’, etc.

Returns:

MagSymmOp object

classmethod from_xyzt_string(*args, **kwargs)[source]

from_xyzt_string is deprecated! Use from_xyzt_str instead

operate_magmom(magmom)[source]

Apply time reversal operator on the magnetic moment. Note that magnetic moments transform as axial vectors, not polar vectors.

See ‘Symmetry and magnetic structures’, Rodríguez-Carvajal and Bourée for a good discussion. DOI: 10.1051/epjconf/20122200010

Parameters:
  • magmom – Magnetic moment as electronic_structure.core.Magmom

  • array-like (class or as list or np) –

Returns:

Magnetic moment after operator applied as Magmom class

class SymmOp(affine_transformation_matrix: ArrayLike, tol: float = 0.01)[source]

Bases: MSONable

A symmetry operation in Cartesian space. Consists of a rotation plus a translation. Implementation is as an affine transformation matrix of rank 4 for efficiency. Read: http://en.wikipedia.org/wiki/Affine_transformation.

affine_matrix[source]

A 4x4 array representing the symmetry operation.

Type:

np.ndarray

Initializes the SymmOp from a 4x4 affine transformation matrix. In general, this constructor should not be used unless you are transferring rotations. Use the static constructors instead to generate a SymmOp from proper rotations and translation.

Parameters:
  • affine_transformation_matrix (4x4 array) – Representing an affine transformation.

  • tol (float) – Tolerance for determining if matrices are equal. Defaults to 0.01.

Raises:

ValueError – if matrix is not 4x4.

apply_rotation_only(vector: ArrayLike) np.ndarray[source]

Vectors should only be operated by the rotation matrix and not the translation vector.

Parameters:

vector (3x1 array) – A vector.

Checks if two points are symmetrically related.

Parameters:
  • point_a (3x1 array) – First point.

  • point_b (3x1 array) – Second point.

  • tol (float) – Absolute tolerance for checking distance. Defaults to 0.001.

Returns:

True if self.operate(point_a) == point_b or vice versa.

Return type:

bool

Checks if two vectors, or rather two vectors that connect two points each are symmetrically related. r_a and r_b give the change of unit cells. Two vectors are also considered symmetrically equivalent if starting and end point are exchanged.

Parameters:
  • from_a (3x1 array) – Starting point of the first vector.

  • to_a (3x1 array) – Ending point of the first vector.

  • from_b (3x1 array) – Starting point of the second vector.

  • to_b (3x1 array) – Ending point of the second vector.

  • r_a (3x1 array) – Change of unit cell of the first vector.

  • r_b (3x1 array) – Change of unit cell of the second vector.

  • tol (float) – Absolute tolerance for checking distance.

Returns:

(are_related, is_reversed)

as_dict() dict[str, Any][source]

MSONable dict.

as_xyz_str() str[source]

Returns a string of the form ‘x, y, z’, ‘-x, -y, z’, ‘-y+1/2, x+1/2, z+1/2’, etc. Only works for integer rotation matrices.

as_xyz_string(*args, **kwargs)[source]

as_xyz_string is deprecated! Use as_xyz_str instead

static from_axis_angle_and_translation(axis: ArrayLike, angle: float, angle_in_radians: bool = False, translation_vec: ArrayLike = (0, 0, 0)) SymmOp[source]

Generates a SymmOp for a rotation about a given axis plus translation.

Parameters:
  • axis – The axis of rotation in Cartesian space. For example, [1, 0, 0]indicates rotation about x-axis.

  • angle (float) – Angle of rotation.

  • angle_in_radians (bool) – Set to True if angles are given in radians. Or else, units of degrees are assumed.

  • translation_vec – A translation vector. Defaults to zero.

Returns:

SymmOp for a rotation about given axis and translation.

classmethod from_dict(d) SymmOp[source]
Parameters:

d – dict

Returns:

SymmOp from dict representation.

static from_origin_axis_angle(origin: ArrayLike, axis: ArrayLike, angle: float, angle_in_radians: bool = False) SymmOp[source]

Generates a SymmOp for a rotation about a given axis through an origin.

Parameters:
  • origin (3x1 array) – The origin which the axis passes through.

  • axis (3x1 array) – The axis of rotation in Cartesian space. For example, [1, 0, 0]indicates rotation about x-axis.

  • angle (float) – Angle of rotation.

  • angle_in_radians (bool) – Set to True if angles are given in radians. Or else, units of degrees are assumed.

Returns:

SymmOp.

static from_rotation_and_translation(rotation_matrix: ArrayLike = ((1, 0, 0), (0, 1, 0), (0, 0, 1)), translation_vec: ArrayLike = (0, 0, 0), tol: float = 0.1) SymmOp[source]

Creates a symmetry operation from a rotation matrix and a translation vector.

Parameters:
  • rotation_matrix (3x3 array) – Rotation matrix.

  • translation_vec (3x1 array) – Translation vector.

  • tol (float) – Tolerance to determine if rotation matrix is valid.

Returns:

SymmOp object

classmethod from_xyz_str(xyz_str: str) SymmOp[source]
Parameters:

xyz_str – string of the form ‘x, y, z’, ‘-x, -y, z’, ‘-2y+1/2, 3x+1/2, z-y+1/2’, etc.

Returns:

SymmOp

classmethod from_xyz_string(*args, **kwargs)[source]

from_xyz_string is deprecated! Use from_xyz_str instead

property inverse: SymmOp[source]

Returns inverse of transformation.

static inversion(origin: ArrayLike = (0, 0, 0)) SymmOp[source]

Inversion symmetry operation about axis.

Parameters:

origin (3x1 array) – Origin of the inversion operation. Defaults to [0, 0, 0].

Returns:

SymmOp representing an inversion operation about the origin.

operate(point: ArrayLike) np.ndarray[source]

Apply the operation on a point.

Parameters:

point – Cartesian coordinate.

Returns:

Coordinates of point after operation.

operate_multi(points: ArrayLike) np.ndarray[source]

Apply the operation on a list of points.

Parameters:

points – List of Cartesian coordinates

Returns:

Numpy array of coordinates after operation

static reflection(normal: ArrayLike, origin: ArrayLike = (0, 0, 0)) SymmOp[source]

Returns reflection symmetry operation.

Parameters:
  • normal (3x1 array) – Vector of the normal to the plane of reflection.

  • origin (3x1 array) – A point in which the mirror plane passes through.

Returns:

SymmOp for the reflection about the plane

property rotation_matrix: ndarray[source]

A 3x3 numpy.array representing the rotation matrix.

static rotoreflection(axis: ArrayLike, angle: float, origin: ArrayLike = (0, 0, 0)) SymmOp[source]

Returns a roto-reflection symmetry operation.

Parameters:
  • axis (3x1 array) – Axis of rotation / mirror normal

  • angle (float) – Angle in degrees

  • origin (3x1 array) – Point left invariant by roto-reflection. Defaults to (0, 0, 0).

Returns:

Roto-reflection operation

transform_tensor(tensor: ndarray) ndarray[source]

Applies rotation portion to a tensor. Note that tensor has to be in full form, not the Voigt form.

Parameters:

tensor (numpy array) – A rank n tensor

Returns:

Transformed tensor.

property translation_vector: ndarray[source]

A rank 1 numpy.array of dim 3 representing the translation vector.

pymatgen.core.periodic_table module

Classes representing Element, Species (Element + oxidation state) and PeriodicTable.

class DummySpecie(symbol: str = 'X', oxidation_state: float | None = 0, spin: float | None = None)[source]

Bases: DummySpecies

This maps the historical grammatically inaccurate DummySpecie to DummySpecies to maintain backwards compatibility.

Parameters:
  • symbol (str) – An assigned symbol for the dummy specie. Strict rules are applied to the choice of the symbol. The dummy symbol cannot have any part of first two letters that will constitute an Element symbol. Otherwise, a composition may be parsed wrongly. E.g., “X” is fine, but “Vac” is not because Vac contains V, a valid Element.

  • oxidation_state (float) – Oxidation state for dummy specie. Defaults to 0. deprecated and retained purely for backward compatibility.

  • spin – Spin associated with Species. Defaults to None.

class DummySpecies(symbol: str = 'X', oxidation_state: float | None = 0, spin: float | None = None)[source]

Bases: Species

A special specie for representing non-traditional elements or species. For example, representation of vacancies (charged or otherwise), or special sites, etc.

oxi_state[source]

Oxidation state associated with Species.

Type:

int

Z[source]

DummySpecies is always assigned an atomic number equal to the hash number of the symbol. Obviously, it makes no sense whatsoever to use the atomic number of a Dummy specie for anything scientific. The purpose of this is to ensure that for most use cases, a DummySpecies behaves no differently from an Element or Species.

Type:

int

X[source]

DummySpecies is always assigned a Pauling electronegativity of 0.

Type:

float

Parameters:
  • symbol (str) – An assigned symbol for the dummy specie. Strict rules are applied to the choice of the symbol. The dummy symbol cannot have any part of first two letters that will constitute an Element symbol. Otherwise, a composition may be parsed wrongly. E.g., “X” is fine, but “Vac” is not because Vac contains V, a valid Element.

  • oxidation_state (float) – Oxidation state for dummy specie. Defaults to 0. deprecated and retained purely for backward compatibility.

  • spin – Spin associated with Species. Defaults to None.

property X: float[source]

DummySpecies is always assigned a Pauling electronegativity of 0. The effect of this is that DummySpecies are always sorted in front of actual Species.

property Z: int[source]

DummySpecies is always assigned an atomic number equal to the hash of the symbol. The expectation is that someone would be an actual dummy to use atomic numbers for a Dummy specie.

as_dict() dict[source]

MSONable dict representation.

classmethod from_dict(d) DummySpecies[source]
Parameters:

d – Dict representation

Returns:

DummySpecies

static from_str(species_string: str) DummySpecies[source]

Returns a Dummy from a string representation.

Parameters:

species_string (str) – A string representation of a dummy species, e.g., “X2+”, “X3+”.

Returns:

A DummySpecies object.

Raises:

ValueError if species_string cannot be interpreted.

property oxi_state: float | None[source]

Oxidation state associated with DummySpecies.

property symbol: str[source]

Symbol for DummySpecies.

class Element(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: ElementBase

Enum representing an element in the periodic table.

Basic immutable element object with all relevant properties.

Only one instance of Element for each symbol is stored after creation, ensuring that a particular element behaves like a singleton. For all attributes, missing data (i.e., data for which is not available) is represented by a None unless otherwise stated.

Parameters:

symbol (str) – Element symbol, e.g., “H”, “Fe”

Z[source]

Atomic number.

Type:

int

symbol[source]

Element symbol.

Type:

str

long_name[source]

Long name for element. E.g., “Hydrogen”.

Type:

str

atomic_radius_calculated[source]

Calculated atomic radius for the element. This is the empirical value. Data is obtained from http://en.wikipedia.org/wiki/Atomic_radii_of_the_elements_(data_page).

Type:

float

van_der_waals_radius[source]

Van der Waals radius for the element. This is the empirical value determined from critical reviews of X-ray diffraction, gas kinetic collision cross-section, and other experimental data by Bondi and later workers. The uncertainty in these values is on the order of 0.1 Å. Data are obtained from “Atomic Radii of the Elements” in CRC Handbook of Chemistry and Physics, 91st Ed.; Haynes, W.M., Ed.; CRC Press: Boca Raton, FL, 2010.

Type:

float

mendeleev_no[source]

Mendeleev number from definition given by Pettifor, D. G. (1984). A chemical scale for crystal-structure maps. Solid State Communications, 51 (1), 31-34.

Type:

int

electrical_resistivity[source]

Electrical resistivity.

Type:

float

velocity_of_sound[source]

Velocity of sound.

Type:

float

reflectivity[source]

Reflectivity.

Type:

float

refractive_index[source]

Refractive index.

Type:

float

poissons_ratio[source]

Poisson’s ratio.

Type:

float

molar_volume[source]

Molar volume.

Type:

float

electronic_structure[source]

Electronic structure. E.g., The electronic structure for Fe is represented as [Ar].3d6.4s2.

Type:

str

atomic_orbitals[source]

Atomic Orbitals. Energy of the atomic orbitals as a dict. E.g., The orbitals energies in eV are represented as {‘1s’: -1.0, ‘2s’: -0.1}. Data is obtained from https://www.nist.gov/pml/data/atomic-reference-data-electronic-structure-calculations. The LDA values for neutral atoms are used.

Type:

dict

thermal_conductivity[source]

Thermal conductivity.

Type:

float

boiling_point[source]

Boiling point.

Type:

float

melting_point[source]

Melting point.

Type:

float

critical_temperature[source]

Critical temperature.

Type:

float

superconduction_temperature[source]

Superconduction temperature.

Type:

float

liquid_range[source]

Liquid range.

Type:

float

bulk_modulus[source]

Bulk modulus.

Type:

float

youngs_modulus[source]

Young’s modulus.

Type:

float

brinell_hardness[source]

Brinell hardness.

Type:

float

rigidity_modulus[source]

Rigidity modulus.

Type:

float

mineral_hardness[source]

Mineral hardness.

Type:

float

vickers_hardness[source]

Vicker’s hardness.

Type:

float

density_of_solid[source]

Density of solid phase.

Type:

float

coefficient_of_linear_thermal_expansion[source]

Coefficient of linear thermal expansion.

Type:

float

ground_level[source]

Ground level for element.

Type:

float

ionization_energies[source]

List of ionization energies. First value is the first ionization energy, second is the second ionization energy, etc. Note that this is zero-based indexing! So Element.ionization_energies[0] refer to the 1st ionization energy. Values are from the NIST Atomic Spectra Database. Missing values are None.

Type:

list[Optional[float]]

Ac = 'Ac'[source]
Ag = 'Ag'[source]
Al = 'Al'[source]
Am = 'Am'[source]
Ar = 'Ar'[source]
As = 'As'[source]
At = 'At'[source]
Au = 'Au'[source]
B = 'B'[source]
Ba = 'Ba'[source]
Be = 'Be'[source]
Bh = 'Bh'[source]
Bi = 'Bi'[source]
Bk = 'Bk'[source]
Br = 'Br'[source]
C = 'C'[source]
Ca = 'Ca'[source]
Cd = 'Cd'[source]
Ce = 'Ce'[source]
Cf = 'Cf'[source]
Cl = 'Cl'[source]
Cm = 'Cm'[source]
Cn = 'Cn'[source]
Co = 'Co'[source]
Cr = 'Cr'[source]
Cs = 'Cs'[source]
Cu = 'Cu'[source]
Db = 'Db'[source]
Ds = 'Ds'[source]
Dy = 'Dy'[source]
Er = 'Er'[source]
Es = 'Es'[source]
Eu = 'Eu'[source]
F = 'F'[source]
Fe = 'Fe'[source]
Fl = 'Fl'[source]
Fm = 'Fm'[source]
Fr = 'Fr'[source]
Ga = 'Ga'[source]
Gd = 'Gd'[source]
Ge = 'Ge'[source]
H = 'H'[source]
He = 'He'[source]
Hf = 'Hf'[source]
Hg = 'Hg'[source]
Ho = 'Ho'[source]
Hs = 'Hs'[source]
I = 'I'[source]
In = 'In'[source]
Ir = 'Ir'[source]
K = 'K'[source]
Kr = 'Kr'[source]
La = 'La'[source]
Li = 'Li'[source]
Lr = 'Lr'[source]
Lu = 'Lu'[source]
Lv = 'Lv'[source]
Mc = 'Mc'[source]
Md = 'Md'[source]
Mg = 'Mg'[source]
Mn = 'Mn'[source]
Mo = 'Mo'[source]
Mt = 'Mt'[source]
N = 'N'[source]
Na = 'Na'[source]
Nb = 'Nb'[source]
Nd = 'Nd'[source]
Ne = 'Ne'[source]
Nh = 'Nh'[source]
Ni = 'Ni'[source]
No = 'No'[source]
Np = 'Np'[source]
O = 'O'[source]
Og = 'Og'[source]
Os = 'Os'[source]
P = 'P'[source]
Pa = 'Pa'[source]
Pb = 'Pb'[source]
Pd = 'Pd'[source]
Pm = 'Pm'[source]
Po = 'Po'[source]
Pr = 'Pr'[source]
Pt = 'Pt'[source]
Pu = 'Pu'[source]
Ra = 'Ra'[source]
Rb = 'Rb'[source]
Re = 'Re'[source]
Rf = 'Rf'[source]
Rg = 'Rg'[source]
Rh = 'Rh'[source]
Rn = 'Rn'[source]
Ru = 'Ru'[source]
S = 'S'[source]
Sb = 'Sb'[source]
Sc = 'Sc'[source]
Se = 'Se'[source]
Sg = 'Sg'[source]
Si = 'Si'[source]
Sm = 'Sm'[source]
Sn = 'Sn'[source]
Sr = 'Sr'[source]
Ta = 'Ta'[source]
Tb = 'Tb'[source]
Tc = 'Tc'[source]
Te = 'Te'[source]
Th = 'Th'[source]
Ti = 'Ti'[source]
Tl = 'Tl'[source]
Tm = 'Tm'[source]
Ts = 'Ts'[source]
U = 'U'[source]
V = 'V'[source]
W = 'W'[source]
Xe = 'Xe'[source]
Y = 'Y'[source]
Yb = 'Yb'[source]
Zn = 'Zn'[source]
Zr = 'Zr'[source]
class ElementBase(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Element class defined without any enum values so it can be subclassed.

This class is needed to get nested (as|from)_dict to work properly. All emmet classes that had Element classes required custom construction whereas this definition behaves more like dataclasses so serialization is less troublesome. There were many times where objects in as_dict serialized only when they were top level. See https://github.com/materialsproject/pymatgen/issues/2999.

Basic immutable element object with all relevant properties.

Only one instance of Element for each symbol is stored after creation, ensuring that a particular element behaves like a singleton. For all attributes, missing data (i.e., data for which is not available) is represented by a None unless otherwise stated.

Parameters:

symbol (str) – Element symbol, e.g., “H”, “Fe”

Z[source]

Atomic number.

Type:

int

symbol[source]

Element symbol.

Type:

str

long_name[source]

Long name for element. E.g., “Hydrogen”.

Type:

str

atomic_radius_calculated[source]

Calculated atomic radius for the element. This is the empirical value. Data is obtained from http://en.wikipedia.org/wiki/Atomic_radii_of_the_elements_(data_page).

Type:

float

van_der_waals_radius[source]

Van der Waals radius for the element. This is the empirical value determined from critical reviews of X-ray diffraction, gas kinetic collision cross-section, and other experimental data by Bondi and later workers. The uncertainty in these values is on the order of 0.1 Å. Data are obtained from “Atomic Radii of the Elements” in CRC Handbook of Chemistry and Physics, 91st Ed.; Haynes, W.M., Ed.; CRC Press: Boca Raton, FL, 2010.

Type:

float

mendeleev_no[source]

Mendeleev number from definition given by Pettifor, D. G. (1984). A chemical scale for crystal-structure maps. Solid State Communications, 51 (1), 31-34.

Type:

int

electrical_resistivity[source]

Electrical resistivity.

Type:

float

velocity_of_sound[source]

Velocity of sound.

Type:

float

reflectivity[source]

Reflectivity.

Type:

float

refractive_index[source]

Refractive index.

Type:

float

poissons_ratio[source]

Poisson’s ratio.

Type:

float

molar_volume[source]

Molar volume.

Type:

float

electronic_structure[source]

Electronic structure. E.g., The electronic structure for Fe is represented as [Ar].3d6.4s2.

Type:

str

atomic_orbitals[source]

Atomic Orbitals. Energy of the atomic orbitals as a dict. E.g., The orbitals energies in eV are represented as {‘1s’: -1.0, ‘2s’: -0.1}. Data is obtained from https://www.nist.gov/pml/data/atomic-reference-data-electronic-structure-calculations. The LDA values for neutral atoms are used.

Type:

dict

thermal_conductivity[source]

Thermal conductivity.

Type:

float

boiling_point[source]

Boiling point.

Type:

float

melting_point[source]

Melting point.

Type:

float

critical_temperature[source]

Critical temperature.

Type:

float

superconduction_temperature[source]

Superconduction temperature.

Type:

float

liquid_range[source]

Liquid range.

Type:

float

bulk_modulus[source]

Bulk modulus.

Type:

float

youngs_modulus[source]

Young’s modulus.

Type:

float

brinell_hardness[source]

Brinell hardness.

Type:

float

rigidity_modulus[source]

Rigidity modulus.

Type:

float

mineral_hardness[source]

Mineral hardness.

Type:

float

vickers_hardness[source]

Vicker’s hardness.

Type:

float

density_of_solid[source]

Density of solid phase.

Type:

float

coefficient_of_linear_thermal_expansion[source]

Coefficient of linear thermal expansion.

Type:

float

ground_level[source]

Ground level for element.

Type:

float

ionization_energies[source]

List of ionization energies. First value is the first ionization energy, second is the second ionization energy, etc. Note that this is zero-based indexing! So Element.ionization_energies[0] refer to the 1st ionization energy. Values are from the NIST Atomic Spectra Database. Missing values are None.

Type:

list[Optional[float]]

property X: float[source]

Pauling electronegativity of element. Note that if an element does not have an Pauling electronegativity, a NaN float is returned.

as_dict() dict[Literal['element', '@module', '@class'], str][source]

Makes Element obey the general json interface used in pymatgen for easier serialization.

property atomic_mass: FloatWithUnit[source]

Returns: float: The atomic mass of the element in amu.

property atomic_radius: FloatWithUnit | None[source]

Returns: float | None: The atomic radius of the element in Ångstroms. Can be None for some elements like noble gases.

property average_anionic_radius: float[source]

Average anionic radius for element (with units). The average is taken over all negative oxidation states of the element for which data is present.

property average_cationic_radius: FloatWithUnit[source]

Average cationic radius for element (with units). The average is taken over all positive oxidation states of the element for which data is present.

property average_ionic_radius: FloatWithUnit[source]

Average ionic radius for element (with units). The average is taken over all oxidation states of the element for which data is present.

property block: str[source]

Return the block character “s,p,d,f”.

property common_oxidation_states: tuple[int, ...][source]

Tuple of common oxidation states.

property data: dict[str, Any][source]

Returns dict of data for element.

property electron_affinity: float[source]

The amount of energy released when an electron is attached to a neutral atom.

property electronic_structure: str[source]

Electronic structure as string, with only valence electrons. E.g., The electronic structure for Fe is represented as ‘[Ar].3d6.4s2’.

static from_Z(Z: int) Element[source]

Get an element from an atomic number.

Parameters:

Z (int) – Atomic number

Returns:

Element with atomic number Z.

static from_dict(d) Element[source]

Makes Element obey the general json interface used in pymatgen for easier serialization.

static from_name(name: str) Element[source]

Get an element from its long name.

Parameters:

name – Long name of the element, e.g. ‘Hydrogen’ or ‘Iron’. Not case-sensitive.

Returns:

Element with the name ‘name’

static from_row_and_group(row: int, group: int) Element[source]

Returns an element from a row and group number. Important Note: For lanthanoids and actinoids, the row number must be 8 and 9, respectively, and the group number must be between 3 (La, Ac) and 17 (Lu, Lr). This is different than the value for Element(symbol).row and Element(symbol).group for these elements.

Parameters:
  • row (int) – (pseudo) row number. This is the standard row number except for the lanthanoids and actinoids for which it is 8 or 9, respectively.

  • group (int) – (pseudo) group number. This is the standard group number except for the lanthanoids and actinoids for which it is 3 (La, Ac) to 17 (Lu, Lr).

Note

The 18 group number system is used, i.e. noble gases are group 18.

property full_electronic_structure: list[tuple[int, str, int]][source]

Full electronic structure as tuple. E.g., The electronic structure for Fe is represented as: [(1, “s”, 2), (2, “s”, 2), (2, “p”, 6), (3, “s”, 2), (3, “p”, 6), (3, “d”, 6), (4, “s”, 2)].

property ground_state_term_symbol[source]

Ground state term symbol Selected based on Hund’s Rule.

property group: int[source]

Returns the periodic table group of the element. Note: For lanthanoids and actinoids, the group is always 3.

property icsd_oxidation_states: tuple[int, ...][source]

Tuple of all oxidation states with at least 10 instances in ICSD database AND at least 1% of entries for that element.

property ionic_radii: dict[int, float][source]

All ionic radii of the element as a dict of {oxidation state: ionic radii}. Radii are given in angstrom.

property ionization_energy: float | None[source]

First ionization energy of element.

property is_actinoid: bool[source]

True if element is a actinoid.

property is_alkali: bool[source]

True if element is an alkali metal.

property is_alkaline: bool[source]

True if element is an alkaline earth metal (group II).

property is_chalcogen: bool[source]

True if element is a chalcogen.

property is_halogen: bool[source]

True if element is a halogen.

property is_lanthanoid: bool[source]

True if element is a lanthanoid.

property is_metal: bool[source]

True if is a metal.

property is_metalloid: bool[source]

True if element is a metalloid.

property is_noble_gas: bool[source]

True if element is noble gas.

property is_post_transition_metal: bool[source]

True if element is a post-transition or poor metal.

property is_quadrupolar: bool[source]

Checks if this element can be quadrupolar.

property is_rare_earth_metal: bool[source]

True if element is a rare earth metal.

property is_transition_metal: bool[source]

True if element is a transition metal.

static is_valid_symbol(symbol: str) bool[source]

Returns true if symbol is a valid element symbol.

Parameters:

symbol (str) – Element symbol

Returns:

True if symbol is a valid element (e.g., “H”).

Return type:

bool

property iupac_ordering[source]

Ordering according to Table VI of “Nomenclature of Inorganic Chemistry (IUPAC Recommendations 2005)”. This ordering effectively follows the groups and rows of the periodic table, except the Lanthanides, Actinides and hydrogen.

property max_oxidation_state: float[source]

Maximum oxidation state for element.

property min_oxidation_state: float[source]

Minimum oxidation state for element.

property nmr_quadrupole_moment: dict[str, FloatWithUnit][source]

Get a dictionary the nuclear electric quadrupole moment in units of e*millibarns for various isotopes.

property number: int[source]

Alternative attribute for atomic number Z.

property oxidation_states: tuple[int, ...][source]

Tuple of all known oxidation states.

static print_periodic_table(filter_function: Callable | None = None)[source]

A pretty ASCII printer for the periodic table, based on some filter_function.

Parameters:

filter_function – A filtering function taking an Element as input and returning a boolean. For example, setting filter_function = lambda el: el.X > 2 will print a periodic table containing only elements with Pauling electronegativity > 2.

property row: int[source]

Returns the periodic table row of the element. Note: For lanthanoids and actinoids, the row is always 6 or 7, respectively.

property term_symbols: list[list[str]][source]

All possible Russell-Saunders term symbol of the Element. eg. L = 1, n_e = 2 (s2) returns [[‘1D2’], [‘3P0’, ‘3P1’, ‘3P2’], [‘1S0’]].

property valence[source]

From full electron config obtain valence subshell angular moment (L) and number of valence e- (v_e).

class Specie(symbol: SpeciesLike, oxidation_state: float | None = None, spin: float | None = None)[source]

Bases: Species

This maps the historical grammatically inaccurate Specie to Species to maintain backwards compatibility.

Parameters:
  • symbol (str) – Element symbol optionally incl. oxidation state. E.g. Fe, Fe2+, O2-.

  • oxidation_state (float) – Explicit oxidation state of element, e.g. -2, -1, 0, 1, 2, … If oxidation state is present in symbol, this argument is ignored.

  • spin – Spin associated with Species. Defaults to None.

Raises:

ValueError – If oxidation state passed both in symbol string and via oxidation_state kwarg.

class Species(symbol: SpeciesLike, oxidation_state: float | None = None, spin: float | None = None)[source]

Bases: MSONable, Stringify

An extension of Element with optional oxidation state and spin. Properties associated with Species should be “idealized” values, not calculated values. For example, high-spin Fe2+ may be assigned an idealized spin of +5, but an actual Fe2+ site may be calculated to have a magmom of +4.5. Calculated properties should be assigned to Site objects, and not Species.

Parameters:
  • symbol (str) – Element symbol optionally incl. oxidation state. E.g. Fe, Fe2+, O2-.

  • oxidation_state (float) – Explicit oxidation state of element, e.g. -2, -1, 0, 1, 2, … If oxidation state is present in symbol, this argument is ignored.

  • spin – Spin associated with Species. Defaults to None.

Raises:

ValueError – If oxidation state passed both in symbol string and via oxidation_state kwarg.

STRING_MODE = 'SUPERSCRIPT'[source]
as_dict() dict[source]

Json-able dictionary representation.

property element: Element[source]

Underlying element object.

classmethod from_dict(d) Species[source]
Parameters:

d – Dict representation.

Returns:

Species.

static from_str(species_string: str) Species[source]

Returns a Species from a string representation.

Parameters:

species_string (str) – A typical string representation of a species, e.g., “Mn2+”, “Fe3+”, “O2-“.

Returns:

A Species object.

Raises:

ValueError if species_string cannot be interpreted.

classmethod from_string(*args, **kwargs)[source]

from_string is deprecated! Use from_str instead

Use from_str instead.

get_crystal_field_spin(coordination: Literal['oct', 'tet'] = 'oct', spin_config: Literal['low', 'high'] = 'high') float[source]

Calculate the crystal field spin based on coordination and spin configuration. Only works for transition metal species.

Parameters:
  • coordination ("oct" | "tet") – Tetrahedron or octahedron crystal site coordination

  • spin_config ("low" | "high") – Whether the species is in a high or low spin state

Returns:

Crystal field spin in Bohr magneton.

Raises:
  • AttributeError if species is not a valid transition metal or has – an invalid oxidation state.

  • ValueError if invalid coordination or spin_config.

get_nmr_quadrupole_moment(isotope: str | None = None) float[source]

Gets the nuclear electric quadrupole moment in units of e * millibarns.

Parameters:

isotope (str) – the isotope to get the quadrupole moment for default is None, which gets the lowest mass isotope

get_shannon_radius(cn: str, spin: Literal['', 'Low Spin', 'High Spin'] = '', radius_type: Literal['ionic', 'crystal'] = 'ionic') float[source]

Get the local environment specific ionic radius for species.

Parameters:
  • cn (str) – Coordination using roman letters. Supported values are I-IX, as well as IIIPY, IVPY and IVSQ.

  • spin (str) – Some species have different radii for different spins. You can get specific values using “High Spin” or “Low Spin”. Leave it as “” if not available. If only one spin data is available, it is returned and this spin parameter is ignored.

  • radius_type (str) – Either “crystal” or “ionic” (default).

Returns:

Shannon radius for specie in the specified environment.

property ionic_radius: float | None[source]

Ionic radius of specie. Returns None if data is not present.

property oxi_state: float | None[source]

Oxidation state of Species.

property spin: float | None[source]

Spin of Species.

to_pretty_string() str[source]

String without properties.

get_el_sp(obj: int | SpeciesLike) Element | Species | DummySpecies[source]

Utility method to get an Element, Species or DummySpecies from any input.

If obj is in itself an element or a specie, it is returned automatically. If obj is an int or a string representing an integer, the Element with the atomic number obj is returned. If obj is a string, Species parsing will be attempted (e.g. Mn2+). Failing that Element parsing will be attempted (e.g. Mn). Failing that DummyElement parsing will be attempted.

Parameters:

obj (Element/Species/str/int) – An arbitrary object. Supported objects are actual Element/Species objects, integers (representing atomic numbers) or strings (element symbols or species strings).

Raises:

ValueError – if obj cannot be converted into an Element or Species.

Returns:

with a bias for the maximum number of properties

that can be determined.

Return type:

Species | Element

pymatgen.core.sites module

This module defines classes representing non-periodic and periodic sites.

class PeriodicSite(species: SpeciesLike | CompositionLike, coords: ArrayLike, lattice: Lattice, to_unit_cell: bool = False, coords_are_cartesian: bool = False, properties: dict | None = None, label: str | None = None, skip_checks: bool = False)[source]

Bases: Site, MSONable

Extension of generic Site object to periodic systems. PeriodicSite includes a lattice system.

Create a periodic site.

Parameters:
  • species

    Species on the site. Can be: i. A Composition-type object (preferred) ii. An element / species specified either as a string

    symbols, e.g. “Li”, “Fe2+”, “P” or atomic numbers, e.g., 3, 56, or actual Element or Species objects.

    iii.Dict of elements/species and occupancies, e.g.,

    {“Fe” : 0.5, “Mn”:0.5}. This allows the setup of disordered structures.

  • coords – Coordinates of site, fractional coordinates by default. See coords_are_cartesian for more details.

  • lattice – Lattice associated with the site.

  • to_unit_cell – Translates fractional coordinate to the basic unit cell, i.e. all fractional coordinates satisfy 0 <= a < 1. Defaults to False.

  • coords_are_cartesian – Set to True if you are providing Cartesian coordinates. Defaults to False.

  • properties – Properties associated with the site as a dict, e.g. {“magmom”: 5}. Defaults to None.

  • label – Label for the site. Defaults to None.

  • skip_checks – Whether to ignore all the usual checks and just create the site. Use this if the PeriodicSite is created in a controlled manner and speed is desired.

property a: float[source]

Fractional a coordinate.

as_dict(verbosity: int = 0) dict[source]

JSON-serializable dict representation of PeriodicSite.

Parameters:

verbosity (int) – Verbosity level. Default of 0 only includes the matrix representation. Set to 1 for more details such as Cartesian coordinates, etc.

property b: float[source]

Fractional b coordinate.

property c: float[source]

Fractional c coordinate.

property coords: ndarray[source]

Cartesian coordinates.

distance(other: PeriodicSite, jimage: ArrayLike | None = None)