digichem-core 6.0.0rc1__py3-none-any.whl

digichem/result/base.py

@@ -0,0 +1,258 @@
+import scipy.constants
+import warnings
+import itertools
+import math
+
+from digichem.exception.base import Result_unavailable_error
+
+
+class Result_object():
+    """
+    Top level class for objects that are designed to hold calculation results.
+    """
+    
+    # A warning issued when attempting to merge non-equivalent objects
+    MERGE_WARNING = "Attempting to merge lists of results that are not identical; non-equivalent results will be ignored"
+    
+    def safe_get(self, *attr_names, default = None):
+        """
+        Access an attribute of this object, returning default if the attribute is None or is not available (raises Result_unavailable_error).
+        """
+        # DO YOU LIKE MY B-TEAM SPAGHETTI CODE!?
+        
+        # Get the first name, which we'll be getattr'ing.
+        first_name = attr_names[0]
+        remaining_names = attr_names[1:]
+        
+        # Get.
+        try:
+            attr = getattr(self, first_name)
+            
+            if attr is not None and len(remaining_names) > 0:
+                if isinstance(attr, Result_object):
+                    # We have remaining names to resolve, call attr's safe_get().
+                    attr = attr.safe_get(*remaining_names, default = default)
+                else:
+                    # We have remaining names to resolve, but our attr is not a Result_set (so we can't use safe_get()).
+                    for remaining_name in remaining_names:
+                        attr = getattr(attr, remaining_name)
+        except Result_unavailable_error:
+            return default
+        
+        # And done.
+        return attr
+    
+    @classmethod
+    def wavelength_to_energy(self, wavelength):
+        """
+        Convert a wavelength (in nm) to energy (in eV).
+        """
+        # e = (c * h) / λ
+        return ((scipy.constants.speed_of_light * scipy.constants.Planck) / (wavelength / 1000000000)) / scipy.constants.eV
+    
+    @classmethod
+    def energy_to_wavelength(self, energy):
+        """
+        Convert an energy (in eV) to wavelength (in nm).
+        """
+        # λ = (c * h) / e
+        return ((scipy.constants.speed_of_light * scipy.constants.Planck) / (energy * scipy.constants.eV)) * 1000000000
+    
+    @classmethod
+    def wavenumbers_to_energy(self, wavenumbers):
+        """
+        Convert wavenumbers (in cm-1) to energy (in eV).
+        """
+        return self.wavelength_to_energy((1 / wavenumbers) * 10000000)
+    
+    @classmethod
+    def merged_attr(self, name, objects):
+        """
+        Merge a number of str like attributes.
+        
+        :param name: The name of the attribute to merge.
+        :param objects: A list of objects to merge from.
+        :return: A single string containing the merged attributes.
+        """
+        attributes = list(dict.fromkeys([getattr(obj, name) for obj in objects]))
+        attributes = [attribute for attribute in attributes if attribute is not None]
+        return ", ".join(attributes) if len(attributes) > 0 else None
+    
+    
+    @classmethod
+    def merge(self, *multiple_objects):
+        """
+        Merge multiple Result objects of the same type into a single Result object.
+        
+        Note that this default implementation is intended for objects that cannot actually be merged;
+        truly mergable objects should implement their own merge() method.
+        """
+        # Check all items are the same.
+        if not all(obj == multiple_objects[0] for obj in multiple_objects if obj is not None):
+            warnings.warn(self.MERGE_WARNING)
+            
+        return multiple_objects[0]
+    
+    def generate_for_dump(self):
+        """
+        Method used to get a dictionary used to generate on-demand values for dumping.
+        
+        This functionality is useful for hiding expense properties from the normal dump process, while still exposing them when specifically requested.
+        
+        Each key in the returned dicrt is the name of a dumpable item, each value is a function to call with digichem_options as its only param.
+        """
+        return {}
+    
+    def dump(self, digichem_options):
+        """
+        Abstract function that is called to dump the value of the result object to a primitive type, suitable for serializing with yaml.
+        
+        For real objects, this will normally be a dict with (at least) the following items:
+         - 'value': The value of the result (for example, 34.5.
+         - 'units': The units of the result (for example, k m^-s).
+        """
+        raise NotImplementedError("Implement in subclass")
+
+
+class Floatable_mixin():
+    """
+    A mixin class for result objects that have an unambigious numerical representation.
+    
+    This mixin class expects the implementing class to define __float__().
+    """
+    
+    def __lt__(self, other):
+        """
+        Is this class less than another?
+        """
+        return float(self) < float(other)
+    
+    def __le__(self, other):
+        """
+        Is this class equal or less than another?
+        """
+        return math.isclose(float(self), float(other)) or float(self) < float(other)
+    
+    def __eq__(self, other):
+        """
+        Is this class equal to another?
+        """
+        #return float(self) == float(other)
+        return math.isclose(float(self), float(other))
+    
+    def __ge__(self, other):
+        """
+        Is this class greater or equal to another?
+        """
+        return math.isclose(float(self), float(other)) or float(self) > float(other)
+    
+    def __gt__(self, other):
+        """
+        Is this class greater than another?
+        """
+        return float(self) > float(other)
+    
+
+class Unmergeable_container_mixin():
+    """
+    Mixin for Result_containers that cannot be merged.
+    
+    Classes which inherit from this mixin should also set a class attribute with the name MERGE_WARNING, which should be a message to be displayed when attempting to merge this container with another.
+    """
+    
+    @classmethod
+    def false_merge(self, *multiple_lists, **kwargs):
+        """
+        'Merge' a number of containers of the same type.
+        
+        As Unmergeable_container objects cannot be merged, this method will instead check that all given containers are equivalent, issuing warnings if this is not the case.
+        
+        :param multiple_lists: A number of container objects to 'merge'.
+        :param kwargs: Key-word arguments to pass to the returned container.
+        """
+        items = self(multiple_lists[0], **kwargs)
+        
+        # Check all other lists are the same.
+        for item_list in multiple_lists[1:]:
+            # If this list has atoms and our current doesn't, use this as our base list.
+            if len(item_list) > 0 and len(items) == 0:
+                items = item_list
+            else:
+                for index, item in enumerate(item_list):
+                    try:
+                        other_item = items[index]
+                        if not self.are_items_equal(item, other_item):
+                            warnings.warn(self.MERGE_WARNING)
+                    except IndexError:
+                        warnings.warn(self.MERGE_WARNING)
+                
+        # Return the 'merged' list.
+        return items
+    
+    @classmethod
+    def are_items_equal(self, item, other_item):
+        """
+        A method which determines whether two items are the same for the purposes of merging.
+        
+        This default implementation simply checks for equivalence between the two items.
+        """
+        return item == other_item
+        
+class Result_container(list, Result_object):
+    """
+    Top level class for Result_objects that hold a list of results.
+    """
+    def __init__(self, *args, **kwargs):
+        list.__init__(self, *args, **kwargs)
+        Result_object.__init__(self)
+    
+    def assign_levels(self):
+        """
+        (Re)assign total levels of the objects in this list.
+        
+        The contents of this list will be modified in place.
+        """
+        total_level = 0
+        
+        for state in self:            
+            # Increment total level.
+            total_level += 1
+                
+            # Set level
+            state.level = total_level
+            
+    @classmethod
+    def merge_default(self, *multiple_lists, **kwargs):
+        """
+        The default implementation of the merge method.
+        """
+        # First, get a new list containing all objects.
+        merged_list = self(itertools.chain(*multiple_lists), **kwargs)
+        
+        # Now sort.
+        # This works because the contained objects are all Floatables (see Floatable_mixin) and therefore have well-defined sort mechanics,
+        # or otherwise define their own __eq__ and related methods.
+        merged_list.sort()
+        
+        # Next, we need to reassign levels of the contained objects.
+        merged_list.assign_levels()
+        
+        # All done.
+        return merged_list
+            
+    @classmethod
+    def merge(self, *multiple_lists, **kwargs):
+        """
+        Merge multiple lists of of the same type into a single, ordered list.
+        
+        Note that this method will return a new list object, but will modify the contained objects (eg, object.level) in place.
+        Inheriting classes may safely override this method.
+        """
+        if hasattr(self, "false_merge"):
+            return self.false_merge(*multiple_lists, **kwargs)
+        else:
+            return self.merge_default(*multiple_lists, **kwargs)
+        
+    def dump(self, digichem_options):
+        return [item.dump(digichem_options) for item in self]
+    

digichem/result/dipole_moment.py

@@ -0,0 +1,332 @@
+# General imports
+import math
+
+# Digichem imports
+from digichem.result import Result_object
+from digichem.result.angle import Angle
+
+
+class Dipole_moment_ABC(Result_object):
+    """
+    ABC that represents a dipole moment.
+    
+    See inheriting classes for concrete implementations (depending on whether they are permanent or transition, and electric or magnetic).
+    """
+    
+    # A warning issued when attempting to merge non-equivalent objects
+    MERGE_WARNING = "Attempting to merge list of DPMs that are not identical; non-equivalent DPMs will be ignored"
+    
+    @property
+    def magnitude(self):
+        """
+        The dipole moment total (root-sum-square of the dipole moment vector).
+        
+        :deprecated: 'magnitude' is a somewhat misleading name for this attribute, use 'total' instead.
+        """
+        return self.total
+    
+    @property
+    def total(self):
+        """
+        The dipole moment total (root-sum-square of the dipole moment vector).
+        """
+        return math.sqrt( self.vector_coords[0] ** 2 + self.vector_coords[1] ** 2 + self.vector_coords[2] ** 2)
+    
+    def __init__(self, origin_coords, vector_coords, atoms = None):
+        """
+        Constructor for Dipole_moment objects.
+        
+        :param origin_coords: Tuple of (x, y, z) coordinates of the origin of this dipole moment.
+        :param vector_coords: Tuple of (x, y, z) coordinates of this dipole  moment.
+        :param atoms: Optional atoms atom list object which is used to calculate addition data about this dipole moment. 
+        """
+        super().__init__()
+        # The start of our vector, normally (0,0,0).
+        self.origin_coords = origin_coords
+        # The end of our vector.
+        self.vector_coords = vector_coords
+        
+        # Save our atoms object.
+        self.atoms = atoms if atoms is not None else []
+        
+        # Save a name describing which dipole we are (permanent vs transition etc).
+        self.dipole_type = "permanent"
+    
+    @property
+    def name(self):
+        """
+        Name that describes this dipole moment.
+        """
+        return "PDM"
+    
+    @property
+    def origin_coords(self):
+        """
+        The origin coords of this vector as a tuple of (x, y, z). origin_coords is automatically realigned by the atoms alignment object of this dipole, use _origin_coords if you do not want this behaviour.
+        """
+        if len(self.atoms) > 0:
+            return self.atoms.apply_transformation(self._origin_coords)
+        else:
+            return self._origin_coords
+        
+    @origin_coords.setter
+    def origin_coords(self, value):
+        """
+        Set the origin coords of this dipole.
+        """
+        self._origin_coords = value
+        
+    @property
+    def vector_coords(self):
+        """
+        The ending coords of this vector as a tuple of (x, y, z). vector_coords is automatically realigned by the atoms alignment object of this dipole, use _vector_coords if you do not want this behaviour.
+        """
+        if len(self.atoms) > 0:
+            return self.atoms.apply_transformation(self._vector_coords)
+        else:
+            return self._vector_coords
+        
+    @vector_coords.setter
+    def vector_coords(self, value):
+        """
+        Set the ending coords of this dipole.
+        """
+        self._vector_coords = value
+        
+    def __float__(self):
+        """
+        Floatify this Dipole_moment.
+        """
+        return self.magnitude
+    
+    def __eq__(self, other):
+        """
+        Is this dipole moment equal to another?
+        
+        A dipole moment is considered equivalent only if all coordinates match.
+        """
+        return self.origin_coords == other.origin_coords and self.vector_coords == other.vector_coords
+    
+    @property
+    def X_axis_angle(self):
+        """
+        The angle between this dipole moment and the X axis of the atom set of the molecule.
+        """
+        if self.total == 0:
+            return Angle(0)
+        elif len(self.atoms) > 0:
+            return Angle(math.fabs(self.atoms.get_X_axis_angle(self.origin_coords, self.vector_coords)), "rad")
+        else:
+            return None
+        
+    @property
+    def XY_plane_angle(self):
+        """
+        The angle between this dipole moment and the XY plane of the atom set of the molecule.
+        """
+        if self.total == 0:
+            return Angle(0)
+        elif len(self.atoms) > 0:
+            return Angle(math.fabs(self.atoms.get_XY_plane_angle(self.origin_coords, self.vector_coords)), "rad")
+        else:
+            return None
+    
+    @property
+    def gaussian_cgs_vector(self):
+        """
+        The vector of this dipole moment in Gaussian-cgs units.
+        
+        Note that the sign of the vector will be reversed in Gaussian-cgs units.
+        See J. Phys. Chem. Lett. 2021, 21, 686-695.
+        """
+        return tuple(self.to_gaussian_cgs(coord) for coord in self.vector_coords)
+    
+    @property
+    def gaussian_cgs(self):
+        """
+        The total of this dipole moment in Gaussian-cgs units.
+        
+        Note that the sign of the vector will be reversed in Gaussian-cgs units.
+        See J. Phys. Chem. Lett. 2021, 21, 686-695.
+        """
+        cgs_vector = self.gaussian_cgs_vector
+        return math.sqrt( cgs_vector[0] **2 + cgs_vector[1] **2 + cgs_vector[2] **2 )
+    
+    def angle(self, other, cgs = True):
+        """
+        Find the angle between this dipole moment and another.
+        
+        :param cgs: Whether to find the angle in Gaussian-cgs units or standard units (the direction of magnetic dipole moments is reversed in the former).
+        """
+        return Angle(math.acos(self.cos_angle(other, cgs)))
+        
+    def cos_angle(self, other, cgs = True):
+        """
+        Find the cosine of the angle between this dipole moment and another.
+        
+        :param cgs: Whether to find the angle in Gaussian-cgs units or standard units (the direction of magnetic dipole moments is reversed in the former).
+        """
+        if cgs:
+            vector_a = self.gaussian_cgs_vector
+            vector_b = other.gaussian_cgs_vector
+        
+        else:
+            vector_a = self.vector_coords
+            vector_b = other.vector_coords
+            
+        vector_a_total = math.sqrt( vector_a[0] **2 + vector_a[1] **2 + vector_a[2] **2 )
+        vector_b_total = math.sqrt( vector_b[0] **2 + vector_b[1] **2 + vector_b[2] **2 )
+        
+        try:
+            return (vector_a[0] * vector_b[0] + vector_a[1] * vector_b[1] + vector_a[2] * vector_b[2]) / (vector_a_total * vector_b_total)
+        except (FloatingPointError, ZeroDivisionError):
+            return 0
+        
+    def dump(self, digichem_options):
+        """
+        Get a representation of this result object in primitive format.
+        """
+        return {
+            "total": {
+                "value": self.total,
+                "units": self.units
+            },
+            "origin": {
+                "x": {
+                    "value": float(self.origin_coords[0]),
+                    "units": "Å",
+                },
+                "y": {
+                    "value": float(self.origin_coords[1]),
+                    "units": "Å",
+                },
+                "z": {
+                    "value": float(self.origin_coords[2]),
+                    "units": "Å",
+                }
+            },
+            "vector": {
+                "x": {
+                    "value": float(self.vector_coords[0]),
+                    "units": self.units
+                },
+                "y": {
+                    "value": float(self.vector_coords[1]),
+                    "units": self.units
+                },
+                "z": {
+                    "value": float(self.vector_coords[2]),
+                    "units": self.units
+                },
+            },
+            "x-angle": {
+                "value": self.X_axis_angle.angle,
+                "units": self.X_axis_angle.units
+            },
+            "xy-angle": {
+                "value": self.XY_plane_angle.angle,
+                "units": self.XY_plane_angle.units
+            }
+        }
+
+
+class Electric_dipole_moment_mixin():
+    """
+    Mixin class for electric dipole moments.
+    """
+    
+    @property
+    def units(self):
+        """
+        The units of this dipole moment object.
+        """
+        # Debye
+        return "D"
+    
+    @property
+    def coulomb_meters(self):
+        """
+        The total of this dipole moment in Coulomb Meters.
+        """
+        return float(self) * 3.335640952e-30
+    
+    @classmethod
+    def D_to_au(self, value):
+        """
+        Convert an electric dipole moment in D to a.u.
+        """
+        return value / 2.541746473
+    
+    @classmethod
+    def to_gaussian_cgs(self, value):
+        """
+        Convert an electric dipole moment in D to Gaussian-cgs units.
+        See J. Phys. Chem. Lett. 2021, 21, 686-695.
+        """
+        # cgs = au * e * a0
+        return self.D_to_au(value) * 4.80320425e-10 * 5.29177210903e-9
+
+
+class Magnetic_dipole_moment_mixin():
+    """
+    Mixin class for magnetic dipole moments.
+    """
+    
+    @property
+    def units(self):
+        """
+        The units of this dipole moment object.
+        """
+        return "a.u."
+    
+    @property
+    def bohr_magnetons(self):
+        """
+        The total of this magnetic dipole moment in bohr magnetons.
+        """
+        return self.total * 2
+    
+    @property
+    def ampere_square_meters(self):
+        """
+        The total of this magnetic dipole moment in SI units.
+        """
+        return self.total * 1.8548e-23
+    
+    @classmethod
+    def to_gaussian_cgs(self, value):
+        """
+        Convert a magnetic dipole moment in a.u. to Gaussian-cgs units.
+        See J. Phys. Chem. Lett. 2021, 21, 686-695.
+        """
+        return value * -9.2740100783e-21
+
+
+class Dipole_moment(Dipole_moment_ABC, Electric_dipole_moment_mixin):
+    """
+    Class that represents the (permanent) dipole moment of a molecule.
+    """
+        
+    @classmethod
+    def from_dump(self, data, result_set, options):
+        """
+        Get a list of instances of this class from its dumped representation.
+        
+        :param data: The data to parse.
+        :param result_set: The partially constructed result set which is being populated.
+        """
+        return self((data['origin']['x']['value'], data['origin']['y']['value'], data['origin']['z']['value']), (data['vector']['x']['value'], data['vector']['y']['value'], data['vector']['z']['value']), atoms = result_set.atoms)
+    
+    @classmethod
+    def from_parser(self, parser):
+        """
+        Construct a Dipole_moment object from an output file parser.
+        
+        :param parser: An output file parser.
+        :result: A single Dipole_moment object, or None if no dipole information is available.
+        """
+        try:
+            return self(parser.data.moments[0], parser.data.moments[1], parser.results.atoms)
+        except AttributeError:
+            return None
+