aton 0.2.2__tar.gz → 0.2.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aton
-Version: 0.2.2
+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
@@ -41,9 +41,11 @@ or [ATON](https://pablogila.github.io/ATON/),
 provides powerful and comprehensive tools
 for cutting-edge materials research,
 focused on (but not limited to) neutron science.
+Designed to bridge the gap between theoretical modeling and experimental validation,
+ATON allows researchers to streamline and simplify workflows in the study of advanced materials.
 
 Just like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,
-this all-in-one Python package contains a range of tools
+this all-in-one Python package comprises a range of utility tools
 from INS spectra analysis to *ab-initio* interfaces
 for [Quantum ESPRESSO](https://www.quantum-espresso.org/),
 [Phonopy](https://phonopy.github.io/phonopy/) and

{aton-0.2.2 → aton-0.2.4}/README.md

@@ -8,9 +8,11 @@ or [ATON](https://pablogila.github.io/ATON/),
 provides powerful and comprehensive tools
 for cutting-edge materials research,
 focused on (but not limited to) neutron science.
+Designed to bridge the gap between theoretical modeling and experimental validation,
+ATON allows researchers to streamline and simplify workflows in the study of advanced materials.
 
 Just like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,
-this all-in-one Python package contains a range of tools
+this all-in-one Python package comprises a range of utility tools
 from INS spectra analysis to *ab-initio* interfaces
 for [Quantum ESPRESSO](https://www.quantum-espresso.org/),
 [Phonopy](https://phonopy.github.io/phonopy/) and

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

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

{aton-0.2.2 → 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.2 → 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.2 → aton-0.2.4}/aton/qrotor/rotate.py

@@ -51,6 +51,11 @@ def structure_qe(
     To override this and instead use the vector between the first two atoms
     as the rotation axis, set `use_centroid = False`.
 
+    **WARNING: The `positions` list is order-sensitive**.
+    If you rotate more than one chemical group in a structure,
+    be sure to follow the same direction for each group (e.g. all clockwise)
+    to ensure that all axes of rotation point in the same direction.
+
     To debug, `show_axis = True` adds two additional helium atoms as the rotation vector.
     """
     print('Rotating Quantum ESPRESSO input structure with QRotor...')
@@ -106,13 +111,21 @@ def rotate_coords(
     Then rotates said coordinates by a given `angle` in degrees.
     Returns a list with the updated positions.
 
-    By default, the rotation axis is defined by the perpendicular vector
+    By default, the rotation vector is defined by the perpendicular
     passing through the geometrical center of the first three points.
     To override this and use the vector between the first two atoms
     as the rotation axis, set `use_centroid = False`.
 
+    **WARNING: The `positions` list is order-sensitive**.
+    If you rotate more than one chemical group in a structure,
+    be sure to follow the same direction for each group (e.g. all clockwise)
+    to ensure that all rotation vectors point in the same direction.
+
     If `show_axis = True` it returns two additional coordinates at the end of the list,
     with the centroid and the rotation vector. Only works with `use_centroid = True`.
+
+    The rotation uses Rodrigues' rotation formula,
+    powered by [`scipy.spatial.transform.Rotation.from_rotvec`](https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.transform.Rotation.from_rotvec.html#scipy.spatial.transform.Rotation.from_rotvec).
     """
     if len(positions) < 3:
         raise ValueError("At least three atoms must be rotated.")

{aton-0.2.2 → 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.2 → 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`.
     
@@ -129,10 +136,8 @@ class System:
         # Check that the grid is still within -2pi and 2pi, otherwise normalise it for a final time
         while self.grid[0] <= (-2 * np.pi + 0.1):  # With a small tolerance
             self.grid = self.grid + 2 * np.pi
-            print('plus 2')
         while self.grid[-1] >= 2.5 * np.pi:  # It was not a problem until reaching 5/2 pi
             self.grid = self.grid -2 * np.pi
-            print('minus 2')
         print(f'Potential shifted by {phase}π')
         if calculate:
             self.solve()
@@ -215,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.2 → 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.2 → aton-0.2.4}/aton/txt/__init__.py

@@ -26,7 +26,7 @@ alat_lines = txt.find.lines('relax.out', 'Lattice parameter =')
 # Extract the numerical value of the last match
 alat = txt.extract.number(alat_lines[-1], 'Lattice parameter')
 # Paste it into another file
-txt.edit.replace_line('scf.in', 'Lattice parameter =', f'Lattice parameter ='{alat})
+txt.edit.replace_line('scf.in', 'Lattice parameter =', f'Lattice parameter = {alat}')
 ```
 
 Advanced usage such as regular expression matching or

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aton
-Version: 0.2.2
+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
@@ -41,9 +41,11 @@ or [ATON](https://pablogila.github.io/ATON/),
 provides powerful and comprehensive tools
 for cutting-edge materials research,
 focused on (but not limited to) neutron science.
+Designed to bridge the gap between theoretical modeling and experimental validation,
+ATON allows researchers to streamline and simplify workflows in the study of advanced materials.
 
 Just like its [ancient Egyptian deity](https://en.wikipedia.org/wiki/Aten) counterpart,
-this all-in-one Python package contains a range of tools
+this all-in-one Python package comprises a range of utility tools
 from INS spectra analysis to *ab-initio* interfaces
 for [Quantum ESPRESSO](https://www.quantum-espresso.org/),
 [Phonopy](https://phonopy.github.io/phonopy/) and