ThermoDynamics – Reference Guide

This guide is for versions 1.0.0rc.8+ (Release Candidate)

Source code

Class ThermoDynamics

    Manage the Thermodynamics aspects of reactions:
    changes in Gibbs Free Energy, Enthalpy, Entropy - and how
    they relate to equilibrium constant, at a given temperature.

    This class does NOT get instantiated.

    UNITS internally used (same as the DEFAULT units for the function calls):
        Temperature:    degree K
        Energy:         kJ              <- NOTE the divergence from SI units, for familiarity of convention
        Molar energy:   kJ/mol
        Molar entropy:  Joules/(mol·K)  <- NOTE : Joules, NOT kJ, for the entropy!

    USING ALTERNATE UNITS:
        We're *beginning* to phase in the units.py module.
        Some - but not yet all - functions now accept arguments such as temp=(25, C)

    ENTITIES:
            "K"       (equilibrium constant - from thermodynamic data)
            "delta_H" (change in Enthalpy: Enthalpy of Products - Enthalpy of Reactants)
            "delta_S" (change in Entropy)
            "delta_G" (change in Gibbs Free Energy)

            No correction is made for the temperature dependency of delta_H
    
nameargumentsreturns
equilibrium_constant_from_gibbs_energydelta_G :float, temp :float|tuplefloat
        Compute a reaction's equilibrium constant from its change in Gibbs Free Energy,
        at the specified temperature

        :param delta_G: Change in Gibbs Free Energy (from reactants to products), in kJ/mol
        :param temp:    In degrees Kelvin, or in pair format such as (25, C)
        :return:        The reaction's equilibrium constant
        
nameargumentsreturns
gibbs_energy_from_equilibrium_constantK :float, temp :float|tuplefloat
        Compute a reaction's change in its Gibbs Free Energy from its equilibrium constant,
        at the specified temperature

        :param K:       The reaction's equilibrium constant
        :param temp:    In degrees Kelvin, or in pair format such as (25, C)
        :return:        The reaction's change in Gibbs Free Energy (from reactants to products),
                            in kJ/mol
        
nameargumentsreturns
gibbs_energy_from_enthalpy_entropydelta_H, delta_S, tempfloat
        Compute the change in Gibbs Free Energy, from Enthalpy and Entropy changes,
        at the specified temperature

        :param delta_H: The reaction's change in Enthalpy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules
        :param delta_S: The reaction's change in Entropy (from reactants to products),
                            in Joules/(mol·K)   NOTE it's Joules, NOT kJ
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Free Energy (from reactants to products),
                            in kJ/mol
        
nameargumentsreturns
enthalpy_from_gibbs_energydelta_G, delta_S, tempfloat
        Compute the change in Enthalpy, from changes in Gibbs Free Energy and in Entropy,
        at the specified temperature

        :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules
        :param delta_S: The reaction's change in Entropy (from reactants to products),
                            in Joules/(mol·K)   NOTE it's Joules, NOT kJ
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Enthalpy (from reactants to products),
                            in kJ/mol
        
nameargumentsreturns
entropy_from_gibbs_energydelta_G, delta_H, tempfloat
        Compute the change in Entropy, from  changes in the Gibbs Free Energy and in Enthalpy,
        at the specified temperature

        :param delta_G: The reaction's change in Gibbs Free Energy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules
        :param delta_H: The reaction's change in Enthalpy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules
        :param temp:    System's temperature, in degree Kelvins
        :return:        The reaction's change in Entropy (from reactants to products),
                            in J mol-1 K-1      NOTE it's Joules, NOT kJ
        
nameargumentsreturns
extract_thermodynamic_datatemp, K=None, delta_H=None, delta_S=None, delta_G=Nonedict
        Given the system temperature, and any combination of thermodynamic data,
        verify the consistency of the given data,
        derive whatever is missing and can be derived

        :param temp:    System's temperature, in degree Kelvins
        :param K:       [OPTIONAL] The reaction's equilibrium constant
        :param delta_H: [OPTIONAL] The reaction's change in Enthalpy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules
        :param delta_S: [OPTIONAL] The reaction's change in Entropy (from reactants to products),
                            in J mol-1 K-1      NOTE it's Joules, NOT kJ
        :param delta_G: [OPTIONAL] The reaction's change in Gibbs Free Energy (from reactants to products),
                            in kJ/mol           NOTE it's KILO-Joules

        :return:        A dict with the 4 keys  "K", "delta_H", "delta_S", "delta_G";
                            any value that wasn't passed, or derivable from the others, will be None
        
nameargumentsreturns
relative_population_statesdelta_molar_energy :float|tuple, temp :float|tuple
        In the presence of two states with respective energies eps_i and eps_j 
        (given our knowledge of eps_j-eps_i),
        use the Boltzmann distribution to determine the ratio of the populations of those state, N_i/N_j

        EXAMPLE: the second state is 6 kJ/mol lower than the first state;
                 at temp=25 C, the ratio of the populations of the 1st state and the 2nd one is
                    relative_population_states(delta_molar_energy=-6, temp=25)

        :param delta_molar_energy:  Molar energy change from state 1 to state 2 (e.g. E2 - E1)
                                        In kJ/mol, or in pair format such as (5000, J_PER_MOL)
        :param temp:                In degrees Kelvin, or in pair format such as (25, C)
        :return:                    Ratio of the populations of the first state over that of the second one