ensembler.analysis package

Submodules

ensembler.analysis.freeEnergyCalculation module

Free Energy Calculations:

This module contains functions for free energy calculations author: Gerhard König, Benjamin Schroeder

class ensembler.analysis.freeEnergyCalculation.bar(C: float = 0.0, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False, convergence_radius: float = 1e-05, max_iterations: int = 500, min_iterations: int = 1)

Bases: ensembler.analysis.freeEnergyCalculation.bennetAcceptanceRatio

convergence_radius: float

max_iterations: int

min_iterations: int

class ensembler.analysis.freeEnergyCalculation.bennetAcceptanceRatio(C: float = 0.0, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False, convergence_radius: float = 1e-05, max_iterations: int = 500, min_iterations: int = 1)

Bases: ensembler.analysis.freeEnergyCalculation._FreeEnergyCalculator

This class implements the BAR method. $dF = -

rac{1}{eta} * ln( rac{flangle(V_j-V_i+C) angle_i}{flangle(V_i-V_j-C) angle_j})+C$

with : $ f(x) =

rac{1}{1+e^(eta x)}$ - fermi function

C = C

T = T

Vi_i = Vi_i

Vi_j = Vi_j

Vj_i = Vj_i

Vj_j = Vj_j

__init__(C: float = 0.0, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False, convergence_radius: float = 1e-05, max_iterations: int = 500, min_iterations: int = 1)

Here you can set Class wide the parameters T and k for the bennet acceptance ration (BAR) Equation

Parameters

• C (float, optional) – is the initial guess of the free Energy.

• T (float, optional) – Temperature in Kelvin, defaults to 398

• k (float, optional) – boltzmann Constant, defaults to const.k*const.Avogadro

• kT (bool, optional) – overwrites T and k to set all results in units of $k_bT$

• kJ (bool, optional) – overwrites k to get the Boltzman constant with units kJ/(mol*K)

• kCal (bool, optional) – overwrites k to get the Boltzman constant with units kcal/(mol*K)

• convergence_radius (float, optional) – when is the result converged? if the deviation of one to another iteration is below the convergence radius.

• max_iterations (int, optional) – maximal number of iterations.

• min_iterations (int, optional) – minimal number of iterations

_calc_bar(C: numbers.Number, Vj_i: numpy.array, Vi_i: numpy.array, Vi_j: numpy.array, Vj_j: numpy.array) → numbers.Number

_calc_bar

this function is calculating the free energy difference of two states for one iteration of the BAR method.

It is implemented straight forwad, but therefore not very numerical stable.

Parameters

• Vi_i (np.array) – potential energies of stateI while sampling stateI

• Vj_i (np.array) – potential energies of stateJ while sampling stateI

• Vi_j (np.array) – potential energies of stateI while sampling stateJ

• Vj_j (np.array) – potential energies of stateJ while sampling stateJ

Returns

free energy difference

Return type

float

_calc_bar_mpmath(C: numbers.Number, Vj_i: numpy.array, Vi_i: numpy.array, Vi_j: numpy.array, Vj_j: numpy.array) → numbers.Number

_calc_bar

this function is calculating the free energy difference of two states for one iteration of the BAR method.

It is implemented straight forwad, but therefore not very numerical stable.

Parameters

• Vi_i (np.array) – potential energies of stateI while sampling stateI

• Vj_i (np.array) – potential energies of stateJ while sampling stateI

• Vi_j (np.array) – potential energies of stateI while sampling stateJ

• Vj_j (np.array) – potential energies of stateJ while sampling stateJ

Returns

free energy difference

Return type

float

_calculate_optimize(Vi_i: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vj_i: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vi_j: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vj_j: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), C0: float = 0, verbose: bool = False) → float

this function is calculating the free energy difference of two states with the BAR method.

it iterates over the _calc_bar method and determines the convergence and the result.

Parameters

• Vi_i (np.array) – potential energies of stateI while sampling stateI

• Vj_i (np.array) – potential energies of stateJ while sampling stateI

• Vi_j (np.array) – potential energies of stateI while sampling stateJ

• Vj_j (np.array) – potential energies of stateJ while sampling stateJ

Returns

free energy difference

Return type

float

beta = beta

calculate(Vi_i: Iterable[numbers.Number], Vj_i: Iterable[numbers.Number], Vi_j: Iterable[numbers.Number], Vj_j: Iterable[numbers.Number], verbose: bool = False) → float

calculate

this function is calculating the free energy difference of two states with the BAR method.

Parameters

• Vi_i (np.array) – potential energies of stateI while sampling stateI

• Vj_i (np.array) – potential energies of stateJ while sampling stateI

• Vi_j (np.array) – potential energies of stateI while sampling stateJ

• Vj_j (np.array) – potential energies of stateJ while sampling stateJ

Returns

free energy difference

Return type

float

constants: dict = {T: 298, k: 8.31446261815324, C: <class 'numbers.Number'>}

convergence_radius: float

equation: sympy.core.function.Function = (-log(exp((C - Vi_i + Vj_i)/(T*k))) + log(exp((C + Vi_j - Vj_j)/(T*k))))/(T*k)

k = k

max_iterations: int

min_iterations: int

set_parameters(C: float = None, T: float = None, k: float = None)

set_parameters setter for the parameters T and k

Parameters

• T (float, optional) – Temperature in Kelvin, defaults to 398

• k (float, optional) – boltzmann Constant, defaults to const.k*const.Avogadro

• C (float, optional) – C is the initial guess of the free energy difference.

class ensembler.analysis.freeEnergyCalculation.dfEDS(kCal: bool = False, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False)

Bases: ensembler.analysis.freeEnergyCalculation.threeStateZwanzig

class ensembler.analysis.freeEnergyCalculation.threeStateZwanzig(kCal: bool = False, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False)

Bases: ensembler.analysis.freeEnergyCalculation.zwanzigEquation

this class provides the implementation for the Free energy calculation with EDS. It calculates the free energy via the reference state.

$dF = dF_{BR}-dF_{AR} =

rac{1}{eta} * ( ln(langle e^{-eta * (V_j-V_R)} angle) - ln(langle e^{-eta * (V_i-V_R)} angle))$

T = T

Vi = Vi

Vj = Vj

Vr = Vr

__init__(kCal: bool = False, T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False)

this class provides the implementation for the Free energy calculation with EDS.

It calculates the free energy via the reference state.

Parameters

• T (float, optional) – Temperature in Kelvin, defaults to 398

• k (float, optional) – boltzmann Constant, defaults to const.k*const.Avogadro

• kT (bool, optional) – overwrites T and k to set all results in units of $k_bT$

• kJ (bool, optional) – overwrites k to get the Boltzman constant with units kJ/(mol*K)

• kCal (bool, optional) – overwrites k to get the Boltzman constant with units kcal/(mol*K)

_calculate_implementation_useZwanzig(Vi: (typing.Iterable, <class 'numbers.Number'>), Vj: (typing.Iterable, <class 'numbers.Number'>), Vr: (typing.Iterable[numbers.Number], <class 'numbers.Number'>)) → float

calculate

this method calculates the zwanzig equation via the intermediate reference state R using the Zwanzig equation. it directly accesses the zwanzig implmentation.

Parameters

• Vi (np.array) – the potential energy of stateI while sampling stateR

• Vj (np.array) – the potential energy of stateJ while sampling stateR

• Vr (np.array) – the potential energy of stateR while sampling stateR

Returns

free energy difference

Return type

float

calculate(Vi: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vj: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vr: (typing.Iterable[numbers.Number], <class 'numbers.Number'>)) → float

calculate

this method calculates the zwanzig equation via the intermediate reference state R using the Zwanzig equation.

Parameters

• Vi (np.array) – the potential energy of stateI while sampling stateR

• Vj (np.array) – the potential energy of stateJ while sampling stateR

• Vr (np.array) – the potential energy of stateR while sampling stateR

Returns

free energy difference

Return type

float

equation: sympy.core.function.Function = -(log(exp(-(Vi - Vr)/(T*k))) - log(exp(-(Vj - Vr)/(T*k))))/(T*k)

k = k

class ensembler.analysis.freeEnergyCalculation.zwanzig(T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False)

Bases: ensembler.analysis.freeEnergyCalculation.zwanzigEquation

constants: dict

class ensembler.analysis.freeEnergyCalculation.zwanzigEquation(T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False)

Bases: ensembler.analysis.freeEnergyCalculation._FreeEnergyCalculator

Zwanzig Equation

This class is a nice wrapper for the zwanzig Equation.

dF = - eta ln(langle e^(-beta(V_j-V_i))

angle)

T = T

Vi = Vi

Vj = Vj

__init__(T: float = 298, k: float = 8.31446261815324, kT: bool = False, kJ: bool = False, kCal: bool = False)

Here you can set Class wide the parameters T and k for the Zwanzig Equation

Parameters

• T (float, optional) – Temperature in Kelvin, defaults to 398

• k (float, optional) – boltzmann Constant, defaults to const.k*const.Avogadro

• kT (bool, optional) – overwrites T and k to set all results in units of $k_bT$

• kJ (bool, optional) – overwrites k to get the Boltzman constant with units kJ/(mol*K)

• kCal (bool, optional) – overwrites k to get the Boltzman constant with units kcal/(mol*K)

_calculate_efficient(Vi: (typing.Iterable, <class 'numbers.Number'>), Vj: (typing.Iterable, <class 'numbers.Number'>)) → float

_calculate_efficient

Calculate a free energy difference with the Zwanzig equation (aka exponential formula or thermodynamic perturbation). The initial state of the free energy difference is denoted as 0, the final state is called 1. The function expects two arrays of size n with potential energies. The first array, u00, contains the potential energies of a set of Boltzmann-weighted conformations of an MD or MC trajectory of the initial state, analyzed with the Hamiltonian of the initial state. The second array, u01 , contains the potential energies of a trajectory of the initial state that was analyzed with the potential energy function of the final state. The variable kT expects the product of the Boltzmann constant with the temperature that was used to generate the trajectory in the respective units of the potential energies.

This is an efficient more overflow robust implementation of the Zwanzig Equation.

@Author: Gerhard König See Zwanzig, R. W. J. Chem. Phys. 1954, 22, 1420-1426. doi:10.1063/1.1740409

$dF =

rac{1}{eta} * ln(langlee^{-eta * (V_j-V_i)} angle)$

Vinp.array

Potential energies of state I

Vjnp.array

Potential energies of state J

float

free energy difference

_calculate_implementation_bruteForce(Vi: (typing.Iterable, <class 'numbers.Number'>), Vj: (typing.Iterable, <class 'numbers.Number'>)) → float

_calculate_implementation_bruteForce

This is a plain implementation of the zwanzig equation. It is not very numerical robust

Parameters

• Vi

• Vj

Parameters

• Vi (np.array) – Potential energies of state I

• Vj (np.array) – Potential energies of state J

Returns

free energy difference

Return type

float

_calculate_meanEfficient(Vi: (typing.Iterable, <class 'numbers.Number'>), Vj: (typing.Iterable, <class 'numbers.Number'>)) → float

Calculate a free energy difference with the Zwanzig equation (aka exponential formula or thermodynamic perturbation). The initial state of the free energy difference is denoted as 0, the final state is called 1. The function expects two arrays of size n with potential energies. The first array, u00, contains the potential energies of a set of Boltzmann-weighted conformations of an MD or MC trajectory of the initial state, analyzed with the Hamiltonian of the initial state. The second array, u01 , contains the potential energies of a trajectory of the initial state that was analyzed with the potential energy function of the final state. The variable kT expects the product of the Boltzmann constant with the temperature that was used to generate the trajectory in the respective units of the potential energies.

This is an efficient more overflow robust implementation of the Zwanzig Equation.

@Author: Gerhard König See Zwanzig, R. W. J. Chem. Phys. 1954, 22, 1420-1426. doi:10.1063/1.1740409

_calculate_implementation_bruteForce

This is a plain implementation of the zwanzig equation. It is not very numerical robust

Parameters

• Vi (np.array) – Potential energies of state I

• Vj (np.array) – Potential energies of state J

Returns

free energy difference

Return type

float

_calculate_mpmath(Vi: (typing.Iterable, <class 'numbers.Number'>), Vj: (typing.Iterable, <class 'numbers.Number'>)) → float

implementation of zwanzig with mpmath package, another way of having a robust variant, but this one is very close to the initial equation thanks to the mpmath package.

$dF =

rac{1}{eta} * ln(langlee^{-eta * (V_j-V_i)} angle)$

Vinp.array

Potential energies of state I

Vjnp.array

Potential energies of state J

float

free energy difference

calculate(Vi: (typing.Iterable[numbers.Number], <class 'numbers.Number'>), Vj: (typing.Iterable[numbers.Number], <class 'numbers.Number'>)) → float

zwanzig

Calculate a free energy difference with the Zwanzig equation (aka exponential formula or thermodynamic perturbation). The initial state of the free energy difference is denoted as 0, the final state is called 1. The function expects two arrays of size n with potential energies. The first array, u00, contains the potential energies of a set of Boltzmann-weighted conformations of an MD or MC trajectory of the initial state, analyzed with the Hamiltonian of the initial state. The second array, u01 , contains the potential energies of a trajectory of the initial state that was analyzed with the potential energy function of the final state. The variable kT expects the product of the Boltzmann constant with the temperature that was used to generate the trajectory in the respective units of the potential energies.

See Zwanzig, R. W. J. Chem. Phys. 1954, 22, 1420-1426. doi:10.1063/1.1740409

Parameters

• Vi (np.array) – Potential energies of state I

• Vj (np.array) – Potential energies of state J

Returns

free energy difference

Return type

float

constants: dict

equation: sympy.core.function.Function = -log(exp(-(-Vi + Vj)/(T*k)))/(T*k)

k = k

set_parameters(T: float = None, k: float = None)

set_parameters setter for the parameters T and k

Parameters

• T (float, optional) – Temperature in Kelvin, defaults to 398

• k (float, optional) – boltzmann Constant, defaults to const.k*const.Avogadro

Module contents

Tools to do analysis of ensembler simulations (e.g. free energy calculations)