qrotor 4.6.0

QRotor

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 section for a quick hands-on introduction.

---

Installation

As always, it is recommended to install your packages in a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

With pip

Install or upgrade QRotor with

pip install qrotor -U

From source

Optionally, you can install QRotor from the GitHub repo. Clone the repository or download the latest stable release as a ZIP, unzip it, and run inside it:

pip install .

---

Documentation

QRotor contains the following modules:

qrotor.constants	Common bond lengths and inertias
qrotor.system	Definition of the quantum System object
qrotor.systems	Utilities to manage several System objects, such as a list of systems
qrotor.rotation	Rotate specific atoms from structural files
qrotor.potential	Potential definitions and loading functions
qrotor.solve	Solve rotation eigenvalues and eigenvectors
qrotor.plot	Plotting utilities

Check the full documentation online.

---

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.

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 documentation. For example, we can solve the system for a hindered methyl group, in a cosine potential of amplitude 30 meV:

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.

First, run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:

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:

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:

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:

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) and A. J. Horsewill, Progress in Nuclear Magnetic Resonance Spectroscopy 35, 359–389 (1999) for further reference.

---

Contributing

If you are interested in opening an issue or a pull request, please feel free to do so on GitHub.
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.
• 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/ folder to check that everything works as intended. To do so, first install PyTest in your environment,

pip install pytest

And then run PyTest inside the main directory,

pytest -vv

Compiling the documentation

The documentation can be compiled automatically to docs/qrotor.html with Pdoc and ATON, by running:

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.