# MoleCool
<p align="center">
<img src="doc/source/_static/molecool_logo.png" alt="MoleCool logo" width="200"/>
</p>
**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.
<p align="center">
<a href="https://molecool-py.readthedocs.io/"><b>📘 Full Documentation</b></a> •
<a href="https://pypi.org/project/MoleCool/"><b>PyPI</b></a> •
<a href="https://github.com/LangenGroup/MoleCool/"><b>GitHub</b></a>
</p>
For citing this package: [](https://arxiv.org/abs/2510.16203)
---
## ✨ Overview
**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.
### Key Features
- **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.
### Target Audience
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
---
## ⚙️ Installation
We recommend installing MoleCool in a dedicated virtual environment
(using either `virtualenv` or `conda`) to avoid dependency conflicts.
See the [Installation Guide](https://molecool-py.readthedocs.io/en/stable/installation.html)
for more details.
> **Requires:** Python ≥ 3.8 (Python ≤ 3.10 recommended)
### Using `pip` (stable release)
```bash
pip install MoleCool
```
### Using `conda` (via conda-forge)
```bash
conda install -c conda-forge MoleCool
```
### Development version (latest from GitHub)
```bash
git clone https://github.com/LangenGroup/MoleCool
cd MoleCool
pip install .
```
---
## 🧪 Verifying the Installation
You can verify a correct installation by running the built-in example suite:
```bash
python -m MoleCool.run_examples
```
Add the `-h` flag for a help message and a list of all available example scripts.
---
## 🚀 Quickstart Example
Below is a minimal working example demonstrating MoleCool’s basic workflow:
```python
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](https://molecool-py.readthedocs.io/en/stable/user_guide/introduction.html)
and [Examples](https://molecool-py.readthedocs.io/en/stable/examples.html).
---
## ⚡ Performance and Parallelization
- Dynamics equations are solved using [`scipy.integrate.solve_ivp`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html)
and compiled with **Numba**’s just-in-time (JIT) compiler for near-C speed.
- Independent simulations are automatically parallelized across multiple cores
using Python’s `multiprocessing` module — ideal for large parameter sweeps
and Monte Carlo trajectory studies.
---
## 🤝 Contributing
Contributions are welcome! To develop MoleCool locally:
```bash
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](https://molecool-py.readthedocs.io/en/stable/installation.html)
for more details.
> ⚠️ **Important:** Do not import the package from its parent folder if the
> directory name is also `MoleCool`, as this can confuse Python’s import system.
---
## 📚 Documentation
Full documentation, tutorials, and API reference are hosted on **ReadTheDocs**:
👉 [https://molecool-py.readthedocs.io/](https://molecool-py.readthedocs.io/)
---
## 🧾 Citation and Further Reading
If you use MoleCool in your research, please cite the corresponding paper:
[](https://arxiv.org/abs/2510.16203)
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](https://doi.org/10.18419/opus-17104)**
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.
---
## 🧠 License
© Felix Kogel — released under the **MIT License**.
See [`LICENSE`](./LICENSE.md) for details.
---
### 👩🔬 Developed by Felix Kogel
For questions or feedback, open an issue on [GitHub](https://github.com/LangenGroup/MoleCool/issues).
---
**MoleCool** — *A modular Python framework for simulating laser cooling of molecules.*
Raw data
{
"_id": null,
"home_page": null,
"name": "MoleCool",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cold molecules, laser cooling, optical Bloch equations, rate equations, diatomic molecules, multi-level systems, Rabi-oscillations, coherent laser forces",
"author": null,
"author_email": "Felix Kogel <felix.kogel@t-online.de>",
"download_url": "https://files.pythonhosted.org/packages/5a/9a/48abc93797151d56cf9945da8e412321b389458a780d8e6a2391e7bbe79d/molecool-3.7.3.tar.gz",
"platform": null,
"description": "# MoleCool\r\n\r\n<p align=\"center\">\r\n <img src=\"doc/source/_static/molecool_logo.png\" alt=\"MoleCool logo\" width=\"200\"/>\r\n</p>\r\n\r\n**MoleCool** is a Python library for **numerical modeling of light\u2013matter interactions**, \r\nwith a focus on **laser cooling of molecules** \u2014 from simple few-level systems and diatomics \r\nto polyatomics and even radioactive species.\r\n\r\n<p align=\"center\">\r\n <a href=\"https://molecool-py.readthedocs.io/\"><b>\ud83d\udcd8 Full Documentation</b></a> \u2022\r\n <a href=\"https://pypi.org/project/MoleCool/\"><b>PyPI</b></a> \u2022\r\n <a href=\"https://github.com/LangenGroup/MoleCool/\"><b>GitHub</b></a>\r\n</p>\r\n\r\nFor citing this package: [](https://arxiv.org/abs/2510.16203)\r\n\r\n---\r\n\r\n## \u2728 Overview\r\n\r\n**MoleCool** enables you to **simulate, analyze, and visualize** the dynamics of laser\u2013molecule interactions \r\nfor designing and optimizing experimental setups in state-of-the-art cooling and trapping experiments.\r\n\r\n### Key Features\r\n\r\n- **Flexible dynamics solvers** \u2014 rate equations and Optical Bloch equations (OBEs), \r\n including effects of external magnetic fields. \r\n MoleCool reads predefined molecular constants (dipole matrix elements, hyperfine frequencies, \r\n g-factors, etc.) from JSON files.\r\n\r\n- **Interactive level-scheme handling** \u2014 intuitive tools for exploring and visualizing \r\n electronic, vibrational, and rotational structures.\r\n\r\n- **Laser cooling force profiles** \u2014 fast evaluation across high-dimensional parameter spaces \r\n for optimization of cooling configurations.\r\n\r\n- **Monte Carlo trajectory simulations** \u2014 track many particles through laser fields \r\n using pre-evaluated force profiles for statistical reliability.\r\n\r\n- **Spectra analysis module** \u2014 compute, fit, and interpret molecular spectra via \r\n effective Hamiltonians; extract constants for use in dynamics simulations.\r\n\r\n### Target Audience\r\n\r\nMoleCool is intended for **researchers and physicists** working in \r\n**atomic, molecular, and optical (AMO) physics**, particularly in:\r\n\r\n- Modeling laser\u2013molecule interactions \r\n- Optimizing cooling and trapping experiments \r\n- Interpreting or predicting spectroscopic measurements \r\n\r\n---\r\n\r\n## \u2699\ufe0f Installation\r\n\r\nWe recommend installing MoleCool in a dedicated virtual environment \r\n(using either `virtualenv` or `conda`) to avoid dependency conflicts.\r\nSee the [Installation Guide](https://molecool-py.readthedocs.io/en/stable/installation.html)\r\nfor more details.\r\n\r\n> **Requires:** Python \u2265 3.8 (Python \u2264 3.10 recommended)\r\n\r\n### Using `pip` (stable release)\r\n\r\n```bash\r\npip install MoleCool\r\n```\r\n\r\n### Using `conda` (via conda-forge)\r\n\r\n```bash\r\nconda install -c conda-forge MoleCool\r\n```\r\n\r\n### Development version (latest from GitHub)\r\n\r\n```bash\r\ngit clone https://github.com/LangenGroup/MoleCool\r\ncd MoleCool\r\npip install .\r\n```\r\n\r\n---\r\n\r\n## \ud83e\uddea Verifying the Installation\r\n\r\nYou can verify a correct installation by running the built-in example suite:\r\n\r\n```bash\r\npython -m MoleCool.run_examples\r\n```\r\n\r\nAdd the `-h` flag for a help message and a list of all available example scripts.\r\n\r\n---\r\n\r\n## \ud83d\ude80 Quickstart Example\r\n\r\nBelow is a minimal working example demonstrating MoleCool\u2019s basic workflow:\r\n\r\n```python\r\nfrom MoleCool import System\r\n\r\n# Initialize a molecular system (e.g. 138BaF)\r\nsystem = System(load_constants='138BaF')\r\n\r\n# Build level scheme and remove loss channels\r\nsystem.levels.add_all_levels(v_max=0)\r\nsystem.levels.X.del_lossstate()\r\n\r\n# Define a multi-sideband laser configuration\r\nsystem.lasers.add_sidebands(\r\n lamb = 859.83e-9,\r\n P = 20e-3,\r\n offset_freq = 19e6,\r\n mod_freq = 39.33e6,\r\n sidebands = [-2, -1, 1, 2],\r\n ratios = [0.8, 1, 1, 0.8],\r\n)\r\n\r\n# Turn on a magnetic field\r\nsystem.Bfield.turnon(strength=5e-4, direction=[1, 1, 1])\r\n\r\n# Run dynamics simulations\r\nsystem.calc_OBEs(t_int=8e-6, dt=1e-9, magn_remixing=True)\r\nsystem.calc_rateeqs(t_int=8e-6, magn_remixing=True, position_dep=True)\r\n\r\n# Visualize populations\r\nsystem.plot_N()\r\n```\r\n\r\nFor detailed usage, see the \r\n\ud83d\udc49 [User Guide](https://molecool-py.readthedocs.io/en/stable/user_guide/introduction.html) \r\nand [Examples](https://molecool-py.readthedocs.io/en/stable/examples.html).\r\n\r\n---\r\n\r\n## \u26a1 Performance and Parallelization\r\n\r\n- Dynamics equations are solved using [`scipy.integrate.solve_ivp`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.solve_ivp.html)\r\n and compiled with **Numba**\u2019s just-in-time (JIT) compiler for near-C speed. \r\n- Independent simulations are automatically parallelized across multiple cores \r\n using Python\u2019s `multiprocessing` module \u2014 ideal for large parameter sweeps \r\n and Monte Carlo trajectory studies.\r\n\r\n---\r\n\r\n## \ud83e\udd1d Contributing\r\n\r\nContributions are welcome! To develop MoleCool locally:\r\n\r\n```bash\r\ngit clone https://github.com/LangenGroup/MoleCool\r\ncd MoleCool\r\npip install -e .[dev,doc]\r\n```\r\n\r\nThe `-e` flag enables **editable mode**, allowing immediate testing of code changes. \r\nSee the [Installation Guide](https://molecool-py.readthedocs.io/en/stable/installation.html)\r\nfor more details.\r\n\r\n> \u26a0\ufe0f **Important:** Do not import the package from its parent folder if the\r\n> directory name is also `MoleCool`, as this can confuse Python\u2019s import system.\r\n\r\n---\r\n\r\n## \ud83d\udcda Documentation\r\n\r\nFull documentation, tutorials, and API reference are hosted on **ReadTheDocs**:\r\n\r\n\ud83d\udc49 [https://molecool-py.readthedocs.io/](https://molecool-py.readthedocs.io/)\r\n\r\n---\r\n\r\n## \ud83e\uddfe Citation and Further Reading\r\n\r\nIf you use MoleCool in your research, please cite the corresponding paper: \r\n[](https://arxiv.org/abs/2510.16203)\r\n\r\nFurther background on molecular level structure, spectroscopy, and laser cooling, as well as\r\nthe application of ``MoleCool`` to achieve **isotopologue-selective laser cooling**\r\nof **complex molecules** via *serrodyne* modulation, is presented in the PhD thesis\r\n\r\n> **Felix Kogel \u2013 [Laser Cooling of Molecules for Precision Measurements of Parity Violation](https://doi.org/10.18419/opus-17104)**\r\n\r\nThis work introduces a novel strategy for designing optimized optical spectra to laser cool\r\nheavy, low-abundant **barium monofluoride (BaF)** molecules, whose additional nuclear spin\r\ncreates an exceptionally intricate level structure.\r\n\r\n---\r\n\r\n## \ud83e\udde0 License\r\n\r\n\u00a9 Felix Kogel \u2014 released under the **MIT License**. \r\nSee [`LICENSE`](./LICENSE.md) for details.\r\n\r\n---\r\n\r\n### \ud83d\udc69\u200d\ud83d\udd2c Developed by Felix Kogel\r\nFor questions or feedback, open an issue on [GitHub](https://github.com/LangenGroup/MoleCool/issues).\r\n\r\n---\r\n\r\n**MoleCool** \u2014 *A modular Python framework for simulating laser cooling of molecules.*\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Molecular Laser-Cooling and Spectra Simulation",
"version": "3.7.3",
"project_urls": {
"Documentation": "https://molecool-py.readthedocs.io/en/stable",
"Homepage": "https://www.coldmolecules.eu/Home/",
"Issues": "https://github.com/LangenGroup/MoleCool/issues",
"Repository": "https://github.com/LangenGroup/MoleCool"
},
"split_keywords": [
"cold molecules",
" laser cooling",
" optical bloch equations",
" rate equations",
" diatomic molecules",
" multi-level systems",
" rabi-oscillations",
" coherent laser forces"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "5e27756a582daf5d904cb7414009062449b897b75a77065f80021d2ca190467d",
"md5": "1b545f3611386a1278172dd6ca75d4bb",
"sha256": "2ef800d99349313ee1ed4644c108f27e76dc8badc9b4eba0fd984a97179428a7"
},
"downloads": -1,
"filename": "molecool-3.7.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b545f3611386a1278172dd6ca75d4bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 143017,
"upload_time": "2025-10-21T08:43:42",
"upload_time_iso_8601": "2025-10-21T08:43:42.341171Z",
"url": "https://files.pythonhosted.org/packages/5e/27/756a582daf5d904cb7414009062449b897b75a77065f80021d2ca190467d/molecool-3.7.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5a9a48abc93797151d56cf9945da8e412321b389458a780d8e6a2391e7bbe79d",
"md5": "dc67a66af840e06dd872d923050971be",
"sha256": "ca84d3a1ed6dd1f911785f9bbbcfd7ff79997c96b649fb680d9fbefec5383d03"
},
"downloads": -1,
"filename": "molecool-3.7.3.tar.gz",
"has_sig": false,
"md5_digest": "dc67a66af840e06dd872d923050971be",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 870343,
"upload_time": "2025-10-21T08:43:43",
"upload_time_iso_8601": "2025-10-21T08:43:43.679611Z",
"url": "https://files.pythonhosted.org/packages/5a/9a/48abc93797151d56cf9945da8e412321b389458a780d8e6a2391e7bbe79d/molecool-3.7.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-21 08:43:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LangenGroup",
"github_project": "MoleCool",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "molecool"
}
JSON
