waterEntropy.analysis package

Submodules

waterEntropy.analysis.HB module

These functions calculate hydrogen bonding within a shell.

class waterEntropy.analysis.HB.HBCollection

Bases: object

Class for hydrogen bond donors and their acceptors

__dict__ = mappingproxy({'__module__': 'waterEntropy.analysis.HB', '__firstlineno__': 12, '__doc__': '\nClass for hydrogen bond donors and their acceptors\n', '__init__': <function HBCollection.__init__>, 'add_data': <function HBCollection.add_data>, 'find_donators': <function HBCollection.find_donators>, 'find_acceptor': <function HBCollection.find_acceptor>, '__static_attributes__': ('accepting_from', 'donating_to'), '__dict__': <attribute '__dict__' of 'HBCollection' objects>, '__weakref__': <attribute '__weakref__' of 'HBCollection' objects>, '__annotations__': {}})

__firstlineno__ = 12

__init__()

__module__ = 'waterEntropy.analysis.HB'

__static_attributes__ = ('accepting_from', 'donating_to')

__weakref__

list of weak references to the object

add_data(UA_idx: int, donator_idx: int, acceptor_idx: int)

For a given donator index, save its acceptor index in the donating_to dictionary. And for that acceptor, save the donator index as a list in the accepting from dictionary.

Parameters:

• self – class instance

• UA_idx – atom index of the UA of the bonded donating hydrogen

• donator_idx – atom index of the donator bonded to the UA

• acceptor_idx – atom index of the UA accepting the hydrogen bond in the coordination shell

find_acceptor(UA_idx: int)

Find the acceptors for a given resid, this returns a dictionary where the key is the donator index and the value is the acceptor index

Parameters:

• cls – class instance

• UA_idx – atom index of UA accepting HBs

find_donators(UA_idx: int)

Find the donators for a given residue, this returns a dict where the key is the accepting atom index and the value is a list of the atom indices that donate to it.

Parameters:

• cls – class instance

• UA_idx – atom index of UA being donated to

waterEntropy.analysis.HB.get_HB_terms(heavy_atom, donator, acceptor, DA_distance, dimensions)

Get two terms for calculating the hydrogen bond between a donator and potential acceptor in a coordination shell. For a hydrogen bond to form, the following criteria need to be met:

1. Angle between heavy atom bonded to donator (X), the donator (D) and the acceptor (A) is over 90 degrees

2. The relative charge is most negative over all other neighbours in a coordination shell

Parameters:

• heavy_atom – the mdanalysis instance for the heavy atom bonded to the donator

• donator – the mdanalysis instance for the donator

• acceptor – the mdanalysis instance for the possible acceptor

• DA_distance – the distance between donor and acceptor

• dimensions – the dimensions of the simulation box

waterEntropy.analysis.HB.get_shell_HB_acceptors(shell, system, HBs: HBCollection)

Find the hydrogen bond acceptors for the central UA hydrogens that are electropositive. The assumption is made that hydrogen bonding can only occur inside the coordination shell, this is needed for shell neighbour labelling used in orientational entropy calculations

Parameters:

• shell – the instance for containing coordination shell neighbours

• system – mdanalysis instance of all atoms in current frame

• HBs – instance of HBCollection class

waterEntropy.analysis.HB.get_shell_HBs(shell, system, HBs: HBCollection, shells: ShellCollection)

For a given UA and its coordination shell neighbours, find what the central UA donates to and accepts from in its shell.

Parameters:

• shell – the instance for class waterEntropy.neighbours.RAD.RAD containing coordination shell neighbours

• system – mdanalysis instance of all atoms in current frame

• HBs – HBCollection instance

• shells – ShellCollection instance

waterEntropy.analysis.HB_labels module

Store the labelled neighbours that are donated to and accepted from the central atom in a shell. Shells with the same neighbours are grouped together and along with the counts for donating to and accepting from each neighbour type. These labelled HB neighbours are used to calculate orientational entropy of water molecules.

class waterEntropy.analysis.HB_labels.HBLabelCollection

Bases: object

Labelled shell counts used for Sorient. The counts are placed into two dictionaries used for statistics later, the structure of these two dictionaries are as follows:

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

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

dict2 = {“nearest_resid”: {“resname”:

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

__dict__ = mappingproxy({'__module__': 'waterEntropy.analysis.HB_labels', '__firstlineno__': 15, '__doc__': '\nLabelled shell counts used for Sorient.\nThe counts are placed into two dictionaries used for statistics later,\nthe structure of these two dictionaries are as follows:\n\ndict1 = {"resname": {("labelled_shell"): {"shell_count": 0, "N_w": N_w,\n                            "donates_to": {"labelled_donators": 0,},\n                            "accepts_from": {"labelled_acceptors": 0,}\n                            }}}\ndict2 = {"nearest_resid": {"resname":\n                            {("labelled_shell"): {"shell_count": 0,\n                            "N_w": N_w,\n                            "donates_to": {"labelled_donators": 0,},\n                            "accepts_from": {"labelled_acceptors": 0,}\n                            }}}\n', '__init__': <function HBLabelCollection.__init__>, 'add_data': <function HBLabelCollection.add_data>, 'add_shell_counts': <function HBLabelCollection.add_shell_counts>, 'add_donates_to': <function HBLabelCollection.add_donates_to>, 'add_accepts_from': <function HBLabelCollection.add_accepts_from>, 'merge': <function HBLabelCollection.merge>, '__static_attributes__': ('labelled_shell_counts', 'resid_labelled_shell_counts'), '__dict__': <attribute '__dict__' of 'HBLabelCollection' objects>, '__weakref__': <attribute '__weakref__' of 'HBLabelCollection' objects>, '__annotations__': {}})

__firstlineno__ = 15

__init__()

__module__ = 'waterEntropy.analysis.HB_labels'

__static_attributes__ = ('labelled_shell_counts', 'resid_labelled_shell_counts')

__weakref__

list of weak references to the object

add_accepts_from(resid, resname, labelled_shell, accepts_from)

Add a labelled neighbours accepted from to in a dictionary that keeps track of the counts for each labelled shell type with constituents alpha-numerically ordered

Parameters:

• self – class instance

• resid – residue id of nearest nonlike atom in the labelled shell

• resname – residue name of nearest nonlike atom in the labelled shell

• labelled_shell – coordination shell with labelled neighbours

• accepts_from – list of labelled neighbours that are accepted_from

add_data(resid, resname, labelled_shell, donates_to, accepts_from, N_w)

Add data to class dictionaries

add_donates_to(resid, resname, labelled_shell, donates_to)

Add a labelled neighbours donated to in a dictionary that keeps track of the counts for each labelled shell type with constituents alpha-numerically ordered

Parameters:

• self – class instance

• resid – residue id of nearest nonlike atom in the labelled shell

• resname – residue name of nearest nonlike atom in the labelled shell

• labelled_shell – coordination shell with labelled neighbours

• donates_to – list of labelled neighbours that are donated to

add_shell_counts(resid, resname, labelled_shell, N_w)

Add a labelled shell to a dictionary that keeps track of the counts for each labelled shell type with constituents alpha-numerically ordered

Parameters:

• self – class instance

• resid – residue id of nearest nonlike atom in the labelled shell

• resname – residue name of nearest nonlike atom in the labelled shell

• labelled_shell – coordination shell with labelled neighbours

merge(other)

Merge another HBLabelCollection into this one.

Parameters:

other – another HBLabelCollection to merge

waterEntropy.analysis.HB_labels.get_HB_labels(atom_idx: int, system, HBs: HBCollection, shells: ShellCollection)

For a given central atom, get what UAs it donates and accepts from, then find what shell labels these correspond to. Update the shells class instance with this information

Parameters:

• atom_idx – atom index to find HB labels for

• system – mdanalysis instance of all atoms in current frame

• HBs – HBCollection class instance

• shells – ShellCollection class instance

waterEntropy.analysis.RAD module

These functions calculate coordination shells using RAD the relative angular distance.

waterEntropy.analysis.RAD.get_RAD_neighbours(i_coords, sorted_indices, sorted_distances, system)

For a given set of atom coordinates, find its RAD shell from the distance sorted atom list, truncated to the closests 30 atoms.

This function calculates coordination shells using RAD the relative angular distance, as defined first in DOI:10.1063/1.4961439 where united atoms (heavy atom + bonded Hydrogens) are defined as neighbours if they fulfil the following condition:

\[\Bigg(\frac{1}{r_{ij}}\Bigg)^2>\Bigg(\frac{1}{r_{ik}}\Bigg)^2 \cos \theta_{jik}\]

For a given particle \(i\), neighbour \(j\) is in its coordination shell if \(k\) is not blocking particle \(j\). In this implementation of RAD, we enforce symmetry, whereby neighbouring particles must be in each others coordination shells.

Parameters:

• i_coords – xyz coordinates of atom \(i\)

• sorted_indices – list of atom indices sorted from closest to furthest from atom \(i\)

• sorted_distances – list of atom distances sorted from closest to furthest from atom \(i\)

• system – mdanalysis instance of atoms in a frame

waterEntropy.analysis.RAD.get_RAD_shell(UA, system, shells: ShellCollection, sorted_indices=None, sorted_distances=None)

For a given united atom, find its RAD shell, returning the atom indices for the heavy atoms that are in its shell.

Parameters:

• UA – mdanalysis instance of a united atom in a frame

• system – mdanalysis instance of atoms in a frame

• shells – ShellCollection instance

waterEntropy.analysis.shell_labels module

Label neighbours in a coordination shell based on what they are and what their neighbours are.

waterEntropy.analysis.shell_labels.get_nearest_nonlike(shell, system)

For a given shell, find the closest neighbour that is not the same atom/molecule type as the central united atom.

Parameters:

• shell – shell instance of an atom

• system – mdanalysis instance of atoms in a frame

waterEntropy.analysis.shell_labels.get_shell_labels(atom_idx: int, system, shell, shells: ShellCollection)

Get the shell labels of an atoms shell based on the following: For a central UA, rank its coordination shell by proximity to that central UA’s nearest non-like molecule UA.

• ‘#_RESNAME’ = RAD shell from same molecule type, when nearest nonlike resid is the same as the reference.

• ‘X_RESNAME’ = when same molecule type has different nearest nonlike resid.

• ‘RESNAME’ = when molecule of different type is in RAD shell.

• ‘0_RESNAME’ = closest different type molecule in RAD shell. (the one its assigned to, its nearest non-like!)

Parameters:

• atom_idx – atom index of central atom in coordination shell

• system – mdanalysis instance of atoms in a frame

• shell – shell instance of atom_idx

• shells – ShellCollection instance

waterEntropy.analysis.shells module

Store shell information here

class waterEntropy.analysis.shells.Shell(atom_idx)

Bases: object

Represent a single atom shell with dynamic properties, which are set in the ShellCollection class.

__dict__ = mappingproxy({'__module__': 'waterEntropy.analysis.shells', '__firstlineno__': 4, '__doc__': 'Represent a single atom shell with dynamic properties, which are set in\nthe ShellCollection class.', '__init__': <function Shell.__init__>, '__getattr__': <function Shell.__getattr__>, '__setattr__': <function Shell.__setattr__>, '__repr__': <function Shell.__repr__>, '__static_attributes__': (), '__dict__': <attribute '__dict__' of 'Shell' objects>, '__weakref__': <attribute '__weakref__' of 'Shell' objects>, '__annotations__': {}})

__firstlineno__ = 4

__getattr__(key: str)

Allow dot notation access to stored properties.

Parameters:

key – name of the property in the properties dictionary

__init__(atom_idx)

__module__ = 'waterEntropy.analysis.shells'

__repr__()

Print the atom and its properties.

__setattr__(key: str, value)

Allow adding properties dynamically, except for ‘atom_idx’.

Parameters:

• key – name of the property being added to the properties dictionary

• value – value for the key being added to the properties dictionary

__static_attributes__ = ()

__weakref__

list of weak references to the object

class waterEntropy.analysis.shells.ShellCollection

Bases: object

Manage multiple atom shells and allow adding/updating properties.

__dict__ = mappingproxy({'__module__': 'waterEntropy.analysis.shells', '__firstlineno__': 37, '__doc__': 'Manage multiple atom shells and allow adding/updating properties.', '__init__': <function ShellCollection.__init__>, 'add_data': <function ShellCollection.add_data>, 'set_property': <function ShellCollection.set_property>, 'find_shell': <function ShellCollection.find_shell>, '__repr__': <function ShellCollection.__repr__>, '__static_attributes__': ('shells',), '__dict__': <attribute '__dict__' of 'ShellCollection' objects>, '__weakref__': <attribute '__weakref__' of 'ShellCollection' objects>, '__annotations__': {}})

__firstlineno__ = 37

__init__()

__module__ = 'waterEntropy.analysis.shells'

__repr__()

Return a dictionary-like representation of stored atoms.

__static_attributes__ = ('shells',)

__weakref__

list of weak references to the object

add_data(atom_idx: int, UA_shell: list[int])

Add a new atom shell to the collection if it doesn’t exist and set various properties used to describe the class.

Parameters:

• atom_idx – the heavy atom index of the central atom in a shell

• UA_shell – the list of heavy atom indices in the shell of atom_idx

find_shell(atom_idx: int)

Get the shell instance if atom_idx is a key in shells dictionary

Parameters:

atom_idx – index of central atom in shell

set_property(atom_idx, key: str, value)

Set a property for a specific atom shell, ensuring it exists first.

Parameters:

• atom_idx – the heavy atom index of the central atom in a shell

• key – the name of the key being added to the shells dictionary

• value – the value of the key being added to the shells dictionary

Module contents

waterEntropy: calculate water entropy near heterogeneous interfaces