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: dict = None)[source]¶ 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: dict = None)[source]¶ 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.
-
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.
- 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
[source]¶ 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
[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.
-
-
class
Element
(value)[source]¶ 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”
-
X
[source]¶ Pauling electronegativity. Elements without an electronegativity number are assigned a value of zero by default.
-
full_electronic_structure
[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)]
-
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, Actanides and hydrogen.
-
atomic_radius
[source]¶ 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).
-
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).
-
van_der_waals_radius
[source]¶ Van der Waals 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).
-
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
-
electronic_structure
[source]¶ Electronic structure. E.g., The electronic structure for Fe is represented as [Ar].3d6.4s2
-
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
-
average_ionic_radius
[source]¶ Average ionic radius for element in ang. The average is taken over all oxidation states of the element for which data is present.
-
average_cationic_radius
[source]¶ Average cationic radius for element in ang. The average is taken over all positive oxidation states of the element for which data is present.
-
average_anionic_radius
[source]¶ Average ionic radius for element in ang. The average is taken over all negative oxidation states of the element for which data is present.
-
class
ElementBase
(value)[source]¶ 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”
-
X
[source]¶ Pauling electronegativity. Elements without an electronegativity number are assigned a value of zero by default.
-
full_electronic_structure
[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)]
-
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, Actanides and hydrogen.
-
atomic_radius
[source]¶ 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).
-
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).
-
van_der_waals_radius
[source]¶ Van der Waals 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).
-
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
-
electronic_structure
[source]¶ Electronic structure. E.g., The electronic structure for Fe is represented as [Ar].3d6.4s2
-
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
-
average_ionic_radius
[source]¶ Average ionic radius for element in ang. The average is taken over all oxidation states of the element for which data is present.
-
average_cationic_radius
[source]¶ Average cationic radius for element in ang. The average is taken over all positive oxidation states of the element for which data is present.
-
average_anionic_radius
[source]¶ Average ionic radius for element in ang. The average is taken over all negative oxidation states of the element for which data is present.
-
ionic_radii
[source]¶ All ionic radii of the element as a dict of {oxidation state: ionic radii}. Radii are given in ang.
-
property
X
[source]¶ Electronegativity of element. Note that if an element does not have an electronegativity, a NaN float is returned.
- Type
return
-
as_dict
()[source]¶ Makes Element obey the general json interface used in pymatgen for easier serialization.
-
property
average_anionic_radius
[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
[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
[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
electronic_structure
[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)[source]¶ Get an element from an atomic number.
- Parameters
z (int) – Atomic number
- Returns
Element with atomic number z.
-
static
from_dict
(d)[source]¶ Makes Element obey the general json interface used in pymatgen for easier serialization.
-
static
from_row_and_group
(row: int, group: int)[source]¶ 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
[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
icsd_oxidation_states
[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
[source]¶ All ionic radii of the element as a dict of {oxidation state: ionic radii}. Radii are given in ang.
-
static
is_valid_symbol
(symbol: str)[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”). False otherwise (e.g., “Zebra”).
-
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, Actanides and hydrogen.
-
property
nmr_quadrupole_moment
[source]¶ Get a dictionary the nuclear electric quadrupole moment in units of e*millibarns for various isotopes
-
static
print_periodic_table
(filter_function: Optional[Callable] = 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 electronegativity > 2.
-
class
Specie
(symbol: str, oxidation_state: Optional[float] = 0.0, properties: dict = None)[source]¶ 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.
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: dict = None)[source]¶ Bases:
monty.json.MSONable
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.
Changed in version 2.6.7: Properties are now checked when comparing two Species for equality.
-
static
from_string
(species_string: str)[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 intepreted. –
-
get_crystal_field_spin
(coordination: str = 'oct', spin_config: str = 'high')[source]¶ Calculate the crystal field spin based on coordination and spin configuration. Only works for transition metal species.
- Parameters
coordination (str) – Only oct and tet are supported at the moment.
spin_config (str) – Supported keywords are “high” or “low”.
- 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=None)[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: str = '', radius_type: str = 'ionic')[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.
-
get_el_sp
(obj)[source]¶ 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. –