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>)

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:

collections.abc.Callable

lower_bound

The minimum length for a bond to be added, expressed in nanometers.

Type:

float

upper_bound

The maximum length for a bond to be added, expressed in nanometers.

Type:

float

decay_factor

Parameter for the decay function.

Type:

float

decay_power

Parameter for the decay function.

Type:

float

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:

float

minimum_force

Minimum force constant in \(kJ.mol^{-1}.nm^{-2}\) under which bonds are not kept.

Type:

float

bond_type

Gromacs bond function type to apply to the elastic network bonds.

Type:

int or None

bond_type_variable

If bond_type is not given, it will be taken from the force field, using this variable name.

Type:

str

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 returns True if the two atoms are part of the same domain; returns False otherwise.

Type:

collections.abc.Callable

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:

str

See also

apply_rubber_band()

run_molecule(molecule)

vermouth.processors.apply_rubber_band.always_true(*args, **kwargs)

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)

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)

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:

bool

vermouth.processors.apply_rubber_band.build_connectivity_matrix(graph, separation, node_to_idx, selected_nodes)

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)

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:

numpy.ndarray

vermouth.processors.apply_rubber_band.compute_decay(distance, shift, rate, power)

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)

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)

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:

bool

vermouth.processors.apply_rubber_band.same_chain(graph, left, right)

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)

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:

numpy.ndarray