digichem-core 6.0.0rc1__py3-none-any.whl

digichem/result/result.py

@@ -0,0 +1,244 @@
+# Code for processing results from calculations and generating reports.
+
+# General imports.
+import itertools
+import warnings
+
+from digichem.exception import Result_unavailable_error
+
+from digichem.result import Result_object
+import digichem.result.excited_state
+from digichem.result.emission import Emissions
+
+
+class Result_set(Result_object):
+    """
+    Class that represents a collection of results from a calculation.
+    
+    This class is a bit heavy and might not be around for long...
+    """
+    
+    def __init__(self, **attributes):
+        """Constructor for Result_set objects."""
+        super().__init__()
+        
+        # The ID uniquely identifies this calculation result.
+        # In most cases, it is generated from the combined chekcsum of the log files from which the results was parsed.
+        # If this result was not read from log files (but was read from a database or from a .si calc result or similar),
+        # then the id will simply be the same as was written previously.
+        #
+        # Note that the underscore here does not imply that this attribute is 'hidden'. Instead, this is used for 
+        # consistency with mongo-like DBs, where the ID field is also typically named _id.
+        #self._id = attributes.pop('database_id', None)
+        self._id = attributes.pop('_id', None)
+        
+        self.results = (self,)
+        self.emission = attributes.pop('emission', Emissions())
+        
+        for attr_name, attribute in attributes.items():
+            setattr(self, attr_name, attribute)
+        
+    @property
+    def alignment(self):
+        warnings.warn("alignment is deprecated, use atoms instead", DeprecationWarning)
+        return self.atoms
+
+    @property
+    def CC_energies(self):
+        warnings.warn("CC_energies is deprecated, use energies.cc instead", DeprecationWarning)
+        return self.energies.cc
+    
+    @CC_energies.setter
+    def CC_energies(self, value):
+        warnings.warn("CC_energies is deprecated, use energies.cc instead", DeprecationWarning)
+        self.energies.cc = value
+    
+    @property
+    def MP_energies(self):
+        warnings.warn("MP_energies is deprecated, use energies.mp instead", DeprecationWarning)
+        return self.energies.mp
+    
+    @MP_energies.setter
+    def MP_energies(self, value):
+        warnings.warn("MP_energies is deprecated, use energies.mp instead", DeprecationWarning)
+        self.energies.mp = value
+    
+    @property
+    def SCF_energies(self):
+        warnings.warn("SCF_energies is deprecated, use energies.scf instead", DeprecationWarning)
+        return self.energies.scf
+    
+    @SCF_energies.setter
+    def SCF_energies(self, value):
+        warnings.warn("SCF_energies is deprecated, use energies.scf instead", DeprecationWarning)
+        self.energies.scf = value
+        
+    @property
+    def molecular_orbitals(self):
+        warnings.warn("molecular_orbitals is deprecated, use orbitals instead", DeprecationWarning)
+        return self.orbitals
+    
+    @molecular_orbitals.setter
+    def molecular_orbitals(self, value):
+        warnings.warn("molecular_orbitals is deprecated, use orbitals instead", DeprecationWarning)
+        self.orbitals = value
+        
+    @property
+    def spin_orbit_coupling(self):
+        warnings.warn("spin_orbit_coupling is deprecated, use soc instead", DeprecationWarning)
+        return self.soc
+    
+    @spin_orbit_coupling.setter
+    def spin_orbit_coupling(self, value):
+        warnings.warn("spin_orbit_coupling is deprecated, use soc instead", DeprecationWarning)
+        self.soc = value
+        
+    @property
+    def dipole_moment(self):
+        warnings.warn("dipole_moment is deprecated, use pdm instead", DeprecationWarning)
+        return self.pdm
+    
+    @dipole_moment.setter
+    def dipole_moment(self, value):
+        warnings.warn("dipole_moment is deprecated, use pdm instead", DeprecationWarning)
+        self.pdm = value
+        
+    @property
+    def vertical_emission(self):
+        warnings.warn("vertical_emission is deprecated, use emission.vertical instead", DeprecationWarning)
+        return self.emission.vertical
+    
+    @vertical_emission.setter
+    def vertical_emission(self, value):
+        warnings.warn("vertical_emission is deprecated, use emission.vertical instead", DeprecationWarning)
+        self.emission.vertical = value
+    
+    @property
+    def adiabatic_emission(self):
+        warnings.warn("adiabatic_emission is deprecated, use emission.adiabatic instead", DeprecationWarning)
+        return self.emission.adiabatic
+    
+    @adiabatic_emission.setter
+    def adiabatic_emission(self, value):
+        warnings.warn("adiabatic_emission is deprecated, use emission.adiabatic instead", DeprecationWarning)
+        self.emission.adiabatic = value
+        
+    @property
+    def metadatas(self):
+        """
+        Property providing access to the list of metadatas of the calculations that were merged together.
+        """
+        return [result.metadata for result in self.results]
+    
+    @property
+    def level_of_theory(self):
+        """
+        A short-hand summary of the methods and basis sets used.
+        """
+        methods = []
+        basis_sets = []
+        for metadata in self.metadatas:
+            if len(metadata.converted_methods) > 0:
+                method = metadata.converted_methods[-1]
+#             for method in metadata.converted_methods:
+                if method not in methods:
+                    methods.append(method)
+                
+            if metadata.basis_set is not None and metadata.basis_set not in basis_sets:
+                basis_sets.append(metadata.basis_set)
+                        
+        return "/".join(itertools.chain(methods, basis_sets))
+    
+    @property
+    def title(self):
+        """
+        A string Title describing this result.
+        """
+        title = ", ".join(self.metadata.calculations)
+        if "Excited States" in self.metadata.calculations:
+            # Add multiplicity based on ES.
+            mult = self.excited_states.group()
+            mult_strings = [digichem.result.excited_state.Energy_state.multiplicity_number_to_string(multiplicity).capitalize() for multiplicity in mult]
+            if len(mult_strings) <= 2:
+                # Add the strings.
+                title += " ({})".format(", ".join(mult_strings))
+            else:
+                # Add something non-specific.
+                title += " (Various Multiplicities)"
+        else:
+            title += " ({})".format(digichem.result.excited_state.Energy_state.multiplicity_number_to_string(self.metadata.multiplicity).capitalize())
+        return title
+    
+    @property
+    def energy(self):
+        """
+        The total energy of this calculation.
+        
+        This convenience property is the energy at the highest level of theory available (CC > MP > SCF).
+        
+        :raises Result_unavailable_error: If no total energy is available.
+        """
+        warnings.warn("energy is deprecated, use energies.final instead", DeprecationWarning)
+        return self.energies.final
+    
+        
+    @property
+    def electric_transition_dipole_moment(self):
+        """
+        The S1 electric dipole moment, commonly referred to as THE electric transition dipole moment (although this name is ambiguous).
+        
+        None is returned if the S1 dipole moment is not available.
+        """
+        tdm = self.transition_dipole_moment
+        if tdm is not None:
+            return tdm.electric
+        
+    @property
+    def magnetic_transition_dipole_moment(self):
+        """
+        The S1 magnetic dipole moment, commonly referred to as THE magnetic transition dipole moment (although this name is ambiguous).
+        
+        None is returned if the S1 dipole moment is not available.
+        """
+        tdm = self.transition_dipole_moment
+        if tdm is not None:
+            return tdm.magnetic
+
+    @property
+    def transition_dipole_moment(self):
+        """
+        The S1 dipole moment (both electric and magnetic), commonly referred to as THE transition dipole moment (although this name is ambiguous).
+        
+        None is returned if the S1 dipole moment is not available.
+        """
+        try:
+            S1 = self.excited_states.get_state("S(1)")
+            return S1.transition_dipole_moment
+        except Result_unavailable_error:
+            # No S1 available.
+            return None
+        
+    def dump(self, digichem_options):
+        "Dump the data contained in this result set, serialising it to a hierarchy of dicts that can be saved in various formats."
+        # Start with our DB ID if we have one.
+        dump_dic = {}
+        if self._id is not None:
+            dump_dic['_id'] = self._id
+            
+        dump_dic.update({
+            "metadata": self.metadata.dump(digichem_options),
+            "ground_state": self.ground_state.dump(digichem_options) if self.ground_state is not None else None,
+            "energies": self.energies.dump(digichem_options),
+            "atoms": self.atoms.dump(digichem_options),
+            "raw_atoms": self.raw_atoms.dump(digichem_options),
+            "orbitals": self.orbitals.dump(digichem_options),
+            "beta_orbitals": self.beta_orbitals.dump(digichem_options),
+            "pdm": self.pdm.dump(digichem_options) if self.pdm is not None else None,
+            "excited_states": self.excited_states.dump(digichem_options),
+            "soc": self.soc.dump(digichem_options),
+            "vibrations": self.vibrations.dump(digichem_options),
+            "nmr": self.nmr.dump(digichem_options),
+            "emission": self.emission.dump(digichem_options)
+        })
+        
+        return dump_dic

digichem/result/soc.py

@@ -0,0 +1,272 @@
+# General imports.
+import math
+
+from digichem.exception import Result_unavailable_error
+from digichem.result import Result_container
+from digichem.result import Result_object
+from digichem.result.base import Floatable_mixin
+
+
+class SOC_list(Result_container):
+    """
+    An augmented list containing spin orbit coupling.
+    """
+    
+    def find(self, criteria):
+        """
+        """
+        states = criteria.split(",")
+        
+        # Check we have two states.
+        if len(states) != 2:
+            raise ValueError("SOC can only be found between exactly 2 states, not {} states.".format(len(states)))
+        
+        return self.between(*states)
+    
+    def between(self, state1, state2, **kwargs):
+        """
+        Return the spin-orbit coupling object between the two states with given symbols.
+        
+        :param states: Symbols identifying the two states to get SOC between (eg, "S(1)" "T(1)").
+        :param default: A default argument that will be returned if the given states cannot be found.
+        """
+        states = set((state1, state2))
+        
+        # Iterate through all our SOC.
+        for soc in self:
+            # Check if the two states match the two we've been asked to find.
+            if len(states.intersection((soc.singlet_state.state_symbol, soc.triplet_state.state_symbol))) == 2:
+                # A match!
+                return soc
+            
+        # No match.
+        # Return the default if given, otherwise panic.
+        if "default" in kwargs:
+            return kwargs['default']
+        else:
+            raise Result_unavailable_error("Spin-orbit coupling", "could not find SOC between states with symbols '{}' and '{}'".format(state1, state2))
+    
+    @classmethod
+    def from_parser(self, parser):
+        """
+        Get a SOC_list object from an output file parser.
+        
+        :param parser: An output file parser.
+        :return: A SOC_list object. The list will be empty if no SOC is available.
+        """
+        # Decide which SOC class to use.
+        if hasattr(parser.data, "socelements"):
+            soc_cls = Spin_orbit_coupling
+        else:
+            soc_cls = Total_spin_orbit_coupling
+        
+        return self(soc_cls.list_from_parser(parser))
+
+    @classmethod
+    def from_dump(self, data, result_set, options):
+        """
+        Get an instance 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([(Spin_orbit_coupling if 'soc' in soc_dict else Total_spin_orbit_coupling).from_dump(soc_dict, result_set, options) for soc_dict in data])
+    
+    def sort(self, *, key = None, **kwargs):
+        """
+        Sort this list in place.
+        """
+        # If no key is given, we use a custom default key.
+        if key is None:
+            key = lambda SOC: (SOC.singlet_state.level, SOC.triplet_state.level)
+            
+        return super().sort(key = key, **kwargs)
+
+
+class Spin_orbit_coupling(Result_object, Floatable_mixin):
+    """
+    Class that represents spin-orbit coupling between two states.
+    """
+    
+    def __init__(self, singlet_state, triplet_state, positive_one, zero, negative_one):
+        """
+        Constructor for SOC objects.
+        
+        :param singlet_state: The singlet excited state this coupling is between.
+        :param triplet_state: The triplet excited state this coupling is between.
+        :param positive_one: SOC between the singlet state and triplet sub-state with quantum number +1 in cm-1.
+        :param zero: SOC between the singlet state and triplet sub-state with quantum number 0 in cm-1.
+        :param negative_one: SOC between the singlet state and triplet sub-state with quantum number -1 in cm-1.
+        """
+        self.singlet_state = singlet_state
+        self.triplet_state = triplet_state
+        self.positive_one = positive_one
+        self.zero = zero
+        self.negative_one = negative_one
+        
+    def dump(self, digichem_options):
+        """
+        Get a representation of this result object in primitive format.
+        """
+        return {
+            "singlet": self.singlet_state.state_symbol,
+            "triplet": self.triplet_state.state_symbol,
+            "soc": {
+                "+1": {
+                    "value": self.positive_one,
+                    "units": "c m^-1",
+                },
+                "0": {
+                    "value": self.zero,
+                    "units": "c m^-1",
+                },
+                "-1": {
+                    "value": self.negative_one,
+                    "units": "c m^-1",
+                },
+            },
+            "rss": {
+                "units": "c m^-1",
+                "value": self.root_sum_square,
+            },
+            "mixing_coefficient": self.mixing_coefficient
+        }
+        
+    @classmethod
+    def from_dump(self, data, result_set, options):
+        """
+        Get an instance 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(result_set.energy_states.find(data['singlet']), result_set.energy_states.find(data['triplet']), data['soc']['+1']['value'], data['soc']['0']['value'], data['soc']['-1']['value'])
+        
+    @classmethod
+    def list_from_parser(self, parser):
+        """
+        Create a SOC object from an output file parser.
+        """
+        # Go through our data.
+        try:
+            return [self(
+                singlet_state = parser.results.energy_states.get_state(state_symbol = singlet_symbol),
+                triplet_state = parser.results.energy_states.get_state(state_symbol = triplet_symbol),
+                positive_one = positive_soc,
+                zero = zero_soc,
+                negative_one = negative_soc
+            ) for (singlet_symbol, triplet_symbol), (positive_soc, zero_soc, negative_soc) in zip(parser.data.socstates, parser.data.socelements)]
+        except AttributeError:
+            # No data.
+            return []
+        
+    @property
+    def splitting_energy(self):
+        """
+        The difference in energy between these two states.
+        """
+        return max(float(self.singlet_state), float(self.triplet_state)) - min(float(self.singlet_state), float(self.triplet_state))
+    
+    @property
+    def mixing_coefficient(self):
+        """
+        The first order mixing coefficient (λ), given by Hso / dEst.
+        Be aware that λ will == math.inf if dEst == 0.
+        """
+        try:
+            return self.energy / self.splitting_energy
+        except (FloatingPointError, ZeroDivisionError):
+            return math.inf
+    
+    @property
+    def root_sum_square(self):
+        """
+        The root sum square of this SOC.
+        """
+        return math.sqrt(self.positive_one **2 + self.zero **2 + self.negative_one **2)
+        
+    def __float__(self):
+        """
+        Floatify this SOC class.
+        """
+        return float(self.root_sum_square)
+    
+    @property
+    def wavenumbers(self):
+        """
+        SOC in wavenumbers.
+        """
+        return self.root_sum_square
+    
+    @property
+    def energy(self):
+        """
+        SOC in eV.
+        """
+        try:
+            return self.wavenumbers_to_energy(self.root_sum_square)
+        except (FloatingPointError, ZeroDivisionError):
+            return 0.0
+    
+    def __str__(self):
+        """
+        Stringify this SOC class.
+        """
+        return "<{}|Hso|{}> (RSS, +1, 0, -1) (cm-1): {:10.5f} {:10.5f} {:10.5f} {:10.5f}".format(self.singlet_state.state_symbol, self.triplet_state.state_symbol, self.root_sum_square, self.positive_one, self.zero, self.negative_one)
+
+
+class Total_spin_orbit_coupling(Spin_orbit_coupling):
+    """
+    A class for representing SOC when only the total is known (and not the individual elements).
+    """
+    
+    def __init__(self, singlet_state, triplet_state, total):
+        super().__init__(singlet_state, triplet_state, None, None, None)
+        
+        self._root_sum_square = total
+        
+    @property
+    def root_sum_square(self):
+        return self._root_sum_square
+        
+    def __str__(self):
+        """
+        Stringify this SOC class.
+        """
+        return "<{}|Hso|{}> (cm-1): {:10.5f}".format(self.singlet_state.state_symbol, self.triplet_state.state_symbol, self.root_sum_square)
+    
+    def dump(self, digichem_options):
+        """
+        Get a representation of this result object in primitive format.
+        """
+        dump_dic = super().dump(digichem_options)
+        # Remove elements.
+        del(dump_dic['soc'])
+        return dump_dic
+    
+    @classmethod
+    def from_dump(self, data, result_set, options):
+        """
+        Get an instance 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(result_set.energy_states.find(data['singlet']), result_set.energy_states.find(data['triplet']), data['rss']['value'])
+        
+    @classmethod
+    def list_from_parser(self, parser):
+        """
+        Create a SOC object from an output file parser.
+        """
+        # Go through our data.
+        try:
+            return [self(
+                singlet_state = parser.results.energy_states.get_state(state_symbol = singlet_symbol),
+                triplet_state = parser.results.energy_states.get_state(state_symbol = triplet_symbol),
+                total = total
+            ) for (singlet_symbol, triplet_symbol), total in zip(parser.data.socstates, parser.data.socenergies)]
+        except (AttributeError, Result_unavailable_error):
+            # No data.
+            return []
+