vermouth.processors.apply_rubber_band module¶
Provides a processor that adds a rubber band elastic network.
- class vermouth.processors.apply_rubber_band.ApplyRubberBand(lower_bound, upper_bound, decay_factor, decay_power, base_constant, minimum_force, res_min_dist=None, bond_type=None, selector=<function select_backbone>, bond_type_variable='elastic_network_bond_type', res_min_dist_variable='elastic_network_res_min_dist', domain_criterion=<function always_true>)[source]¶
Bases:
Processor
Add an elastic network to a system between particles fulfilling the following criteria:
They must be close enough together in space
They must be separated far enough in graph space
They must be either in the same chain/molecule/system
They must be selected by
selector
The resulting elastic bond must be stiff enough
- selector¶
Selection function.
- Type:
- base_constant¶
The base force constant for the bonds in \(kJ.mol^{-1}.nm^{-2}\). If ‘decay_factor’ or ‘decay_power’ is set to 0, then it will be the used force constant.
- Type:
- minimum_force¶
Minimum force constant in \(kJ.mol^{-1}.nm^{-2}\) under which bonds are not kept.
- Type:
- bond_type_variable¶
If bond_type is not given, it will be taken from the force field, using this variable name.
- Type:
- domain_criterion¶
Function to establish if two atoms are part of the same domain. Elastic bonds are only added within a domain. By default, all the atoms in the molecule are considered part of the same domain. The function expects a graph (e.g. a
Molecule
) and two atom node keys as argument and returnsTrue
if the two atoms are part of the same domain; returnsFalse
otherwise.- Type:
- res_min_dist¶
Minimum separation between two atoms for a bond to be kept. Bonds are kept is the separation is greater or equal to the value given.
- Type:
int or None
- res_min_dist_variable¶
If res_min_dist is not given it will be taken from the force field using this variable name.
- Type:
See also
- vermouth.processors.apply_rubber_band.always_true(*args, **kwargs)[source]¶
Returns
True
whatever the arguments are.
- vermouth.processors.apply_rubber_band.apply_rubber_band(molecule, selector, lower_bound, upper_bound, decay_factor, decay_power, base_constant, minimum_force, bond_type, domain_criterion, res_min_dist)[source]¶
Adds a rubber band elastic network to a molecule.
The elastic network is applied as bounds between the atoms selected by the function declared with the ‘selector’ argument. The equilibrium length for the bonds is measured from the coordinates in the molecule, the force constant is computed from the base force constant and an optional decay function.
The decay function for the force constant is defined as:
\[\exp^{-r(d - s)^p}\]where \(r\) is the decay rate given by the ‘decay_factor’ argument, \(p\) is the decay power given by ‘decay_power’, \(s\) is a shift given by ‘lower_bound’, and \(d\) is the distance between the two atoms in the molecule. If the rate or the power are set to 0, then the decay function does not modify the force constant.
The ‘selector’ argument takes a callback that accepts a atom dictionary and returns
True
if the atom match the conditions to be kept.Only nodes that are in the same domain can be connected by the elastic network. The ‘domain_criterion’ argument accepts a callback that determines if two nodes are in the same domain. That callback accepts a graph and two node keys as argument and returns whether or not the nodes are in the same domain as a boolean.
- Parameters:
molecule (vermouth.molecule.Molecule) – The molecule to which apply the elastic network. The molecule is modified in-place.
selector (collections.abc.Callable) – Selection function.
lower_bound (float) – The minimum length for a bond to be added, expressed in nanometers.
upper_bound (float) – The maximum length for a bond to be added, expressed in nanometers.
decay_factor (float) – Parameter for the decay function.
decay_power (float) – Parameter for the decay function.
base_constant (float) – The base force constant for the bonds in \(kJ.mol^{-1}.nm^{-2}\). If ‘decay_factor’ or ‘decay_power’ is set to 0, then it will be the used force constant.
minimum_force (float) – Minimum force constant in \(kJ.mol^{-1}.nm^{-2}\) under which bonds are not kept.
bond_type (int) – Gromacs bond function type to apply to the elastic network bonds.
domain_criterion (collections.abc.Callable) – Function to establish if two atoms are part of the same domain. Elastic bonds are only added within a domain. By default, all the atoms in the molecule are considered part of the same domain. The function expects a graph (e.g. a
Molecule
) and two atom node keys as argument and returnsTrue
if the two atoms are part of the same domain; returnsFalse
otherwise.res_min_dist (int) – Minimum separation between two atoms for a bond to be kept. Bonds are kept is the separation is greater or equal to the value given.
- vermouth.processors.apply_rubber_band.are_connected(graph, left, right, separation)[source]¶
True
if the nodes are at most ‘separation’ nodes away.- Parameters:
graph (networkx.Graph) – The graph/molecule to work on.
left – One node key from the graph.
right – One node key from the graph.
separation (int) – The maximum number of nodes in the shortest path between two nodes of interest for these two nodes to be considered connected. Must be >= 0.
- Return type:
- vermouth.processors.apply_rubber_band.build_connectivity_matrix(graph, separation, node_to_idx, selected_nodes)[source]¶
Build a connectivity matrix based on the separation between nodes in a graph.
The connectivity matrix is a symmetric boolean matrix where cells contain
True
if the corresponding atoms are connected in the graph and separated by less or as much nodes as the given ‘separation’ argument.In the following examples, the separation between A and B is 0, 1, and 2. respectively:
` A - B A - X - B A - X - X - B `
Note that building the connectivity matrix with a separation of 0 is the same as building the adjacency matrix.
- Parameters:
graph (networkx.Graph) – The graph/molecule to work on.
separation (int) – The maximum number of nodes in the shortest path between two nodes of interest for these two nodes to be considered connected. Must be >= 0.
selected_nodes (collections.abc.Collection) – A list of nodes to work on.
- Returns:
A boolean matrix.
- Return type:
- vermouth.processors.apply_rubber_band.build_pair_matrix(graph, criterion, idx_to_node, selected_nodes)[source]¶
Build a boolean matrix telling if a pair of nodes fulfil a criterion.
- Parameters:
graph (networkx.Graph) – The graph/molecule to work on.
criterion (collections.abc.Callable) – A function that determines if a pair of nodes fulfill the criterion. It takes a graph and two node keys as arguments and returns a boolean.
selected_nodes (collections.abc.Collection) – A list of nodes to work on.
- Returns:
A boolean matrix.
- Return type:
- vermouth.processors.apply_rubber_band.compute_decay(distance, shift, rate, power)[source]¶
Compute the decay function of the force constant as function to the distance.
The decay function for the force constant is defined as:
\[\exp^{-r(d - s)^p}\]where \(r\) is the decay rate given by the ‘rate’ argument, \(p\) is the decay power given by ‘power’, \(s\) is a shift given by ‘shift’, and \(d\) is the distance between the two atoms given in ‘distance’. If the rate or the power are set to 0, then the decay function does not modify the force constant.
The ‘distance’ argument can be a scalar or a numpy array. If it is an array, then the returned value is an array of decay factors with the same shape as the input.
- vermouth.processors.apply_rubber_band.compute_force_constants(distance_matrix, lower_bound, upper_bound, decay_factor, decay_power, base_constant, minimum_force)[source]¶
Compute the force constant of an elastic network bond.
The force constant can be modified with a decay function, and it can be bounded with a minimum threshold, or a distance upper and lower bonds.
If decay_factor = decay_power = 0 all forces applied are = base_constant
Forces applied to distances above upper_bound are removed. Forces below minimum_force are removed.
If decay_factor or decay_power != 0, forces below lower_bound are greater than base_constant, in which case they are set back to = base_constant
- vermouth.processors.apply_rubber_band.make_same_region_criterion(regions)[source]¶
Returns
True
is the nodes are part of the same region.Nodes are considered part of the same region if their value under the “resid” attribute are within the same residue range. By default the resids of the input file are used (i.e. “_old_resid” attribute).
- Parameters:
graph (networkx.Graph) – A graph the nodes are part of.
left – A node key in ‘graph’.
right – A node key in ‘graph’.
regions – [(resid_start_1,resid_end_1),(resid_start_2,resid_end_2),…] resid_start and resid_end are included)
- Returns:
True
if the nodes are part of the same region.- Return type:
- vermouth.processors.apply_rubber_band.same_chain(graph, left, right)[source]¶
Returns
True
is the nodes are part of the same chain.Nodes are considered part of the same chain if they both have the same value under the “chain” attribute, or if neither of the 2 nodes have that attribute.
- Parameters:
graph (networkx.Graph) – A graph the nodes are part of.
left – A node key in ‘graph’.
right – A node key in ‘graph’.
- Returns:
True
if the nodes are part of the same chain.- Return type:
- vermouth.processors.apply_rubber_band.self_distance_matrix(coordinates)[source]¶
Compute a distance matrix between points in a selection.
Notes
This function does not account for periodic boundary conditions.
- Parameters:
coordinates (numpy.ndarray) – Coordinates of the points in the selection. Each row must correspond to a point and each column to a dimension.
- Return type: