# 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 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 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
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
Double bond covalent radius in pm from P. Pyykkö et al.
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
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 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
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.
Van der Waals radius according to Bondi in pm
Van der Waals radius according to Truhlar in pm
Van der Waals radius according to Rowland and Taylor in pm
Van der Waals radius according to Batsanov in pm
Van der Waals radius from the DREIDING force field in pm
Van der Waals radius from the UFF in pm
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 to use in the calcualtion
covalent_radius()[source]

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

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

 [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
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
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