qrotor 4.0.0a2__tar.gz → 4.0.2__tar.gz

{qrotor-4.0.0a2 → qrotor-4.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qrotor
-Version: 4.0.0a2
+Version: 4.0.2
 Summary: QRotor
 Author: Pablo Gila-Herranz
 Author-email: pgila001@ikasle.ehu.eus
@@ -21,6 +21,7 @@ Requires-Dist: pandas
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: aton
+Requires-Dist: periodictable
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -33,7 +34,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-<p align="center"><img width="40.0%" src="pics/qrotor.png"></p>
+<p align="center"><img width="60.0%" src="pics/qrotor.png"></p>
  
 QRotor is a Python package used to study molecular rotations,
 such as those of methyl and amine groups.
@@ -44,27 +45,66 @@ These quantum systems are represented by the `qrotor.System()` object.
 QRotor can obtain custom potentials from DFT,
 which are used to solve the quantum system.
 
-Check the [full documentation online](https://pablogila.github.io/qrotor/).
+
+---
+
+
+# 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 .
+```
 
 
-# Index
+---
+
+
+# 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)     | Functions to manage several System objects, such as a list of systems |
+| [qrotor.systems](https://pablogila.github.io/qrotor/qrotor/systems.html)     | Utilities to manage several System objects, such as a list of systems |
 | [qrotor.rotate](https://pablogila.github.io/qrotor/qrotor/rotate.html)       | Rotate specific atoms from structural files |
-| [qrotor.constants](https://pablogila.github.io/qrotor/qrotor/constants.html) | Common bond lengths and inertias |
 | [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 functions |
+| [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 rotational systems
 
-A basic calculation of the eigenvalues for a zero potential goes as follows.
+Let's start with a basic calculation of the eigenvalues for a zero potential, corresponding to a free rotor. 
+A predefined synthetic potential can be used, see all available options in the [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) documentation.
 Note that the default energy unit is meV unless stated otherwise.
 
 ```python
@@ -74,7 +114,7 @@ system.gridsize = 200000  # Size of the potential grid
 system.B = 1  # Rotational inertia
 system.potential_name = 'zero'
 system.solve()
-system.eigenvalues
+print(system.eigenvalues)
 # [0.0, 1.0, 1.0, 4.0, 4.0, 9.0, 9.0, ...]  # approx values
 ```
 
@@ -87,10 +127,10 @@ in a cosine potential of amplitude 30 meV:
 ```python
 import qrotor as qr
 system = qr.System()
-system.gridsize = 200000  # Size of the potential grid
+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 cos pot.)
+system.potential_constants = [0, 30, 3, 0]  # Offset, max, freq, phase (for cosine potential)
 system.solve()
 # Plot potential and eigenvalues
 qr.plot.energies(system)
@@ -102,7 +142,7 @@ qr.plot.wavefunction(system, levels=[0,1,2], square=True)
 ## Custom potentials from DFT
 
 QRotor can be used to obtain custom rotational potentials from DFT calculations.
-Using Quantum ESPRESSO, running an SCF calculation for a methyl rotation every 10 degrees:
+To run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:
 
 ```python
 import qrotor as qr
@@ -121,10 +161,8 @@ api.slurm.sbatch(files=scf_files)
 
 To load the calculated potential to a QRotor System,
 ```python
-# Compile a 'potential.csv' file with the calculated potential as a function of the angle
-qr.potential.from_qe()
-# Load to the system
-system = qr.potential.load()
+# 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()
 # Solve the system, interpolating to a bigger gridsize
 system.B = qr.B_CH3
 system.solve(200000)
@@ -139,9 +177,9 @@ below the potential maximum are also calculated upon solving the system:
 
 ```python
 system.solve()
-system.splittings
-system.excitations
-system.deg
+print(system.splittings)
+print(system.excitations)
+print(system.deg)
 ```
 
 An integer `System.deg` degeneracy (e.g. 3 for methyls)
@@ -165,3 +203,71 @@ See [R. M. Dimeo, American Journal of Physics 71, 885–893 (2003)](https://doi.
 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,
+> Pablo Gila-Herranz, *QRotor*, 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.  
+

{qrotor-4.0.0a2 → qrotor-4.0.2}/README.md

@@ -1,4 +1,4 @@
-<p align="center"><img width="40.0%" src="pics/qrotor.png"></p>
+<p align="center"><img width="60.0%" src="pics/qrotor.png"></p>
  
 QRotor is a Python package used to study molecular rotations,
 such as those of methyl and amine groups.
@@ -9,27 +9,66 @@ These quantum systems are represented by the `qrotor.System()` object.
 QRotor can obtain custom potentials from DFT,
 which are used to solve the quantum system.
 
-Check the [full documentation online](https://pablogila.github.io/qrotor/).
+
+---
+
+
+# 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 .
+```
 
 
-# Index
+---
+
+
+# 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)     | Functions to manage several System objects, such as a list of systems |
+| [qrotor.systems](https://pablogila.github.io/qrotor/qrotor/systems.html)     | Utilities to manage several System objects, such as a list of systems |
 | [qrotor.rotate](https://pablogila.github.io/qrotor/qrotor/rotate.html)       | Rotate specific atoms from structural files |
-| [qrotor.constants](https://pablogila.github.io/qrotor/qrotor/constants.html) | Common bond lengths and inertias |
 | [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 functions |
+| [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 rotational systems
 
-A basic calculation of the eigenvalues for a zero potential goes as follows.
+Let's start with a basic calculation of the eigenvalues for a zero potential, corresponding to a free rotor. 
+A predefined synthetic potential can be used, see all available options in the [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) documentation.
 Note that the default energy unit is meV unless stated otherwise.
 
 ```python
@@ -39,7 +78,7 @@ system.gridsize = 200000  # Size of the potential grid
 system.B = 1  # Rotational inertia
 system.potential_name = 'zero'
 system.solve()
-system.eigenvalues
+print(system.eigenvalues)
 # [0.0, 1.0, 1.0, 4.0, 4.0, 9.0, 9.0, ...]  # approx values
 ```
 
@@ -52,10 +91,10 @@ in a cosine potential of amplitude 30 meV:
 ```python
 import qrotor as qr
 system = qr.System()
-system.gridsize = 200000  # Size of the potential grid
+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 cos pot.)
+system.potential_constants = [0, 30, 3, 0]  # Offset, max, freq, phase (for cosine potential)
 system.solve()
 # Plot potential and eigenvalues
 qr.plot.energies(system)
@@ -67,7 +106,7 @@ qr.plot.wavefunction(system, levels=[0,1,2], square=True)
 ## Custom potentials from DFT
 
 QRotor can be used to obtain custom rotational potentials from DFT calculations.
-Using Quantum ESPRESSO, running an SCF calculation for a methyl rotation every 10 degrees:
+To run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:
 
 ```python
 import qrotor as qr
@@ -86,10 +125,8 @@ api.slurm.sbatch(files=scf_files)
 
 To load the calculated potential to a QRotor System,
 ```python
-# Compile a 'potential.csv' file with the calculated potential as a function of the angle
-qr.potential.from_qe()
-# Load to the system
-system = qr.potential.load()
+# 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()
 # Solve the system, interpolating to a bigger gridsize
 system.B = qr.B_CH3
 system.solve(200000)
@@ -104,9 +141,9 @@ below the potential maximum are also calculated upon solving the system:
 
 ```python
 system.solve()
-system.splittings
-system.excitations
-system.deg
+print(system.splittings)
+print(system.excitations)
+print(system.deg)
 ```
 
 An integer `System.deg` degeneracy (e.g. 3 for methyls)
@@ -130,3 +167,71 @@ See [R. M. Dimeo, American Journal of Physics 71, 885–893 (2003)](https://doi.
 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,
+> Pablo Gila-Herranz, *QRotor*, 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.  
+

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor/_version.py

@@ -10,5 +10,5 @@ https://semver.org/
 
 """
 
-__version__ = 'v4.0.0a2'
+__version__ = 'v4.0.2'
 

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor/constants.py

@@ -11,7 +11,8 @@ Bond lengths and angles were obtained from MAPbI3, see
 
 
 import numpy as np
-import aton.phys as phys
+import periodictable
+import scipy.constants as const
 
 
 # Distance between Carbon and Hydrogen atoms (measured from MAPbI3)
@@ -31,29 +32,31 @@ angle_NH = 180 - angle_NH_external
 """Internal angle of the X-N-H bond, in degrees."""
 
 # Rotation radius (calculated from distance and angle)
-r_CH = distance_CH * np.sin(np.deg2rad(angle_CH)) * phys.AA_to_m
+r_CH = distance_CH * np.sin(np.deg2rad(angle_CH)) * 1e-10
 """Rotation radius of the methyl group, in meters."""
-r_NH = distance_NH * np.sin(np.deg2rad(angle_NH)) * phys.AA_to_m
+r_NH = distance_NH * np.sin(np.deg2rad(angle_NH)) * 1e-10
 """Rotation radius of the amine group, in meters."""
 
 # Inertia, SI units
-I_CH3 = 3 * (phys.atoms['H'].mass * phys.amu_to_kg * r_CH**2)
+_amu = const.physical_constants['atomic mass constant'][0]
+I_CH3 = 3 * (periodictable.H.mass * _amu * r_CH**2)
 """Inertia of CH3, in kg·m^2."""
-I_CD3 = 3 * (phys.atoms['H'].isotope[2].mass * phys.amu_to_kg * r_CH**2)
+I_CD3 = 3 * (periodictable.D.mass * _amu * r_CH**2)
 """Inertia of CD3, in kg·m^2."""
-I_NH3 = 3 * (phys.atoms['H'].mass * phys.amu_to_kg * r_NH**2)
+I_NH3 = 3 * (periodictable.H.mass * _amu * r_NH**2)
 """Inertia of NH3, in kg·m^2."""
-I_ND3 = 3 * (phys.atoms['H'].isotope[2].mass * phys.amu_to_kg * r_NH**2)
+I_ND3 = 3 * (periodictable.D.mass * _amu * r_NH**2)
 """Inertia of ND3, in kg·m^2."""
 
-# Rotational energy.
-B_CH3 = ((phys.hbar**2) / (2 * I_CH3)) * phys.J_to_meV
+# Rotational energy
+_hbar = const.physical_constants['reduced Planck constant'][0]
+B_CH3 = ((_hbar**2) / (2 * I_CH3)) * (1000 / const.eV)
 """Rotational energy of CH3, in meV·s/kg·m^2."""
-B_CD3 = ((phys.hbar**2) / (2 * I_CD3)) * phys.J_to_meV
+B_CD3 = ((_hbar**2) / (2 * I_CD3)) * (1000 / const.eV)
 """Rotational energy of CD3, in meV·s/kg·m^2."""
-B_NH3 = ((phys.hbar**2) / (2 * I_NH3)) * phys.J_to_meV
+B_NH3 = ((_hbar**2) / (2 * I_NH3)) * (1000 / const.eV)
 """Rotational energy of NH3, in meV·s/kg·m^2."""
-B_ND3 = ((phys.hbar**2) / (2 * I_ND3)) * phys.J_to_meV
+B_ND3 = ((_hbar**2) / (2 * I_ND3)) * (1000 / const.eV)
 """Rotational energy of ND3, in meV·s/kg·m^2."""
 
 # Potential constants from titov2023 [C1, C2, C3, C4, C5]
@@ -70,3 +73,13 @@ for the `qrotor.potential.titov2023` potential.
 In meV units.
 """
 
+# Quick conversion factors
+Ry_to_eV = const.physical_constants['Rydberg constant times hc in eV'][0]
+"""Quick conversion factor from eV to Rydberg energy."""
+Ry_to_meV = Ry_to_eV * 1000
+"""Quick conversion factor from meV to Rydberg energy."""
+eV_to_Ry = 1 / Ry_to_eV
+"""Quick conversion factor from Rydberg to eV."""
+meV_to_Ry = 1 / Ry_to_meV
+"""Quick conversion factor from Rydberg to meV."""
+

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor/plot.py

@@ -21,11 +21,11 @@ This module provides straightforward functions to plot QRotor data.
 
 from .system import System
 from . import systems
+from . import constants
 import matplotlib.pyplot as plt
 import numpy as np
 from copy import deepcopy
 import aton.alias as alias
-import aton.phys as phys
 
 
 def potential(
@@ -271,7 +271,7 @@ def splittings(
     The different `System.comment` are shown in the horizontal axis.
     An optional `title` can be specified.
     Default units shown are $\\mu$eV (`'ueV'`).
-    Available units are: `'ueV'`, `'meV'`, `'Ry'`.
+    Available units are: `'ueV'`, `'meV'`, `'Ry'`, or `'B'` (free rotor units).
     """
     title = title if title != None else 'Tunnel splitting energies'
     calcs = deepcopy(data)
@@ -284,11 +284,14 @@ def splittings(
     x = [c.comment for c in calcs]
     # What units do we want?
     if units.lower() in alias.units['ueV']:
-        y = [j * phys.meV_to_ueV for j in y]
+        y = [j * 1000 for j in y]  # Convert meV to micro eV
         ax.set_ylabel("Energy / $\\mu$eV")
     elif units.lower() in alias.units['Ry']:
-        y = [j * phys.meV_to_Ry for j in y]
+        y = [j * constants.meV_to_Ry for j in y]
         ax.set_ylabel("Energy / Ry")
+    elif units.upper() == 'B':
+        y = [j / c.B for j, c in zip(y, calcs)]
+        ax.set_ylabel("Energy / B")
     #else:  # It's okay let's use meV
 
     ax.bar(range(len(y)), y)

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor/potential.py

@@ -50,7 +50,6 @@ from scipy.interpolate import CubicSpline
 import aton.alias as alias
 import aton.file as file
 import aton.api.qe as qe
-import aton.phys as phys
 from ._version import __version__
 
 
@@ -67,6 +66,7 @@ def save(
     in degrees and meVs by default.
     The units can be changed with `angle` and `energy`,
     but only change these defaults if you know what you are doing.
+    An optional `comment` can be included in the header of the file.
     """
     print('Saving potential data file...')
     # Check if a previous potential.dat file exists, and ask to overwrite it
@@ -78,7 +78,7 @@ def save(
             print("Aborted.")
             return None
     # Set header
-    potential_data = f'# {comment}\n' if comment else f'# {system.comment}\n' if system.comment else ''
+    potential_data = f'## {comment}\n' if comment else f'## {system.comment}\n' if system.comment else ''
     potential_data += '# Rotational potential dataset\n'
     potential_data += f'# Saved with QRotor {__version__}\n'
     potential_data += '# https://pablogila.github.io/qrotor\n'
@@ -100,10 +100,10 @@ def save(
     if energy.lower() in alias.units['meV']:
         potential_data += 'Potential/meV\n'
     elif energy.lower() in alias.units['eV']:
-        potential_values = potential_values * phys.meV_to_eV
+        potential_values = potential_values * 1e-3
         potential_data += 'Potential/eV\n'
     elif energy.lower() in alias.units['Ry']:
-        potential_values = potential_values * phys.meV_to_Ry
+        potential_values = potential_values * constants.meV_to_Ry
         potential_data += 'Potential/Ry\n'
     else:
         print(f"WARNING:  Unrecognised '{energy}' energy units, using meV instead")
@@ -144,6 +144,11 @@ def load(
     system = System() if system is None else system
     with open(file_path, 'r') as f:
         lines = f.readlines()
+    # Read the comment
+    loaded_comment = ''
+    if lines[0].startswith('## '):
+        loaded_comment = lines[0][3:].strip()
+    # Read data
     positions = []
     potentials = []
     for line in lines:
@@ -161,19 +166,24 @@ def load(
         raise ValueError(f"Angle unit '{angle}' not recognized.")
     # Save energies to numpy arrays
     if energy.lower() in alias.units['eV']:
-        potentials = np.array(potentials) * phys.eV_to_meV
+        potentials = np.array(potentials) * 1000
     elif energy.lower() in alias.units['meV']:
         potentials = np.array(potentials)
     elif energy.lower() in alias.units['Ry']:
-        potentials = np.array(potentials) * phys.Ry_to_meV
+        potentials = np.array(potentials) * constants.Ry_to_meV
     else:
         raise ValueError(f"Energy unit '{energy}' not recognized.")
     # Set the system
     system.grid = np.array(positions)
     system.gridsize = len(positions)
     system.potential_values = np.array(potentials)
-    # System comment as the parent folder name
-    system.comment = os.path.basename(os.path.dirname(file_path)) if comment==None else comment
+    # System comment as the loaded comment or the parent folder name
+    if comment:
+        system.comment = comment
+    elif loaded_comment:
+        system.comment = loaded_comment
+    else:
+        system.comment = os.path.basename(os.path.dirname(file_path))
     print(f"Loaded {filepath}")
     return system
 
@@ -185,9 +195,10 @@ def from_qe(
         exclude:list=['slurm-'],
         energy:str='meV',
         comment:str=None,
-        ) -> None:
+        ) -> System:
     """Compiles a rotational potential CSV file from Quantum ESPRESSO outputs,
     created with `qrotor.rotate.structure_qe()`.
+    Returns a `System` object with the new potential values.
 
     The angle in degrees is extracted from the output filenames,
     which must follow `whatever_ANGLE.out`.
@@ -214,7 +225,7 @@ def from_qe(
     files = file.get_list(folder=folder, include=include, exclude=exclude, abspath=True)
     folder_name = os.path.basename(folder)
     # Set header
-    potential_data = f'# {comment}\n' if comment else f'# {folder_name}\n'
+    potential_data = f'## {comment}\n' if comment else f'## {folder_name}\n'
     potential_data += '# Rotational potential dataset\n'
     potential_data += f'# Calculated with QE using QRotor {__version__}\n'
     potential_data += '# https://pablogila.github.io/qrotor\n'
@@ -244,15 +255,15 @@ def from_qe(
             counter_errors += 1
             continue
         if energy.lower() in alias.units['eV']:
-            energy_value = content['Energy'] * phys.Ry_to_eV
+            energy_value = content['Energy'] * constants.Ry_to_eV
         elif energy.lower() in alias.units['meV']:
-            energy_value = content['Energy'] * phys.Ry_to_meV
+            energy_value = content['Energy'] * constants.Ry_to_meV
         elif energy.lower() in alias.units['Ry']:
             energy_value = content['Energy']
         else:
             print(f"WARNING: Energy unit '{energy}' not recognized, using meV instead.")
             energy = 'meV'
-            energy_value = content['Energy'] * phys.Ry_to_meV
+            energy_value = content['Energy'] * constants.Ry_to_meV
         splits = filename.split('_')
         angle_value = splits[-1].replace('.out', '')
         angle_value = float(angle_value)
@@ -274,7 +285,12 @@ def from_qe(
     # Warn the user if not in default units
     if energy.lower() not in alias.units['meV']:
         print(f"WARNING: You saved the potential in '{energy}' units! Remember that QRotor works in meVs!")
-    return None
+    new_system = None
+    try:
+        new_system = load(filepath=filepath, comment=comment, energy=energy)
+    except:
+        pass
+    return new_system
 
 
 def merge(

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qrotor
-Version: 4.0.0a2
+Version: 4.0.2
 Summary: QRotor
 Author: Pablo Gila-Herranz
 Author-email: pgila001@ikasle.ehu.eus
@@ -21,6 +21,7 @@ Requires-Dist: pandas
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: aton
+Requires-Dist: periodictable
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier
@@ -33,7 +34,7 @@ Dynamic: requires-dist
 Dynamic: requires-python
 Dynamic: summary
 
-<p align="center"><img width="40.0%" src="pics/qrotor.png"></p>
+<p align="center"><img width="60.0%" src="pics/qrotor.png"></p>
  
 QRotor is a Python package used to study molecular rotations,
 such as those of methyl and amine groups.
@@ -44,27 +45,66 @@ These quantum systems are represented by the `qrotor.System()` object.
 QRotor can obtain custom potentials from DFT,
 which are used to solve the quantum system.
 
-Check the [full documentation online](https://pablogila.github.io/qrotor/).
+
+---
+
+
+# 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 .
+```
 
 
-# Index
+---
+
+
+# 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)     | Functions to manage several System objects, such as a list of systems |
+| [qrotor.systems](https://pablogila.github.io/qrotor/qrotor/systems.html)     | Utilities to manage several System objects, such as a list of systems |
 | [qrotor.rotate](https://pablogila.github.io/qrotor/qrotor/rotate.html)       | Rotate specific atoms from structural files |
-| [qrotor.constants](https://pablogila.github.io/qrotor/qrotor/constants.html) | Common bond lengths and inertias |
 | [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 functions |
+| [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 rotational systems
 
-A basic calculation of the eigenvalues for a zero potential goes as follows.
+Let's start with a basic calculation of the eigenvalues for a zero potential, corresponding to a free rotor. 
+A predefined synthetic potential can be used, see all available options in the [qrotor.potential](https://pablogila.github.io/qrotor/qrotor/potential.html) documentation.
 Note that the default energy unit is meV unless stated otherwise.
 
 ```python
@@ -74,7 +114,7 @@ system.gridsize = 200000  # Size of the potential grid
 system.B = 1  # Rotational inertia
 system.potential_name = 'zero'
 system.solve()
-system.eigenvalues
+print(system.eigenvalues)
 # [0.0, 1.0, 1.0, 4.0, 4.0, 9.0, 9.0, ...]  # approx values
 ```
 
@@ -87,10 +127,10 @@ in a cosine potential of amplitude 30 meV:
 ```python
 import qrotor as qr
 system = qr.System()
-system.gridsize = 200000  # Size of the potential grid
+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 cos pot.)
+system.potential_constants = [0, 30, 3, 0]  # Offset, max, freq, phase (for cosine potential)
 system.solve()
 # Plot potential and eigenvalues
 qr.plot.energies(system)
@@ -102,7 +142,7 @@ qr.plot.wavefunction(system, levels=[0,1,2], square=True)
 ## Custom potentials from DFT
 
 QRotor can be used to obtain custom rotational potentials from DFT calculations.
-Using Quantum ESPRESSO, running an SCF calculation for a methyl rotation every 10 degrees:
+To run a Quantum ESPRESSO SCF calculation for a methyl rotation every 10 degrees:
 
 ```python
 import qrotor as qr
@@ -121,10 +161,8 @@ api.slurm.sbatch(files=scf_files)
 
 To load the calculated potential to a QRotor System,
 ```python
-# Compile a 'potential.csv' file with the calculated potential as a function of the angle
-qr.potential.from_qe()
-# Load to the system
-system = qr.potential.load()
+# 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()
 # Solve the system, interpolating to a bigger gridsize
 system.B = qr.B_CH3
 system.solve(200000)
@@ -139,9 +177,9 @@ below the potential maximum are also calculated upon solving the system:
 
 ```python
 system.solve()
-system.splittings
-system.excitations
-system.deg
+print(system.splittings)
+print(system.excitations)
+print(system.deg)
 ```
 
 An integer `System.deg` degeneracy (e.g. 3 for methyls)
@@ -165,3 +203,71 @@ See [R. M. Dimeo, American Journal of Physics 71, 885–893 (2003)](https://doi.
 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,
+> Pablo Gila-Herranz, *QRotor*, 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.  
+

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor.egg-info/SOURCES.txt

@@ -16,4 +16,8 @@ qrotor.egg-info/dependency_links.txt
 qrotor.egg-info/requires.txt
 qrotor.egg-info/top_level.txt
 tests/__init__.py
-tests/test_qrotor.py
+tests/test_constants.py
+tests/test_potential.py
+tests/test_rotate.py
+tests/test_solve.py
+tests/test_system.py

{qrotor-4.0.0a2 → qrotor-4.0.2}/qrotor.egg-info/requires.txt

@@ -3,3 +3,4 @@ pandas
 numpy
 matplotlib
 aton
+periodictable

{qrotor-4.0.0a2 → qrotor-4.0.2}/setup.py

@@ -1,7 +1,6 @@
 from setuptools import setup, find_packages
 
 DESCRIPTION = "QRotor"
-LONG_DESCRIPTION = "QRotor"
 
 exec(open('qrotor/_version.py').read())
 
@@ -17,7 +16,7 @@ setup(
     long_description = LONG_DESCRIPTION,
     long_description_content_type = 'text/markdown',
     packages = find_packages(),
-    install_requires = ['scipy', 'pandas', 'numpy', 'matplotlib', 'aton'],
+    install_requires = ['scipy', 'pandas', 'numpy', 'matplotlib', 'aton', 'periodictable'],
     extras_requires = {'dev': ['pytest', 'twine', 'build']},
     python_requires = '>=3',
     license = 'AGPL-3.0',

qrotor-4.0.2/tests/test_constants.py

@@ -0,0 +1,13 @@
+import qrotor as qr
+
+
+def test_constants():
+    assert round(qr.B_CH3, 5) == 0.64518
+    assert round(qr.B_CD3, 5) == 0.32289
+    assert round(qr.B_NH3, 5) == 0.73569
+    assert round(qr.B_ND3, 5) == 0.36819
+    assert round(qr.Ry_to_eV, 5)  == 13.60569
+    assert round(qr.Ry_to_meV, 5) == 13605.69312
+    assert round(qr.eV_to_Ry, 5)  == 0.07350
+    assert round(qr.meV_to_Ry, 10) == .0000734986
+

qrotor-4.0.2/tests/test_potential.py

@@ -0,0 +1,37 @@
+import qrotor as qr
+import aton
+
+
+folder = 'tests/samples/'
+structure = folder + 'CH3NH3.in'
+structure_120 = folder + 'CH3NH3_120.in'
+structure_60 = folder + 'CH3NH3_60.in'
+
+
+def test_save_and_load():
+    system = qr.System()
+    system.gridsize = 36
+    system.potential_name = 'sin'
+    system.B = 1
+    system.solve_potential()
+    potential_file = folder + '_temp_potential.csv'
+    # Remove the file if it exists
+    try:
+        aton.file.remove(potential_file)
+    except:
+        pass
+    qr.potential.save(system, comment='hi', filepath=potential_file)
+    system_new = qr.potential.load(potential_file)
+    assert system_new.gridsize == system.gridsize
+    assert round(system_new.potential_values[0], 5) == round(system.potential_values[0], 5)
+    assert round(system_new.potential_values[5], 5) == round(system.potential_values[5], 5)
+    assert round(system_new.potential_values[13], 5) == round(system.potential_values[13], 5)
+    assert system_new.comment == 'hi'
+    aton.file.remove(potential_file)
+    # If we don't provide a comment, it should be the name of the folder
+    system.comment = None
+    qr.potential.save(system, filepath=potential_file)
+    system_new = qr.potential.load(potential_file)
+    assert system_new.comment == 'samples'
+    aton.file.remove(potential_file)
+

qrotor-4.0.0a2/tests/test_qrotor.py → qrotor-4.0.2/tests/test_rotate.py

@@ -1,8 +1,7 @@
-import aton.qrotor as qr
+import qrotor as qr
 import aton.api as api
 import aton.txt.extract as extract
 import aton.file as file
-import numpy as np
 
 
 folder = 'tests/samples/'
@@ -52,50 +51,3 @@ def test_rotate():
         assert coord_rounded == rotated_coord_rounded
     file.remove(structure_60)
 
-
-def test_solve_zero():
-    system = qr.System()
-    system.gridsize = 50000
-    system.potential_name = 'zero'
-    system.B = 1
-    system.solve()
-    assert round(system.eigenvalues[0], 2) == 0.0
-    assert round(system.eigenvalues[1], 2) == 1.0
-    assert round(system.eigenvalues[2], 2) == 1.0
-    assert round(system.eigenvalues[3], 2) == 4.0
-    assert round(system.eigenvalues[4], 2) == 4.0
-    assert round(system.eigenvalues[5], 2) == 9.0
-    assert round(system.eigenvalues[6], 2) == 9.0
-    assert round(system.eigenvalues[7], 2) == 16.0
-    assert round(system.eigenvalues[8], 2) == 16.0
-
-
-def test_solve_potential():
-    system = qr.System()
-    system.gridsize = 500
-    system.potential_name = 'sin'
-    system.potential_constants = [0, 1, 3, 0]
-    system.solve_potential()
-    assert round(system.potential_max, 2) == 1.0
-
-
-def test_phase():
-    sys = qr.System()
-    sys.B = 1.0
-    sys.potential_name = 'cos'
-    sys.gridsize = 10000
-    sys.solve()
-    # plus pi/2, which will be -3pi/2
-    sys.change_phase(0.5)
-    assert round(sys.grid[0], 2) == round(-np.pi * 3/2, 2)
-    # The first potential value should be 0,
-    # but remember that the potential offset is corrected
-    # so it should be half potential_max, so 1.0/2
-    assert round(sys.potential_values[0], 2) == 0.5
-    # minus pi, which will become -pi/2
-    sys.change_phase(-1)
-    assert round(sys.grid[0], 2) == round(-np.pi/2, 2)
-    assert round(sys.potential_values[0], 2) == 0.5
-    # Were eigenvalues calculated?
-    assert len(sys.eigenvalues) > 0
-

qrotor-4.0.2/tests/test_solve.py

@@ -0,0 +1,28 @@
+import qrotor as qr
+
+
+def test_solve_zero():
+    system = qr.System()
+    system.gridsize = 50000
+    system.potential_name = 'zero'
+    system.B = 1
+    system.solve()
+    assert round(system.eigenvalues[0], 2) == 0.0
+    assert round(system.eigenvalues[1], 2) == 1.0
+    assert round(system.eigenvalues[2], 2) == 1.0
+    assert round(system.eigenvalues[3], 2) == 4.0
+    assert round(system.eigenvalues[4], 2) == 4.0
+    assert round(system.eigenvalues[5], 2) == 9.0
+    assert round(system.eigenvalues[6], 2) == 9.0
+    assert round(system.eigenvalues[7], 2) == 16.0
+    assert round(system.eigenvalues[8], 2) == 16.0
+
+
+def test_solve_potential():
+    system = qr.System()
+    system.gridsize = 500
+    system.potential_name = 'sin'
+    system.potential_constants = [0, 1, 3, 0]
+    system.solve_potential()
+    assert round(system.potential_max, 2) == 1.0
+

qrotor-4.0.2/tests/test_system.py

@@ -0,0 +1,24 @@
+import qrotor as qr
+import numpy as np
+
+
+def test_phase():
+    sys = qr.System()
+    sys.B = 1.0
+    sys.potential_name = 'cos'
+    sys.gridsize = 10000
+    sys.solve()
+    # plus pi/2, which will be -3pi/2
+    sys.change_phase(0.5)
+    assert round(sys.grid[0], 2) == round(-np.pi * 3/2, 2)
+    # The first potential value should be 0,
+    # but remember that the potential offset is corrected
+    # so it should be half potential_max, so 1.0/2
+    assert round(sys.potential_values[0], 2) == 0.5
+    # minus pi, which will become -pi/2
+    sys.change_phase(-1)
+    assert round(sys.grid[0], 2) == round(-np.pi/2, 2)
+    assert round(sys.potential_values[0], 2) == 0.5
+    # Were eigenvalues calculated?
+    assert len(sys.eigenvalues) > 0
+