src.easycrystallography.Elements
periodic_table
DummySpecie
Bases: DummySpecies
This maps the historical grammatically inaccurate DummySpecie to DummySpecies to maintain backwards compatibility.
DummySpecies
Bases: Species
A special specie for representing non-traditional elements or species. For example, representation of vacancies (charged or otherwise), or special sites, etc.
.. attribute:: oxi_state
Oxidation state associated with Species.
.. attribute:: 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.
.. attribute:: X
DummySpecies is always assigned an electronegativity of 0.
X: float
property
DummySpecies is always assigned an electronegativity of 0. The effect of this is that DummySpecies are always sorted in front of actual Species.
Z: int
property
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.
oxi_state: Optional[float]
property
Oxidation state associated with DummySpecies
symbol: str
property
:return: Symbol for DummySpecies.
__eq__(other)
Species is equal to other only if element and oxidation states are exactly the same.
__init__(symbol='X', oxidation_state=0, properties=None)
Parameters:
Name | Type | Description | Default |
---|---|---|---|
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. |
'X'
|
oxidation_state
|
float
|
Oxidation state for dummy specie. Defaults to zero. |
0
|
__lt__(other)
Sets a default sort order for atomic species by electronegativity, followed by oxidation state.
as_dict()
:return: MSONAble dict representation.
from_dict(d, skip=None)
classmethod
:param d: Dict representation :return: DummySpecies
from_string(species_string)
staticmethod
Returns a Dummy from a string representation.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
species_string
|
str
|
A string representation of a dummy species, e.g., "X2+", "X3+". |
required |
Returns:
Type | Description |
---|---|
A DummySpecies object. |
Element
Bases: Enum
Enum representing an element in the periodic table.
X
property
:return: Electronegativity of element. Note that if an element does not have an electronegativity, a NaN float is returned.
atomic_mass
property
Returns: The atomic mass of the element in amu.
atomic_radius
property
Returns: The atomic radius of the element in Ångstroms.
average_anionic_radius
property
Average anionic radius for element (with units). The average is taken over all negative oxidation states of the element for which data is present.
average_cationic_radius
property
Average cationic radius for element (with units). The average is taken over all positive oxidation states of the element for which data is present.
average_ionic_radius
property
Average ionic radius for element (with units). The average is taken over all oxidation states of the element for which data is present.
block
property
Return the block character "s,p,d,f"
common_oxidation_states
property
Tuple of all known oxidation states
data: dict
property
Returns dict of data for element.
electronic_structure: str
property
Electronic structure as string, with only valence electrons. E.g., The electronic structure for Fe is represented as '[Ar].3d6.4s2'
full_electronic_structure
property
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)]
ground_state_term_symbol
property
Ground state term symbol Selected based on Hund's Rule
group
property
Returns the periodic table group of the element.
icsd_oxidation_states
property
Tuple of all oxidation states with at least 10 instances in ICSD database AND at least 1% of entries for that element
ionic_radii
property
All ionic radii of the element as a dict of {oxidation state: ionic radii}. Radii are given in ang.
is_actinoid
property
True if element is a actinoid.
is_alkali: bool
property
True if element is an alkali metal.
is_alkaline: bool
property
True if element is an alkaline earth metal (group II).
is_chalcogen
property
True if element is a chalcogen.
is_halogen
property
True if element is a halogen.
is_lanthanoid
property
True if element is a lanthanoid.
is_metal: bool
property
:return: True if is a metal.
is_metalloid: bool
property
True if element is a metalloid.
is_noble_gas
property
True if element is noble gas.
is_post_transition_metal
property
True if element is a post-transition or poor metal.
is_quadrupolar
property
Checks if this element can be quadrupolar
is_rare_earth_metal: bool
property
True if element is a rare earth metal.
is_transition_metal
property
True if element is a transition metal.
iupac_ordering
property
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.
max_oxidation_state
property
Maximum oxidation state for element
metallic_radius
property
Metallic radius of the element. Radius is given in ang.
min_oxidation_state
property
Minimum oxidation state for element
nmr_quadrupole_moment
property
Get a dictionary the nuclear electric quadrupole moment in units of e*millibarns for various isotopes
number
property
Alternative attribute for atomic number
oxidation_states
property
Tuple of all known oxidation states
row
property
Returns the periodic table row of the element.
term_symbols
property
All possible Russell-Saunders term symbol of the Element eg. L = 1, n_e = 2 (s2) returns [['1D2'], ['3P0', '3P1', '3P2'], ['1S0']]
valence
property
From full electron config obtain valence subshell
angular moment (L) and number of valence e- (v_e)
__init__(symbol)
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:
Name | Type | Description | Default |
---|---|---|---|
symbol
|
str
|
Element symbol, e.g., "H", "Fe" |
required |
.. attribute:: Z
Atomic number
.. attribute:: symbol
Element symbol
.. attribute:: X
Pauling electronegativity. Elements without an electronegativity
number are assigned a value of zero by default.
.. attribute:: number
Alternative attribute for atomic number
.. attribute:: max_oxidation_state
Maximum oxidation state for element
.. attribute:: min_oxidation_state
Minimum oxidation state for element
.. attribute:: oxidation_states
Tuple of all known oxidation states
.. attribute:: common_oxidation_states
Tuple of all common oxidation states
.. attribute:: full_electronic_structure
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)]
.. attribute:: row
Returns the periodic table row of the element.
.. attribute:: group
Returns the periodic table group of the element.
.. attribute:: block
Return the block character "s,p,d,f"
.. attribute:: is_noble_gas
True if element is noble gas.
.. attribute:: is_transition_metal
True if element is a transition metal.
.. attribute:: is_post_transition_metal
True if element is a post transition metal.
.. attribute:: is_rare_earth_metal
True if element is a rare earth metal.
.. attribute:: is_metalloid
True if element is a metalloid.
.. attribute:: is_alkali
True if element is an alkali metal.
.. attribute:: is_alkaline
True if element is an alkaline earth metal (group II).
.. attribute:: is_halogen
True if element is a halogen.
.. attribute:: is_lanthanoid
True if element is a lanthanoid.
.. attribute:: is_actinoid
True if element is a actinoid.
.. attribute:: 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.
.. attribute:: long_name
Long name for element. E.g., "Hydrogen".
.. attribute:: atomic_mass
Atomic mass for the element.
.. attribute:: atomic_radius
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).
.. attribute:: 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).
.. attribute:: van_der_waals_radius
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).
.. attribute:: 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
.. attribute:: electrical_resistivity
Electrical resistivity
.. attribute:: velocity_of_sound
Velocity of sound
.. attribute:: reflectivity
Reflectivity
.. attribute:: refractive_index
Refractice index
.. attribute:: poissons_ratio
Poisson's ratio
.. attribute:: molar_volume
Molar volume
.. attribute:: electronic_structure
Electronic structure.
E.g., The electronic structure for Fe is represented as
[Ar].3d6.4s2
.. attribute:: 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
.. attribute:: thermal_conductivity
Thermal conductivity
.. attribute:: boiling_point
Boiling point
.. attribute:: melting_point
Melting point
.. attribute:: critical_temperature
Critical temperature
.. attribute:: superconduction_temperature
Superconduction temperature
.. attribute:: liquid_range
Liquid range
.. attribute:: bulk_modulus
Bulk modulus
.. attribute:: youngs_modulus
Young's modulus
.. attribute:: brinell_hardness
Brinell hardness
.. attribute:: rigidity_modulus
Rigidity modulus
.. attribute:: mineral_hardness
Mineral hardness
.. attribute:: vickers_hardness
Vicker's hardness
.. attribute:: density_of_solid
Density of solid phase
.. attribute:: coefficient_of_linear_thermal_expansion
Coefficient of linear thermal expansion
.. attribute:: average_ionic_radius
Average ionic radius for element in ang. The average is taken over all
oxidation states of the element for which data is present.
.. attribute:: average_cationic_radius
Average cationic radius for element in ang. The average is taken over all
positive oxidation states of the element for which data is present.
.. attribute:: average_anionic_radius
Average ionic radius for element in ang. The average is taken over all
negative oxidation states of the element for which data is present.
.. attribute:: ionic_radii
All ionic radii of the element as a dict of
{oxidation state: ionic radii}. Radii are given in ang.
__lt__(other)
Sets a default sort order for atomic species by electronegativity. Very useful for getting correct formulas. For example, FeO4PLi is automatically sorted into LiFePO4.
as_dict(skip=None)
Makes Element obey the general json interface used in pymatgen for easier serialization.
from_Z(z)
staticmethod
Get an element from an atomic number.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
z
|
int
|
Atomic number |
required |
Returns:
Type | Description |
---|---|
Element with atomic number z. |
from_dict(d)
staticmethod
Makes Element obey the general json interface used in pymatgen for easier serialization.
from_row_and_group(row, group)
staticmethod
Returns an element from a row and group number.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
row
|
int
|
Row number |
required |
group
|
int
|
Group number |
required |
.. note:: The 18 group number system is used, i.e., Noble gases are group 18.
is_valid_symbol(symbol)
staticmethod
Returns true if symbol is a valid element symbol.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
symbol
|
str
|
Element symbol |
required |
Returns:
Type | Description |
---|---|
True if symbol is a valid element (e.g., "H"). False otherwise |
|
(e.g., "Zebra"). |
print_periodic_table(filter_function=None)
staticmethod
A pretty ASCII printer for the periodic table, based on some filter_function.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
filter_function
|
Optional[Callable]
|
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. |
None
|
Specie
Bases: Species
This maps the historical grammatically inaccurate Specie to Species to maintain backwards compatibility.
Species
Bases: ComponentSerializer
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.
element
property
Underlying element object
ionic_radius
property
Ionic radius of specie. Returns None if data is not present.
oxi_state
property
Oxidation state of Species.
__eq__(other)
Species is equal to other only if element and oxidation states are exactly the same.
__hash__()
Equal Species should have the same str representation, hence should hash equally. Unequal Species will have differnt str representations.
__init__(symbol, oxidation_state=0.0, properties=None)
Initializes a Species.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
symbol
|
str
|
Element symbol, e.g., Fe |
required |
oxidation_state
|
float
|
Oxidation state of element, e.g., 2 or -2 |
0.0
|
properties
|
dict
|
Properties associated with the Species, e.g., {"spin": 5}. Defaults to None. Properties must be one of the Species supported_properties. |
None
|
.. attribute:: oxi_state
Oxidation state associated with Species
.. attribute:: ionic_radius
Ionic radius of Species (with specific oxidation state).
.. versionchanged:: 2.6.7
Properties are now checked when comparing two Species for equality.
__lt__(other)
Sets a default sort order for atomic species by electronegativity, followed by oxidation state, followed by spin.
as_dict(skip=None)
:return: Json-able dictionary representation.
from_dict(d)
classmethod
:param d: Dict representation. :return: Species.
from_string(species_string)
staticmethod
Returns a Species from a string representation.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
species_string
|
str
|
A typical string representation of a species, e.g., "Mn2+", "Fe3+", "O2-". |
required |
Returns:
Type | Description |
---|---|
A Species object. |
get_crystal_field_spin(coordination='oct', spin_config='high')
Calculate the crystal field spin based on coordination and spin configuration. Only works for transition metal species.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
coordination
|
str
|
Only oct and tet are supported at the moment. |
'oct'
|
spin_config
|
str
|
Supported keywords are "high" or "low". |
'high'
|
Returns:
Type | Description |
---|---|
Crystal field spin in Bohr magneton. |
get_nmr_quadrupole_moment(isotope=None)
Gets the nuclear electric quadrupole moment in units of e*millibarns
Parameters:
Name | Type | Description | Default |
---|---|---|---|
isotope
|
str
|
the isotope to get the quadrupole moment for default is None, which gets the lowest mass isotope |
None
|
get_shannon_radius(cn, spin='', radius_type='ionic')
Get the local environment specific ionic radius for species.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
cn
|
str
|
Coordination using roman letters. Supported values are I-IX, as well as IIIPY, IVPY and IVSQ. |
required |
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). |
'ionic'
|
Returns:
Type | Description |
---|---|
Shannon radius for specie in the specified environment. |
formula_double_format(afloat, ignore_ones=True, tol=1e-08)
This function is used to make pretty formulas by formatting the amounts. Instead of Li1.0 Fe1.0 P1.0 O4.0, you get LiFePO4. Args: afloat (float): a float ignore_ones (bool): if true, floats of 1 are ignored. tol (float): Tolerance to round to nearest int. i.e. 2.0000000001 -> 2 Returns: A string representation of the float for formulas.
get_el_sp(obj)
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:
Name | Type | Description | Default |
---|---|---|---|
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). |
required |
Returns:
Type | Description |
---|---|
Species or Element, with a bias for the maximum number of properties |
|
that can be determined. |