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: 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>, {})}

A dict of all known parser methods, mapping section names to the function to be called and the associated keyword arguments.

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]