molfoundry.DGVertexMapper

molfoundry.DGVertexMapper#

class molfoundry.DGVertexMapper(edge, limit=1, vertex_filter=None)[source]#

Bases: TSObject

Enumerates the atom-atom maps of a hyperedge.

A derivation records one map per match, but relabeling a map by an automorphism of the educts or of the products gives another valid map, so the full set is an orbit whose size is the product of two automorphism group orders — easily thousands for ordinary molecules. Maps are therefore produced one at a time as they are iterated, and never more than limit of them:

for m in DGVertexMapper(edge, limit=10):
    for entry in m:
        print(entry)

No map is yielded twice, however it was reached. The enumeration is single-pass: a mapper that has run out stays exhausted, so build a new one to start over.

When only some atoms matter, pass vertex_filter — a predicate on the Vertex atoms of the hyperedge’s compounds. Only maps that differ on the accepted atoms are then enumerated, and every automorphism that fixes all of them is skipped, so the orbit shrinks to the accepted atoms’ own symmetry. Tracing carbon through a hydrogen-rich network this way avoids the hydrogen permutations entirely — an ethanol whose 12-map orbit is all hydrogen relabelings collapses to a single map:

for m in DGVertexMapper(edge, limit=1000,
                        vertex_filter=lambda v: v.atomId.symbol == 'C'):
    ...

The maps produced are still complete (every atom is present); the atoms the filter rejects are simply frozen at one representative labeling rather than permuted. vertex_filter is evaluated at most once per atom.

Parameters:
property limit: int#
property hyperEdge: HyperEdge#