Quick start
1. Installation
Jupyter / Google Colab (first cell of your notebook). This cell hides the long, harmless pip warnings and simply prints a confirmation message:
import subprocess, sys
result = subprocess.run(
[sys.executable, "-m", "pip", "install", "pyphyschemtools", "-q"],
capture_output=True, text=True
)
print("✅ pyphyschemtools installed" if result.returncode == 0
else f"⚠️ Installation problem:\n{result.stdout}\n{result.stderr}")
If you see ✅ pyphyschemtools installed, everything is fine and you can go on to the next cell.
Alternative (to see the full pip output): !pip install pyphyschemtools in a notebook, or pip install pyphyschemtools in a terminal.
2. First steps
Modules are loaded on demand (lazy loading): there is no need for import pyphyschemtools as ppct, simply import the names you need.
from pyphyschemtools import Energy, plot_radial, HMO
# Units: convert 1 eV to kJ/mol
print(Energy(1, "eV").to("kJ/mol")) # 96.4853 kJ/mol
# Hydrogen-like atomic orbitals: radial probability density of 1s, 2s, 2p
plot_radial([(1, 0), (2, 0), (2, 1)], density=True)
# Hückel molecular orbitals from a SMILES string (butadiene)
mol = HMO("C=CC=C")
mol.show() # molecule with its π system
mol.plot_energy_diagram() # MO energy diagram with occupations
To organise the output of your notebook, two very convenient helpers are available: centerTitle (a centered, dark banner for section titles) and centertxt (centered text, with optional style="grey", "title", "warning" or "info"):
from pyphyschemtools import centerTitle, centertxt
centerTitle("Hückel analysis of butadiene")
centertxt("Energies are given in units of β", style="info")
centertxt("Check your units!", style="warning")
Bundled example data are available through get_ppct_data:
from pyphyschemtools import get_ppct_data
mol = get_ppct_data("Molecules/betaCD-closed.xyz")
The file can then be displayed as an interactive 3D structure (rotate, zoom) with molView:
from pyphyschemtools import molView
molView(mol)
3. Kinetics on Google Colab, with your own data
!pip install pyphyschemtools
from pyphyschemtools import kbasic
kb = kbasic()
kb.read(colab=True) # opens an upload dialog: pick your Excel file
# (2 columns: time, property G)
kb.fit(ordre=1) # prints the optimal k and the RMSD
kb.plot() # data + model, and the RMSD landscape
Here kb.read(colab=True) is a convenience built into kbasic: it opens the Colab upload button itself, then reads the file you picked.
The same thing can be done in two explicit steps, with the generic colab_upload function (which kbasic.read uses internally). It returns the path of the uploaded file, so you can pass it to kb.read(...) or to pandas directly:
from pyphyschemtools import kbasic, colab_upload
path = colab_upload() # opens the upload dialog, returns the file path
kb = kbasic()
kb.read(path) # same as kb.read(colab=True)
kb.fit(ordre=1)
kb.plot()
This form is handy when you want to look at or process the file yourself first, e.g. pd.read_excel(path), or when the function you use has no colab=True option.
Not on Colab, or just want to try it? Use the bundled example file:
from pyphyschemtools import kbasic, get_ppct_data
kb = kbasic()
kb.read(get_ppct_data("Kinetics/kbasic.xlsx"))
kb.fit(ordre=1)
kb.plot()
4. Interactive tools (periodic table, organic chemistry quiz)
Some classes open a small interactive application directly in the notebook (Jupyter or Google Colab), with nothing to configure.
Periodic table: hover over a tile to see the properties of an element, then query one element in detail.
from pyphyschemtools import PeriodicTable
pt = PeriodicTable()
pt.display() # interactive periodic table (hover over the tiles)
pt.prop("O") # detailed properties of oxygen (symbol or atomic number)
pt.isotopes("Cl") # isotopes of chlorine
A French version with the same methods is available: TableauPeriodique (afficher() instead of display()).
Organic chemistry: the explorer and quiz opens as soon as the object is created. It has three tabs (functional group explorer, structure quiz, nomenclature quiz) and a button to switch between French and English.
from pyphyschemtools import FunctionalGroupExplorer
app = FunctionalGroupExplorer() # displays the interactive interface
The IUPAC names are retrieved from PubChem, so an internet connection is needed for that part.
5. Documentation
In Python: every public class and function has a docstring, so
help()works directly in a notebook or a terminal:from pyphyschemtools import HMO help(HMO)
Online: the full documentation is on Read the Docs. For each module you will find a few theoretical reminders and some context, followed by the API reference (all classes, functions and their parameters).
The full tutorial is available as an interactive notebook on Google Colab.