API Reference

Accessing data

Individual 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: Union[int, str]) Element[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.

Parameters

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

Fetching data in bulk

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

fetch_table(table: str, **kwargs) pandas.DataFrame[source]

Return a table from the database as pandas.DataFrame

Parameters
  • table – Name of the table from the database

  • kwargs – A dictionary of keyword arguments to pass to the pandas.read_qsl()

Returns

Pandas DataFrame with the contents of the table

Return type

df (pandas.DataFrame)

Example

>>> from mendeleev.fetch import fetch_table
>>> df = fetch_table('elements')
>>> type(df)
pandas.core.frame.DataFrame
fetch_ionization_energies(degree: Union[List[int], int] = 1) pandas.DataFrame[source]

Fetch a pandas.DataFrame with ionization energies for all elements indexed by atomic number.

Parameters

degree – Degree of ionization, either as int or a list of ints. If a list is passed then the output will contain ionization energies corresponding to particalr degrees in columns.

Returns

ionization energies, indexed by atomic number

Return type

df (pandas.DataFrame)

fetch_ionic_radii(radius: str = 'ionic_radius') pandas.DataFrame[source]

Fetch a pandas DataFrame with ionic radii for all the elements.

Parameters

radius – The radius to be returned either ionic_radius or crystal_radius

Returns

a table with atomic numbers, symbols and ionic radii for all

coordination numbers

Return type

df (pandas.DataFrame)

Computed properties

Some properties need to be computed rather than directly retrieved from the database. Electronegativities

fetch_electronegativities(scales: Optional[List[str]] = None) pandas.DataFrame[source]

Fetch electronegativity scales for all elements as pandas.DataFrame

Parameters

scales – list of scale names, defaults to all available scales

Returns

Pandas DataFrame with the contents of the table

Return type

df (pandas.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: Optional[str] = None) Session[source]

Return the database session connection.

get_engine(dbpath: Optional[str] = None) Engine[source]

Return the db engine

Classes

Element

class Element(**kwargs)[source]

Chemical element.

For full list of available data with references see Data.

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

  • electrophilicity (float) – Parr’s electrophilicity index

  • 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_id (int) – Group number

  • heat_of_formation (float) – Heat of formation in kJ/mol

  • inchi (str) – International Chemical Identifier

  • 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

  • molar_heat_capacity (flaot) – Molar heat capacity in J/mol K

  • 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

  • nist_webbook_url (str) – URL for the NIST Chemistry WebBook

  • 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_capacity (float) – Specific heat in J/g K @ 20 C

  • symbol (str) – 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

  • ionenergies (dict) – Ionization energies in eV parsed from http://physics.nist.gov/cgi-bin/ASD/ie.pl on April 13, 2015

property boiling_point: Union[float, Dict[str, float]]

Boiling point

covalent_radius

Return the default covalent radius which is covalent_radius_pyykko

electronegativity(scale: str = 'pauling', **kwargs) float[source]

Calculate the electronegativity using one of the methods

Parameters
  • scale – Name of the electronegativity scale, one of

  • kwargs – keyword arguments that are passed to compute a specific electronegativity

electronegativity_allen() float[source]

Allen’s electronegativity

electronegativity_allred_rochow(radius='covalent_radius_pyykko') float[source]

Allred-Rochow’s electronegativity

electronegativity_cottrell_sutton(radius='covalent_radius_pyykko') float[source]

Cottrell-Sutton’s electronegativity

electronegativity_ghosh() float[source]

Ghosh’s electronegativity

electronegativity_gordy(radius='covalent_radius_pyykko') float[source]

Gordy’s electronegativity

electronegativity_li_xue(charge: int = 1, radius: str = 'crystal_radius') Dict[Tuple[str, str], float][source]

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

Parameters
  • charge – charge of the ion

  • radius – type of radius to be used in the calculation, either crystal_radius as recommended in the paper or ionic_radius

Returns

dictionary with electronegativities as values and

coordination string as keys or tuple of coordination and spin if the ion is LS or HS

Return type

out (dict)

electronegativity_martynov_batsanov() float[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

  • \(I_{k}\) is the \(k\) th ionization potential.

electronegativity_mulliken(charge: int = 0, missing_is_zero: bool = False, allow_negative_ea: bool = False) float[source]

Return the absolute electronegativity (Mulliken scale), calculated as

Parameters
  • charge – charge of the ion

  • missing_is_zero – missing values are substituted with zero

  • allow_negative_ea – if True negative EA values will be allowed

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

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

electronegativity_nagle() float[source]

Nagle’s electronegativity

electronegativity_pauling() float[source]

Pauling’s electronegativity

electronegativity_sanderson(radius='covalent_radius_pyykko') float[source]

Sanderson electronegativity

Parameters

radius – radius to use in the calculation

electronegativity_scales(name: Optional[str] = None) Union[Callable, List[str]][source]

Available electronegativity scales

electrons

Return the number of electrons.

electrophilicity() Optional[float][source]

Calculate electrophilicity index

\[\omega = \frac{\mu}{2\eta}\]
hardness(charge: int = 0) Optional[float][source]

Return the absolute hardness, calculated as

Parameters

charge – Charge of the cation for which the hardness will be calculated

\[\eta = \frac{IE - EA}{2}\]

where:

  • \(IE\) is the ionization energy,

  • :math`EA` is the electron affinity

inchi

International Chemical Identifier.

See: https://en.wikipedia.org/wiki/International_Chemical_Identifier

init_on_load() None[source]

Initialize the ElectronicConfiguration class as attribute of self

mass

Return the atomic_weight if defined or mass number otherwise.

mass_str() str[source]

String representation of atomic weight

property melting_point: Union[float, Dict[str, float]]

Melting point

property nist_webbook_url: str

URL for the NIST Chemistry WebBook

nvalence(method: Optional[str] = None) int[source]

Return the number of valence electrons

oxidation_states(category: str = 'main') List[int][source]

Utility method for accessing oxidation states.

Parameters

category (str) – Category of oxidation state, Either - main - for main, most common, oxidataion states - extended - for less common oxidation states - all - all oxidation states

oxides() List[str][source]

Return a list of possible oxides based on the oxidation number

protons

Return the number of protons.

softness(charge: int = 0) Optional[float][source]

Return the absolute softness, calculated as

Parameters

charge – Charge of the cation for which the hardness will be calculated

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

where :

  • \(\eta\) is the absolute hardness

specific_heat

Alias for specific_heat_capacity for backwards compatibility

zeff(n: Optional[int] = None, o: Optional[str] = None, method: str = 'slater', alle: bool = False) Optional[float][source]

Return the effective nuclear charge for (n, s)

Parameters
  • method

    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 – Principal quantum number

  • o – Orbital label, (s, p, d, …)

  • alle – Use all the valence electrons, i.e. calculate screening for an extra electron when method=’slater’, if method=’clementi’ this option is ignored

Ion

class Ion(label, q=1)[source]

Class representating atomic ions

ionic_potential(radius_most_reliable: bool = True) float[source]

Calculate the ionic potential

Parameters

radius_most_reliable – flag to use the most reliable ionic radius, default is True

unicode_ion_symbol() str[source]

Return a unicode string symbol of the ion

IonicRadius

class IonicRadius(**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

Parameters
  • 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(**kwargs)[source]

Ionization energy of an element

Parameters

Isotope

class Isotope(**kwargs)[source]
Parameters
  • abundance (float) – Abundance of the isotope

  • abundance_uncertainty (float) – Abundance uncertainty

  • atomic_number (int) – Atomic number

  • discovery_year (int) – Year the isotope was discovered

  • g_factor (float) – Dimensionless magnetic moment

  • g_factor_uncertainty (float) – Uncertainty for the g_factor

  • half_life (float) – Half life time

  • half_life_uncertainty (float) – Uncertainty for the half_life

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

  • parity (str) – Parity, if present, it can be either + or -

  • quadrupole_moment (float) – Quadrupole moment

  • quadrupole_moment_uncertainty (float) – Uncertainty for the quadrupole_moment

  • spin (str) – Nuclear spin

is_stable

Flag to indicate whether the isotope is stable

ScreeningConstant

class ScreeningConstant(**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

Args::

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

Series

class Series(**kwargs)[source]

Name of the series in the periodic table.

Parameters
  • 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(**kwargs)[source]

Name of the group in the periodic table.

Parameters
  • group_id (int) – group number

  • symbol – (str): group symbol

  • name (str) – group name

OxidationState

class OxidationState(**kwargs)[source]

Oxidation states of an element

Parameters
  • atomic_number (int) – Atomic number

  • oxidation_state (int) – Oxidation state

  • category (str) – Either main or extended flag to indicate the type of oxidation state.

ElectronicConfiguration

class ElectronicConfiguration(conf: Optional[Union[str, Dict]] = None, atomre: Optional[str] = None, shellre: Optional[str] = None)[source]

Electronic configuration handler

property atomre: Pattern

Regular expression for atomic symbols

property conf: OrderedDict

Return the configuration

electrons_per_shell() Dict[str, int][source]

Return number of electrons per shell as dict

get_largest_core() Tuple[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: int = 1)[source]

Remove n electrons from and return a new ElectronicConfiguration object

last_subshell(wrt: str = 'order')[source]

Return the valence shell

max_l(n: int) int[source]

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

Parameters

n – int Principal quantum number

Returns

int

Azimutal quantum number

Return type

l

max_n() int[source]

Return the largest value of principal quantum number for the atom

ne() int[source]

Number of electrons

nvalence(block: str, period: int, method: Optional[str] = None) int[source]

Return the number of valence electrons

parse(string: str) None[source]

Parse a string with electronic configuration into an OrderedDict representation

shell2int() List[Tuple[int]][source]

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

property shellre: Pattern

Regular expression for the shell

slater_screening(n: int, o: str, alle: bool = 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

Parameters
  • 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: bool = 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() float[source]

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

to_str() str[source]

Return a string with the configuration

unpaired_electrons() int[source]

Number of unpaired electrons

Modules

electronegativity module

Electronegativity scale formulas

allred_rochow(zeff: float, radius: float) float[source]

Calculate the electronegativity of an atom according to the definition of Allred and Rochow

Parameters
  • zeff – effective nuclear charge

  • radius – value of the radius

cottrell_sutton(zeff: float, radius: float) float[source]

Calculate the electronegativity of an atom according to the definition of Allred and Rochow

Parameters
  • zeff – effective nuclear charge

  • radius – value of the radius

generic(zeff: float, radius: float, rpow: float = 1, apow: float = 1) float[source]

Calculate the electronegativity from a general formula

Parameters
  • zeff – effective nuclear charge

  • radius – radius value for the element

  • rpow – power to raise the radius to (see equation below)

  • apow – power to raise the fraction to (see equation below)

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

gordy(zeff: float, radius: float) float[source]

Calculate the electronegativity of an atom according to the definition of Allred and Rochow

Parameters
  • zeff – effective nuclear charge

  • radius – value of the radius

li_xue(ionization_energy: float, radius: float, valence_pqn: int) float[source]

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

Parameters
  • charge – Charge of the ion

  • radius – Type of radius to be used in the calculation, either crystal_radius as recommended in the paper or ionic_radius

  • valence_pqn – valence principal quantum number

martynov_batsanov(ionization_energies: List[float]) float[source]

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

Parameters

ionization_energies – ionization energies for 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.

mulliken(ionization_energy: float, electron_affinity: float, missing_is_zero: bool = False, allow_negative_ea: bool = False) float[source]

Return the absolute electronegativity (Mulliken scale), calculated as

Parameters
  • ionization_energy – ionization energy

  • electron_affinity – electron affinity

  • missing_is_zero – missing values are substituted with zero

  • allow_negative_ea – if True negative EA values will be allowed

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

where:

  • \(I\) is the ionization energy,

  • \(A\) is the electron affinity

nagle(nvalence: int, polarizability: float) float[source]

Calculate the electronegativity of an atom according to the definition of Nagle

Parameters
  • nvalence – number of valence electrons

  • polarizability – dipole polarizability

sanderson(radius: float, noble_gas_radius: float) float[source]

Calculate Sanderson’s electronegativity

Parameters
  • radius – radius value for the element

  • noble_gas_radius – value of the radius of a hypothetical noble gas with

  • calculated (the atomic number of element for which electronegativity is) –

\[\chi = \frac{AD}{AD_{\text{ng}}}\]

vis module

utils module

coeffs(a: int, b: int = 2) Tuple[int, int][source]

Return stoichometric coefficients from oxidation states

Parameters
  • a – oxidation state of the first element

  • b – oxidation state of the second element

n_effective(n: int, source: str = 'slater') Optional[float][source]

Effective principal quantum number

Parameters
  • n – Principal quantum number

  • source – either slater or zhang, for more information see note below.

Note

Slater’s values are taken from J. A. Pople, D. L. Beveridge, “Approximate Molecular Orbital Theory”, McGraw-Hill, 1970

Zhang’s values are taken from Zhang, Y. (1982). Electronegativities of elements in valence states and their applications. 1. Electronegativities of elements in valence states. Inorganic Chemistry, 21(11), 3886–3889. https://doi.org/10.1021/ic00141a005