qrotor 4.0.0__py3-none-any.whl

qrotor/systems.py

@@ -0,0 +1,245 @@
+"""
+# Description
+
+This module contains utility functions to handle multiple `qrotor.system` calculations.
+These are commonly used as a list of `System` objects.
+
+
+# Index
+
+| | |
+| --- | --- |
+| `as_list()`          | Ensures that a list only contains System objects |
+| `save_energies()`    | Save the energy eigenvalues for all systems to a CSV |
+| `save_splittings()`  | Save the tunnel splitting energies for all systems to a CSV |
+| `get_energies()`     | Get the eigenvalues from all systems |
+| `get_gridsizes()`    | Get all gridsizes |
+| `get_runtimes()`     | Get all runtimes |
+| `get_groups()`       | Get the chemical groups in use |
+| `get_ideal_E()`      | Calculate the ideal energy for a specified level |
+| `sort_by_gridsize()` | Sort systems by gridsize |
+| `reduce_size()`      | Discard data that takes too much space |
+| `summary()`          | Print a summary of a System or list of Systems |
+
+---
+"""
+
+
+from .system import System
+from aton import txt
+import pandas as pd
+
+
+def as_list(systems) -> None:
+    """Ensures that `systems` is a list of System objects.
+
+    If it is a System, returns a list with that System as the only element.
+    If it is neither a list nor a System,
+    or if the list does not contain only System objects,
+    it raises an error.
+    """
+    if isinstance(systems, System):
+        systems = [systems]
+    if not isinstance(systems, list):
+        raise TypeError(f"Must be a System object or a list of systems, found instead: {type(systems)}")
+    for i in systems:
+        if not isinstance(i, System):
+            raise TypeError(f"All items in the list must be System objects, found instead: {type(i)}")
+    return systems
+
+
+def save_energies(
+        systems:list,
+        comment:str='',
+        filepath:str='eigenvalues.csv',
+        ) -> pd.DataFrame:
+    """Save the energy eigenvalues for all `systems` to a eigenvalues.csv file.
+
+    Returns a Pandas Dataset with `System.comment` columns and `System.eigenvalues` values.
+
+    The output file can be changed with `filepath`,
+    or set to null to avoid saving the dataset.
+    A `comment` can be included at the top of the file.
+    Note that `System.comment` must not include commas (`,`).
+    """
+    as_list(systems)
+    version = systems[0].version
+    E = {}
+    # Find max length of eigenvalues
+    max_len = max((len(s.eigenvalues) if s.eigenvalues is not None else 0) for s in systems)
+    for s in systems:
+        if s.eigenvalues is not None:
+            # Filter out None values and replace with NaN
+            valid_eigenvalues = [float('nan') if e is None else e for e in s.eigenvalues]
+            padded_eigenvalues = valid_eigenvalues + [float('nan')] * (max_len - len(s.eigenvalues))
+        else:
+            padded_eigenvalues = [float('nan')] * max_len
+        E[s.comment] = padded_eigenvalues
+    df = pd.DataFrame(E)
+    if not filepath:
+        return df
+    # Else save to file
+    df.to_csv(filepath, sep=',', index=False)
+    # Include a comment at the top of the file
+    file_comment = f'# {comment}\n' if comment else f''
+    file_comment += f'# Energy eigenvalues\n'
+    file_comment += f'# Calculated with QRotor {version}\n'
+    file_comment += f'# https://pablogila.github.io/qrotor\n#'
+    txt.edit.insert_at(filepath, file_comment, 0)
+    print(f'Energy eigenvalues saved to {filepath}')
+    return df
+
+
+def save_splittings(
+    systems:list,
+    comment:str='',
+    filepath:str='splittings.csv',
+    ) -> pd.DataFrame:
+    """Save the tunnel splitting energies for all `systems` to a splittings.csv file.
+
+    Returns a Pandas Dataset with `System.comment` columns and `System.splittings` values.
+
+    The output file can be changed with `filepath`,
+    or set to null to avoid saving the dataset.
+    A `comment` can be included at the top of the file.
+    Note that `System.comment` must not include commas (`,`).
+    Different splitting lengths across systems are allowed - missing values will be NaN.
+    """
+    as_list(systems)
+    version = systems[0].version
+    tunnelling_E = {}
+    # Find max length of splittings
+    max_len = max(len(s.splittings) for s in systems)
+    for s in systems:  # Pad shorter splittings with NaN
+        padded_splittings = s.splittings + [float('nan')] * (max_len - len(s.splittings))
+        tunnelling_E[s.comment] = padded_splittings
+    df = pd.DataFrame(tunnelling_E)
+    if not filepath:
+        return df
+    # Else save to file
+    df.to_csv(filepath, sep=',', index=False)
+    # Include a comment at the top of the file 
+    file_comment = f'# {comment}\n' if comment else f''
+    file_comment += f'# Tunnel splitting energies\n'
+    file_comment += f'# Calculated with QRotor {version}\n'
+    file_comment += f'# https://pablogila.github.io/qrotor\n#'
+    txt.edit.insert_at(filepath, file_comment, 0)
+    print(f'Tunnel splitting energies saved to {filepath}')
+    return df
+
+
+def get_energies(systems:list) -> list:
+    """Get a list with all lists of eigenvalues from all systems.
+
+    If no eigenvalues are present for a particular system, appends None.
+    """
+    as_list(systems)
+    energies = []
+    for i in systems:
+        if all(i.eigenvalues):
+            energies.append(i.eigenvalues)
+        else:
+            energies.append(None)
+    return energies
+
+
+def get_gridsizes(systems:list) -> list:
+    """Get a list with all gridsize values.
+
+    If no gridsize value is present for a particular system, appends None.
+    """
+    as_list(systems)
+    gridsizes = []
+    for i in systems:
+        if i.gridsize:
+            gridsizes.append(i.gridsize)
+        elif any(i.potential_values):
+            gridsizes.append(len(i.potential_values))
+        else:
+            gridsizes.append(None)
+    return gridsizes
+
+
+def get_runtimes(systems:list) -> list:
+    """Returns a list with all runtime values.
+    
+    If no runtime value is present for a particular system, appends None.
+    """
+    as_list(systems)
+    runtimes = []
+    for i in systems:
+        if i.runtime:
+            runtimes.append(i.runtime)
+        else:
+            runtimes.append(None)
+    return runtimes
+
+
+def get_groups(systems:list) -> list:
+    """Returns a list with all `System.group` values."""
+    as_list(systems)
+    groups = []
+    for i in systems:
+        if i.group not in groups:
+            groups.append(i.group)
+    return groups
+
+
+def get_ideal_E(E_level:int) -> int:
+    """Calculates the ideal energy for a specified `E_level`.
+
+    To be used in convergence tests with `potential_name = 'zero'`.
+    """
+    real_E_level = None
+    if E_level % 2 == 0:
+        real_E_level = E_level / 2
+    else:
+        real_E_level = (E_level + 1) / 2
+    ideal_E = int(real_E_level ** 2)
+    return ideal_E
+
+
+def sort_by_gridsize(systems:list) -> list:
+    """Sorts a list of System objects by `System.gridsize`."""
+    as_list(systems)
+    systems = sorted(systems, key=lambda sys: sys.gridsize)
+    return systems
+
+
+def reduce_size(systems:list) -> list:
+    """Discard data that takes too much space.
+
+    Removes eigenvectors, potential values and grids,
+    for all System values inside the `systems` list.
+    """
+    as_list(systems)
+    for dataset in systems:
+        dataset = dataset.reduce_size()
+    return systems
+
+
+def summary(systems, verbose:bool=False) -> None:
+    """Print a summary of a System or list of Systems.
+    
+    Print extra info with `verbose=True`
+    """
+    print('--------------------')
+    systems = as_list(systems)
+    for system in systems:
+        dictionary = system.summary()
+        if verbose:
+            for key, value in dictionary.items():
+                print(f'{key:<24}', value)
+        else:
+            eigenvalues = system.eigenvalues if any(system.eigenvalues) else []
+            extra = ''
+            if len(system.eigenvalues) > 6:
+                eigenvalues = eigenvalues[:6]
+                extra = '...'
+            print('comment     ' + str(system.comment))
+            print('B           ' + str(system.B))
+            print('eigenvalues ' + str([float(round(e, 4)) for e in eigenvalues]) + extra)
+            print('version     ' + str(system.version))
+        print('--------------------')
+    return None
+

qrotor-4.0.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: qrotor
+Version: 4.0.0
+Summary: QRotor
+Author: Pablo Gila-Herranz
+Author-email: pgila001@ikasle.ehu.eus
+License: AGPL-3.0
+Keywords: QRotor,Molecular rotations,Quantum rotations,Quantum,Molecular,Rotations,Neutrons,Research,Ab-initio,DFT,Density Functional Theory,Quantum ESPRESSO,Phonons,Electronic structure
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Natural Language :: English
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: Other OS
+Requires-Python: >=3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: aton
+Requires-Dist: periodictable
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<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.
+It can calculate their quantum energy levels and wavefunctions,
+along with excitations and tunnel splittings.
+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/).
+
+
+# Index
+
+| | |
+| --- | --- |
+| [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.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 |
+
+
+# Usage
+
+## Solving quantum rotational systems
+
+A basic calculation of the eigenvalues for a zero potential goes as follows.
+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()
+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.
+
+The same calculation can be performed for a methyl group,
+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.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.solve()
+# Plot potential and eigenvalues
+qr.plot.energies(system)
+# Plot the first wavefunctions
+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:
+
+```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.rotate.structure_qe('molecule.in', positions=atoms, angle=10, repeat=True)
+# Run the Quantum ESPRESSO calculations
+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()
+# Solve the system, interpolating to a bigger gridsize
+system.B = qr.B_CH3
+system.solve(200000)
+qr.plot.energies(system)
+```
+
+
+## Tunnel splittings and excitations
+
+Tunnel splittings, excitations and energy level degeneracy
+below the potential maximum are also calculated upon solving the system:
+
+```python
+system.solve()
+system.splittings
+system.excitations
+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,
+please 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.
+

qrotor-4.0.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+qrotor/__init__.py,sha256=rG2dH4QjsVUOMBhFnv5gXs3QnrUg7fywd5pIDmMBXcQ,246
+qrotor/_version.py,sha256=DMTqecCyKBSdEUmHjpS5DWtkxTyh6_wQz3QzeNRMd9E,194
+qrotor/constants.py,sha256=pp3HwRPF4kvQBGBgZTR3PkeJgWrYMfHu288UcSQ9m_U,3195
+qrotor/plot.py,sha256=SeQX8PM5qPdedmo0DzfGFbA8m_sH2mcK50aTuWXN8HA,13335
+qrotor/potential.py,sha256=4sONrwnJkKy2zyquX6AFpNVLXrRMX9XUJUnuS6eZ9bc,17781
+qrotor/rotate.py,sha256=Wje9Q9SFhDvizz58MzNGBwsmgV-3wN9z2SnUNTIXzeg,8107
+qrotor/solve.py,sha256=tnkE5JYT8wW85gNbOEMgHTnzOZCb8q5xPcJbDI4uOB0,10724
+qrotor/system.py,sha256=onY3HfY2zpRLDJUjBJRX-nJu6YH_qhnPnCW6Uyam_Ws,11453
+qrotor/systems.py,sha256=Hcx0QvMWpaPMfC6HWpkZPPWDyHk9rxWKdAxWNnD2NMg,8184
+qrotor-4.0.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_qrotor.py,sha256=KL5i1YVFOB5cFc7BXCtbrbBKKMCHyGM-B20m4unz1q0,3457
+qrotor-4.0.0.dist-info/METADATA,sha256=x4P2QdhlPMmPCFiqg6w2ndS06xshZhltnSal6enQuTE,5912
+qrotor-4.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+qrotor-4.0.0.dist-info/top_level.txt,sha256=mLnYs07-amqX4TqbDV2_XvgdpHfgrYmzmYb7dwoh6EQ,13
+qrotor-4.0.0.dist-info/RECORD,,

qrotor-4.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+