schrodinger.application.matsci.network_cg_mapping.mapping module

Construct repeat-covariant coarse-grained partitions of atomic networks.

For a repeated network, the mapping cell is partitioned once in quotient-site coordinates and that template is lifted across the stored atoms. The template retains edges crossing its periodic boundary so a finite bead may straddle an arbitrary mapping-cell boundary. Complete translated copies share a template-group ID. Atoms that do not form complete copies, including non-core atoms, are partitioned directly into residual groups. Rank-zero networks are partitioned entirely in the atomic graph.

This module assigns atoms to beads, but deliberately does not assign chemical bead types or construct a Schrodinger Structure. Those responsibilities belong to the automated-CG integration layer.

Copyright Schrodinger, LLC. All rights reserved.

class schrodinger.application.matsci.network_cg_mapping.mapping.MappingCellCandidate(score: float, mapping_cell: Sequence[Sequence[int]], graph: MultiGraph, groups: Sequence[Sequence[Tuple[int, Sequence[int]]]])

Bases: NamedTuple

A mapping-cell template and the values used to rank it.

Parameters:

  • score – Template partition score, including cell-size and shape penalties

  • mapping_cell – Integer row-basis of the mapping cell in primitive- cell coordinates

  • graph – Wrapped, shift-labelled graph induced by the mapping cell

  • groups – Connected partition of the mapping-cell graph

score: float

Alias for field number 0

mapping_cell: Sequence[Sequence[int]]

Alias for field number 1

graph: MultiGraph

Alias for field number 2

groups: Sequence[Sequence[Tuple[int, Sequence[int]]]]

Alias for field number 3

class schrodinger.application.matsci.network_cg_mapping.mapping.LiftResult(complete_atom_count: int, phase: Sequence[int], groups: Sequence[Sequence[int]], template_group_ids: Sequence[int], residual_atom_ids: frozenset[int])

Bases: NamedTuple

One mapping-cell phase lifted onto the stored atomic network.

Parameters:

  • complete_atom_count – Number of atoms in complete template groups

  • phase – Mapping-cell origin in primitive-cell coordinates

  • groups – Complete concrete atom groups

  • template_group_ids – Template-group ID for each concrete group

  • residual_atom_ids – Atoms not included in a complete template group

complete_atom_count: int

Alias for field number 0

phase: Sequence[int]

Alias for field number 1

groups: Sequence[Sequence[int]]

Alias for field number 2

template_group_ids: Sequence[int]

Alias for field number 3

residual_atom_ids: frozenset[int]

Alias for field number 4

schrodinger.application.matsci.network_cg_mapping.mapping.atomic_graph(network)

Return the simple stored-atom connectivity graph.

Periodic image shifts and parallel image bonds do not affect whether a proposed bead is connected, so all edges between the same stored atoms collapse into one graph edge.

Parameters:

network (AtomicNetwork) – Atomic network whose connectivity should be represented

Return type:

networkx.Graph

Returns:

Simple graph containing every stored atom

schrodinger.application.matsci.network_cg_mapping.mapping.quotient_site_gauge(repeat_model)

Return a deterministic connected gauge for the core quotient sites.

A quotient-site gauge chooses which primitive-cell image represents each site. The returned offset moves each current representative to a canonical one. A deterministic spanning forest makes every selected tree edge have zero image shift. This removes arbitrary input-gauge choices before the mapping template is constructed.

Parameters:

repeat_model (RepeatModel) – Detected repeat model to normalize

Return type:

dict[int, model.Cell]

Returns:

Primitive-cell representative offset for each core quotient site

schrodinger.application.matsci.network_cg_mapping.mapping.normalized_edge_shift(edge, site_gauge)

Return an edge shift after applying a quotient-site gauge.

Parameters:

  • edge (PeriodicEdge) – Quotient edge whose shift should be transformed

  • site_gauge (collections.abc.Mapping[int, model.Cell]) – Representative offset for each quotient site

Return type:

model.Cell

Returns:

Primitive-cell shift in the normalized quotient-site gauge

schrodinger.application.matsci.network_cg_mapping.mapping.template_graph(repeat_model, mapping_cell, site_gauge=None)

Return the wrapped core graph inside one mapping cell.

Quotient edges are lifted into every primitive cell represented by mapping_cell. An edge leaving the mapping cell wraps to the corresponding local node, while cell_shift retains the primitive-cell displacement and block_shift records the mapping-cell image crossed by the edge. Parallel wrapped edges remain distinct.

Parameters:

  • repeat_model (RepeatModel) – Detected repeat model whose core should be lifted

  • mapping_cell (model.MappingCell) – Integer row-basis of the mapping cell in primitive- cell coordinates

  • site_gauge (collections.abc.Mapping[int, model.Cell] or None) – Canonical quotient-site gauge, or None to construct it

Return type:

networkx.MultiGraph

Returns:

Periodic graph of (quotient site, local cell) nodes

schrodinger.application.matsci.network_cg_mapping.mapping.oriented_cell_shift(node, edge_data)

Return a wrapped edge’s primitive-cell shift away from node.

Parameters:

  • node (model.TemplateNode) – Endpoint from which the edge is being traversed

  • edge_data (collections.abc.Mapping) – Attributes stored on a wrapped template edge

Return type:

model.Cell

Returns:

Primitive-cell shift from node to the other endpoint

schrodinger.application.matsci.network_cg_mapping.mapping.unwrap_template_group(graph, group)

Return one finite connected lift of a wrapped template group.

Each mapping-cell node occurs once in group, but the returned primitive- cell coordinates may lie outside the nominal mapping cell. They record how the finite group crosses its arbitrary periodic boundary.

Parameters:

  • graph (networkx.MultiGraph) – Wrapped, shift-labelled mapping-cell graph

  • group (collections.abc.Collection[model.TemplateNode]) – Connected mapping-cell nodes to lift

Return type:

model.TemplateGroup

Returns:

Group nodes with unwrapped primitive-cell coordinates

schrodinger.application.matsci.network_cg_mapping.mapping.partition_periodic_template(graph, scale)

Partition and finitely unwrap a wrapped mapping-cell graph.

Parameters:

  • graph (networkx.MultiGraph) – Wrapped, shift-labelled mapping-cell graph

  • scale (int) – Requested number of nodes per group

Return type:

tuple(model.TemplateGroup)

Returns:

Connected finite groups covering the periodic template nodes

schrodinger.application.matsci.network_cg_mapping.mapping.adjacent_group_pairs(graph, groups)

Return partition-group pairs connected by graph edges.

Parameters:

  • graph (networkx.Graph) – Connectivity graph containing the partitioned nodes

  • groups (collections.abc.Sequence[collections.abc.Collection]) – Node groups forming a complete graph partition

Return type:

set[tuple[int, int]]

Returns:

Canonically ordered pairs of adjacent group indices

schrodinger.application.matsci.network_cg_mapping.mapping.refine_partition_by_joins(graph, groups, scale, periodic_template=False)

Join adjacent graph groups whenever doing so improves their score.

For a periodic template, each operation joins two complete template groups, so lifting the refined partition applies the same join to every translated copy. Such candidates are scored using their finite unwrapped representation, including any mapping-cell boundary crossing. Direct graph groups are scored in their stored connectivity graph.

Parameters:

  • graph (networkx.Graph or networkx.MultiGraph) – Stored connectivity graph or wrapped mapping-cell graph

  • groups (collections.abc.Iterable[collections.abc.Collection]) – Initial partition of the graph nodes

  • scale (int) – Requested number of nodes per group

  • periodic_template (bool) – Whether graph is a wrapped periodic template

Return type:

tuple(tuple)

Returns:

Refined graph groups

schrodinger.application.matsci.network_cg_mapping.mapping.positioned_group_graph(graph, group)

Return the concrete connectivity of an unwrapped template group.

Parameters:

  • graph (networkx.MultiGraph) – Wrapped, shift-labelled mapping-cell graph

  • group (model.TemplateGroup) – Unwrapped finite template group

Return type:

networkx.Graph

Returns:

Graph containing only edges internal to this finite group lift

schrodinger.application.matsci.network_cg_mapping.mapping.template_partition_score(groups, scale, graph)

Return the score of an unwrapped periodic template partition.

Parameters:

  • groups (collections.abc.Iterable[model.TemplateGroup]) – Proposed finite template groups

  • scale (int) – Requested number of nodes per group

  • graph (networkx.MultiGraph) – Wrapped mapping-cell graph containing the groups

Return type:

float

Returns:

Total size and finite-lift compactness penalty

schrodinger.application.matsci.network_cg_mapping.mapping.balanced_group_sizes(num_nodes, num_groups)

Return group sizes that differ by at most one node.

Parameters:

  • num_nodes (int) – Number of nodes to distribute

  • num_groups (int) – Number of nonempty groups

Return type:

tuple(int)

Returns:

Balanced group sizes whose sum is num_nodes

schrodinger.application.matsci.network_cg_mapping.mapping.group_size_penalty(group_size, scale)

Return the asymmetric size penalty for one group.

Parameters:

  • group_size (int) – Number of nodes in the group

  • scale (int) – Requested number of nodes per group

Return type:

int

Returns:

Squared size error, with extra weight for oversized groups

schrodinger.application.matsci.network_cg_mapping.mapping.group_score(group, scale, graph)

Return the partition score contribution of one group.

Parameters:

  • group (collections.abc.Collection) – Connected nodes assigned to one group

  • scale (int) – Requested number of nodes per group

  • graph (networkx.Graph) – Graph containing the group

Return type:

float

Returns:

Size and compactness penalty for the group

schrodinger.application.matsci.network_cg_mapping.mapping.partition_score(groups, scale, graph)

Return the additive score of a complete graph partition.

Parameters:

  • groups (collections.abc.Iterable[collections.abc.Collection]) – Proposed graph partition containing connected groups

  • scale (int) – Requested number of nodes per group

  • graph (networkx.Graph) – Graph being partitioned

Return type:

float

Returns:

Total size and compactness penalty

schrodinger.application.matsci.network_cg_mapping.mapping.partition_connected_graph(graph, scale)

Return a deterministic connected partition of one component.

Parameters:

  • graph (networkx.Graph) – Connected graph to partition

  • scale (int) – Requested number of nodes per group

Return type:

tuple(tuple)

Returns:

Connected groups covering graph

Raises:

ValueError – If graph contains more than one connected component

schrodinger.application.matsci.network_cg_mapping.mapping.partition_graph(graph, scale, join_refinement=True)

Partition every connected component into connected groups.

Parameters:

  • graph (networkx.Graph) – Graph to partition

  • scale (int) – Requested number of nodes per group

  • join_refinement (bool) – Whether to apply score-improving group joins

Return type:

tuple(tuple)

Returns:

Connected groups covering graph

schrodinger.application.matsci.network_cg_mapping.mapping.factor_tuples(rank, product, prefix=())

Yield positive tuples of a requested length and product.

Parameters:

  • rank (int) – Number of remaining tuple entries

  • product (int) – Product available to the remaining entries

  • prefix (collections.abc.Sequence[int]) – Entries selected in preceding dimensions

Return type:

collections.abc.Iterator[tuple(int)]

Returns:

Positive tuples having the requested complete product

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_cell_matrices(rank, size)

Yield row-Hermite mapping cells with a requested lattice index.

Every rank-dimensional integer sublattice has one row-Hermite normal-form basis. Enumerating these bases therefore considers diagonal mapping cells, skew mapping cells, and every other sublattice containing size primitive cells exactly once.

Parameters:

  • rank (int) – Number of primitive repeat directions

  • size (int) – Number of primitive cells in each mapping cell

Return type:

collections.abc.Iterator[model.MappingCell]

Returns:

Lower-triangular row-Hermite mapping-cell matrices

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_cell_size(mapping_cell)

Return the number of primitive cells in a mapping cell.

Parameters:

mapping_cell (model.MappingCell) – Row-Hermite mapping-cell matrix

Return type:

int

Returns:

Integer lattice index of the mapping cell

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_cell_coordinates(mapping_cell)

Return canonical primitive-cell representatives of a mapping cell.

Parameters:

mapping_cell (model.MappingCell) – Row-Hermite mapping-cell matrix

Return type:

tuple(model.Cell)

Returns:

Representatives of the primitive-cell cosets

schrodinger.application.matsci.network_cg_mapping.mapping.reduce_mapping_cell_coordinate(cell, mapping_cell)

Reduce a primitive-cell coordinate modulo a mapping cell.

The result satisfies cell = local_cell + block @ mapping_cell. The canonical local cell identifies a primitive cell inside the mapping cell, while block identifies the translated copy of that mapping cell.

Parameters:

  • cell (collections.abc.Sequence[int]) – Primitive-cell coordinate to reduce

  • mapping_cell (model.MappingCell) – Lower-triangular row-Hermite mapping-cell matrix

Return type:

tuple(model.Cell, model.Cell)

Returns:

Canonical local-cell coordinate and mapping-block coordinate

schrodinger.application.matsci.network_cg_mapping.mapping.is_commensurate_mapping_cell(repeat_model, mapping_cell)

Return whether a mapping cell tiles the periodic input supercell.

Parameters:

  • repeat_model (RepeatModel) – Repeat model containing the input supercell matrix

  • mapping_cell (model.MappingCell) – Candidate row-Hermite mapping-cell matrix

Return type:

bool

Returns:

Whether every periodic supercell row belongs to the mapping-cell lattice

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_cell_shape(mapping_cell)

Return a basis-shape measure that is zero for an isotropic cell.

Parameters:

mapping_cell (model.MappingCell) – Row-Hermite mapping-cell matrix

Return type:

float

Returns:

Spread of the mapping-cell matrix’s singular values

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_cell_candidates(repeat_model, scale)

Return bounded mapping-cell candidates ordered by quality.

Candidate mapping cells are integer sublattices of the primitive repeat lattice. For periodic directions, the input supercell translations must belong to the candidate lattice so translated mapping groups close consistently across its PBC.

Parameters:

  • repeat_model (RepeatModel) – Repeat model to partition

  • scale (int) – Requested number of atoms per group

Return type:

tuple(MappingCellCandidate)

Returns:

Candidate cells ordered from best to worst

schrodinger.application.matsci.network_cg_mapping.mapping.canonical_periodic_block(block, block_lattice)

Return a stable key for a block modulo input-PBC translations.

The periodic block lattice may have lower rank than the complete repeat basis, as for a finite slab with two periodic directions and one finite repeat direction. Fractional coordinates in its row span are reduced modulo one, while the component outside that span is retained.

Parameters:

  • block (collections.abc.Sequence[int]) – Mapping-block coordinate

  • block_lattice (numpy.ndarray or None) – Input-PBC translations in mapping-block coordinates

Return type:

tuple(int)

Returns:

Quantized key for the equivalent periodic block

schrodinger.application.matsci.network_cg_mapping.mapping.mapping_block_lattice(repeat_model, mapping_cell)

Return input-PBC translations in mapping-block coordinates.

Parameters:

  • repeat_model (RepeatModel) – Repeat model containing the supercell matrix

  • mapping_cell (model.MappingCell) – Row-Hermite mapping-cell matrix

Return type:

numpy.ndarray or None

Returns:

Periodic block-lattice rows, or None for finite inputs

schrodinger.application.matsci.network_cg_mapping.mapping.lift_template_phases(network, repeat_model, mapping_cell, template_groups, graph)

Lift every mapping-cell origin phase onto the stored atoms.

A lifted group is complete only when it contains every abstract template node and is connected in the actual atomic graph. Incomplete copies are returned as residual atoms rather than forcing a broken translation- symmetric bead.

Parameters:

  • network (AtomicNetwork) – Atomic network being mapped

  • repeat_model (RepeatModel) – Repeat assignments for the atomic network

  • mapping_cell (model.MappingCell) – Row-Hermite mapping-cell matrix

  • template_groups (collections.abc.Sequence[model.TemplateGroup]) – Partition of the mapping-cell template

  • graph (networkx.Graph) – Stored-atom connectivity graph

Return type:

tuple(LiftResult)

Returns:

Lifted result for every possible mapping-cell phase

schrodinger.application.matsci.network_cg_mapping.mapping.direct_partition(graph, scale, diagnostics=())

Return a rank-zero-style partition of the actual atomic graph.

Parameters:

  • graph (networkx.Graph) – Stored-atom connectivity graph to partition directly

  • scale (int) – Requested number of atoms per group

  • diagnostics (collections.abc.Sequence[str]) – Messages to retain on the result

Return type:

MappingPartition

Returns:

Connected residual groups covering the network

class schrodinger.application.matsci.network_cg_mapping.mapping.NetworkPartitioner(network, repeat_model, scale)

Bases: object

Partition an atomic network while preserving detected translations.

Core quotient sites are partitioned once inside a periodic mapping cell. Each template group is unwrapped into a finite connected lift before it is copied across the stored primitive cells. The origin phase with the most complete lifted atoms is selected. Non-core atoms and atoms from incomplete template copies are partitioned directly as residual groups.

The implementation searches commensurate integer mapping-cell lattices and assumes that the repeat model describes one coherent translation domain. The constructor validates and retains the shared inputs and builds the atomic connectivity graph once for use throughout partitioning.

__init__(network, repeat_model, scale)

Prepare a network partitioning calculation.

Parameters:

  • network (AtomicNetwork) – Atomic network to partition

  • repeat_model (RepeatModel) – Repeat lattice and quotient graph for network

  • scale (int) – Requested number of network atoms per CG bead

Raises:

NetworkMappingError – If scale or the repeat assignments are invalid

partition()

Construct the repeat-aware atomic partition.

Return type:

MappingPartition

Returns:

Connected concrete groups and their repeat-template relationship

Raises:

NetworkMappingError – If the constructed partition violates a core mapping invariant