<p align="center"><img width="60.0%" src="pics/qrotor.png"></p>
QRotor is a Python package used to study molecular rotations
based on the one-dimensional hindered-rotor model,
such as those of methyl and amine groups.
It can calculate their quantum energy levels and wavefunctions,
along with excitations and tunnel splittings.
QRotor systematically produces Quantum ESPRESSO SCF calculations to obtain
the rotational Potential Energy Surface (PES) of custom molecular structures.
This potential is used to solve the quantum hamiltonian of the hindered rotor model:
$$
H = -B \frac{d^2}{d\varphi^2} + V(\varphi)
$$
where $B$ is the *kinetic rotational energy* constant,
$$
B = \frac{\hbar^2}{2I}=\frac{\hbar^2}{2\sum_{i}m_{i}r_{i}^{2}}
$$
Head to the [Usage](#usage) section for a quick hands-on introduction.
---
# Installation
As always, it is recommended to install your packages in a virtual environment:
```bash
python3 -m venv .venv
source .venv/bin/activate
```
## With pip
Install or upgrade ATON with
```bash
pip install qrotor -U
```
## From source
Optionally, you can install ATON from the [GitHub repo](https://github.com/pablogila/qrotor/).
Clone the repository or download the [latest stable release](https://github.com/pablogila/qrotor/tags)
as a ZIP, unzip it, and run inside it:
```bash
pip install .
```
---
# Documentation
QRotor contains the following modules:
| | |
| --- | --- |
| [qrotor.constants](https://pablogila.github.io/qrotor/qrotor/constants.html) | Common bond lengths and inertias |
| [qrotor.system](https://pablogila.github.io/qrotor/qrotor/system.html) | Definition of the quantum `System` object |
| [qrotor.systems](https://pablogila.github.io/qrotor/qrotor/systems.html) | Utilities to manage several System objects, such as a list of systems |
| [qrotor.rotation](https://pablogila.github.io/qrotor/qrotor/rotation.html) | Rotate specific atoms from structural files |
| [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) | Potential definitions and loading functions |
| [qrotor.solve](https://pablogila.github.io/qrotor/qrotor/solve.html) | Solve rotation eigenvalues and eigenvectors |
| [qrotor.plot](https://pablogila.github.io/qrotor/qrotor/plot.html) | Plotting utilities |
Check the [full documentation online](https://pablogila.github.io/qrotor/).
---
# Usage
## Solving quantum eigenvalues for one-dimensional rotor systems
Let's start with a basic calculation of the eigenvalues for a zero potential, corresponding to a free rotor.
Note that the default energy unit is meV unless stated otherwise.
```python
import qrotor as qr
system = qr.System()
system.gridsize = 200000 # Size of the potential grid
system.B = 1 # Rotational inertia
system.potential_name = 'zero'
system.solve()
print(system.eigenvalues)
# [0.0, 1.0, 1.0, 4.0, 4.0, 9.0, 9.0, ...] # approx values
```
The accuracy of the calculation increases with bigger gridsizes,
but note that the runtime increases exponentially.
Predefined synthetic potentials can be used,
see all available options in the [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) documentation.
For example, we can solve the system for a hindered methyl group,
in a [cosine potential](https://pablogila.github.io/qrotor/qrotor/potential.html#cosine) of amplitude 30 meV:
```python
import qrotor as qr
system = qr.System()
system.gridsize = 200000
system.B = qr.B_CH3 # Rotational inertia of a methyl group
system.potential_name = 'cosine'
system.potential_constants = [0, 30, 3, 0] # Offset, max, freq, phase (for cosine potential)
system.solve()
# Plot potential and eigenvalues
qr.plot.energies(system)
# Plot the first wavefunctions
qr.plot.wavefunction(system, levels=[0,1,2], square=True)
```
## Rotational PES from custom structures
QRotor can be used to calculate the rotational Potential Energy Surface (PES) from DFT calculations.
Currently only Quantum ESPRESSO is supported,
although other DFT codes can be easily implemented through [ATON](https://pablogila.github.io/aton).
First, run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:
```python
import qrotor as qr
from aton import api
# Approx crystal positions of the atoms to rotate
atoms = [
'1.101 1.204 1.307'
'2.102 2.205 2.308'
'3.103 3.206 3.309'
]
# Create the input SCF files, saving the filenames to a list
scf_files = qr.rotation.rotate_qe('molecule.in', positions=atoms, angle=10, repeat=True)
# Run the Quantum ESPRESSO calculations
api.slurm.sbatch(files=scf_files)
```
You can compile a `potential.csv` file with the calculated potential as a function of the angle,
and load it into a new [system](https://pablogila.github.io/qrotor/qrotor/system.html):
```python
system = qr.potential.from_qe()
# Check the potential
qr.plot.potential(system)
# Solve the system, interpolating to a bigger gridsize
system.B = qr.B_CH3
system.solve(200000)
qr.plot.energies(system)
```
## Other quantum observables
The Zero-Point Energies (ZPEs), quantum tunnel splittings, excitations and energy level degeneracy
below the potential maximum are also calculated upon solving the [system](https://pablogila.github.io/qrotor/qrotor/system.html):
```python
system.solve()
print(system.eigenvalues[0])
print(system.splittings)
print(system.excitations)
print(system.deg)
```
An integer `System.deg` degeneracy (e.g. 3 for methyls)
indicates that the energy levels have been properly estimated.
However, if the degeneracy is a float instead,
you might want to check the splittings and excitations manually from the system eigenvalues.
To export the energies and the tunnel splittings of several calculations to a CSV file:
```python
calculations = [system1, system2, system3]
qr.systems.save_energies(calculations)
qr.systems.save_splittings(calculations)
```
Excitations are calculated using the mean for each energy level
with respect to the ground state.
Tunnel splittings for each level are calculated as the difference between A and E,
considering the mean of the eigenvalues for each sublevel.
See [R. M. Dimeo, American Journal of Physics 71, 885–893 (2003)](https://doi.org/10.1119/1.1538575)
and [A. J. Horsewill, Progress in Nuclear Magnetic Resonance Spectroscopy 35, 359–389 (1999)](https://doi.org/10.1016/S0079-6565(99)00016-3)
for further reference.
---
# Contributing
If you are interested in opening an issue or a pull request, please feel free to do so on [GitHub](https://github.com/pablogila/qrotor/).
For major changes, please get in touch first to discuss the details.
## Code style
Please try to follow some general guidelines:
- Use a code style consistent with the rest of the project.
- Include docstrings to document new additions.
- Include automated tests for new features or modifications, see [automated testing](#automated-testing).
- Arrange function arguments by order of relevance.
## Automated testing
If you are modifying the source code, you should run the automated tests of the [`tests/`](https://github.com/pablogila/qrotor/tree/main/tests) folder to check that everything works as intended.
To do so, first install PyTest in your environment,
```bash
pip install pytest
```
And then run PyTest inside the main directory,
```bash
pytest -vv
```
## Compiling the documentation
The documentation can be compiled automatically to `docs/qrotor.html` with [Pdoc](https://pdoc.dev/) and [ATON](https://pablogila.github.io/aton), by running:
```shell
python3 makedocs.py
```
This runs Pdoc, updating links and pictures, and using the custom theme CSS template from the `css/` folder.
---
# Citation
QRotor is currently under development.
Please cite it if you use it in your research,
> Gila-Herranz, P. (2024). QRotor: Solving one-dimensional hindered-rotor quantum systems. https://pablogila.github.io/qrotor
---
# License
Copyright (C) 2025 Pablo Gila-Herranz
This program is free software: you can redistribute it and/or modify
it under the terms of the **GNU Affero General Public License** as published
by the Free Software Foundation, either version **3** of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the attached GNU Affero General Public License for more details.
Raw data
{
"_id": null,
"home_page": null,
"name": "qrotor",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "QRotor, Molecular rotations, Quantum rotations, Quantum, Molecular, Rotations, Neutrons, Research, Ab-initio, DFT, Density Functional Theory, Quantum ESPRESSO, Phonons, Electronic structure",
"author": "Pablo Gila-Herranz",
"author_email": "pgila001@ikasle.ehu.eus",
"download_url": "https://files.pythonhosted.org/packages/02/03/299554545d0741df003c535af972269a9970cfc73b2a394a53147a3913d8/qrotor-4.5.1.tar.gz",
"platform": null,
"description": "<p align=\"center\"><img width=\"60.0%\" src=\"pics/qrotor.png\"></p>\n \n\nQRotor is a Python package used to study molecular rotations\nbased on the one-dimensional hindered-rotor model,\nsuch as those of methyl and amine groups.\nIt can calculate their quantum energy levels and wavefunctions,\nalong with excitations and tunnel splittings.\n\nQRotor systematically produces Quantum ESPRESSO SCF calculations to obtain\nthe rotational Potential Energy Surface (PES) of custom molecular structures.\nThis potential is used to solve the quantum hamiltonian of the hindered rotor model:\n\n$$\nH = -B \\frac{d^2}{d\\varphi^2} + V(\\varphi)\n$$\n\nwhere $B$ is the *kinetic rotational energy* constant,\n\n$$\nB = \\frac{\\hbar^2}{2I}=\\frac{\\hbar^2}{2\\sum_{i}m_{i}r_{i}^{2}}\n$$\n\nHead to the [Usage](#usage) section for a quick hands-on introduction.\n\n\n---\n\n\n# Installation\n\n\nAs always, it is recommended to install your packages in a virtual environment: \n```bash\npython3 -m venv .venv\nsource .venv/bin/activate\n```\n\n\n## With pip\n\n\nInstall or upgrade ATON with \n```bash\npip install qrotor -U\n```\n\n\n## From source\n\n\nOptionally, you can install ATON from the [GitHub repo](https://github.com/pablogila/qrotor/).\nClone the repository or download the [latest stable release](https://github.com/pablogila/qrotor/tags)\nas a ZIP, unzip it, and run inside it: \n```bash\npip install .\n```\n\n\n---\n\n\n# Documentation\n\n\nQRotor contains the following modules:\n\n| | |\n| --- | --- |\n| [qrotor.constants](https://pablogila.github.io/qrotor/qrotor/constants.html) | Common bond lengths and inertias |\n| [qrotor.system](https://pablogila.github.io/qrotor/qrotor/system.html) | Definition of the quantum `System` object |\n| [qrotor.systems](https://pablogila.github.io/qrotor/qrotor/systems.html) | Utilities to manage several System objects, such as a list of systems |\n| [qrotor.rotation](https://pablogila.github.io/qrotor/qrotor/rotation.html) | Rotate specific atoms from structural files |\n| [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) | Potential definitions and loading functions |\n| [qrotor.solve](https://pablogila.github.io/qrotor/qrotor/solve.html) | Solve rotation eigenvalues and eigenvectors |\n| [qrotor.plot](https://pablogila.github.io/qrotor/qrotor/plot.html) | Plotting utilities |\n\nCheck the [full documentation online](https://pablogila.github.io/qrotor/).\n\n\n---\n\n\n# Usage\n\n\n## Solving quantum eigenvalues for one-dimensional rotor systems\n\n\nLet's start with a basic calculation of the eigenvalues for a zero potential, corresponding to a free rotor. \nNote that the default energy unit is meV unless stated otherwise.\n\n```python\nimport qrotor as qr\nsystem = qr.System()\nsystem.gridsize = 200000 # Size of the potential grid\nsystem.B = 1 # Rotational inertia\nsystem.potential_name = 'zero'\nsystem.solve()\nprint(system.eigenvalues)\n# [0.0, 1.0, 1.0, 4.0, 4.0, 9.0, 9.0, ...] # approx values\n```\n\nThe accuracy of the calculation increases with bigger gridsizes,\nbut note that the runtime increases exponentially.\n\nPredefined synthetic potentials can be used,\nsee all available options in the [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) documentation.\nFor example, we can solve the system for a hindered methyl group,\nin a [cosine potential](https://pablogila.github.io/qrotor/qrotor/potential.html#cosine) of amplitude 30 meV:\n\n```python\nimport qrotor as qr\nsystem = qr.System()\nsystem.gridsize = 200000\nsystem.B = qr.B_CH3 # Rotational inertia of a methyl group\nsystem.potential_name = 'cosine'\nsystem.potential_constants = [0, 30, 3, 0] # Offset, max, freq, phase (for cosine potential)\nsystem.solve()\n# Plot potential and eigenvalues\nqr.plot.energies(system)\n# Plot the first wavefunctions\nqr.plot.wavefunction(system, levels=[0,1,2], square=True)\n```\n\n\n## Rotational PES from custom structures\n\n\nQRotor can be used to calculate the rotational Potential Energy Surface (PES) from DFT calculations.\nCurrently only Quantum ESPRESSO is supported,\nalthough other DFT codes can be easily implemented through [ATON](https://pablogila.github.io/aton).\n\nFirst, run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:\n\n```python\nimport qrotor as qr\nfrom aton import api\n# Approx crystal positions of the atoms to rotate\natoms = [\n '1.101 1.204 1.307'\n '2.102 2.205 2.308'\n '3.103 3.206 3.309'\n]\n# Create the input SCF files, saving the filenames to a list\nscf_files = qr.rotation.rotate_qe('molecule.in', positions=atoms, angle=10, repeat=True)\n# Run the Quantum ESPRESSO calculations\napi.slurm.sbatch(files=scf_files)\n```\n\nYou can compile a `potential.csv` file with the calculated potential as a function of the angle,\nand load it into a new [system](https://pablogila.github.io/qrotor/qrotor/system.html):\n\n```python\nsystem = qr.potential.from_qe()\n# Check the potential\nqr.plot.potential(system)\n# Solve the system, interpolating to a bigger gridsize\nsystem.B = qr.B_CH3\nsystem.solve(200000)\nqr.plot.energies(system)\n```\n\n\n## Other quantum observables\n\n\nThe Zero-Point Energies (ZPEs), quantum tunnel splittings, excitations and energy level degeneracy\nbelow the potential maximum are also calculated upon solving the [system](https://pablogila.github.io/qrotor/qrotor/system.html):\n\n```python\nsystem.solve()\nprint(system.eigenvalues[0])\nprint(system.splittings)\nprint(system.excitations)\nprint(system.deg)\n```\n\nAn integer `System.deg` degeneracy (e.g. 3 for methyls)\nindicates that the energy levels have been properly estimated.\nHowever, if the degeneracy is a float instead,\nyou might want to check the splittings and excitations manually from the system eigenvalues.\n\nTo export the energies and the tunnel splittings of several calculations to a CSV file:\n\n```python\ncalculations = [system1, system2, system3]\nqr.systems.save_energies(calculations)\nqr.systems.save_splittings(calculations)\n```\n\nExcitations are calculated using the mean for each energy level\nwith respect to the ground state.\nTunnel splittings for each level are calculated as the difference between A and E,\nconsidering the mean of the eigenvalues for each sublevel.\nSee [R. M. Dimeo, American Journal of Physics 71, 885\u2013893 (2003)](https://doi.org/10.1119/1.1538575)\nand [A. J. Horsewill, Progress in Nuclear Magnetic Resonance Spectroscopy 35, 359\u2013389 (1999)](https://doi.org/10.1016/S0079-6565(99)00016-3)\nfor further reference.\n\n\n---\n\n\n# Contributing\n\n\nIf you are interested in opening an issue or a pull request, please feel free to do so on [GitHub](https://github.com/pablogila/qrotor/). \nFor major changes, please get in touch first to discuss the details. \n\n\n## Code style\n\n\nPlease try to follow some general guidelines: \n- Use a code style consistent with the rest of the project. \n- Include docstrings to document new additions. \n- Include automated tests for new features or modifications, see [automated testing](#automated-testing). \n- Arrange function arguments by order of relevance. \n\n\n## Automated testing\n\n\nIf you are modifying the source code, you should run the automated tests of the [`tests/`](https://github.com/pablogila/qrotor/tree/main/tests) folder to check that everything works as intended.\nTo do so, first install PyTest in your environment,\n```bash\npip install pytest\n```\n\nAnd then run PyTest inside the main directory,\n```bash\npytest -vv\n```\n\n\n## Compiling the documentation\n\nThe documentation can be compiled automatically to `docs/qrotor.html` with [Pdoc](https://pdoc.dev/) and [ATON](https://pablogila.github.io/aton), by running:\n```shell\npython3 makedocs.py\n```\n\nThis runs Pdoc, updating links and pictures, and using the custom theme CSS template from the `css/` folder.\n\n\n---\n\n\n# Citation\n\nQRotor is currently under development.\nPlease cite it if you use it in your research,\n> Gila-Herranz, P. (2024). QRotor: Solving one-dimensional hindered-rotor quantum systems. https://pablogila.github.io/qrotor\n\n\n---\n\n\n# License\n\n\nCopyright (C) 2025 Pablo Gila-Herranz \nThis program is free software: you can redistribute it and/or modify\nit under the terms of the **GNU Affero General Public License** as published\nby the Free Software Foundation, either version **3** of the License, or\n(at your option) any later version. \nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. \nSee the attached GNU Affero General Public License for more details. \n\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "QRotor",
"version": "4.5.1",
"project_urls": null,
"split_keywords": [
"qrotor",
" molecular rotations",
" quantum rotations",
" quantum",
" molecular",
" rotations",
" neutrons",
" research",
" ab-initio",
" dft",
" density functional theory",
" quantum espresso",
" phonons",
" electronic structure"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7d176df9763725f5aecb8d64ff70e83ee8fb6bd8b2c88805429e9e965571647c",
"md5": "2133cc6d0bd9270c5fef61f2240bba2a",
"sha256": "76a719ef0ea651fb1977bfcc358df969e9b09aec1ea3a514e1c10fc7cd070df0"
},
"downloads": -1,
"filename": "qrotor-4.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2133cc6d0bd9270c5fef61f2240bba2a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 44601,
"upload_time": "2025-10-17T11:12:38",
"upload_time_iso_8601": "2025-10-17T11:12:38.312821Z",
"url": "https://files.pythonhosted.org/packages/7d/17/6df9763725f5aecb8d64ff70e83ee8fb6bd8b2c88805429e9e965571647c/qrotor-4.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0203299554545d0741df003c535af972269a9970cfc73b2a394a53147a3913d8",
"md5": "74328f4623047df6a627094f3578adea",
"sha256": "85b164a630f653ef462c5b7b131e7fbf4d6a131c77e52af8d49b65503356edff"
},
"downloads": -1,
"filename": "qrotor-4.5.1.tar.gz",
"has_sig": false,
"md5_digest": "74328f4623047df6a627094f3578adea",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 43043,
"upload_time": "2025-10-17T11:12:40",
"upload_time_iso_8601": "2025-10-17T11:12:40.152158Z",
"url": "https://files.pythonhosted.org/packages/02/03/299554545d0741df003c535af972269a9970cfc73b2a394a53147a3913d8/qrotor-4.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 11:12:40",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "qrotor"
}
JSON