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: vermouth.processors.processor.Processor

run_molecule(molecule)[source]
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 returns True if the two atoms are part of the same domain; returns False 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.

Returns

Return type

bool

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

numpy.ndarray

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
Returns

A boolean matrix.

Return type

numpy.ndarray

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.

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

bool

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.

Returns

Return type

numpy.ndarray