waterEntropy.entropy package

Submodules

waterEntropy.entropy.convariances module

Store the rotated mass-weighted forces and inertia-weighted torques in this class.

class waterEntropy.entropy.convariances.CovarianceCollection[source]

Bases: object

Class for covariance matrices molecules, grouped by what their closest non-like molecule is.

__dict__ = mappingproxy({'__module__': 'waterEntropy.entropy.convariances', '__firstlineno__': 10, '__doc__': '\nClass for covariance matrices molecules, grouped by what their closest\nnon-like molecule is.\n', '__init__': <function CovarianceCollection.__init__>, 'add_data': <function CovarianceCollection.add_data>, 'populate_dicts': <function CovarianceCollection.populate_dicts>, 'update_counts': <function CovarianceCollection.update_counts>, 'merge': <function CovarianceCollection.merge>, '__static_attributes__': ('counts', 'forces', 'torques'), '__dict__': <attribute '__dict__' of 'CovarianceCollection' objects>, '__weakref__': <attribute '__weakref__' of 'CovarianceCollection' objects>, '__annotations__': {}})
__firstlineno__ = 10
__init__()[source]
__module__ = 'waterEntropy.entropy.convariances'
__static_attributes__ = ('counts', 'forces', 'torques')
__weakref__

list of weak references to the object

add_data(nearest, molecule_name: str, force: ndarray, torque: ndarray)[source]

Add force, torque covariances to the class dictionaries

Parameters:

  • nearest – the value for grouping molecules into a class. e.g. the name of the nearest molecule

  • molecule_name – the name of the molecule being populated into the dictionaries

  • force – array of the mass-weighted forces of the molecule

  • torque – array of the inertia-weighted torques of the molecule

merge(other)[source]

Merge another CovarianceCollection into this one.

Parameters:

other – another CovarianceCollection to merge

populate_dicts(nearest, molecule_name, variable, variable_dict, count_dict)[source]

For a given molecule, append the summed, weighted and rotated forces, and the torques for the whole molecule. Add as a running average by keeping count of the number of molecules added.

Parameters:

  • self – class instance

  • nearest – the value for grouping molecules into a class. e.g. the name of the nearest molecule

  • molecule_name – name of molecule

  • variable – variable to update a dict

  • variable_dict – the dictionary where updated variables are added

  • count_dict – the dictionary where counts are updated

update_counts(nearest, molecule_name, count_dict)[source]

Update the counts in dictionary

Parameters:

  • nearest – the value for grouping molecules into a class. e.g. the name of the nearest molecule

  • molecule_name – name of molecule

  • count_dict – the dictionary where counts are updated

waterEntropy.entropy.orientations module

Store orientational entropies here

class waterEntropy.entropy.orientations.Orientations[source]

Bases: object

Store orientational entropies here

__dict__ = mappingproxy({'__module__': 'waterEntropy.entropy.orientations', '__firstlineno__': 241, '__doc__': '\nStore orientational entropies here\n', '__init__': <function Orientations.__init__>, 'add_data': <function Orientations.add_data>, 'get_resid_orientational_entropy_from_dict': <function Orientations.get_resid_orientational_entropy_from_dict>, 'get_running_average': <function Orientations.get_running_average>, 'get_orientational_entropy_from_dict': <function Orientations.get_orientational_entropy_from_dict>, '__static_attributes__': ('resid_labelled_Sorient', 'resname_labelled_Sorient'), '__dict__': <attribute '__dict__' of 'Orientations' objects>, '__weakref__': <attribute '__weakref__' of 'Orientations' objects>, '__annotations__': {}})
__firstlineno__ = 241
__init__()[source]
__module__ = 'waterEntropy.entropy.orientations'
__static_attributes__ = ('resid_labelled_Sorient', 'resname_labelled_Sorient')
__weakref__

list of weak references to the object

add_data(hb_labels: <module 'waterEntropy.analysis.HB_labels' from '/home/docs/checkouts/readthedocs.org/user_builds/waterentropy/envs/stable/lib/python3.13/site-packages/waterEntropy/analysis/HB_labels.py'>)[source]

Add orientational entropy data

get_orientational_entropy_from_dict(labelled_dict: dict, Sorient_dict: dict)[source]

For a given dictionary containing labelled shells and HBing within the shell with format:

labelled_dict = {“resname”: {(“labelled_shell”): {“shell_count”: 0,

“N_w”: N_w, “donates_to”: {“labelled_donators”: 0,}, “accepts_from”: {“labelled_acceptors”: 0,} }}}

Get the orientational entropy of the molecules in this dict

Parameters:

labelled_dict – dictionary of format dict1 containing labelled coordination shells and HB donating and accepting

get_resid_orientational_entropy_from_dict(resid_labelled_dict: dict)[source]

For a given dictionary containing labelled shells and HBing within the shell with format:

resid_labelled_dict = {“nearest_resid”: {“resname”:

{(“labelled_shell”): {“shell_count”: 0, “N_w”: N_w, “donates_to”: {“labelled_donators”: 0,}, “accepts_from”: {“labelled_acceptors”: 0,} }}}

Get the orientational entropy of the molecules in this dict

Parameters:

resid_labelled_dict – dictionary of format dict2 containing labelled coordination shells and HB donating and accepting

get_running_average(value: float, count: int, running_average_value: float, count_stored: int)[source]

For a given value, get it’s running average from the current value

Parameters:

  • value – the value that needs to be added to the running average

  • count – the number of times the value occurs from statistics

  • running_average_value – the currently stored running average

  • count_stored – the currently stored count for the running average

class waterEntropy.entropy.orientations.WaterOrientCalculator[source]

Bases: object

Calculate orientational entropy of water molecules here

GAS_CONSTANT = 8.314
__dict__ = mappingproxy({'__module__': 'waterEntropy.entropy.orientations', '__firstlineno__': 14, '__doc__': 'Calculate orientational entropy of water molecules here', 'GAS_CONSTANT': 8.314, '__init__': <function WaterOrientCalculator.__init__>, 'add_data': <function WaterOrientCalculator.add_data>, 'get_non_HB_data': <function WaterOrientCalculator.get_non_HB_data>, 'get_shell_degeneracy': <function WaterOrientCalculator.get_shell_degeneracy>, 'get_donor_acceptor_probabilities': <function WaterOrientCalculator.get_donor_acceptor_probabilities>, 'get_reduced_neighbours_biases': <function WaterOrientCalculator.get_reduced_neighbours_biases>, 'get_orientation_S': <function WaterOrientCalculator.get_orientation_S>, 'get_hb_probability': <function WaterOrientCalculator.get_hb_probability>, '__static_attributes__': ('Nc_eff', 'Sorient', 'pbias_ave'), '__dict__': <attribute '__dict__' of 'WaterOrientCalculator' objects>, '__weakref__': <attribute '__weakref__' of 'WaterOrientCalculator' objects>, '__annotations__': {}})
__firstlineno__ = 14
__init__()[source]
__module__ = 'waterEntropy.entropy.orientations'
__static_attributes__ = ('Nc_eff', 'Sorient', 'pbias_ave')
__weakref__

list of weak references to the object

add_data(shell_label: list, shell_values: dict)[source]

Calculate the orientational entropy for water molecules with a specific shell type/environment.

Parameters:

  • shell_label – the list or tuple of the shell labels of a coordination shell

  • shell_values – the dictionary containing information about what neighbour types are donated to and accepted from

get_donor_acceptor_probabilities(HB_vals_dict: dict, hb_selection: str)[source]

For a given labelled shell type, find the probability of accepting from or donating to a given neighbour type over all other donors or acceptors

Parameters:

  • vals_dict – dictionary containing the HB donors or acceptors and how often they occur for a given neighbour in a shell e.g. {“donates_to”: {“labelled_donators”: 0,}, “accepts_from”: {“labelled_acceptors”: 0,}}

  • degeneracy – dictionary containing the counts for each neighbour type in a shell

  • hb_selection – string for determining which HB type to analyse, options are either “donates_to” or “accepts_from”

get_hb_probability(count: int, total_count: int)[source]

For a given HB donor/acceptor, find the probablity of that HB occurring in a given unique labelled shell over all the other acceptors or donors, so

\[pA_i = \frac{N_{i_A}}{\sum_i(N_{i_A})}\]

or

\[pD_i = \frac{N_{i_D}}{\sum_i(N_{i_D})}\]
Parameters:

  • count – number of HB donors/acceptors for a given neighbour type

  • total_count – total number of either acceptor or donor counts over all neighbour types

get_non_HB_data(Nc)[source]

Calculate water orientational entropies without accounting for HB biasing, using the following equation (as in the host-guest systems paper, https://doi.org/10.1007/s10822-021-00406-5):

\[S_\mathrm{orient} = \ln \Bigg(N_c ^ {(3 / 2)} imes \pi ^ {0.5} imes\]

rac{p_mathrm{corr}}{sigma} Bigg)

where \(N_{c}\) is the number of UAs in the coordination shell, \(p_\mathrm{corr}\) is the probability that the neighboring molecules are oriented suitably for each solute, which is set to 0.25 for water. And \(\sigma\) is the symmetry number for water which is 2.

get_orientation_S(Nc_eff: float, pbias_ave: float)[source]

Get the orientational entropy of water molecules, or any single UA molecule containing two hydrogen bond donors.

\[S_\mathrm{orient} = \ln \Bigg(N_{c_\mathrm{eff}} ^ {(3 / 2)} \times \pi ^ {0.5} \times \frac{p_\mathrm{bias\_ave}}{2} \Bigg)\]

This equation is modified from the previous theory of water molecule orientational entropy, where hydrogen bonding is accounted for by reducing the number of available neighbours. Here, the coordination shell neighbours available to hydrogen bond with are reduced to \(N_{c_\mathrm{eff}}\). The reduction in available HBing neighbours is calculated from statistics gathered from simulation trajectories, where neighbour types that are donated to or accepted from are counted.

\[N_{c_\mathrm{eff}} = \sum_i \bigg((ppD_i \times ppA_i) \times \frac{N_i}{0.25} \bigg)\]

where \(ppD_i\) is the probability to donate to a given neighbour type \(i\) compared to accepting from the same neighbour type. \(ppA_i\) is the equivalent probability for accepting from neighbour type \(i\).

\(p_\mathrm{bias\_ave}\) is the average bias in accepting from and donating to a given neighbour type \(i\). If it is equally likely to donate to and accept from all neighbour types, then \(p_\mathrm{bias\_ave}=0.25\), but if there is any bias in preferentially donating to, accepting from or not HBing to a neighbour at all, then \(p_\mathrm{bias\_ave} < 0.25\).

\[p_\mathrm{bias\_ave} = \frac{\sum_i(ppD_i * ppA_i)}{N_c}\]

Both \(N_{c_\mathrm{eff}}\) and \(p_\mathrm{bias\_ave}\) are used to reduce the orientational entropy of the central molecule by accounting for the HBing observed in a simulation.

Parameters:

  • Nc_eff – effective number of available neighbours to rotate around

  • pbias_ave – the average biasing in hydrogen bonding donating or accepting over all shell neighbours

get_reduced_neighbours_biases(degeneracy: dict, pD_dict: dict, pA_dict: dict)[source]

For a given labelled shell and the dictionary containing the counts for each neighbour type in the shell, the dictionaries for the acceptor and donator probabilities, use these to find the probability of accepting from or donating to over all other HBing to that particular neighbour type i:

\[ppD_i = \frac{pD_i}{(pD_i + pA_i)}\]
Parameters:

  • degeneracy – dictionary of shell constituent and count

  • pD_dict – dictionary of neighbours donated to and how often that occurs

  • pA_dict – dictionary of neighbours accepted from and how often that occurs

get_shell_degeneracy(shell_label: list)[source]

For a given labelled shell, find the degeneracy, i.e. count of each unique label in the shell

Parameters:

shell_label – the list or tuple of the shell labels of a coordination shell

waterEntropy.entropy.orientations.print_Sorient_dicts(Sorient_dict: dict)[source]

Print the orientational entropies of interfacial solvent

Parameters:

Sorient_dict – dictionary containing orientational entropy values

waterEntropy.entropy.vibrations module

Store vibrational entropy from covariance matrices

class waterEntropy.entropy.vibrations.Vibrations(temperature)[source]

Bases: object

Store molecule vibrational entropy information here, where

\[S^{\mathrm{vib}} = S^{\mathrm{trans}} + S^{\mathrm{rot}}\]

Entropies are calculated from the covariance matrices inputted in the add_data method.

ANGSTROM_TO_METRE = 1e-10
AVOGADRO = 6.022e+23
BOLTZMANN = 1.38064852e-23
CALORIE_TO_JOULE = 4184
GAS_CONSTANT = 8.314
HBAR = 1.0545718e-34
KG_TO_AMU = 6.02214086e+26
KJ_TO_J = 1000
NANOMETRE_TO_METRE = 1e-09
PER_MOLE_TO_PER_MOLECULE = 6.02214086e+23
__dict__ = mappingproxy({'__module__': 'waterEntropy.entropy.vibrations', '__firstlineno__': 14, '__doc__': '\nStore molecule vibrational entropy information here, where\n\n.. math::\n    S^{\\mathrm{vib}} = S^{\\mathrm{trans}} + S^{\\mathrm{rot}}\n\nEntropies are calculated from the covariance matrices inputted in the\nadd_data method.\n', 'BOLTZMANN': 1.38064852e-23, 'HBAR': 1.0545718e-34, 'AVOGADRO': 6.022e+23, 'GAS_CONSTANT': 8.314, 'CALORIE_TO_JOULE': 4184, 'KG_TO_AMU': 6.02214086e+26, 'PER_MOLE_TO_PER_MOLECULE': 6.02214086e+23, 'ANGSTROM_TO_METRE': 1e-10, 'KJ_TO_J': 1000, 'NANOMETRE_TO_METRE': 1e-09, '__init__': <function Vibrations.__init__>, 'add_data': <function Vibrations.add_data>, 'get_data': <function Vibrations.get_data>, 'populate_dicts': <function Vibrations.populate_dicts>, 'kJ_conversion': <function Vibrations.kJ_conversion>, 'mda_conversion': <function Vibrations.mda_conversion>, 'kcal_conversion': <function Vibrations.kcal_conversion>, 'calculate_entropies': <function Vibrations.calculate_entropies>, 'calculate_frequencies': <function Vibrations.calculate_frequencies>, '__static_attributes__': ('rotational_S', 'rotational_freq', 'temperature', 'translational_S', 'translational_freq'), '__dict__': <attribute '__dict__' of 'Vibrations' objects>, '__weakref__': <attribute '__weakref__' of 'Vibrations' objects>, '__annotations__': {}})
__firstlineno__ = 14
__init__(temperature)[source]
__module__ = 'waterEntropy.entropy.vibrations'
__static_attributes__ = ('rotational_S', 'rotational_freq', 'temperature', 'translational_S', 'translational_freq')
__weakref__

list of weak references to the object

add_data(covariances: CovarianceCollection, diagonalise=True)[source]

Calculate and add the frequencies and vibrational entropies to class instance

Parameters:

  • covariances – instance of CovarianceCollection class

  • diagonalise – diagonalise the covariance matrix rather than getting the eigenvalues and eigenvectors

calculate_entropies(covariance: CovarianceCollection, diagonalise: bool)[source]

Calculate the vibrational entropies from the equation of a quantum harmonic oscillator:

\[\begin{split}S^{\mathrm{vib}} = k_{\mathrm{B}} \sum_{i=1}^{N_\mathrm{vib}} \\ \Bigg( \frac{h\nu_i/k_{\mathrm{B}}T}{e^{h\nu_i/k_{\mathrm{B}}T}-1} \\ - \ln(1 - e^{-h\nu_i/k_{\mathrm{B}}T} ) \Bigg)\end{split}\]

where:

  • \(k_{\mathrm{B}}\) is the Boltzmann constant \(\mathrm{J/K}\) (Joule per Kelvin),

Parameters:

  • covariances – instance of CovarianceCollection class

  • diagonalise – whether to diagonalise the covariance matrix

calculate_frequencies(covariance: CovarianceCollection, diagonalise: bool)[source]

Calculate the frequencies for each molecule from the force and torque covariance matrices.

Parameters:

  • covariances – instance of CovarianceCollection class

  • diagonalise – whether to diagonalise the covariance matrix

get_data(covariance: CovarianceCollection, diagonalise: bool)[source]

Get the frequencies and vibrational entropies from the covariance matrix

Parameters:

  • covariances – instance of CovarianceCollection class

  • diagonalise – whether to diagonalise the covariance matrix

kJ_conversion()[source]

Convert force covariance matrix from kJ/(mol nm m^2) to J/mol SI: kg.m/s^2 = N The forces are squared, so do the same for the constant

kcal_conversion()[source]

Convert force covariance matrix from Kcal/(mol Ang m^2) to J/mol SI: kg.m/s^2 = N The forces are squared, so do the same for the constant

mda_conversion()[source]

MDAnalysis stores forces as kJ/(mol Ang) by default, so: Convert force covariance matrix from kJ/(mol Ang m^2) to J/mol SI: kg.m/s^2 = N The forces are squared, so do the same for the constant

populate_dicts(nearest, molecule_name: str, variable, variable_dict)[source]

Add frequencies / entropies to class instance dictionaries

Parameters:

  • nearest – the value for grouping molecules into a class. e.g. the name of the nearest molecule

  • molecule_name – the name of the molecule being populated into the dictionaries

  • variable – the variable being added to the variable dictionary

  • variable_dict – the dictionary being updated with a variable

waterEntropy.entropy.vibrations.print_Svib_data(vibrations: Vibrations, covariances: CovarianceCollection)[source]

Print the orientational entropies of interfacial solvent

Parameters:

  • vibrations – instance of Vibrations class

  • covariances – instance of CovarianceCollection class

Module contents

waterEntropy: calculate water entropy near heterogeneous interfaces