# pymatgen.core.periodic_table module

Module contains classes presenting Element and Species (Element + oxidation state) and PeriodicTable.

class DummySpecie(symbol: str = 'X', oxidation_state: Optional[float] = 0, properties: Optional[dict] = None)

  Bases: `pymatgen.core.periodic_table.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 zero.

class DummySpecies(symbol: str = 'X', oxidation_state: Optional[float] = 0, properties: Optional[dict] = None)

  Bases: `pymatgen.core.periodic_table.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

    Oxidation state associated with Species.

  Z

    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.

  X

    DummySpecies is always assigned an electronegativity of 0.

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

  property X: float

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

  property Z: int

    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
    Returns

      MSONAble dict representation.

  classmethod from_dict(d) → pymatgen.core.periodic_table.DummySpecies
    Parameters

      d – Dict representation

    Returns

      DummySpecies

  static from_string(species_string: str) → pymatgen.core.periodic_table.DummySpecies

    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 intepreted. –

  property oxi_state: Optional[float]

    Oxidation state associated with DummySpecies

  property symbol: str

    Symbol for DummySpecies.

    Type

      return

class Element(value)

  Bases: `pymatgen.core.periodic_table.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

    Atomic number

  symbol

    Element symbol

  long_name

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

  atomic_radius_calculated

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

  van_der_waals_radius

    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.

  mendeleev_no

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

  electrical_resistivity

    Electrical resistivity

  velocity_of_sound

    Velocity of sound

  reflectivity

    Reflectivity

  refractive_index

    Refractice index

  poissons_ratio

    Poisson’s ratio

  molar_volume

    Molar volume

  electronic_structure

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

  atomic_orbitals

    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

  thermal_conductivity

    Thermal conductivity

  boiling_point

    Boiling point

  melting_point

    Melting point

  critical_temperature

    Critical temperature

  superconduction_temperature

    Superconduction temperature

  liquid_range

    Liquid range

  bulk_modulus

    Bulk modulus

  youngs_modulus

    Young’s modulus

  brinell_hardness

    Brinell hardness

  rigidity_modulus

    Rigidity modulus

  mineral_hardness

    Mineral hardness

  vickers_hardness

    Vicker’s hardness

  density_of_solid

    Density of solid phase

  coefficient_of_linear_thermal_expansion

    Coefficient of linear thermal expansion

  ground_level

    Ground level for element

  ionization_energies

    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.

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

class ElementBase(value)

  Bases: `enum.Enum`

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

  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

    Atomic number

  symbol

    Element symbol

  long_name

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

  atomic_radius_calculated

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

  van_der_waals_radius

    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.

  mendeleev_no

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

  electrical_resistivity

    Electrical resistivity

  velocity_of_sound

    Velocity of sound

  reflectivity

    Reflectivity

  refractive_index

    Refractice index

  poissons_ratio

    Poisson’s ratio

  molar_volume

    Molar volume

  electronic_structure

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

  atomic_orbitals

    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

  thermal_conductivity

    Thermal conductivity

  boiling_point

    Boiling point

  melting_point

    Melting point

  critical_temperature

    Critical temperature

  superconduction_temperature

    Superconduction temperature

  liquid_range

    Liquid range

  bulk_modulus

    Bulk modulus

  youngs_modulus

    Young’s modulus

  brinell_hardness

    Brinell hardness

  rigidity_modulus

    Rigidity modulus

  mineral_hardness

    Mineral hardness

  vickers_hardness

    Vicker’s hardness

  density_of_solid

    Density of solid phase

  coefficient_of_linear_thermal_expansion

    Coefficient of linear thermal expansion

  ground_level

    Ground level for element

  ionization_energies

    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.

  property X: float

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

    Type

      return

  as_dict() → dict

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

  property atomic_mass: Optional[pymatgen.core.units.FloatWithUnit]

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

  property atomic_radius: Optional[pymatgen.core.units.FloatWithUnit]

    Returns: float | None: The atomic radius of the element in Ångstroms.

  property average_anionic_radius: float

    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: pymatgen.core.units.FloatWithUnit

    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: pymatgen.core.units.FloatWithUnit

    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

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

  property common_oxidation_states: Tuple

    Tuple of common oxidation states

  property data: dict

    Returns dict of data for element.

  property electron_affinity: float

    First ionization energy of element.

  property electronic_structure: str

    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) → pymatgen.core.periodic_table.Element

    Get an element from an atomic number.

    Parameters

      z (int) – Atomic number

    Returns

      Element with atomic number z.

  static from_dict(d) → pymatgen.core.periodic_table.Element

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

  static from_row_and_group(row: int, group: int) → pymatgen.core.periodic_table.Element

    Returns an element from a row and group number.

    Parameters

      - row (int) – Row number

      - group (int) – Group number

    Note

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

  property full_electronic_structure: List[Tuple[int, str, int]]

    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

    Ground state term symbol Selected based on Hund’s Rule

  property group: int

    Returns the periodic table group of the element.

  property icsd_oxidation_states: Tuple

    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]

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

  property ionization_energy: float

    First ionization energy of element.

  property is_actinoid: bool

    True if element is a actinoid.

  property is_alkali: bool

    True if element is an alkali metal.

  property is_alkaline: bool

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

  property is_chalcogen: bool

    True if element is a chalcogen.

  property is_halogen: bool

    True if element is a halogen.

  property is_lanthanoid: bool

    True if element is a lanthanoid.

  property is_metal: bool

    True if is a metal.

    Type

      return

  property is_metalloid: bool

    True if element is a metalloid.

  property is_noble_gas: bool

    True if element is noble gas.

  property is_post_transition_metal: bool

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

  property is_quadrupolar: bool

    Checks if this element can be quadrupolar

  property is_rare_earth_metal: bool

    True if element is a rare earth metal.

  property is_transition_metal: bool

    True if element is a transition metal.

  static is_valid_symbol(symbol: str) → bool

    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”). False otherwise (e.g., “Zebra”).

  property iupac_ordering

    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, Actanides and hydrogen.

  property max_oxidation_state: float

    Maximum oxidation state for element

  property metallic_radius: float

    Metallic radius of the element. Radius is given in ang.

  property min_oxidation_state: float

    Minimum oxidation state for element

  property nmr_quadrupole_moment: dict

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

  property number: int

    Alternative attribute for atomic number

  property oxidation_states: Tuple

    Tuple of all known oxidation states

  static print_periodic_table(filter_function: Optional[Callable] = None)

    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 electronegativity > 2.

  property row: int

    Returns the periodic table row of the element.

  property term_symbols: List[List[str]]

    All possible Russell-Saunders term symbol of the Element eg. L = 1, n_e = 2 (s2) returns

    > [[‘1D2’], [‘3P0’, ‘3P1’, ‘3P2’], [‘1S0’]]

  property valence

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

class Specie(symbol: str, oxidation_state: Optional[float] = 0.0, properties: Optional[dict] = None)

  Bases: `pymatgen.core.periodic_table.Species`

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

  Initializes a Species.

  Parameters

    - symbol (str) – Element symbol, e.g., Fe

    - oxidation_state (float) – Oxidation state of element, e.g., 2 or -2

    - properties – Properties associated with the Species, e.g., {“spin”: 5}. Defaults to None. Properties must be one of the Species supported_properties.

  oxi_state

    Oxidation state associated with Species

  ionic_radius

    Ionic radius of Species (with specific oxidation state).

  Changed in version 2.6.7: Properties are now checked when comparing two Species for equality.

class Species(symbol: str, oxidation_state: Optional[float] = 0.0, properties: Optional[dict] = None)

  Bases: `monty.json.MSONable`, `pymatgen.util.string.Stringify`

  An extension of Element with an oxidation state and other optional properties. 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.

  Initializes a Species.

  Parameters

    - symbol (str) – Element symbol, e.g., Fe

    - oxidation_state (float) – Oxidation state of element, e.g., 2 or -2

    - properties – Properties associated with the Species, e.g., {“spin”: 5}. Defaults to None. Properties must be one of the Species supported_properties.

  oxi_state

    Oxidation state associated with Species

  ionic_radius

    Ionic radius of Species (with specific oxidation state).

  Changed in version 2.6.7: Properties are now checked when comparing two Species for equality.

  STRING_MODE = 'SUPERSCRIPT'
  as_dict() → dict
    Returns

      Json-able dictionary representation.

  property element

    Underlying element object

  classmethod from_dict(d) → pymatgen.core.periodic_table.Species
    Parameters

      d – Dict representation.

    Returns

      Species.

  static from_string(species_string: str) → pymatgen.core.periodic_table.Species

    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 intepreted. –

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

    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: Optional[str] = None) → float

    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

    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: Optional[float]

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

  property oxi_state: Optional[float]

    Oxidation state of Species.

  supported_properties = ('spin',)
  to_pretty_string() → str
    Returns

      String without properties.

get_el_sp(obj) → Union[pymatgen.core.periodic_table.Element, pymatgen.core.periodic_table.Species, pymatgen.core.periodic_table.DummySpecies]

  Utility method to get an Element or Species from an input obj. 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 which Element parsing will be attempted (e.g., Mn), failing which 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).

  Returns

    Species or Element, with a bias for the maximum number of properties that can be determined.

  Raises

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