API Reference

Accessing data

Elements

The easiest way to access individual elements is simply by importing them from the mendeleev directly using their symbols:

>>> from mendeleev import H, C, O, Og
>>> [x.name for x in [H, C, O, Og]]
['Hydrogen', 'Carbon', 'Oxygen', 'Oganesson']

An alternative method of access is through the element() function that returns either a single Element instance or a tuple of those instances depending on the input. It provides a more flexible interface since it accepts element names, atomic numbers and symbols as well as their combinations.

element(ids)[source]

Based on the type of the ids identifier return either an Element object from the database, or a list of Element objects if the ids is a list or a tuple of identifiers. Valid identifiers for an element are: name, symbol, and atomic number.

Args:
ids (str): element identifier
Raises:
ValueError: when the identifier is not a list/tuple, int or str
Example:

The element can be identified by symbol

>>> from mendeleev import element
>>> si = element('Si')
>>> si.atomic_number
14

by the atomic number

>>> al = element(13)
>>> al.name
'Aluminum'

or by the name

>>> o = element('Oxygen')
>>> o.symbol
'O'

Mutiple elements can be instantiated simultaneously through as combination of identifiers

>>> c, h, o = element(['C', 'Hydrogen', 8])
>>> print(c.name, h.name, o.name)
Carbon Hydrogen Oxygen

Tables

If you want a whole set of data you can retrieve one of the tables from the database as pandas DataFrame through the get_table. The following tables are available:

get_table(tablename, **kwargs)[source]

Return a table from the database as pandas DataFrame

Args:
tablename: str
Name of the table from the database
kwargs:
A dictionary of keyword arguments to pass to the pandas.read_qsl
Returns:
df: pandas.DataFrame
Pandas DataFrame with the contents of the table
Example:
>>> from mendeleev import get_table
>>> df = get_table('elements')
>>> type(df)
pandas.core.frame.DataFrame

Database session and engine

For those how want to interact with the database through a layer of SQLAlchemy there are methods for getting the session or the engine:

get_session(dbpath=None)[source]

Return the database session connection.

get_engine(dbpath=None)[source]

Return the db engine

Classes

Element

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

Chemical element.

Attributes:
abundance_crust : float
Abundance in the earth’s crust in mg/kg
abundance_sea : float
Abundance in the seas in mg/L
annotation : str
Annotations regarding the data
atomic_number : int
Atomic number
atomic_radius : float
Atomic radius in pm
atomic_radius_rahm : float
Atomic radius by Rahm et al. in pm
atomic_volume : float
Atomic volume in cm3/mol
atomic_weight : float
Relative atomic weight as the ratio of the average mass of atoms of the element to 1/12 of the mass of an atom of 12C
block : str
Block in periodic table, s, p, d, f
boiling_point : float
Boiling temperature in K
c6 : float
C_6 dispersion coefficient in a.u. from X. Chu & A. Dalgarno, J. Chem. Phys., 121(9), 4083–4088 (2004) doi:10.1063/1.1779576, and the value for Hydrogen was taken from K. T. Tang, J. M. Norbeck and P. R. Certain, J. Chem. Phys. 64, 3063 (1976), doi:10.1063/1.432569
c6_gb : float
C_6 dispersion coefficient in a.u. from Gould, T., & Bučko, T. (2016). JCTC, 12(8), 3603–3613. http://doi.org/10.1021/acs.jctc.6b00361
cas : str
Chemical Abstracts Service identifier
covalent_radius_bragg : float
Covalent radius in pm from
covalent_radius_cordero : float
Covalent radius in pm from Cordero, B., Gómez, V., Platero-Prats, A. E., Revés, M., Echeverría, J., Cremades, E., … Alvarez, S. (2008). Covalent radii revisited. Dalton Transactions, (21), 2832. doi:10.1039/b801115j
covalent_radius_pyykko : float
Single bond covalent radius in pm Pyykkö, P., & Atsumi, M. (2009). Molecular Single-Bond Covalent Radii for Elements 1-118. Chemistry - A European Journal, 15(1), 186–197. doi:10.1002/chem.200800987
covalent_radius_pyykko_double : float
Double bond covalent radius in pm from P. Pyykkö et al.
covalent_radius_pyykko_triple : float
Triple bond covalent radius in pm from P. Pyykkö et al.
cpk_color : str
CPK color of the atom in HEX, see http://jmol.sourceforge.net/jscolors/#color_U
density : float
Density at 295K in g/cm3
description : str
Short description of the element
dipole_polarizability : float
Dipole polarizability in atomic units
dipole_polarizability_unc: float
Uncertainty of the dipole polarizability
discoverers: str
The discoverers of the element
discovery_location: str
The location where the element was discovered
discovery_year: int
The year the element was discovered
electron_affinity : float
Electron affinity in eV
en_allen : float
Allen’s scale of electronegativity (Configurational energy)
en_ghosh : float
Ghosh’s scale of enectronegativity
en_pauling : float
Pauling’s scale of electronegativity
econf : str
Ground state electron configuration
evaporation_heat : float
Evaporation heat in kJ/mol
fusion_heat : float
Fusion heat in kJ/mol
gas_basicity : float
Gas basicity
geochemical_class : str
Geochemical classification of the elements
glawe_number: int
Glawe number (scale)
goldschmidt_class : str
Goldschmidt classification of the elements
group : int
Group number
group_id : Group
Group details
heat_of_formation : float
Heat of formation in kJ/mol
is_monoisotopic : bool
A flag marking if the element is monoisotopic
jmol_color : str
Color of the atom as used in Jmol, in HEX, see http://jmol.sourceforge.net/jscolors/#color_U
lattice_constant : float
Lattice constant in ang
lattice_structure : str
Lattice structure code
mass : float
Relative atomic mass. Ratio of the average mass of atoms of the element to 1/12 of the mass of an atom of 12C
mendeleev_number : int
Mendeleev number
melting_point : float
Melting temperature in K
metallic_radius : Float
Single-bond metallic radius or metallic radius, have been calculated by Pauling using interatomic distances and an equation relating such distances with bond number
metallic_radius_c12 : Float
Metallic radius obtained by Pauling with an assumed number of nearest neighbors equal to 12
molcas_gv_color : str
Color of an atom in HEX from MOLCAS GV http://www.molcas.org/GV/
name : str
Name in English
name_origin: str
Origin of the name
period : int
Period in periodic table
pettifor_number: int
Pettifor scale
proton_affinity : Float
Proton affinity
series : int
Index to chemical series
sources: str
Sources of the element
specific_heat : float
Specific heat in J/g mol @ 20 C
symbol : str of length 1 or 2
Chemical symbol
thermal_conductivity : float
Thermal conductivity in @/m K @25 C
uses: str
Uses of the element
vdw_radius : float
Van der Waals radius in pm from W. M. Haynes, Handbook of Chemistry and Physics 95th Edition, CRC Press, New York, 2014, ISBN-10: 1482208679, ISBN-13: 978-1482208672.
vdw_radius_bondi : float
Van der Waals radius according to Bondi in pm
vdw_radius_truhlar : float
Van der Waals radius according to Truhlar in pm
vdw_radius_rt : float
Van der Waals radius according to Rowland and Taylor in pm
vdw_radius_batsanov : float
Van der Waals radius according to Batsanov in pm
vdw_radius_dreiding : float
Van der Waals radius from the DREIDING force field in pm
vdw_radius_uff : float
Van der Waals radius from the UFF in pm
vdw_radius_mm3 : float
Van der Waals radius from MM3 in pm
oxistates : list
Oxidation states
ionenergy : dict
Ionization energies in eV parsed from http://physics.nist.gov/cgi-bin/ASD/ie.pl on April 13, 2015
calc_en_sanderson(radius='covalent_radius_pyykko')[source]

Sanderson electronegativity

\[\chi = \frac{AD}{AD_{\text{ng}}}\]
Args:
radius : str
Radius to use in the calcualtion
covalent_radius()[source]

Return the default covalent radius which is covalent_radius_pyykko

electronegativity(scale='pauling', charge=0)[source]

Calculate the electronegativity using one of the methods

Args:
scale : str

Name of the electronegativity scale, one of

  • allen
  • allred-rochow
  • cottrell-sutton
  • gordy
  • li-xue
  • martynov-batsanov
  • mulliken
  • nagle
  • pauling
  • sanderson
electrons()[source]

Return the number of electrons.

en_calc(radius='covalent_radius_pyykko', rpow=1, apow=1, **zeffkwargs)[source]

Calculate the electronegativity from a general formula

\[\chi = \left(\frac{Z_{\text{eff}}}{r^{\beta}}\right)^{\alpha}\]

where

  • \(Z_{\text{eff}}\) is the effective nuclear charge
  • \(r\) is the covalent radius
  • \(\alpha,\beta\) parameters
en_li_xue(charge=0, radius='crystal_radius')[source]

Calculate the electronegativity of an atom according to the definition of Li and Xue

Args:
charge : int
Charge of the ion
radius : str
Type of radius to be used in the calculation, either crystal_radius as recommended in the paper or ionic_radius
Returns:
out : dict
A dictionary with electronegativities as values and coordination string as keys or tuple of coordination and spin if the ion is LS or HS
en_martynov_batsanov()[source]

Calculates the electronegativity value according to Martynov and Batsanov as the average of the ionization energies of the valence electrons

\[\chi_{MB} = \sqrt{\frac{1}{n_{v}}\sum^{n_{v}}_{k=1} I_{k}}\]

where: \(n_{v}\) is the number of valence electrons and \(I_{k}\) is the \(k\) th ionization potential.

en_mulliken(charge=0, missingIsZero=False, useNegativeEA=False)[source]

Return the absolute electronegativity (Mulliken scale), calculated as

\[\chi = \frac{I + A}{2}\]

where \(I\) is the ionization energy and \(A\) is the electron affinity

hardness(charge=0)[source]

Return the absolute hardness, calculated as

\[\eta = \frac{I - A}{2}\]

where I is the ionization energy and A is the electron affinity

Args:
charge: int
Charge of the cation for which the hardness will be calculated
init_on_load()[source]

Initialize the ElectronicConfiguration class as attribute of self

ionenergies()[source]

Return a dict with ionization degree as keys and ionization energies in eV as values.

mass()[source]

Return the atomic_weight if defined or mass number otherwise.

mass_number()[source]

Return the mass number of the most abundant natural stable isotope

mass_str()[source]

String representation of atomic weight

neutrons()[source]

Return the number of neutrons of the most abundant natural stable isotope.

nvalence(method=None)[source]

Return the number of valence electrons

oxistates()[source]

Return the oxidation states as a list of ints

protons()[source]

Return the number of protons.

sconst()[source]

Return a dict with screening constants with tuples (n, s) as keys and screening constants as values

softness(charge=0)[source]

Return the absolute softness, calculated as

\[S = \frac{1}{2\eta}\]

where \(\eta\) is the absolute hardness

Args:
charge: int
Charge of the cation for which the hardness will be calculated
zeff(n=None, o=None, method='slater', alle=False)[source]

Return the effective nuclear charge for (n, s)

Args:
method : str
Method to calculate the screening constant, the choices are
  • slater, for Slater’s method as in Slater, J. C. (1930). Atomic Shielding Constants. Physical Review, 36(1), 57–64. doi:10.1103/PhysRev.36.57
  • clementi for values of screening constants from Clementi, E., & Raimondi, D. L. (1963). Atomic Screening Constants from SCF Functions. The Journal of Chemical Physics, 38(11), 2686. doi:10.1063/1.1733573 and Clementi, E. (1967). Atomic Screening Constants from SCF Functions. II. Atoms with 37 to 86 Electrons. The Journal of Chemical Physics, 47(4), 1300. doi:10.1063/1.1712084
n : int
Principal quantum number
o : str
Orbital label, (s, p, d, …)
alle : bool
Use all the valence electrons, i.e. calculate screening for an extra electron when method=’slater’, if method=’clementi’ this option is ignored

IonicRadius

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

Effective ionic radii and crystal radii in pm retrieved from [1].

[1]Shannon, R. D. (1976). Revised effective ionic radii and systematic studies of interatomic distances in halides and chalcogenides. Acta Crystallographica Section A. doi:10.1107/S0567739476001551
Attributes:
atomic_number : int
Atomic number
charge : int
Charge of the ion
econf : str
Electronic configuration of the ion
coordination : str
Type of coordination
spin : str
Spin state: HS - high spin, LS - low spin
crystal_radius : float
Crystal radius in pm
ionic_radius : float
Ionic radius in pm
origin : str
Source of the data
most_reliable : bool
Most reliable value (see reference)

IonizationEnergy

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

Ionization energy of an element

Attributes:
atomic_number : int
Atomic number
degree : int
Degree of ionization with respect to neutral atom
energy : float
Ionization energy in eV parsed from http://physics.nist.gov/cgi-bin/ASD/ie.pl on April 13, 2015

Isotope

class Isotope(*args, **kwargs)[source]
Attributes:
abundance : float
Abundance of the isotope
atomic_number : int
Atomic number
half_life : float
Half life time
half_life_unit : str
Unit for the half life time
is_radioactive : bool
A flag marking wheather the isotope is radioactive
mass : float
Mass of the isotope
mass_number : int
Mass number of the isotope
mass_uncertainty : float
Uncertainty of the mass

ScreeningConstant

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

Nuclear screening constants from Clementi, E., & Raimondi, D. L. (1963). Atomic Screening Constants from SCF Functions. The Journal of Chemical Physics, 38(11), 2686. doi:10.1063/1.1733573 and Clementi, E. (1967). Atomic Screening Constants from SCF Functions. II. Atoms with 37 to 86 Electrons. The Journal of Chemical Physics, 47(4), 1300. doi:10.1063/1.1712084

Attributes:
atomic_number : int
Atomic number
n : int
Principal quantum number
s : str
Subshell label, (s, p, d, …)
screening : float
Screening constant

Series

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

Name of the series in the periodic table.

Attributes:
name : str
Name of the series
color : str
The HEX representation of a color of the series, the colors were obtained from ColorBrewer the qualitative 10-class paired colormap

Group

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

Name of the group in the periodic table.

OxidationState

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

Oxidation states of an element

Attributes:
atomic_number : int
Atomic number
oxidation_state : int
Oxidation state

ElectronicConfiguration

class ElectronicConfiguration(conf=None, atomre=None, shellre=None)[source]

Electronic configuration handler

atomre

Regular expression for atomic symbols

conf

Return the configuration

electrons_per_shell()[source]

Return number of electrons per shell as dict

get_largest_core()[source]

Find the largest noble gas core possible for the current configuration and return the symbol of the corresponding noble gas element.

get_valence()[source]

Find the valence configuration i.e. remove the largest noble gas core from the current configuration and return the result.

ionize(n=1)[source]

Remove n electrons from and return a new ElectronicConfiguration object

last_subshell(wrt='order')[source]

Return the valence shell

max_l(n)[source]

Return the largest value of azimutal quantum number for a given value of principal quantum number

Args:
n : int
Principal quantum number
max_n()[source]

Return the largest value of principal quantum number for the atom

ne()[source]

Return the number of electrons

nvalence(block, method=None)[source]

Return the number of valence electrons

parse(string)[source]

Parse a string with electronic configuration into an OrderedDict representation

shell2int()[source]

configuration as list of tuples (n, l, e)

shellre

Regular expression for the shell

slater_screening(n, o, alle=False)[source]

Calculate the screening constant using the approach introduced by Slater in Slater, J. C. (1930). Atomic Shielding Constants. Physical Review, 36(1), 57-64. doi:10.1103/PhysRev.36.57

Args:
n : int
Principal quantum number
o : str
orbtial label, (s, p, d, …)
alle : bool
Use all the valence electrons, i.e. calculate screening for an extra electron
sort(inplace=True)[source]

Sort the occupations OD

spin_occupations()[source]

For each subshell calculate the number of alpha, beta electrons, electron pairs and unpaired electrons

spin_only_magnetic_moment()[source]

Return the magnetic moment insluding only spin of the electrons and not the angular momentum

to_str()[source]

Return a string with the configuration

unpaired_electrons()[source]

Return the number of unpaired electrons