aton 0.2.3__tar.gz → 0.2.4__tar.gz

{aton-0.2.3 → aton-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aton
-Version: 0.2.3
+Version: 0.2.4
 Summary: The Ab-iniTiO & Neutron research toolbox, or ATON, provides powerful and comprehensive tools for cutting-edge materials research, focused on (but not limited to) neutron science.
 Author: Pablo Gila-Herranz
 Author-email: pgila001@ikasle.ehu.eus

{aton-0.2.3 → aton-0.2.4}/aton/_version.py

@@ -10,5 +10,5 @@ https://semver.org/
 
 """
 
-__version__ = 'v0.2.3'
+__version__ = 'v0.2.4'
 

{aton-0.2.3 → aton-0.2.4}/aton/qrotor/__init__.py

@@ -94,6 +94,29 @@ system.solve(200000)
 qr.plot.energies(system)
 ```
 
+
+## Tunnel splittings and excitations
+
+By default, energy eigenvalues are assumed to present triplet degeneracy,
+see [A. J. Horsewill, Progress in Nuclear Magnetic Resonance Spectroscopy 35, 359–389 (1999)](https://doi.org/10.1016/S0079-6565(99)00016-3).
+If this is not the case, check `aton.qrotor.solve.excitations()`.
+
+When the quantum System is solved, tunnel splittings and excitations are also calculated:
+
+```python
+system.solve()
+system.splittings
+system.excitations
+```
+
+To export the tunnel splittings of several calculations to a CSV file:
+
+```python
+calculations = [system1, system2, system3]
+qr.systems.splittings(calculations)
+```
+
+
 Check the API documentation for more details.
 
 """

{aton-0.2.3 → aton-0.2.4}/aton/qrotor/potential.py

@@ -205,13 +205,13 @@ def from_qe(
     potential_data += '# https://pablogila.github.io/ATON\n'
     potential_data += '#\n'
     if energy.lower() in alias.units['eV']:
-        potential_data += '# Angle/deg    Potential/eV\n'
+        potential_data += '# Angle/deg,    Potential/eV\n'
     elif energy.lower() in alias.units['meV']:
-        potential_data += '# Angle/deg    Potential/meV\n'
+        potential_data += '# Angle/deg,    Potential/meV\n'
     elif energy.lower() in alias.units['Ry']:
-        potential_data += '# Angle/deg    Potential/Ry\n'
+        potential_data += '# Angle/deg,    Potential/Ry\n'
     else:
-        potential_data += '# Angle/deg    Potential/meV\n'
+        potential_data += '# Angle/deg,    Potential/meV\n'
     potential_data += '#\n'
     potential_data_list = []
     print('Extracting the potential as a function of the angle...')
@@ -248,7 +248,7 @@ def from_qe(
     potential_data_list_sorted = sorted(potential_data_list, key=lambda x: x[0])
     # Append the sorted values as a string
     for angle_value, energy_value in potential_data_list_sorted:
-        potential_data += f'{angle_value}    {energy_value}\n'
+        potential_data += f'{angle_value},    {energy_value}\n'
     with open(filepath, 'w') as f:
         f.write(potential_data)
     print('----------------------------------')

{aton-0.2.3 → aton-0.2.4}/aton/qrotor/solve.py

@@ -1,8 +1,14 @@
 """
 # Description
 
-This module is used to solve the hamiltonian eigenvalues and eigenvectors for a given quantum system.
-Sparse matrices are used to achieve optimal performance.
+This module is used to solve any given quantum system.
+
+Although the functions of this module can be used independently,
+it is highly recommended to use the `System.solve()` method instead,
+which does all the solving automatically (see `aton.qrotor.system.System.solve()`).
+However, advanced users might want to use some of these functions independently;
+for example, if your system energy levels are not degenerated in triplets,
+you might want to use `excitations()` to solve the energy excitations and tunnel splittings with the proper degeneracy.
 
 
 # Index
@@ -14,6 +20,7 @@ Sparse matrices are used to achieve optimal performance.
 | `schrodinger()`           | Solve the Schrödiger equation for the system |
 | `hamiltonian_matrix()`    | Calculate the hamiltonian matrix of the system |
 | `laplacian_matrix()`      | Calculate the second derivative matrix for a given grid |
+| `excitations()`           | Get excitation levels and tunnel splitting energies for a set of eigenvalues |
 
 ---
 """
@@ -86,16 +93,16 @@ def schrodinger(system:System) -> System:
     system.potential_max = max(V)
     system.potential_min = min(V)
     system.energy_barrier = max(V) - min(eigenvalues)
-    system.transitions = []
-    for i in range(len(eigenvalues)-1):
-        system.transitions.append(eigenvalues[i+1] - eigenvalues[0])
+    # Solve excitations and tunnel splittings, assuming triplet degeneracy
+    system = excitations(system, deg=3)
+    # Do we really need to save eigenvectors?
     if system.save_eigenvectors == True:
         system.eigenvectors = np.transpose(eigenvectors)
     return system
 
 
 def hamiltonian_matrix(system:System):
-    """Calculates the Hamiltonian matrix for a given `system`."""
+    """Calculates the Hamiltonian sparse matrix for a given `system`."""
     print(f'Creating Hamiltonian matrix of size {system.gridsize}...')
     V = system.potential_values.tolist()
     potential = sparse.diags(V, format='lil')
@@ -117,3 +124,49 @@ def laplacian_matrix(grid):
     laplacian_matrix /= dx**2
     return laplacian_matrix
 
+
+def excitations(
+        system:System,
+        deg:int=3,
+        ) -> tuple:
+    """Calculate the excitation levels and the tunnel splitting energies of a system.
+
+    Stops the calculation when energies reach the maximum potential.
+    Assumes that eigenvalues are degenerated in triplets;
+    this degeneracy can be specified with `deg`.
+    """
+    eigenvalues = system.eigenvalues
+    V_max = system.potential_max
+    ground_energy = min(eigenvalues)
+    excitations = []
+    tunnel_splittings = []
+    i = 0
+    while (i + deg-1) <= len(eigenvalues):
+        # Get the eigenvalues corresponding to this triplet (or whatever degeneracy)
+        i_max = i + deg  # Index indicating the end of this triplet
+        triplet = eigenvalues[i:i_max]
+        # Check that we are still below the potential max
+        if any(triplet) > V_max:
+            break
+        # Check that all eigenvalues are valid, and not None
+        if any(triplet) is None:
+            break
+        # Get the excitation energy, by comparing with the ground state
+        if i != 0:  # Skip the ground energy level
+            excitations.append(min(triplet) - ground_energy)
+        # Check the energy differences inside each triplet (or whatever degeneracy)
+        E_diff = []
+        for j in range(deg-1):  # 0, 1 (not 2)
+            E_0 = triplet[j]
+            E_1 = triplet[j+1]
+            diff = E_1 - E_0
+            E_diff.append(diff)
+        # Get the maximum energy difference inside the triplet, which is the tunnel splitting
+        tunnel_splittings.append(max(E_diff))
+        # Move to the next triplet
+        i += deg
+    # Set the energy excitations and tunnel splittings
+    system.excitations = excitations
+    system.splittings = tunnel_splittings
+    return system
+

{aton-0.2.3 → aton-0.2.4}/aton/qrotor/system.py

@@ -18,6 +18,8 @@ class System:
     """Quantum system.
 
     Contains all the data for a single QRotor calculation, with both inputs and outputs.
+
+    Energy units are in meV and angles are in radians, unless stated otherwise.
     """
     def __init__(
             self,
@@ -85,14 +87,19 @@ class System:
         self.eigenvectors = []
         """Eigenvectors, if `save_eigenvectors` is True. Beware of the file size."""
         self.energy_barrier: float = None
-        """`max(V) - min(eigenvalues)`"""
-        self.transitions: list = None
-        """eigenvalues[i+1] - eigenvalues[0]"""
+        """Activation energy or energy barrier, from the ground torsional state to the top of the potential barrier, `max(V) - min(eigenvalues)`"""
+        self.excitations: list = None
+        """Torsional excitations, as eigenvalues with respect to the ground state.
+
+        Considers the lowest eigenvalue from each degenerated energy level.
+        """
+        self.splittings: list = None
+        """Tunnel splitting energies, for every degenerated energy level."""
         self.runtime: float = None
         """Time taken to solve the eigenvalues."""
 
     def solve(self, new_gridsize:int=None):
-        """Solves the quantum system.
+        """Default method to solve the quantum system.
 
         The potential can be interpolated to a `new_gridsize`.
     
@@ -213,7 +220,8 @@ class System:
             'potential_max': self.potential_max,
             'eigenvalues': self.eigenvalues.tolist() if isinstance(self.eigenvalues, np.ndarray) else self.eigenvalues,
             'energy_barrier': self.energy_barrier,
-            'transitions': self.transitions,
+            'excitations': self.excitations,
+            'splittings': self.splittings,
             'runtime': self.runtime,
         }
 

{aton-0.2.3 → aton-0.2.4}/aton/qrotor/systems.py

@@ -16,12 +16,15 @@ This module contains utility functions to handle multiple `aton.qrotor.system` c
 | `sort_by_gridsize()` | Sort systems by gridsize |
 | `reduce_size()`      | Discard data that takes too much space |
 | `get_ideal_E()`      | Calculate the ideal energy for a specified level |
+| `splittings()`       | Get the first tunnel splitting energies for all systems |
 
 ---
 """
 
 
 from .system import System
+from aton import txt
+import pandas as pd
 
 
 def as_list(systems) -> None:
@@ -129,3 +132,37 @@ def get_ideal_E(E_level:int) -> int:
     ideal_E = int(real_E_level ** 2)
     return ideal_E
 
+
+def splittings(
+        systems:list,
+        comment:str='',
+        filepath:str='tunnel_splittings.csv',
+        ) -> pd.DataFrame:
+    """Save the tunnel splitting energies for all `systems` to a tunnel_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 (`,`).
+    """
+    as_list(systems)
+    version = systems[0].version
+    tunnelling_E = {}
+    for s in systems:
+        tunnelling_E[s.comment] = s.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 ATON {version}\n'
+    file_comment += f'# https://pablogila.github.io/ATON\n#'
+    txt.edit.insert_at(filepath, file_comment, 0)
+    print(f'Tunnel splitting energies saved to {filepath}')
+    return df
+

{aton-0.2.3 → aton-0.2.4}/aton.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aton
-Version: 0.2.3
+Version: 0.2.4
 Summary: The Ab-iniTiO & Neutron research toolbox, or ATON, provides powerful and comprehensive tools for cutting-edge materials research, focused on (but not limited to) neutron science.
 Author: Pablo Gila-Herranz
 Author-email: pgila001@ikasle.ehu.eus