digichem-core 6.0.0rc1__py3-none-any.whl

digichem/result/alignment/AAA.py

@@ -0,0 +1,61 @@
+from digichem.result.alignment.AA import Average_angle
+from statistics import  mean
+
+class Adjusted_average_angle(Average_angle):
+    """
+    A further enhancement to average angle, this method uses a second set of rotations to improve alignment.
+    """
+    
+    # Names that uniquely describe this alignment protocol.
+    CLASS_HANDLE = ["Adjusted Average Angle", "AAA"]    
+    
+    def align_axes(self):
+        """
+        Realign the axes of our coordinate system, so they have the following meaning:
+        
+        X-axis: The long axis (the kebab skewer), which we define as passing through the pair of atoms with the greatest separation in our set.
+        Y-axis: The middle axis, which we define as perpendicular to the the X-axis (obviously) and passing through the atom that is furthest from the X-axis. Note that the Y-axis only has to pass through one atom; there may not be a corresponding atom on the other side (but there will be if the molecule is symmetrical about the X-axis).
+        Z-axis: The short axis, defined as perpendicular to both the X and Y-axes (so we have no choice where this goes).
+        
+        :return: Nothing. The atoms are rearranged in place.
+        """
+        # First complete a total AA alignment.
+        super().align_X()
+        super().align_Y()
+        super().align_Z()
+        
+        # Now align using our methods.
+        self.align_X()
+        self.align_Y()
+        self.align_Z()
+    
+    def align_X(self):
+        """
+        Align the X axis.
+        
+        You do not need to call this method yourself; it is called as part of align_axes().
+        """
+        # This is important because average angle always produces the same results regardless of the initial rotation of the molecule, which is not true of the rotation we are about to perform. Hence it is vital that we always start with the same coordinates regardless of initial orientation. AA does that for us.
+        
+        # Now determine the mean (note that this is not a true 'averaged angle' as used in the AA method, this is your bog-standard average).
+        mean_angle = mean([self.get_theta(atom.coords[1], atom.coords[0]) for atom in self]) 
+        self.rotate_XY(mean_angle)
+        
+        # Do the same along the Y axis.
+        mean_angle = mean([self.get_theta(atom.coords[2], atom.coords[0]) for atom in self]) 
+        self.rotate_XZ(mean_angle)
+        
+                
+    def align_Y(self):
+        """
+        Align the Y axis.
+        
+        You do not need to call this method yourself; it is called as part of align_axes().
+        """
+        
+        # Rotate xz coords (along Y axis).
+        # Get our angle.
+        theta = mean([self.get_theta(atom.coords[2], atom.coords[1]) for atom in self])
+        self.rotate_YZ(theta)
+        
+        

digichem/result/alignment/FAP.py

@@ -0,0 +1,148 @@
+# Methodologies for determining molecule linearity.
+import math
+
+from statistics import pstdev
+from digichem.result.alignment import Alignment
+
+class Furthest_atom_pair(Alignment):
+    """
+    The 'kebab' (skewer) method for estimating molecule linearity. 
+    """
+        
+    # Names that uniquely describe this alignment protocol.
+    CLASS_HANDLE = ["Furthest Atom Pair", "FAP", "Kebab"]
+        
+    def align_axes(self):
+        """
+        Realign the axes of our coordinate system, so they have the following meaning:
+        
+        X-axis: The long axis (the kebab skewer), which we define as passing through the pair of atoms with the greatest separation in our set.
+        Y-axis: The middle axis, which we define as perpendicular to the the X-axis (obviously) and passing through the atom that is furthest from the X-axis. Note that the Y-axis only has to pass through one atom; there may not be a corresponding atom on the other side (but there will be if the molecule is symmetrical about the X-axis).
+        Z-axis: The short axis, defined as perpendicular to both the X and Y-axes (so we have no choice where this goes).
+        
+        :return: Nothing. The atoms are rearranged in place.
+        """
+        # First align our X axis.
+        self.align_X()
+        
+        # Next we want to orientate our secondary (Y) axis.
+        self.align_Y()
+        
+        # This does nothing (but might not in the future).
+        self.align_Z()
+        
+    def align_X(self):
+        """
+        Align the X axis.
+        
+        You do not need to call this method yourself; it is called as part of align_axes().
+        """
+        # First get our most separated atoms. This is probably inefficient.
+        # This is a tuple of (distance, atom1, atom2).
+        furthest = self.get_furthest_atom_pair()
+                    
+        # Our new origin is halfway along these two points.
+        new_origin = ( (furthest[1].coords[0] + furthest[2].coords[0]) /2, (furthest[1].coords[1] + furthest[2].coords[1]) /2, (furthest[1].coords[2] + furthest[2].coords[2]) /2)
+        # Translate to new origin.
+        self.translate((-new_origin[0], -new_origin[1], -new_origin[2]))
+        
+        # Now we need to rotate, because we're going to set these two atoms as points on the x axis.
+        # We rotate twice, once to set y = 0, once to set z = 0.
+        
+        # Rotate xy coords (along Z axis).
+        # First determine angle (we should be able to use either atom as reference because we rotate about their midpoint).
+        theta = self.get_theta(furthest[1].coords[1], furthest[1].coords[0])
+        self.rotate_XY(theta)
+        
+        # Rotate xz coords (along Y axis).
+        # Get our angle again.
+        theta = self.get_theta(furthest[1].coords[2], furthest[1].coords[0])
+        self.rotate_XZ(theta)
+        
+    def align_Y(self):
+        """
+        Align the Y axis.
+        
+        You do not need to call this method yourself; it is called as part of align_axes().
+        """
+        # Note that we're not just looking for the atom furthest away, we're looking for the greatest distance across.
+        
+        # Get the most separated pair of atoms in this plane.
+        furthest = self.get_furthest_atom_pair_in_YZ()
+            
+        # Work out the angle between the two atoms.
+        theta = self.get_theta(furthest[1].coords[2] - furthest[2].coords[2], furthest[1].coords[1] - furthest[2].coords[1])
+        
+        # Rotate so the Y axis is parallel to a line drawn between our two furthest atoms in this plane.
+        self.rotate_YZ(theta)
+        
+    def align_Z(self):
+        """
+        Align the Z axis.
+        
+        You do not need to call this method yourself; it is called as part of align_axes().
+        """
+        # We don't need to align our Z axis, as it is automatically defined once we've aligned out X and Y.
+        pass
+    
+    def get_deviation_from_X(self):
+        # First get the distance of each atom from the X-axis.
+        distance = [math.sqrt( (atom.coords[1])**2 + (atom.coords[2])**2 ) for atom in self]
+        # Get the deviation.
+        return pstdev(distance)
+                
+    def get_furthest_atom_pair(self):
+        """
+        Get the pair of atoms in our set that are separated by the greatest distance.
+        
+        :return: A tuple of the form (distance, atom1, atom2) where 'distance' is the straight line distance between 'atom1' and 'atom2'. The order of 'atom1' vs 'atom2' is essentially random and is irrelevant.
+        """
+        # This is a tuple of (distance, atom1, atom2).
+        furthest = (0, None, None)
+        
+        for atom in self:
+            for foreign_atom in self:
+                # Compute distance.
+                distance = (atom.distance(foreign_atom), atom, foreign_atom)
+                # Check to see if we're further.
+                if distance[0] >= furthest[0]:
+                    # This distance is greater, so update.
+                    furthest = distance
+        
+        # And return.
+        return furthest
+    
+    def get_furthest_atom_from_X(self):
+        """
+        Get the atom that is furthest from the X-axis.
+        
+        :return: A tuple of the form (distance, atom) where 'distance' is the straight line distance from 'atom' to the X-axis.
+        """
+        furthest = (0, None)
+        for atom in self:
+            # Calculate distance
+            distance = math.sqrt((atom.coords[1])**2 + (atom.coords[2])**2)
+            # Check.
+            if distance >= furthest[0]:
+                # Set.
+                furthest = (distance, atom)
+                
+        # And return
+        return furthest
+    
+    def get_furthest_atom_pair_in_YZ(self):
+        """
+        Get the pair of atoms in our set that are separated by the greatest distance in the YZ plane.
+        
+        :return: A tuple of the form (distance, atom1, atom2) where 'distance' is the  distance between 'atom1' and 'atom2'. The order of 'atom1' vs 'atom2' is essentially random and is irrelevant.
+        """
+        furthest = (0, None, None)
+        for atom in self:
+            for foreign_atom in self:
+                # Get the greatest distance in this plane.
+                distance = (math.sqrt( (atom.coords[1] - foreign_atom.coords[1])**2 + (atom.coords[2] - foreign_atom.coords[2])**2 ), atom, foreign_atom)
+                if distance[0] >= furthest[0]:
+                    furthest = distance
+        # And return.
+        return furthest
+        

digichem/result/alignment/__init__.py

@@ -0,0 +1,3 @@
+from .base import Alignment
+from .base import Axis_swapper_mix
+from .base import Minimal

digichem/result/alignment/base.py

@@ -0,0 +1,310 @@
+import math
+
+from configurables.parent import Dynamic_parent
+
+from digichem.result.atom import Atom_list
+
+
+class Alignment(Atom_list, Dynamic_parent):
+    """
+    A class that carries out a series of transformations to realign the Cartesian axes of a set of atoms in a particular manner.
+    """
+    
+    def __init__(self, atoms, *args, charge = None, **kwargs):
+        """
+        Constructor for this alignment class.
+        
+        :param atoms: The list of atoms to transform (can be any object that provides a 'coords' attribute which is a tuple of (x, y, z) coordinates.) Note that these coordinates will be transformed in place, so make a copy of your atom list if you want to preserve your original coordinates.
+        """
+        # Call our parent first.
+        super().__init__(atoms, *args, charge = charge, **kwargs)
+        
+        # Keep track of the transformation we make so we can apply them later.
+        # The translations applied to all atoms. 
+        self.translations = (0, 0, 0)
+        # The rotations in radians applied to all atoms. This is a list of tuples, of the form (axis, angle), where axis is 0 = X, 1 = Y, 2 = Z.
+        self.rotations = []
+        
+        # And transform (if we have some atoms).
+        if len(self) > 0:
+            self.align_axes()
+            
+        #self.debug_print()
+        #exit()
+    
+    @property
+    def method_type(self):
+        return self.CLASS_HANDLE[1]
+    
+    @property
+    def human_method_type(self):
+        return self.CLASS_HANDLE[0]
+
+    
+    def align_axes(self):
+        """
+        The 'main' method of this alignment class; executes the necessary transformations to align the given atoms.
+        
+        The inheriting subclass should provide a concrete implementation of this method.
+        """
+        pass
+    
+    @classmethod
+    def translate_coords(self, coords, factor):
+        """
+        Translate a given set of coordinates by a constant amount.
+        
+        :param coords: A tuple of the coords (x, y, z) to translate.
+        :param factor: A tuple of the amount to translate the coord by (x, y, z).
+        :return: The translated coords.
+        """
+        return (coords[0] + factor[0],
+                coords[1] + factor[1],
+                coords[2] + factor[2])
+    
+    def translate(self, factor):
+        """
+        Translate all the atoms of this set by a constant amount.
+        
+        :param factor: A tuple of the amount to translate each atom's (x, y, z) coord by.
+        """
+        for atom in self:
+            # Translate.
+            atom.coords = self.translate_coords(atom.coords, factor)
+                    
+        # Update our param which keeps track of transformations.
+        self.translations = self.translate_coords(self.translations, factor)
+        
+    @classmethod
+    def rotate_coords_XY(self, coords, theta):
+        """
+        Rotate a set of coordinates in the XY plane (down the Z-axis).
+        
+        :param coords: The (X, Y, Z) coordinates to rotate.
+        :param theta: The angle (in radians) to rotate by.
+        :return: The rotated coords.
+        """
+        #TODO: Some of these rotation functions rotate in unexpected directions. This works for the alignment classes written so far, but is unexpected and confusing.
+        # Rotate (z stays the same).
+        return    ((coords[0] * math.cos(theta) + coords[1] * math.sin(theta)), 
+                ((-coords[0]) * math.sin(theta) + coords[1] * math.cos(theta)),
+                (coords[2]))
+    
+    @classmethod
+    def rotate_coords_XZ(self, coords, theta):
+        """
+        Rotate a set of coordinates in the XZ plane (down the Y-axis).
+        
+        :param coords: The (X, Y, Z) coordinates to rotate.
+        :param theta: The angle (in radians) to rotate by.
+        :return: The rotated coords.
+        """
+        # Rotate (y stays the same).
+        return    ((coords[0] * math.cos(theta) + coords[2] * math.sin(theta)),
+                (coords[1]),
+                ((-coords[0]) * math.sin(theta) + coords[2] * math.cos(theta)))
+    
+    @classmethod
+    def rotate_coords_YZ(self, coords, theta):
+        """
+        Rotate a set of coordinates in the YZ plane (down the X-axis).
+        
+        :param coords: The (X, Y, Z) coordinates to rotate.
+        :param theta: The angle (in radians) to rotate by.
+        :return: The rotated coords.
+        """
+        # Rotate (x stays the same).
+        #return ((coords[0]),
+        #        (),
+        #        ())
+        return    ((coords[0]),
+                (coords[1] * math.cos(theta) + coords[2] * math.sin(theta)),
+                ((-coords[1]) * math.sin(theta) + coords[2] * math.cos(theta)))
+        
+    @classmethod
+    def axis_to_index(self, axis):
+        if axis == 'X' or axis == 0:
+            return 0
+        elif axis == 'Y' or axis == 1:
+            return 1
+        elif axis == 'Z' or axis == 2:
+            return 2
+        else:
+            raise ValueError("Axis '{}' is out of bounds. Possible  values are 0 (X), 1 (Y) or 2 (Z)")
+        
+    def rotate_coords(self, coords, axis, theta):
+        """
+        Rotate a set of coordinates around an axis.
+        
+        :param coords: Tuple of (X, Y, Z) coords to rotate.
+        :param axis: The axis to rotate around, either ('X' or 0), ('Y' or 1) or ('Z' or 2).
+        :param theta: The angle (in radians) to rotate by.
+        :return: The rotated coords.
+        """
+        # First decide which function to use.
+        axis = self.axis_to_index(axis)
+        if  axis == 0:
+            func = self.rotate_coords_YZ
+        elif axis == 1:
+            func = self.rotate_coords_XZ
+        elif axis == 2:
+            func = self.rotate_coords_XY
+        
+        # Do the rotation.
+        return func(coords, theta)
+        
+    def rotate(self, axis, theta):
+        """
+        Rotate all the atoms of this set around a given axis by a given angle.
+        
+        :param axis: The axis to rotate around, either ('X' or 0), ('Y' or 1) or ('Z' or 2). Coordinates in this axis will not be changed.
+        :param theta: The angle (in radians) to rotate by.
+        """
+        # Rotate each atom.
+        for atom in self:
+            atom.coords = self.rotate_coords(atom.coords, axis, theta)
+            
+        # And to our track of all our rotations.
+        self.rotations.append((self.axis_to_index(axis), theta))
+        
+            
+    def rotate_XY(self, theta):
+        """
+        Rotate all the atoms of this set in the xy plane (down the z-axis).
+        
+        :param theta: The angle (in radians) to rotate by.
+        """
+        return self.rotate('Z', theta)
+        
+    def rotate_XZ(self, theta):
+        """
+        Rotate all the atoms of this set in the xz plane (down the y-axis).
+        
+        :param theta: The angle (in radians) to rotate by.
+        """
+        return self.rotate('Y', theta)
+            
+    def rotate_YZ(self, theta):
+        """
+        Rotate all the atoms of this set in the yz plane (down the x-axis).
+        
+        :param theta: The angle (in radians) to rotate by.
+        """
+        return self.rotate('X', theta)
+    
+    @classmethod
+    def get_theta(self, opposite, adjacent):
+        """
+        Determine the angle needed (theta) to rotate a point.
+        
+        This function does atan(opposite / adjacent), watching out for div by 0.
+        :param opposite: the coordinate of the point along the axis opposite to the angle to calculate.. After rotation, the point will have this coord == 0.
+        :param adjacent: The coordinate of the point along the axis adjacent to the angle to calculate. After rotation, the point will be on this axis.
+        :return: The angle (in radians).
+        """
+        try:
+            return math.atan(opposite / adjacent)
+        except (FloatingPointError, ZeroDivisionError):
+            # Think it's safe to assume the angle is 90 degrees in this instance.
+            return math.pi /2
+    
+    def get_coordinate_list(self):
+        """
+        Get the coordinates of all the atoms of our set as a tuple of lists of the form ([X1, X2...], [Y1, Y2...], [Z1, Z2...]).
+        
+        This is transposed compared to the normal format, which is [(X1, Y1, Z1), (X2, Y2, Z2)...].
+        :return: A tuple of lists of X, Y and Z coordinates. Each list is guaranteed to be the same length.
+        """
+        return list(map(list, zip(* [(atom.coords[0], atom.coords[1], atom.coords[2]) for atom in self])))
+    
+    def apply_transformation(self, coords):
+        """
+        Apply the transformations that have been used to align this atom set to a set of coordinates.
+        
+        This method is useful if you have objects that you would like to re-align to this atom set, but you don't want to influence the actual alignment process (eg, dipole moments).
+        
+        :param coords: A list-like set of 3 coordinates (X, Y, Z).
+        :return: The transformed coordinates as a tuple.
+        """
+        # First, translate.
+        coords = self.translate_coords(coords, self.translations)
+        # Now, rotate.
+        for axis, theta in self.rotations:
+            coords = self.rotate_coords(coords, axis, theta)
+
+        # Return as a tuple.
+        return coords
+    
+    def debug_print(self):
+        
+        for atom in self:
+            print("{}, {}, {}, {}".format(atom.element, atom.coords[0], atom.coords[1], atom.coords[2]))
+            
+    def dump(self, digichem_options):
+        """
+        Get a representation of this result object in primitive format.
+        """
+        dump_dict = super().dump(digichem_options)
+        dump_dict['alignment_method'] = self.human_method_type
+        return dump_dict
+    
+    
+#     @classmethod
+#     def merge(self, *multiple_lists):
+#         """
+#         Merge multiple lists of atoms into a single list.
+#         
+#         Note that it does not make logical sense to combine different list of atoms into one; hence the method only ensures that all given lists are the same and then returns the first given.
+#         If the atom lists are not equivalent, a warning will be issued.
+#         If any of the alignment methods are not the same, a warning will be issued.
+#         """
+#         alignment = multiple_lists[0]
+#         
+#         # Check all other lists are the same.
+#         for atom_list in multiple_lists[1:]:
+#             if type(alignment) != type(atom_list):
+#                 warnings.warn("")
+#                 
+#         # Return the 'merged' list.
+#         return alignment
+    
+    
+class Axis_swapper_mix():
+    """
+    A class mixin for automatically re-assigning the axes so that X, Y & Z axes are in decreasing length.
+    """
+    
+    def reassign_axes(self):
+        """
+        Automatically swap the axes of this class so that X, Y & Z axes are in decreasing length.
+        """
+        if self.X_length < self.Y_length and self.Y_length > self.Z_length:
+            # Swap X and Y.
+            self.rotate_XY(-math.pi/2)
+        elif self.X_length < self.Z_length:
+            # Swap X and Z.
+            self.rotate_XZ(-math.pi/2)
+            
+        if self.Y_length < self.Z_length:
+            # Swap. Y and Z.
+            self.rotate_YZ(-math.pi/2)
+
+            
+class Minimal(Alignment, Axis_swapper_mix):
+    """
+    A basic alignment class, only checks to ensure that the X, Y & Z axes are in decreasing length.
+    """
+    
+    # Names that uniquely describe this alignment protocol.
+    CLASS_HANDLE = ["Minimal", "MIN"]
+    
+    def align_axes(self):
+        """
+        The 'main' method of this alignment class; executes the necessary transformations to align the given atoms.
+        """
+        # All we do is swap axes.
+        self.reassign_axes()
+        
+    
+    
+    

digichem/result/angle.py

@@ -0,0 +1,153 @@
+import math
+
+import digichem.config
+
+
+class Angle():
+    """
+    A class for representing angles (either in radians or degrees).
+    """
+    
+#     # The default units to print angles in.
+#     _default_angle_units = "deg"
+#     
+#     @classmethod
+#     def set_default_angle_units(self, angle_units):
+#         """
+#         Change the default angle units used by subsequent objects.
+#         """
+#         if angle_units != "rad" and angle_units != "deg":
+#             self._raise_angle_unit_error(angle_units)
+#         else:
+#             self._default_angle_units = angle_units
+
+    @property
+    def _default_angle_units(self):
+        return  digichem.config.get_config()['angle_units']
+            
+    
+    def __init__(self, angle, angle_units = None, output_units = "def"):
+        """
+        Constructor for angle objects.
+        
+        :param angle: The numerical value of the angle. Note that this will be stored internally in radians under the 'radians' attribute, and as degrees under 'degrees'.
+        :param angle_units: The units of the angle, either "rad" for radians or "deg" for degrees. If angle is an Angle object, angle_units is ignored and determined automatically. Otherwise and if angle_units is None, "rad" is assumed as the default.
+        :param output_units: The units to use when accessing the angle, either "def" to use the class default 'default_angle_units', "rad" for radians or "deg" for degrees. This can be changed post init by setting the 'units' property.
+        """
+        if isinstance(angle, Angle):
+            angle_units = angle.units
+            angle = float(angle)
+        
+        if angle_units is None:
+            angle_units = "rad"
+        
+        # Check our units are valid and save our angle.
+        if angle_units == "rad":
+            self._angle = angle
+        elif angle_units == "deg":
+            self._angle = self.deg_to_rad(angle)
+        else:
+            # Get upset.
+            self._raise_angle_unit_error(angle_units)
+        
+        # Save our output units (this is type checked for us).
+        if output_units == "def":
+            # Use our default (which can be set at the module level).
+            self.units = self._default_angle_units
+        else:
+            self.units = output_units
+            
+    @classmethod
+    def _raise_angle_unit_error(self, angle_unit):
+        """
+        Convenience function that raises an exception.
+        """
+        raise ValueError('\'{}\' is not a valid angle unit. Accepted values are "rad" or "deg"'.format(angle_unit))
+            
+    @property
+    def radians(self):
+        """
+        The angle in radians.
+        """
+        return self._angle
+    
+    @property
+    def degrees(self):
+        """
+        The angle in degrees.
+        """
+        return self.rad_to_deg(self._angle)
+    
+    @property
+    def angle(self):
+        if self._units == "rad":
+            return self._angle
+        elif self._units == "deg":
+            return self.rad_to_deg(self._angle)
+        else:
+            self._raise_angle_unit_error(self._units)
+        
+    @property
+    def units(self):
+        """
+        The units of the angle, either "deg" for degrees or "rad" for radians.
+        """
+        return self._units
+    
+    @units.setter
+    def units(self, value):
+        if value == "rad" or value == "deg":
+            self._units = value
+        else:
+            self._raise_angle_unit_error(self._units)
+    
+    @property
+    def pretty_units(self):
+        """
+        The units of the angle, currently either "°" for degrees or "rad" for radians.
+        
+        Note that the units returned by this method may change without warning so they are not suitable for type checking, use 'units' for actually checking the type of angle.
+        """
+        return self.units_to_pretty_units(self.units)
+        
+    @classmethod
+    def units_to_pretty_units(self, units):
+        """
+        Convert a string describing angle units (either 'deg' or 'rad') to an appropriate symbol, currently either "°" for degrees or "rad" for radians.
+        
+        :param units: The units as a string.
+        :return: An appropriate unit symbol as a string.
+        """
+        if units == "deg":
+            return "°"
+        elif units == "rad":
+            return "rad"
+        else:
+            return ""
+        
+    
+    def __float__(self):
+        """
+        Get the numerical value of this angle, according to our current 'units'.
+        
+        Use either the 'radians' or 'degrees' properties to use a specific unit.
+        """
+        return self.angle
+    
+    def __str__(self):
+        """
+        String representation of this angle, currently in the format: "angle" "units".
+        """
+        return "{} {}".format(self.angle, self.pretty_units)
+            
+            
+    @classmethod
+    def deg_to_rad(self, deg):
+        return math.radians(deg)
+    
+    @classmethod
+    def rad_to_deg(self, rad):
+        return math.degrees(rad)
+            
+            
+