vermouth.map_parser module

Contains the Mapping object and the associated parser.

class vermouth.map_parser.Mapping(block_from, block_to, mapping, references, ff_from=None, ff_to=None, extra=(), normalize_weights=False, type='block', names=())

Bases: object

A mapping object that describes a mapping from one resolution to another.

block_from

The graph which this Mapping object can transform.

Type

networkx.Graph

block_to

The vermouth.molecule.Block we can transform to.

Type

vermouth.molecule.Block

references

A mapping of node keys in block_to to node keys in block_from that describes which node in blocks_from should be taken as a reference when determining node attributes for nodes in block_to.

Type

collections.abc.Mapping

ff_from

The forcefield of block_from.

Type

vermouth.forcefield.ForceField

ff_to

The forcefield of block_to.

Type

vermouth.forcefield.ForceField

names

The names of the mapped blocks.

Type

tuple[str]

mapping

The actual mapping that describes for every node key in block_from to what node key in block_to it contributes to with what weight. {node_from: {node_to: weight, ...}, ...}.

Type

dict[collections.abc.Hashable, dict[collections.abc.Hashable, float]]

Note

Only nodes described in mapping will be used.

Parameters

• block_from (networkx.Graph) – As per block_from.

• block_to (vermouth.molecule.Block) – As per block_to.

• mapping (dict[collections.abc.Hashable, dict[collections.abc.Hashable, float]]) – As per mapping.

• references (collections.abc.Mapping) – As per references.

• ff_from (vermouth.forcefield.ForceField) – As per ff_from.

• ff_to (vermouth.forcefield.ForceField) – As per ff_to.

• extra (tuple) – Extra information to be attached to block_to.

• normalize_weights (bool) – Whether the weights should be normalized such that the sum of the weights of nodes mapping to something is 1.

• names (tuple) – As per names.

map(graph, node_match=None, edge_match=None)

Performs the partial mapping described by this object on graph. It first find the induced subgraph isomorphisms between graph and block_from, after which it will process the found isomorphisms according to mapping.

None of the yielded dictionaries will refer to node keys of block_from. Instead, those will be translated to node keys of graph based on the found isomorphisms.

Note

Only nodes described in mapping will be used in the isomorphism.

Parameters

• graph (networkx.Graph) – The graph on which this partial mapping should be applied.

• node_match (collections.abc.Callable or None) – A function that should take two dictionaries with node attributes, and return True if those nodes should be considered equal, and False otherwise. If None, all nodes will be considered equal.

• edge_match (collections.abc.Callable or None) – A function that should take six arguments: two graphs, and four node keys. The first two node keys will be in the first graph and share an edge; and the last two node keys will be in the second graph and share an edge. Should return True if a pair of edges should be considered equal, and False otherwise. If None, all edges will be considered equal.

Yields

• dict[collections.abc.Hashable, dict[collections.abc.Hashable, float]] – the correspondence between nodes in graph and nodes in block_to, with the associated weights.

• vermouth.molecule.Block – block_to.

• dict – references on which mapping has been applied.

property reverse_mapping

The reverse of mapping. {node_to: {node_from: weight, ...}, ...}

class vermouth.map_parser.MappingBuilder

Bases: object

An object that is in charge of building the arguments needed to create a Mapping object. It’s attributes describe the information accumulated so far.

mapping

Type

collections.defaultdict

blocks_from

Type

None or vermouth.molecule.Block

blocks_to

Type

None or vermouth.molecule.Block

ff_from

Type

None or vermouth.forcefield.ForceField

ff_to

Type

None or vermouth.forcefield.ForceField

names

Type

list

references

Type

dict

add_block_from(block)

Add a block to blocks_from. In addition, apply any ‘replace’ operation described by nodes on themselves:

{'atomname': 'C', 'charge': 0, 'replace': {'charge': -1}}

becomes:

{'atomname': 'C', 'charge': -1}

Parameters

block (vermouth.molecule.Block) – The block to add.

add_block_to(block)

Add a block to blocks_to.

Parameters

block (vermouth.molecule.Block) – The block to add.

add_edge_from(attrs1, attrs2, edge_attrs)

Add a single edge to blocks_from between two nodes in blocks_from described by attrs1 and attrs2. The nodes described should not be the same.

Parameters

• attrs1 (dict[str]) – The attributes that uniquely describe a node in blocks_from

• attrs2 (dict[str]) – The attributes that uniquely describe a node in blocks_from

• edge_attrs (dict[str]) – The attributes that should be assigned to the new edge.

add_edge_to(attrs1, attrs2, edge_attrs)

Add a single edge to blocks_to between two nodes in blocks_to described by attrs1 and attrs2. The nodes described should not be the same.

Parameters

• attrs1 (dict[str]) – The attributes that uniquely describe a node in blocks_to

• attrs2 (dict[str]) – The attributes that uniquely describe a node in blocks_to

• edge_attrs (dict[str]) – The attributes that should be assigned to the new edge.

add_mapping(attrs_from, attrs_to, weight)

Add part of a mapping to mapping. attrs_from uniquely describes a node in blocks_from and attrs_to a node in blocks_to. Adds a mapping between those nodes with the given weight.

Parameters

• attrs_from (dict[str]) – The attributes that uniquely describe a node in blocks_from

• attrs_to (dict[str]) – The attributes that uniquely describe a node in blocks_to

• weight (float) – The weight associated with this partial mapping.

add_name(name)

Add a name to the mapping.

Parameters

name (str) – The name to add

add_node_from(attrs)

Add a single node to blocks_from.

Parameters

attrs (dict[str]) – The attributes the new node should have.

add_node_to(attrs)

Add a single node to blocks_to.

Parameters

attrs (dict[str]) – The attributes the new node should have.

add_reference(attrs_to, attrs_from)

Add a reference to references.

Parameters

• attrs_to (dict[str]) – The attributes that uniquely describe a node in blocks_to

• attrs_from (dict[str]) – The attributes that uniquely describe a node in blocks_from

from_ff(ff_name)

Sets ff_from

Parameters

ff_name –

get_mapping(type)

Instantiate a Mapping object with the information accumulated so far, and return it.

Returns

The mapping object made from the accumulated information.

Return type

Mapping

reset()

Reset the object to a clean initial state.

to_ff(ff_name)

Sets ff_to

Parameters

ff_name –

class vermouth.map_parser.MappingDirector(force_fields, builder=None)

Bases: vermouth.parser_utils.SectionLineParser

A director in charge of parsing the new mapping format. It constructs a new Mapping object by calling methods of it’s builder (default MappingBuilder) with the correct arguments.

Parameters

• force_fields (dict[str, ForceField]) – Dict of known force fields.

• builder (MappingBuilder) –

builder

The builder used to build the Mapping object. By default MappingBuilder.

identifiers

All known identifiers at this point. The key is the actual identifier, prefixed with either “to_” or “from_”, and the values are the associated node attributes.

Type

dict[str, dict[str]]

section

The name of the section currently being processed.

Type

str

from_ff

The name of the forcefield from which this mapping describes a transfomation.

Type

str

to_ff

The name of the forcefield to which this mapping describes a transfomation.

Type

str

macros

A dictionary of known macros.

Type

dict[str, str]

COMMENT_CHAR = ';'

The character that starts a comment.

METH_DICT = {('block', 'from'): (<function MappingDirector._ff>, {'direction': 'from'}), ('block', 'from blocks'): (<function MappingDirector._blocks>, {'direction': 'from', 'map_type': 'block'}), ('block', 'from edges'): (<function MappingDirector._edges>, {'direction': 'from'}), ('block', 'from nodes'): (<function MappingDirector._nodes>, {'direction': 'from'}), ('block', 'mapping'): (<function MappingDirector._mapping>, {}), ('block', 'reference atoms'): (<function MappingDirector._reference_atoms>, {}), ('block', 'to'): (<function MappingDirector._ff>, {'direction': 'to'}), ('block', 'to blocks'): (<function MappingDirector._blocks>, {'direction': 'to', 'map_type': 'block'}), ('block', 'to edges'): (<function MappingDirector._edges>, {'direction': 'to'}), ('block', 'to nodes'): (<function MappingDirector._nodes>, {'direction': 'to'}), ('macros',): (<function SectionLineParser._macros>, {}), ('modification', 'from'): (<function MappingDirector._ff>, {'direction': 'from'}), ('modification', 'from blocks'): (<function MappingDirector._blocks>, {'direction': 'from', 'map_type': 'modification'}), ('modification', 'from edges'): (<function MappingDirector._edges>, {'direction': 'from'}), ('modification', 'from nodes'): (<function MappingDirector._nodes>, {'direction': 'from'}), ('modification', 'mapping'): (<function MappingDirector._mapping>, {}), ('modification', 'reference atoms'): (<function MappingDirector._reference_atoms>, {}), ('modification', 'to'): (<function MappingDirector._ff>, {'direction': 'to'}), ('modification', 'to blocks'): (<function MappingDirector._blocks>, {'direction': 'to', 'map_type': 'modification'}), ('modification', 'to edges'): (<function MappingDirector._edges>, {'direction': 'to'}), ('modification', 'to nodes'): (<function MappingDirector._nodes>, {'direction': 'to'}), ('molecule',): (<function MappingDirector._molecule>, {})}

NO_FETCH_BLOCK = '!'

The character that specifies no block should be fetched automatically.

RESIDUE_ATOM_SEP = ':'

The character that separates a residue identifier from an atomname.

RESNAME_NUM_SEP = '#'

The character that separates a resname from a resnumber in shorthand block formats.

SECTION_ENDS = ['block', 'modification']

finalize_section(previous_section, ended_section)

Wraps up parsing of a single mapping.

Parameters

• previous_section (collections.abc.Sequence[str]) – The previously parsed section.

• ended_section (collections.abc.Iterable[str]) – The just finished sections.

Returns

The accumulated mapping if the mapping is complete, None otherwise.

Return type

Mapping or None

vermouth.map_parser.parse_mapping_file(filepath, force_fields)

Parses a mapping file.

Parameters

• filepath (str) – The path of the file to parse.

• force_fields (dict[str, ForceField]) – Dict of known forcefields

Returns

A list of all mappings described in the file.

Return type

list[Mapping]