vermouth.molecule module

class vermouth.molecule.Block(incoming_graph_data=None, **attr)

Bases: Molecule

Residue topology template

Two blocks are equal if the underlying molecules are equal, and if the block names are equal.

Parameters:

• incoming_graph_data – Data to initialize graph. If None (default) an empty graph is created.

• attr – Attributes to add to graph as key=value pairs.

name

The name of the residue. Set to None if undefined.

Type:

str or None

add_atom(atom)

Add an atom. atom must contain an ‘atomname’. This value will be this atom’s index.

Parameters:

atom (collections.abc.Mapping) – The attributes of the atom to add. Must contain ‘atomname’

Raises:

ValueError – If atom does not contain ‘atomname’

property atoms

” The atoms in the residue. Each atom is a dict with a minima a key ‘name’ for the name of the atom, and a key ‘atype’ for the atom type. An atom can also have a key ‘charge’, ‘charge_group’, ‘comment’, or any arbitrary key.

Return type:

collections.abc.Iterator[dict]

guess_angles()

Generates all possible triplets of node indices that correspond to angles.

Yields:

tuple[collections.abc.Hashable, collections.abc.Hashable, collections.abc.Hashable] – All possible angles.

guess_dihedrals(angles=None)

Generates all possible quadruplets of node indices that correspond to torsion angles.

Parameters:

angles (collections.abc.Iterable) – All possible angles from which to start looking for torsion angles. Generated from guess_angles() if not provided.

Yields:

tuple[collections.abc.Hashable, collections.abc.Hashable, collections.abc.Hashable, collections.abc.Hashable] – All possible torsion angles.

has_dihedral_around(center)

Returns True if the block has a dihedral centered around the given bond.

Parameters:

center (tuple) – The name of the two central atoms of the dihedral angle. The method is sensitive to the order.

Return type:

bool

has_improper_around(center)

Returns True if the block has an improper centered around the given bond.

Parameters:

center (tuple) – The name of the two central atoms of the improper torsion. The method is sensitive to the order.

Return type:

bool

node_dict_factory

alias of OrderedDict

to_molecule(atom_offset=0, offset_resid=0, offset_charge_group=0, force_field=None, default_attributes=None)

Converts this block to a Molecule.

Parameters:

• atom_offset (int) – The number at which to start numbering the node indices.

• offset_resid (int) – The offset for the resid attributes.

• offset_charge_group (int) – The offset for the charge_group attributes.

• force_field (None or vermouth.forcefield.ForceField)

• default_attributes (collections.abc.Mapping[str]) – Attributes to set to for nodes that are missing them.

Returns:

This block as a molecule.

Return type:

Molecule

class vermouth.molecule.Choice(value)

Bases: LinkPredicate

Test if an attribute is defined and in a predefined list.

Parameters:

value (list) – The list of value in which to look for the attribute.

match(node, key)

Apply the comparison.

class vermouth.molecule.DeleteInteraction(atoms, atom_attrs, parameters, meta)

Bases: tuple

Create new instance of DeleteInteraction(atoms, atom_attrs, parameters, meta)

atom_attrs

Alias for field number 1

atoms

Alias for field number 0

meta

Alias for field number 3

parameters

Alias for field number 2

class vermouth.molecule.Interaction(atoms, parameters, meta)

Bases: tuple

Create new instance of Interaction(atoms, parameters, meta)

atoms

Alias for field number 0

meta

Alias for field number 2

parameters

Alias for field number 1

class vermouth.molecule.Link(incoming_graph_data=None, **attr)

Bases: Block

Template link between two residues.

Two links are equal if:

• the underlying molecules are equal

• the names are equal

• the negative edges (“non-edges”) are equal regardless of order

• the interactions to remove are the same and in the same order

• the meta variables are equal

• the pattern definitions are equal and in the same order

• the features are equals regardless of order

A link does not match if any of the non-edges match the target; their order therefore is not important. Same goes for features that just need to be present or not. The order does matter however for interactions to remove as removing the interactions in a different order may lead to a different set of remaining interactions.

Parameters:

• incoming_graph_data – Data to initialize graph. If None (default) an empty graph is created.

• attr – Attributes to add to graph as key=value pairs.

node_dict_factory

alias of OrderedDict

same_non_edges(other)

Returns True if all the non-edges of an other link are equal to those of this link. Returns False otherwise.

class vermouth.molecule.LinkParameterEffector(keys, format_spec=None)

Bases: object

Rule to calculate an interaction parameter in a link.

This class allows to store dynamic parameters in link interactions. The value of the parameter can be computed from the graph using the node keys given when creating the instance.

An instance of this class is first initialized with a list of node keys from the link in which it is defined. The instance is latter called like a function, and takes as arguments a molecule and a match dictionary linking the link nodes with the molecule ones. The format of the dictionary is expected to be {link key: molecule key}.

An instance can also have a format defined. If defined, that format will be applied to the value computed by the _apply() method causing the output to be a string. The format is given as a ‘format_spec’ from the python format string syntax. This format spec corresponds to what follows the column the column in string templates. For instance, formating a floating number to have 2 decimal places will be obtained by setting format to .2f. If no format is defined, then the calculated value is not modified.

This is a base class; it needs to be subclassed. A subclass must define an _apply() method that takes a molecule and a list of node keys from that molecule as arguments. This method is not called directly by the user, instead it is called by the __call__() method when the user calls the instance as a function. A subclass can also set the n_keys_asked class attribute to the number of required keys. If the attribute is set, then the number of keys provided when initializing a new instance will be validated against that number; else, the user can pass an arbitrary number of keys without validation.

__call__(molecule, match)

Parameters:

• molecule (Molecule) – The molecule from which to calculate the parameter value.

• match (dict) – The correspondence between the nodes from the link (keys), and the nodes from the molecule (values).

Returns:

The calculated parameter value, formatted if required.

Return type:

float

_apply(molecule, keys)

Calculate the parameter value from the molecule.

Notes

This method must be defined in a subclass.

Parameters:

• molecule (Molecule) – The molecule from which to compute the parameter value.

• keys (list) – A list of keys to use from the molecule.

Returns:

The value for the parameter.

Return type:

float

Parameters:

• keys (list) – A list of node keys from the link. If the n_keys_asked class argument is set, the number of keys must correspond to the value of the attribute.

• format_spec (str) – Format specification.

Raises:

ValueError – Raised if the n_keys_asked class attribute is set and the number of keys does not correspond.

n_keys_asked = None

Class attribute describing the number of keys required.

class vermouth.molecule.LinkPredicate(value)

Bases: object

Comparison criteria for node and molecule attributes in links.

When comparing an attribute from a link to a corresponding attribute from a molecule or a molecule node, the default behavior is to use the equality as criterion for the correspondence. Some correspondence, however must be broader for the link to be usable. Such alternative criteria are defined as link predicates.

If an attribute in a link is set to an instance of a predicate, then the correspondence is defined as the boolean result of the match method.

This is the base class for such predicate. It must be subclassed, and subclasses must define a match() method that takes a dictionary and a potential key from that dictionary as arguments.

Parameters:

value – The per-instance value that serve as reference. How this value is treated depends on the subclass.

match(node, key)

Do the comparison with the reference value.

Notes

This function must be defined by the subclasses. This docstring describe the expected format of the method.

Parameters:

• node (dict) – A dictionary of attributes in which to look up. This can be a node dictionary of a molecule meta attribute.

• key – A potential key from the node dictionary.

Return type:

bool

class vermouth.molecule.Modification(incoming_graph_data=None, **attr)

Bases: Link

A modification which describes deviations from a Block.

class vermouth.molecule.Molecule(*args, **kwargs)

Bases: Graph

Represents a molecule as per a specific force field. Consists of atoms (nodes), bonds (edges) and interactions such as angle potentials.

Two molecules are equal if:

• the exclusion distance (nrexcl) are equal

• the force fields are equal (but may be different instances)

• the nodes are equal and in the same order

• the edges are equal (but order is not accounted for)

• the interactions are the same and in the same order within an interaction type

When comparing molecules, the order of the nodes is considered as it determines in what order atoms will be written in the output. Same goes for the interactions within an interaction type. The order of edges is not guaranteed anywhere in the code, and they are not writen in the output.

meta

Type:

dict

nrexcl

Type:

int

interactions

All the known interactions. Each item of the dictionary is a type of interaction, with the key being the name of the kind of interaction using Gromacs itp/rtp conventions (‘bonds’, ‘angles’, …) and the value being a list of all the interactions of that type in the residue. An interaction is a dict with a key ‘atoms’ under which is stored the list of the atoms involved (referred by their name), a key ‘parameters’ under which is stored an arbitrary list of non-atom parameters as written in a RTP file, and arbitrary keys to store custom metadata. A given interaction can have a comment under the key ‘comment’.

Type:

dict[str, list[Interaction]]

citations

The citation keys associated with this molecule.

Type:

set[str]

add_interaction(type_, atoms, parameters, meta=None)

Add an interaction of the specified type with the specified parameters involving the specified atoms.

Parameters:

• type (str) – The type of interaction, such as ‘bonds’ or ‘angles’.

• atoms (collections.abc.Sequence) – The atoms that are involved in this interaction. Must be in this molecule

• parameters (collections.abc.Iterable) – The parameters for this interaction.

• meta (collections.abc.Mapping) – Metadata for this interaction, such as comments to be written to the output.

Raises:

KeyError – If one of the atoms is not in this molecule.

add_node(*args, **kwargs)

add_or_replace_interaction(type_, atoms, parameters, meta=None, citations=None)

Adds a new interaction if it doesn’t exists yet, and replaces it otherwise. Interactions are deemed the same if they’re the same type, and they involve the same atoms, and their meta['version'] is the same.

Parameters:

• type (str) – The type of interaction, such as ‘bonds’ or ‘angles’.

• atoms (collections.abc.Sequence) – The atoms that are involved in this interaction. Must be in this molecule

• parameters (collections.abc.Iterable) – The parameters for this interaction.

• meta (collections.abc.Mapping) – Metadata for this interaction, such as comments to be written to the output.

• citations (set) – set of citations that apply when this link is addded to molecule

See also

add_interaction()

property atoms

All atoms in this molecule. Alias for nodes.

copy()

Creates a copy of the molecule.

Return type:

Molecule

edges_between(n_bunch1, n_bunch2, data=False)

Returns all edges in this molecule between nodes in n_bunch1 and n_bunch2.

Parameters:

• n_bunch1 (Iterable) – The first bunch of node indices.

• n_bunch2 (Iterable) – The second bunch of node indices.

Returns:

A list of tuples of edges in this molecule. The first element of the tuple will be in n_bunch1, the second element in n_bunch2.

Return type:

list

find_atoms(**attrs)

Yields all indices of atoms that match attrs

Parameters:

**attrs (collections.abc.Mapping) – The attributes and their desired values.

Yields:

collections.abc.Hashable – All atom indices that match the specified attrs

property force_field

The force field the molecule is described for.

The force field is assumed to be consistent for all the molecules of a system. While it is possible to reassign attribute Molecule._force_field, it is recommended to assign the force field at the system level as reassigning force_field will propagate the change to all the molecules in that system.

get_interaction(type_)

Returns all interactions of type_

Parameters:

type (collections.abc.Hashable) – The type which interactions should be found.

Returns:

The interactions of the specified type.

Return type:

list[Interaction]

iter_residues()

Returns a generator over the nodes of this molecules residues.

Return type:

collections.abc.Generator

make_edges_from_interaction_type(type_)

Create edges from the interactions of a given type.

The interactions must be described so that two consecutive atoms in an interaction should be linked by an edge. This is the case for bonds, angles, proper dihedral angles, and cmap torsions. It is not always true for improper torsions.

Cmap are described as two consecutive proper dihedral angles. The atoms for the interaction are the 4 atoms of the first dihedral angle followed by the next atom forming the second dihedral angle with the 3 previous ones. Each pair of consecutive atoms generate an edge.

Warning

If there is no interaction of the required type, it will be silently ignored.

Parameters:

type (str) – The name of the interaction type the edges should be built from.

make_edges_from_interactions()

Create edges from the interactions we know how to convert to edges.

The known interactions are bonds, angles, proper dihedral angles, cmap torsions and constraints.

merge_molecule(molecule)

Add the atoms and the interactions of a molecule at the end of this one.

Atom and residue index of the new atoms are offset to follow the last atom of this molecule.

Parameters:

molecule (Molecule) – The molecule to merge at the end.

Returns:

A dict mapping the node indices of the added molecule to their new indices in this molecule.

Return type:

dict

node_dict_factory

alias of OrderedDict

remove_interaction(type_, atoms, version=0)

Removes the specified interaction.

Parameters:

• type (str) – The type of interaction, such as ‘bonds’ or ‘angles’.

• atoms (collections.abc.Sequence) – The atoms that are involved in this interaction.

• version (int) – Sometimes there can be multiple distinct interactions between the same group of atoms. This is reflected with their version meta attribute.

Raises:

KeyError – If the specified interaction could not be found

remove_matching_interaction(type_, template_interaction)

Removes any interactions that match the template.

Parameters:

• type (collections.abc.Hashable) – The type of interaction to look for.

• template_interaction (Interaction)

See also

interaction_match()

remove_node(node)

Overriding the remove_node method of networkx as we have to delete the interaction from the interactions list separately which is not a part of the graph and hence does not get deleted.

remove_nodes_from(nodes)

Overriding the remove_nodes_from method of networkx as we have to delete the interaction from the interactions list separately which is not a part of the graph and hence does not get deleted.

same_edges(other)

Compare the edges between this molecule and an other.

Edges are unordered and undirected, but they can have attributes.

Parameters:

other (networkx.Graph) – The other molecule to compare the edges with.

Return type:

bool

same_interactions(other)

Returns True if the interactions are the same.

To be equal, two interactions must share the same node key reference, the same interaction parameters, and the same meta attributes. Empty interaction categories are ignored.

Parameters:

other (Molecule)

Return type:

bool

same_nodes(other, ignore_attr=())

Returns True if the nodes are the same and in the same order.

The equality criteria used for the attribute values are those of vermouth.utils.are_different().

Parameters:

• other (Molecule)

• ignore_attr (collections.abc.Container) – Attribute keys that will not be considered in the comparison.

Return type:

bool

share_moltype_with(other)

Checks whether other has the same shape as this molecule.

Parameters:

other (Molecule)

Returns:

True iff other has the same shape as this molecule.

Return type:

bool

static sort_interactions(all_interactions)

Returns keys in interactions sorted by (number_of_atoms, name). Keys with no interactions are skipped.

property sorted_nodes

subgraph(nodes)

Creates a subgraph from the molecule.

Return type:

Molecule

class vermouth.molecule.NotDefinedOrNot(value)

Bases: LinkPredicate

Test if an attribute is not the reference value.

This test passes if the attribute is not defined, if it is set to None, or if its value is different from the reference.

Notes

If the reference is set to None, then the test does not pass if the attribute is explicitly set to None. It still passes if the attribute is not defined.

Parameters:

value – The value the attribute is tested not to be.

match(node, key)

Apply the comparison.

class vermouth.molecule.ParamAngle(keys, format_spec=None)

Bases: LinkParameterEffector

Calculate the angle in degrees between three consecutive nodes.

Parameters:

• keys (list) – A list of node keys from the link. If the n_keys_asked class argument is set, the number of keys must correspond to the value of the attribute.

• format_spec (str) – Format specification.

Raises:

ValueError – Raised if the n_keys_asked class attribute is set and the number of keys does not correspond.

n_keys_asked = 3

Class attribute describing the number of keys required.

class vermouth.molecule.ParamDihedral(keys, format_spec=None)

Bases: LinkParameterEffector

Calculate the dihedral angle in degrees defined by four nodes.

Parameters:

• keys (list) – A list of node keys from the link. If the n_keys_asked class argument is set, the number of keys must correspond to the value of the attribute.

• format_spec (str) – Format specification.

Raises:

ValueError – Raised if the n_keys_asked class attribute is set and the number of keys does not correspond.

n_keys_asked = 4

Class attribute describing the number of keys required.

class vermouth.molecule.ParamDihedralPhase(keys, format_spec=None)

Bases: LinkParameterEffector

Calculate the dihedral angle in degrees defined by four nodes shifted by -180 degrees.

Parameters:

• keys (list) – A list of node keys from the link. If the n_keys_asked class argument is set, the number of keys must correspond to the value of the attribute.

• format_spec (str) – Format specification.

Raises:

ValueError – Raised if the n_keys_asked class attribute is set and the number of keys does not correspond.

n_keys_asked = 4

Class attribute describing the number of keys required.

class vermouth.molecule.ParamDistance(keys, format_spec=None)

Bases: LinkParameterEffector

Calculate the distance between a pair of nodes.

Parameters:

• keys (list) – A list of node keys from the link. If the n_keys_asked class argument is set, the number of keys must correspond to the value of the attribute.

• format_spec (str) – Format specification.

Raises:

ValueError – Raised if the n_keys_asked class attribute is set and the number of keys does not correspond.

n_keys_asked = 2

Class attribute describing the number of keys required.

vermouth.molecule.attributes_match(attributes, template_attributes, ignore_keys=())

Compare a dict of attributes from a molecule with one from a link.

Returns True if the attributes from the link match the ones from the molecule; returns False otherwise. The attributes from a link match with those of a molecule if all the individual attribute from the link match the corresponding ones in the molecule. In the simplest case, these attribute match if their values are equal. If the value of the link attribute is an instance of LinkPredicate, then the attributes match if the match method of the predicate returns True.

Parameters:

• attributes (dict) – Attributes from the molecule.

• template_attributes (dict) – Attributes from the link.

• ignore_keys (list) – List of keys to ignore from ‘template_attributes’.

Return type:

bool

vermouth.molecule.interaction_match(molecule, interaction, template_interaction)

Compare an interaction with a template interaction or interaction to delete.

An instance of Interaction matches a template instance of the same class or of DeleteInteraction if, at the minimum, it involves the same atoms in the same order. If the template defines parameters, then they have to match as well. In the case of of a DeleteInteraction, atoms may have attributes as well, then they have to match with the attributes of the corresponding atoms in the molecule.

Parameters:

• molecule (networkx.Graph) – The molecule that contains the interaction.

• interaction (Interaction) – The interaction in the molecule.

• template_interaction (Interaction or DeleteInteraction) – The template to match with the interaction.

Return type:

bool

See also

attributes_match