Periodic Table

PeriodicTable.py module

An interactive wrapper around the mendeleev library: element properties, isotope tables, mononuclidic elements, and a bokeh-based periodic table you can hover over in a notebook.

Two classes are provided, sharing the same underlying data and methods:

  • TableauPeriodique — the original, French-language class: element names, family names, and all printed output are in French.

  • PeriodicTable — an English-language subclass of TableauPeriodique. It reuses everything (data, corrections, extra columns) but skips the French localization step, so element/family names and printed output are in English instead.

Note: both classes build on mendeleev’s own element and isotope data (fetched once, at instantiation) and add a few corrections/extensions on top — a group-12 “not a transition metal” classification fix, a working first-ionization-energy column, and pedagogical warnings around mononuclidic/radiogenic elements and IUPAC/CIAAW atomic-weight ranges (see below).

Quick Start

from pyphyschemtools import TableauPeriodique, PeriodicTable

# French
tp = TableauPeriodique()
tp.prop('O')            # detailed properties of oxygen, in French
tp.isotopes('Cl')        # isotope table + pedagogical warnings
tp.mononucleides()       # all mononuclidic elements
tp.afficher()            # interactive periodic table (bokeh)

# English
pt = PeriodicTable()
pt.prop('O')
pt.isotopes('Cl')
pt.mononucleides()
pt.display()            # interactive periodic table (bokeh); afficher() also works

ou bien

import pyphyschemtools.PeriodicTable as PT
tp = PT.TableauPeriodique()
tp.prop(8)

Element properties

prop(elt_id) prints a detailed summary of one element — symbol, atomic number, electron configuration, group/period/block, family, molar mass, natural isotopes, Pauling electronegativity, first ionization energy, electron affinity, atomic radius, and a short textual description/sources/uses (all from mendeleev). elt_id can be a symbol ('O') or an atomic number (8).

Isotopes

isotopes(elt_id) displays a table of an element’s isotopes (mass number, isotopic mass, natural abundance, half-life), sorted by increasing mass number, followed by its molar mass. An isotope with no abundance listed is simply not naturally occurring (e.g. the radioactive isotopes of a radioelement).

Two pedagogical warnings are printed automatically when they apply:

  • Radiogenic reclassification. A handful of elements that look “mononuclidic” at first glance (because mendeleev lists more than one isotope with nonzero natural abundance) hold a non-primordial isotope produced by the decay of a longer-lived parent. Thorium is the IUPAC/CIAAW reference case: trace amounts of \(^{230}\text{Th}\), a decay product of \(^{238}\text{U}\), led the Commission to reclassify Th as binuclidic in 2013.

  • IUPAC/CIAAW atomic-weight ranges. For 12 elements (H, Li, B, C, N, O, Mg, Si, S, Cl, Br, Tl), natural isotopic composition varies enough — by geological origin and, for some, industrial isotope separation — that IUPAC/CIAAW publishes a range [min, max] rather than a single standard atomic weight. mendeleev’s single atomic_weight value is only a conventional choice within that range, and is not guaranteed to equal \(\sum (\text{abundance} \times \text{isotopic mass})\) computed from mendeleev’s own isotope table (lithium is a striking example of this).

Mononuclidic elements

mononucleides(exclude_radiogenic=True) (French: exclure_radiogeniques) lists every element with a single naturally-occurring isotope — symbol, mass number, isotopic mass, molar mass, half-life (“stable” when applicable). By default, elements like thorium — which hold only a dominant primordial isotope plus a radiogenic trace isotope — are excluded, matching the strict IUPAC/CIAAW definition. Pass exclude_radiogenic=False to include them instead; they are then marked with a trailing * and footnoted.

Implementation note: both classes fetch the whole isotopes and elements tables in two bulk queries and group/merge them with pandas, rather than querying mendeleev one element at a time — this brings the running time down from several seconds to well under a tenth of a second.

Interactive periodic table

afficher(self) (on TableauPeriodique) / display(self) (on PeriodicTable, with afficher kept as an alias) opens an interactive bokeh periodic table in the current Jupyter notebook: each tile shows the symbol, atomic number, name and molar mass, colored by family, with a hover tooltip giving name, family, atomic number, molar mass, atomic radius, first ionization energy, electron affinity, Pauling electronegativity and electron configuration — in French for TableauPeriodique, in English for PeriodicTable.

API reference

class pyphyschemtools.PeriodicTable.PeriodicTable[source]

Bases: TableauPeriodique

English-language counterpart of TableauPeriodique.

Same underlying data (fetched through the ‘mendeleev’ library) and the same set of methods, but without the French localization patch: element and family/series names are left as mendeleev provides them (English), and all printed output (prop, isotopes, mononucleides) is in English.

Everything else — the group-12-is-not-a-transition-metal correction, the extra data merged in (first ionization energy), the radiogenic-isotope and CIAAW-interval warnings — is shared with TableauPeriodique via inheritance.

afficher()

Generates and displays the interactive periodic table in a Jupyter notebook.

Hover over a tile to see the element’s properties.

English-named counterpart of TableauPeriodique.afficher(). Also reachable as afficher() (kept as an alias below) so that code written against either class can call the same method name.

display()[source]

Generates and displays the interactive periodic table in a Jupyter notebook.

Hover over a tile to see the element’s properties.

English-named counterpart of TableauPeriodique.afficher(). Also reachable as afficher() (kept as an alias below) so that code written against either class can call the same method name.

isotopes(elt_id)[source]

Prints an element’s isotope table (mass number, natural abundance, half-life), sorted by increasing mass number.

Generalizes the thorium example: for a radioelement, the absence of an abundance value simply means that no isotope is stable/natural in mendeleev’s sense.

Parameters:

elt_id (str or int) – Element symbol (e.g. ‘Th’) or atomic number (e.g. 90).

mononucleides(exclude_radiogenic=True)[source]

Prints the mononuclidic elements, i.e. elements with a single isotope of measurable natural abundance (in mendeleev’s sense: abundance is not None).

Parameters:

exclude_radiogenic (bool) – if True (default), excludes elements such as thorium, reclassified as binuclidic (or more) by the IUPAC in 2013 because of a trace radiogenic isotope (see TableauPeriodique.exceptionsRadiogeniques).

prop(elt_id)[source]

Prints detailed properties of a chemical element.

Parameters:

elt_id (str or int) – Element symbol (e.g. ‘O’) or atomic number (e.g. 8).

class pyphyschemtools.PeriodicTable.TableauPeriodique[source]

Bases: object

Classe permettant de manipuler et d’afficher les données du tableau périodique.

Cette classe utilise la bibliothèque ‘mendeleev’ pour récupérer les données chimiques et ‘bokeh’ pour la visualisation interactive. Elle francise les noms et corrige certaines classifications de familles chimiques.

Initialise l’objet TableauPeriodique en chargeant les données de la bibliothèque mendeleev.

Note

See also PeriodicTable, the English-language counterpart of this class (same data and methods, but without the French localization patch).

afficher()[source]

Génère et affiche le tableau périodique interactif dans un notebook Jupyter.

Le tableau permet de visualiser les propriétés au survol de la souris.

exceptionsRadiogenic = {90: '230-Th, a decay product of 238U (IUPAC/CIAAW, 2013)'}
exceptionsRadiogeniques = {90: "230-Th, issu de la désintégration de l'238U (IUPAC/CIAAW, 2013)"}
intervallesCIAAW = {1: (1.00784, 1.00811), 3: (6.938, 6.997), 5: (10.806, 10.821), 6: (12.0096, 12.0116), 7: (14.00643, 14.00728), 8: (15.99903, 15.99977), 12: (24.304, 24.307), 14: (28.084, 28.086), 16: (32.059, 32.076), 17: (35.446, 35.457), 35: (79.901, 79.907), 81: (204.382, 204.385)}
isotopes(elt_id)[source]

Affiche la table des isotopes d’un élément (numéro de masse, abondance naturelle, demi-vie), triée par numéro de masse croissant.

Généralise l’exemple du thorium : pour un radioélément, l’absence d’abondance signifie simplement qu’aucun isotope n’est stable/naturel au sens de mendeleev.

Parameters:

elt_id (str ou int) – Symbole de l’élément (ex: ‘Th’) ou numéro atomique (ex: 90).

mononucleides(exclure_radiogeniques=True)[source]

Affiche les éléments mononucléidiques, c’est-à-dire possédant un seul isotope naturel (au sens de mendeleev : abundance non None).

Parameters:

exclure_radiogeniques (bool) – si True (par défaut), exclut les éléments comme le thorium, reclassés binucléidiques (ou plus) par l’IUPAC en 2013 à cause d’isotopes radiogéniques présents en traces (voir TableauPeriodique.exceptionsRadiogeniques).

nomsFr = ['Hydrogène', 'Hélium', 'Lithium', 'Béryllium', 'Bore', 'Carbone', 'Azote', 'Oxygène', 'Fluor', 'Néon', 'Sodium', 'Magnésium', 'Aluminium', 'Silicium', 'Phosphore', 'Soufre', 'Chlore', 'Argon', 'Potassium', 'Calcium', 'Scandium', 'Titane', 'Vanadium', 'Chrome', 'Manganèse', 'Fer', 'Cobalt', 'Nickel', 'Cuivre', 'Zinc', 'Gallium', 'Germanium', 'Arsenic', 'Sélénium', 'Brome', 'Krypton', 'Rubidium', 'Strontium', 'Yttrium', 'Zirconium', 'Niobium', 'Molybdène', 'Technétium', 'Ruthénium', 'Rhodium', 'Palladium', 'Argent', 'Cadmium', 'Indium', 'Étain', 'Antimoine', 'Tellure', 'Iode', 'Xénon', 'Césium', 'Baryum', 'Lanthane', 'Cérium', 'Praséodyme', 'Néodyme', 'Prométhium', 'Samarium', 'Europium', 'Gadolinium', 'Terbium', 'Dysprosium', 'Holmium', 'Erbium', 'Thulium', 'Ytterbium', 'Lutetium', 'Hafnium', 'Tantale', 'Tungstène', 'Rhénium', 'Osmium', 'Iridium', 'Platine', 'Or', 'Mercure', 'Thallium', 'Plomb', 'Bismuth', 'Polonium', 'Astate', 'Radon', 'Francium', 'Radium', 'Actinium', 'Thorium', 'Protactinium', 'Uranium', 'Neptunium', 'Plutonium', 'Americium', 'Curium', 'Berkelium', 'Californium', 'Einsteinium', 'Fermium', 'Mendelevium', 'Nobelium', 'Lawrencium', 'Rutherfordium', 'Dubnium', 'Seaborgium', 'Bohrium', 'Hassium', 'Meitnerium', 'Darmstadtium', 'Roentgenium', 'Copernicium', 'Nihonium', 'Flerovium', 'Moscovium', 'Livermorium', 'Tennesse', 'Oganesson']
patch_elements()[source]

Ce patch, appliqué à self.elements, créé par l’appel à create_vis_dataframe(), va servir à : - corriger certaines classifications de familles (retire les éléments du groupe 12 de la

famille des métaux de transition, qui est le choix CONTESTABLE par défaut de mendeleev) ; cette partie est commune à TableauPeriodique et à sa sous-classe anglaise PeriodicTable

  • ajouter des informations localisées (noms des éléments et des familles) via self._localize_names(), surchargeable par une sous-classe

  • ajouter des données supplémentaires (énergie de première ionisation) via self._ajouter_donnees()

input : elements est un dataframe pandas préalablement créé par la fonction create_vis_dataframe() de mendeleev.vis

output : elements avec les colonnes ajoutées par _localize_names() et _ajouter_donnees() + correction des données name_series et series_id pour les éléments Zn, Cd, Hg, Cn

prop(elt_id)[source]

Affiche les propriétés détaillées d’un élément chimique.

Parameters:

elt_id (str ou int) – Symbole de l’élément (ex: ‘O’) ou numéro atomique (ex: 8).

trad = {'Actinides': 'Actinide', 'Alkali metals': 'Métal alcalin', 'Alkaline earth metals': 'Métal alcalino-terreux', 'Halogens': 'Halogène', 'Lanthanides': 'Lanthanide', 'Metalloids': 'Métalloïde', 'Metals': 'Métal', 'Noble gases': 'Gaz noble', 'Nonmetals': 'Non métal', 'Poor metals': 'Métal pauvre', 'Transition metals': 'Métal de transition'}