vibrav.numerical.boltzmann module

vibrav.numerical.boltzmann.boltz_dist(energies, temp, tol=1e-06, states=None, ignore_max=False)[source]

Generate the vibrational boltzmann distributions for all vibrational frequencies up to when the distribution is less than the given tolerance value.

Note

This does not take into account any energetic degeneracies of the input energies/states and the primary purpose is to calculate the Boltzmann distribution of vibrational states.

Parameters:

  • energies (numpy.ndarray or list) – Array of energies in wavenumbers.

  • temp (float) – Temperature to calculate the distribution.

  • tol (float, optional) – Tolerance threshold to cutoff the calculation of the distribution factors. Defaults to 1e-5.

  • states (int, optional) – Number of states to calculate. Defaults to None (all states with a distribution less than the tol value for the lowest frequency).

  • ignore_max (bool, optional) – Ignore the default matimum number of max states to be calculated. This is very dangerous use at your own risk. There is a possibility of hitting the recursion limit in python. Defaults to False.

Returns:

boltz (pandas.DataFrame) – Data frame of the boltzmann factors for each energy.

Raises:

  • ValueError – If the states parameter given is more than 1000 as we consider this to be unphysical.

  • ValueError – If the states parameter is zero.

  • ValueError – If the temp paramter is less than or equal to zero.

  • ValueError – If the program calculates more than 1000 states at a given tolerance.

Examples

Calculating the boltzmann distribution of a two state system at room temperature (298 K) with the energies 10, 20 and 80 wavenumbers (cm \(^{-1}\)).

>>> temp = 298
>>> freq = [10, 20, 80]
>>> boltz_dist(energies=freq, temp=temp, states=2)
          0         1  freqdx  partition  energy
0  0.512068  0.487932       0   1.952866      10
1  0.524122  0.475878       1   1.907953      20
2  0.595379  0.404621       2   1.679601      80

It is not necessary that the input energies be ordered as shown by the next example. The only thing that will change is that the output pandas.DataFrame will have a freqdx column that will reflect the ordeting of the input energies.

>>> temp = 298
>>> freq = [10, 80, 20]
>>> boltz_dist(energies=freq, temp=temp, states=2)
          0         1  freqdx  partition  energy
0  0.512068  0.487932       0   1.952866      10
1  0.524122  0.475878       2   1.907953      20
2  0.595379  0.404621       1   1.679601      80

These examples have truncated the number of states to actually calculate by a user defined value. If the user is interested in getting all of the available states above a given threshold, 1e-6 by default, this can be done by passing the states parameter as None.

>>> temp = 40
>>> freq = [100, 200, 300]
>>> boltz_dist(energies=freq, temp=temp, states=None)
          0         1             2        3  freqdx  partition  energy
0  0.972593  0.026656  7.305767e-04  0.00002       0   1.028179     100
1  0.999249  0.000751  5.638231e-07  0.00000       1   1.000752     200
2  0.999979  0.000021  0.000000e+00  0.00000       2   1.000021     300

Notice, that in the example above, the threshold is only applied to the lowest energy and all higher energies calculate the same number of states even when the threshold is already met. This is purely done for the sake of simplifying data storage in a later step with the numpy.stack() function. It is not believed that this will affect memory usage or performance greatly.

The program is designed to detect if there are more than 1000 states calculated and automatically throw an error as this is an unphysical number of states to calculate.