quadlib 0.1.0__py3-none-any.whl

quadlib/tools/constants.py

@@ -0,0 +1,289 @@
+# QuaDLib: QUAntum Dynamics LIBrary for research and methods development
+# Copyright (C) 2018-2026, The Theoretical Chemistry Group, Heidelberg University
+#
+# This software is licensed under the MIT License (https://spdx.org/licenses/MIT.html)
+
+"""
+Compendium of conversion factors and physical constants:
+
+PI                = 3.1415926535897    #Pi
+E                 = 2.718281828459     #E
+FPC_c             = 299792458          #speed of light in vacuum (def) m/s
+FPC_h_BAR         = 1.05457266e-34     #Planck constant, reduced (63) J s
+FPC_h_BAR_MeVs    = 6.582122e-22       #Planck constant, reduced (20) MeV s
+FPC_e_C           = 1.60217733e-19     #electron charge magnitude (49) C
+FPC_e_ESU         = 4.8032068e-10      #electron charge magnitude (15) esu
+FPC_hBARc         = 197.327053         #conversion constant hbar*c (59) MeV Fm
+FPC_hBARc2        = 0.38937966         #conversion constant (hbar*c)^2 (23) GeV^2 mbarn
+FPC_m_e_kg        = 9.1093897e-31      #electron mass (54) kg
+FPC_m_e_MeV       = 0.51099906         #electron mass (15) MeV/c^2
+FPC_m_P_MeV       = 938.27231          #proton mass (28) MeV/c^2
+FPC_m_P_u         = 1.00727647         #proton mass (12) u
+FPC_m_P_kg        = 1.6726231e-27      #proton mass (10) kg
+FPC_m_P_M_E       = 1836.152701        #proton mass (37) m_e
+FPC_m_D_MeV       = 1875.61339         #deuteron mass (57) MeV/c^2
+FPC_u_MeV         = 931.49432          #unified atomic mass unit (u) (28) MeV/c^2
+FPC_u_kg          = 1.6605402e-27      #unified atomic mass unit (u) (10) kg
+FPC_EPSILON_0     = 8.854187817e-12    #permittivity of free space F/m
+FPC_MU_0          = 1.2566370614e-06   #permeability of free space N/A^2
+FPC_ALPHA         = 0.0072973530796448 #fine-structure constant (61)
+FPC_r_e           = 2.81794092e-15     #classical electron radius (38) m
+FPC_LAMBDA_BAR_e  = 3.86159323e-13     #electron Compton wavelength (35) m
+FPC_a_0           = 5.29177249e-11     #Bohr radius (mnucleus= infty) (24) m
+FPC_LAMBDA_1EV    = 1.23984244e-06     #wavelength of 1 eV/c particle (37) m
+FPC_R_INFINITY_EV = 13.6056981         #Rydberg energy (mnucleus = infinity) (40) eV
+FPC_SIGMA_0_BARN  = 0.66524616         #Thomson cross section (18) barn
+FPC_MU_B_MeV_T    = 5.78838263e-11     #Bohr magneton (52)  MeV/T
+FPC_MU_N_MeV_T    = 3.15245166e-14     #nuclear magneton (28) MeV/T
+FPC_E_M_e         = 175881962000       #electron cyclotron freq./field (53) C/kg (rad/sT)
+FPC_E_M_P         = 95788309           #proton cyclotron freq./field (29) C/kg (rad/sT)
+FPC_G_SI          = 6.67259e-11        #gravitational constant (85) m^3/kgs^2
+FPC_G_P           = 6.70711e-39        #gravitational constant (86) h_bar c (GeV/c^2)^{-2}
+FPC_g             = 9.80665            #standard grav. accel., sea level m/s^2
+FPC_N_A           = 6.0221367e+23      #Avogadro constant (36)  /mole
+FPC_K_B           = 1.380658e-23       #Boltzmann constant (12) J/K
+FPC_K_B_EV        = 8.617385e-05       #Boltzmann constant (73) eV/K
+FPC_V_MOLAR       = 0.0224141          #molar volume, ideal gas at STP (19) m^3/mole
+FPC_LAMBDAT       = 0.002897756        #Wien displacement law constant (24) m K
+FPC_SIGMA_SB      = 5.67051e-08        #Stefan-Boltzmann constant (19) W/m^2K^4
+FPC_G_F           = 1.16639e-05        #Fermi coupling constant (2)  GeV^{-2}
+FPC_SIN2_THETA_W  = 0.23192            #weak mixing angle  (5)  at M_Z
+FPC_M_W           = 80.22              #W boson mass (26) GeV/c^2
+FPC_M_Z0          = 91.187             #Z_0 boson mass (7) GeV/c^2
+FPC_G_S           = 0.117              #strong coupling constant (5))  at M_Z
+AUCHARGE          = 1.60217733e-19     #1 a.u. charge in SI, elementary charge
+AUMASS            = 9.1093897e-31      #1 a.u. mass in SI, electron rest mass
+AUENERGY          = 4.3597482e-18      #1 a.u. energy in SI, hartree energy
+AULENGTH          = 5.29177249e-11     #1 a.u. length in SI, bohrradius
+AUACTION          = 1.05457266e-34     #1 a.u. action in SI, Planck constant/(2*PI)
+AUTIME            = 2.4188843341e-17   #1 a.u. time in SI
+AUFORCE           = 8.2387295e-08      #1 a.u. force in  SI
+AUVELOCITY        = 2187691.42         #1 a.u. velocity in SI
+AUMOMENTUM        = 1.9928534e-34      #1 a.u. momentum in SI
+AUEFIELD          = 514220820000       #1 a.u. el. field in SI
+AUEDIPOLE         = 8.4783579e-30      #1 a.u. el. dipole in SI
+AUMFLUX           = 235051.808         #1 a.u. magn. flux in SI
+AUMDIPOLE         = 1.85480308e-23     #1 a.u. magn. flux in  SI
+ELECTRONVOLT      = 1.60217733e-19     #1 eV charge in SI
+ATOMICMASS        = 1.6605402e-27      #1 amu mass in SI
+ASTRONOMICALUNIT  = 149597870000       #1 AE length in SI
+MOL               = 6.0221367e+23      #Avogadro constant
+au2an             = 0.529177249        #[a.u.] -> [Angstroem]
+an2au             = 1.8897259885789    #[Angstroem] -> [a.u.]
+au2ev             = 27.211396131788    #[a.u.] -> [eV]
+ev2au             = 0.036749308824762  #[eV] -> [a.u.]
+au2am             = 0.00054857989586762#[a.u.] -> [atomar mass units]
+am2au             = 1822.8885300626    #[atomar mass units] -> [a.u.]
+au2fs             = 0.024188843341     #[a.u.] -> [fs]
+fs2au             = 41.341373206755    #[fs] -> [a.u.]
+ev2kc             = 23.05              #[eV] -> [kcal/mol]
+kc2ev             = 0.043364476254697  #[kcal/mol] -> [eV]
+au2kc             = 627.50431878767    #[a.u.] -> [kcal/mol]
+kc2au             = 0.0015936145299079 #[kcal/mol] -> [a.u.]
+au2ic             = 219474.7           #[au] -> [1/cm]
+ic2au             = 4.5563338279993e-06#[1/cm] -> [au]
+ev2ic             = 8065.54353         #[eV] -> [1/cm]
+ic2ev             = 0.0001239842047    #[1/cm] -> [eV]
+ev2kj             = 96.485             #[eV] -> [kJoule/mol]
+kj2ev             = 0.0103643          #[kJoule/mol] -> [eV]
+in2cm             = 2.54               #[inch] -> [cm]
+ft2m              = 0.3048             #[feet] -> [cm]
+yd2m              = 0.9144             #[yard] -> [cm]
+cm2in             = 0.39370078740157   #[inch] -> [cm]
+m2ft              = 3.2808398950131    #[feet] -> [cm]
+m2yd              = 1.0936132983377    #[yard] -> [cm]
+"""
+
+PI                = 3.1415926535897    #Pi
+E                 = 2.718281828459     #E
+FPC_c             = 299792458          #speed of light in vacuum (def) m/s
+FPC_h_BAR         = 1.05457266e-34     #Planck constant, reduced (63) J s
+FPC_h_BAR_MeVs    = 6.582122e-22       #Planck constant, reduced (20) MeV s
+FPC_e_C           = 1.60217733e-19     #electron charge magnitude (49) C
+FPC_e_ESU         = 4.8032068e-10      #electron charge magnitude (15) esu
+FPC_hBARc         = 197.327053         #conversion constant hbar*c (59) MeV Fm
+FPC_hBARc2        = 0.38937966         #conversion constant (hbar*c)^2 (23) GeV^2 mbarn
+FPC_m_e_kg        = 9.1093897e-31      #electron mass (54) kg
+FPC_m_e_MeV       = 0.51099906         #electron mass (15) MeV/c^2
+FPC_m_P_MeV       = 938.27231          #proton mass (28) MeV/c^2
+FPC_m_P_u         = 1.00727647         #proton mass (12) u
+FPC_m_P_kg        = 1.6726231e-27      #proton mass (10) kg
+FPC_m_P_M_E       = 1836.152701        #proton mass (37) m_e
+FPC_m_D_MeV       = 1875.61339         #deuteron mass (57) MeV/c^2
+FPC_u_MeV         = 931.49432          #unified atomic mass unit (u) (28) MeV/c^2
+FPC_u_kg          = 1.6605402e-27      #unified atomic mass unit (u) (10) kg
+FPC_EPSILON_0     = 8.854187817e-12    #permittivity of free space F/m
+FPC_MU_0          = 1.2566370614e-06   #permeability of free space N/A^2
+FPC_ALPHA         = 0.0072973530796448 #fine-structure constant (61)
+FPC_r_e           = 2.81794092e-15     #classical electron radius (38) m
+FPC_LAMBDA_BAR_e  = 3.86159323e-13     #electron Compton wavelength (35) m
+FPC_a_0           = 5.29177249e-11     #Bohr radius (mnucleus= infty) (24) m
+FPC_LAMBDA_1EV    = 1.23984244e-06     #wavelength of 1 eV/c particle (37) m
+FPC_R_INFINITY_EV = 13.6056981         #Rydberg energy (mnucleus = infinity) (40) eV
+FPC_SIGMA_0_BARN  = 0.66524616         #Thomson cross section (18) barn
+FPC_MU_B_MeV_T    = 5.78838263e-11     #Bohr magneton (52)  MeV/T
+FPC_MU_N_MeV_T    = 3.15245166e-14     #nuclear magneton (28) MeV/T
+FPC_E_M_e         = 175881962000       #electron cyclotron freq./field (53) C/kg (rad/sT)
+FPC_E_M_P         = 95788309           #proton cyclotron freq./field (29) C/kg (rad/sT)
+FPC_G_SI          = 6.67259e-11        #gravitational constant (85) m^3/kgs^2
+FPC_G_P           = 6.70711e-39        #gravitational constant (86) h_bar c (GeV/c^2)^{-2}
+FPC_g             = 9.80665            #standard grav. accel., sea level m/s^2
+FPC_N_A           = 6.0221367e+23      #Avogadro constant (36)  /mole
+FPC_K_B           = 1.380658e-23       #Boltzmann constant (12) J/K
+FPC_K_B_EV        = 8.617385e-05       #Boltzmann constant (73) eV/K
+FPC_V_MOLAR       = 0.0224141          #molar volume, ideal gas at STP (19) m^3/mole
+FPC_LAMBDAT       = 0.002897756        #Wien displacement law constant (24) m K
+FPC_SIGMA_SB      = 5.67051e-08        #Stefan-Boltzmann constant (19) W/m^2K^4
+FPC_G_F           = 1.16639e-05        #Fermi coupling constant (2)  GeV^{-2}
+FPC_SIN2_THETA_W  = 0.23192            #weak mixing angle  (5)  at M_Z
+FPC_M_W           = 80.22              #W boson mass (26) GeV/c^2
+FPC_M_Z0          = 91.187             #Z_0 boson mass (7) GeV/c^2
+FPC_G_S           = 0.117              #strong coupling constant (5))  at M_Z
+AUCHARGE          = 1.60217733e-19     #1 a.u. charge in SI, elementary charge
+AUMASS            = 9.1093897e-31      #1 a.u. mass in SI, electron rest mass
+AUENERGY          = 4.3597482e-18      #1 a.u. energy in SI, hartree energy
+AULENGTH          = 5.29177249e-11     #1 a.u. length in SI, bohrradius
+AUACTION          = 1.05457266e-34     #1 a.u. action in SI, Planck constant/(2*PI)
+AUTIME            = 2.4188843341e-17   #1 a.u. time in SI
+AUFORCE           = 8.2387295e-08      #1 a.u. force in  SI
+AUVELOCITY        = 2187691.42         #1 a.u. velocity in SI
+AUMOMENTUM        = 1.9928534e-34      #1 a.u. momentum in SI
+AUEFIELD          = 514220820000       #1 a.u. el. field in SI
+AUEDIPOLE         = 8.4783579e-30      #1 a.u. el. dipole in SI
+AUMFLUX           = 235051.808         #1 a.u. magn. flux in SI
+AUMDIPOLE         = 1.85480308e-23     #1 a.u. magn. flux in  SI
+ELECTRONVOLT      = 1.60217733e-19     #1 eV charge in SI
+ATOMICMASS        = 1.6605402e-27      #1 amu mass in SI
+ASTRONOMICALUNIT  = 149597870000       #1 AE length in SI
+MOL               = 6.0221367e+23      #Avogadro constant
+au2an             = 0.529177249        #[a.u.] -> [Angstroem]
+an2au             = 1.8897259885789    #[Angstroem] -> [a.u.]
+au2ev             = 27.211396131788    #[a.u.] -> [eV]
+ev2au             = 0.036749308824762  #[eV] -> [a.u.]
+au2am             = 0.00054857989586762#[a.u.] -> [atomar mass units]
+am2au             = 1822.8885300626    #[atomar mass units] -> [a.u.]
+au2fs             = 0.024188843341     #[a.u.] -> [fs]
+fs2au             = 41.341373206755    #[fs] -> [a.u.]
+ev2kc             = 23.05              #[eV] -> [kcal/mol]
+kc2ev             = 0.043364476254697  #[kcal/mol] -> [eV]
+au2kc             = 627.50431878767    #[a.u.] -> [kcal/mol]
+kc2au             = 0.0015936145299079 #[kcal/mol] -> [a.u.]
+au2ic             = 219474.7           #[au] -> [1/cm]
+ic2au             = 4.5563338279993e-06#[1/cm] -> [au]
+ev2ic             = 8065.54353         #[eV] -> [1/cm]
+ic2ev             = 0.0001239842047    #[1/cm] -> [eV]
+ev2kj             = 96.485             #[eV] -> [kJoule/mol]
+kj2ev             = 0.0103643          #[kJoule/mol] -> [eV]
+in2cm             = 2.54               #[inch] -> [cm]
+ft2m              = 0.3048             #[feet] -> [cm]
+yd2m              = 0.9144             #[yard] -> [cm]
+cm2in             = 0.39370078740157   #[inch] -> [cm]
+m2ft              = 3.2808398950131    #[feet] -> [cm]
+m2yd              = 1.0936132983377    #[yard] -> [cm]
+
+au2va             = 51.4220652         #[au of E-Field] -> [V/A]
+va2au             = 1.0/au2va          #[V/A] -> [au of E-Field]
+de2au             = 0.393430307        #[debye] -> [au of dipole]
+
+def wcm22va(I):
+    return 2.744e-7 * I**0.5
+
+def va2wcm2(E):
+    return (E/2.744e-7)**2
+
+# Dictionary of element names and atomic number:
+periodicTable = {
+        'H'  :  { 'atomic_number' : 1,
+                  'atomic_mass'   : 1.007825
+                },
+        'D'  :  { 'atomic_number' : 1,
+                  'atomic_mass'   : 2.0140
+                },
+        'He' :  { 'atomic_number' : 2,
+                  'atomic_mass'   : 4.00260         # He 4
+                },
+        'Li' :  { 'atomic_number' : 3,
+                  'atomic_mass'   : 7.016003        # Li 7
+                },
+        'Be' :  { 'atomic_number' : 4,
+                  'atomic_mass'   : 9.012182
+                },
+        'B'  :  { 'atomic_number' : 5,
+                  'atomic_mass'   : 11.009305       # Be 11
+                },
+        'C'  :  { 'atomic_number' : 6,
+                  'atomic_mass'   : 12.000000       # C 12
+                },
+        'N'  :  { 'atomic_number' : 7,
+                  'atomic_mass'   : 14.003074       # N 14
+                },
+        'O'  :  { 'atomic_number' : 8,
+                  'atomic_mass'   : 15.994915       # O 16
+                },
+        'F'  :  { 'atomic_number' : 9,
+                  'atomic_mass'   : 18.9984032
+                },
+        'Ne' :  { 'atomic_number' : 10,
+                  'atomic_mass'   : 19.992435       # Ne 20
+                },
+        'Na' :  { 'atomic_number' : 11,
+                  'atomic_mass'   : 22.989767       # Na 23 100% abundance/Nist
+                },
+        'S'  :  { 'atomic_number' : 16,
+                  'atomic_mass'   : 32.065          # Nist value
+                },
+        'I' :   { 'atomic_number' : 53,
+                  'atomic_mass'   : 126.904473      # NIST value
+                },
+        'Pb':   { 'atomic_number' : 82,
+                  'atomic_mass'   : 207.976627      # NIST value Pb 208
+                }
+        }
+
+
+def factor(unit,unit_type):
+    if unit == 'au':
+        return 1.0
+    if unit_type == 'energy' and unit == 'cm-1':
+        return ic2au
+    if unit_type == 'energy' and unit == 'ic':
+        return ic2au
+    if unit_type == 'energy' and unit == 'ev':
+        return ev2au
+    if unit_type == 'time' and unit == 'fs':
+        return fs2au
+    if unit_type == 'time' and unit == 'ps':
+        return fs2au*1.0e3
+    if unit_type == 'efield' and unit == 'va':
+        return va2au
+    raise ValueError('Conversion of '+unit_type+' from '+unit+' not available')
+
+
+def numval(inpline,unit_type):
+    """
+    Return numeric value of input parameter in atomic units
+
+    Input:
+        inpline -- list ['value','unit']
+        unit_type -- 'energy', 'time',...
+
+    It also accepts ['value'], then au are assumed
+    """
+    if len(inpline) == 2:
+        return factor(inpline[1],unit_type) * float( inpline[0] )
+    elif len(inpline) == 1:
+        return float( inpline[0] )
+    else:
+        raise ValueError
+
+
+def filterNum(line):
+    """
+    Filter a line of numbers and look for occurrences of the exponential
+    Fortran format, e.g. -3.45432345-324, which does not contain the E sign for
+    the exponential, and add it.
+    """
+    pass
+
+
+

quadlib/tools/iterators.py

@@ -0,0 +1,276 @@
+# QuaDLib: QUAntum Dynamics LIBrary for research and methods development
+# Copyright (C) 2018-2026, The Theoretical Chemistry Group, Heidelberg University
+#
+# This software is licensed under the MIT License (https://spdx.org/licenses/MIT.html)
+
+import numpy as np
+
+
+class MultiCounter:
+    """Emulate the behaviour of multiple nested do loops
+
+    Maintains a list of integers that evolve as the indexes
+    of a nested "for" loop.
+    It may be useful to construct nested "for" loops from which
+    the number of nested elements is not known at programming time,
+    but at execution time.
+    """
+
+    def __init__(self,length=1,maxiter=1):
+        self.pointers=[]
+        self.ini_pointers=[]
+        self.limits=[]
+        self.ini_limits=[]
+        self.start=True
+        self.end=False
+        self.setPointersN(0,length)
+        self.setLimitsN(maxiter,length)
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        """Increase the pointers vector and return it
+        """
+        if self.start:
+            self.start = False
+            return self.getPointers()
+        else:
+            self.increase()
+            return self.getPointers()
+
+    def setPointers(self,p):
+        """set the list of initial pointers from a given list
+        """
+        self.pointers=[]
+        self.ini_pointers=[]
+        for n in p:
+            self.pointers.append(n)
+            self.ini_pointers.append(n)
+
+    def setPointersN(self,n=0,nd=1):
+        """set the list of initial pointers to a given number N
+        n -- number at which the pointers are set
+        nd -- length of the vector
+        """
+        self.pointers=[]
+        self.ini_pointers=[]
+        for _ in range(nd):
+            self.pointers.append(n)
+            self.ini_pointers.append(n)
+
+    def setLimits(self,l):
+        """set the list of index limits from a given list
+        """
+        self.limits=[]
+        self.ini_limits=[]
+        for n in l:
+            self.limits.append(n)
+            self.ini_limits.append(n)
+
+    def setLimitsN(self,n=0,nd=1):
+        """set the list of initial limits to a given number N
+        n -- number at which the pointers are set
+        nd -- length of the vector
+        """
+        self.limits=[]
+        for _ in range(nd):
+            self.limits.append(n)
+            self.ini_limits.append(n)
+
+    def setMaxIter(self,l):
+        """set the list of maximum iterations per index
+        """
+        self.limits=[]
+        self.ini_limits=[]
+        for n in l:
+            self.limits.append(n-1)
+            self.ini_limits.append(n-1)
+
+    def setMaxIterN(self,n=1,nd=1):
+        """set the list of initial limits to a given number N
+        n -- number at which the pointers are set
+        nd -- length of the vector
+        """
+        self.limits=[]
+        self.ini_limits=[]
+        for _ in range(nd):
+            self.limits.append(n-1)
+            self.ini_limits.append(n-1)
+
+    def getPointers(self):
+        """return the list of pointers
+        """
+        return tuple(self.pointers)
+
+    def getLimits(self):
+        """return the list of limits
+        """
+        return tuple(self.limits)
+
+    def reset(self):
+        """reset the iterator to the initial state
+        """
+        self.start=True
+        self.end=False
+        for i in range(len(self.pointers)):
+            self.pointers[i] = self.ini_pointers[i]
+            self.limits[i] = self.ini_limits[i]
+
+    def increase(self):
+        """increase the list of pointers
+        return 0 if the end is reached
+        return 1 if succeed
+        """
+        _increase(self.pointers,self.limits,self.end)
+
+
+class MultiCombination:
+    """
+    Iterate over all possible combinations of n indices taken in groups of m
+    """
+    def __init__(self,n,m):
+        self.n = n
+        self.m = m
+        self.mm = m
+        self.ind = np.zeros((m),int)
+        self.min = np.zeros((m),int)
+        self.max = np.zeros((m),int)
+        for k in range(m):
+            self.ind[k] = k
+            self.min[k] = k
+            self.max[k] = n - m + k
+        if m > 0:
+            self.ind[-1] = self.ind[-1] - 1
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if (self.ind==self.max).all():
+            raise StopIteration
+        k = self.m - 1
+        while(self.ind[k] == self.max[k]):
+            k = k - 1
+        self.ind[k] += 1
+        for kk in range(k+1,self.m):
+            self.ind[kk] = self.ind[kk-1] + 1
+        return self.ind
+
+
+def _increase(p,l,end):
+    for i in range(len(p)):
+        if i == len(p)-1:
+            if p[i] == l[i]:
+                raise StopIteration
+        if p[i] < l[i]:
+            p[i] = p[i]+1
+            break
+        else:
+            p[i] = 0
+
+
+def decreaseTuple(t):
+    """Decrease in 1 the value at every position of a tuple
+    """
+    l = list(t)
+    for i in range(len(l)):
+        l[i]=l[i]-1
+    return tuple(l)
+
+def mapTuple(t1,t2):
+    """Return a new tuple with the elements of t1 mapped at the positions
+       specified in t2
+    """
+    l=[]
+    for i in t2:
+        l.append(t1[i])
+    return tuple(l)
+
+
+
+#def excitations(x,m):
+#   """
+#   Generate excitation indices for x degrees of freedom up to m quanta
+
+#   x -- integer, number of degrees of freedom
+#   m -- integer, maximum quanta of excitation
+#   returns an interator object.
+#   """
+#   if isinstance(x,int):
+#       ref = np.ones(x,int)
+#       yield ref
+#   else:
+#       ref = x
+#   if ref.sum() - len(ref) == m: return
+#   # make excitations
+#   exclist = []
+#   for i in range(len(ref)):
+#       exc = ref.copy()
+#       exc[i] = exc[i] + 1
+#       exclist.append(exc)
+#       yield exc
+#   for exc in exclist:
+#       for exc2 in excitations(exc,m):
+#           yield exc2
+
+
+def excitations(x,m,n=None,r=None):
+    """
+    Generate excitation indices for x degrees of freedom up to m quanta
+
+    x -- integer, number of degrees of freedom
+    m -- integer, maximum quanta of excitation
+    ----
+    n -- tuple with maximum states per DOF (max states = max quanta + 1)
+    r -- reference tuple passed recursively
+    returns an interator object.
+    """
+    if r is None:
+        ref = _zeroTuple(x)
+        yield ref
+    else:
+        ref = r
+    if _sumTuple(ref) == m: return
+    # make excitations
+    excdict = {}
+    for i in range(x):
+        exc = list(ref)
+        if n is None:
+            exc[i] += 1
+        elif exc[i] < n[i] - 1:
+            exc[i] += 1
+        else:
+            continue
+        texc = tuple(exc)
+        excdict[texc] = 0
+        yield texc
+    for exc in list(excdict.keys()):
+        for exc2 in excitations(x,m,n,exc):
+            if exc2 not in excdict:
+                excdict[exc2] = 0
+                yield exc2
+
+
+def excitationsN(x,m,n=None):
+    """
+    Generate excitations exactly of m quanta for x degrees of freedom
+
+    x -- integer, number of degrees of freedom
+    m -- integer, exact quanta of excitation
+    ----
+    n -- tuple with maximum states per DOF (max states = max quanta + 1)
+    """
+    for e in excitations(x,m,n):
+        if _sumTuple(e) == m: yield e
+
+
+
+def _sumTuple(t):
+    s = 0
+    for e in t: s = s + e
+    return s
+
+def _zeroTuple(l):
+    z = np.zeros(l,int)
+    return tuple(z)