MoleCool is a Python library for numerical modeling of light–matter interactions,
with a focus on laser cooling of molecules — from simple few-level systems and diatomics
to polyatomics and even radioactive species.
📘 Full Documentation • PyPI • GitHub
For citing this package:
MoleCool enables you to simulate, analyze, and visualize the dynamics of laser–molecule interactions
for designing and optimizing experimental setups in state-of-the-art cooling and trapping experiments.
-
Flexible dynamics solvers — rate equations and Optical Bloch equations (OBEs),
including effects of external magnetic fields.
MoleCool reads predefined molecular constants (dipole matrix elements, hyperfine frequencies,
g-factors, etc.) from JSON files. -
Interactive level-scheme handling — intuitive tools for exploring and visualizing
electronic, vibrational, and rotational structures. -
Laser cooling force profiles — fast evaluation across high-dimensional parameter spaces
for optimization of cooling configurations. -
Monte Carlo trajectory simulations — track many particles through laser fields
using pre-evaluated force profiles for statistical reliability. -
Spectra analysis module — compute, fit, and interpret molecular spectra via
effective Hamiltonians; extract constants for use in dynamics simulations.
MoleCool is intended for researchers and physicists working in
atomic, molecular, and optical (AMO) physics, particularly in:
- Modeling laser–molecule interactions
- Optimizing cooling and trapping experiments
- Interpreting or predicting spectroscopic measurements
We recommend installing MoleCool in a dedicated virtual environment
(using either virtualenv or conda) to avoid dependency conflicts.
See the Installation Guide
for more details.
Requires: Python ≥ 3.8 (Python ≤ 3.10 recommended)
pip install MoleCoolconda install -c conda-forge MoleCoolgit clone https://github.com/LangenGroup/MoleCool
cd MoleCool
pip install .You can verify a correct installation by running the built-in example suite:
python -m MoleCool.run_examplesAdd the -h flag for a help message and a list of all available example scripts.
Below is a minimal working example demonstrating MoleCool’s basic workflow:
from MoleCool import System
# Initialize a molecular system (e.g. 138BaF)
system = System(load_constants='138BaF')
# Build level scheme and remove loss channels
system.levels.add_all_levels(v_max=0)
system.levels.X.del_lossstate()
# Define a multi-sideband laser configuration
system.lasers.add_sidebands(
lamb = 859.83e-9,
P = 20e-3,
offset_freq = 19e6,
mod_freq = 39.33e6,
sidebands = [-2, -1, 1, 2],
ratios = [0.8, 1, 1, 0.8],
)
# Turn on a magnetic field
system.Bfield.turnon(strength=5e-4, direction=[1, 1, 1])
# Run dynamics simulations
system.calc_OBEs(t_int=8e-6, dt=1e-9, magn_remixing=True)
system.calc_rateeqs(t_int=8e-6, magn_remixing=True, position_dep=True)
# Visualize populations
system.plot_N()For detailed usage, see the
👉 User Guide
and Examples.
- Dynamics equations are solved using
scipy.integrate.solve_ivpand compiled with Numba’s just-in-time (JIT) compiler for near-C speed. - Independent simulations are automatically parallelized across multiple cores
using Python’smultiprocessingmodule — ideal for large parameter sweeps
and Monte Carlo trajectory studies.
Contributions are welcome! To develop MoleCool locally:
git clone https://github.com/LangenGroup/MoleCool
cd MoleCool
pip install -e .[dev,doc]The -e flag enables editable mode, allowing immediate testing of code changes.
See the Installation Guide
for more details.
⚠️ Important: Do not import the package from its parent folder if the directory name is alsoMoleCool, as this can confuse Python’s import system.
Full documentation, tutorials, and API reference are hosted on ReadTheDocs:
👉 https://molecool-py.readthedocs.io/
If you use MoleCool in your research, please cite the corresponding paper:
Further background on molecular level structure, spectroscopy, and laser cooling, as well as
the application of MoleCool to achieve isotopologue-selective laser cooling
of complex molecules via serrodyne modulation, is presented in the PhD thesis
Felix Kogel – Laser Cooling of Molecules for Precision Measurements of Parity Violation
This work introduces a novel strategy for designing optimized optical spectra to laser cool heavy, low-abundant barium monofluoride (BaF) molecules, whose additional nuclear spin creates an exceptionally intricate level structure.
© Felix Kogel — released under the MIT License.
See LICENSE for details.
For questions or feedback, open an issue on GitHub.
MoleCool — A modular Python framework for simulating laser cooling of molecules.