schrodinger.application.matsci.network_cg_mapping.model module

Data contracts for automated coarse-grained mapping of atomic networks.

This module deliberately contains no mapping algorithms and no Schrodinger Structure dependencies. It defines the values exchanged by structure conversion, repeat detection, graph partitioning, and bead typing.

Copyright Schrodinger, LLC. All rights reserved.

exception schrodinger.application.matsci.network_cg_mapping.model.NetworkMappingError

Bases: ValueError

Raised when an atomic network cannot be represented or mapped.

class schrodinger.application.matsci.network_cg_mapping.model.AtomLabel(atomic_number: int, formal_charge: int = 0)

Bases: object

Chemical attributes used when comparing atomic-network sites.

Parameters:

• atomic_number (int) – Atomic number of the element

• formal_charge (int) – Formal atomic charge

atomic_number: int

formal_charge: int = 0

__init__(atomic_number: int, formal_charge: int = 0) → None

class schrodinger.application.matsci.network_cg_mapping.model.AtomicEdge(atom1: int, atom2: int, image_shift: Tuple[int, int, int], bond_order: float)

Bases: object

A chemical bond and the periodic image containing its second atom.

Parameters:

• atom1 (int) – ID of the first stored atom

• atom2 (int) – ID of the second stored atom

• image_shift (tuple[int, int, int]) – Input-PBC image containing atom2 relative to atom1

• bond_order (float) – Chemical bond order

atom1: int

atom2: int

image_shift: Tuple[int, int, int]

bond_order: float

__init__(atom1: int, atom2: int, image_shift: Tuple[int, int, int], bond_order: float) → None

class schrodinger.application.matsci.network_cg_mapping.model.AtomicNetwork(atom_ids: Sequence[int], positions: Mapping[int, ndarray], labels: Mapping[int, AtomLabel], edges: Sequence[AtomicEdge], box: Optional[ndarray] = None, aromatic_bonds: FrozenSet[Tuple[int, int]] = frozenset({}))

Bases: object

Neutral representation of an attributed, possibly periodic network.

Parameters:

• atom_ids (collections.abc.Sequence[int]) – Stable IDs of the stored atoms

• positions (collections.abc.Mapping[int, numpy.ndarray]) – Cartesian position of each stored atom in angstroms

• labels (collections.abc.Mapping[int, AtomLabel]) – Chemical comparison label for each stored atom

• edges (collections.abc.Sequence[AtomicEdge]) – Chemical bonds with explicit input-PBC image shifts

• box (numpy.ndarray or None) – Input-PBC box vectors stored as rows, or None for a nonperiodic network

• aromatic_bonds (frozenset[tuple[int, int]]) – Stored atom pairs perceived as aromatic

atom_ids: Sequence[int]

positions: Mapping[int, ndarray]

labels: Mapping[int, AtomLabel]

edges: Sequence[AtomicEdge]

box: Optional[ndarray] = None

aromatic_bonds: FrozenSet[Tuple[int, int]] = frozenset({})

property is_periodic

Return whether the network has a periodic box.

validate()

Validate the atomic-network data contract.

Raises:

NetworkMappingError – if the network data contract is violated.

__init__(atom_ids: Sequence[int], positions: Mapping[int, ndarray], labels: Mapping[int, AtomLabel], edges: Sequence[AtomicEdge], box: Optional[ndarray] = None, aromatic_bonds: FrozenSet[Tuple[int, int]] = frozenset({})) → None

class schrodinger.application.matsci.network_cg_mapping.model.TranslationMatch(vector: ndarray, atom_map: Mapping[int, int], image_shift_by_atom: Mapping[int, Tuple[int, int, int]], atom_coverage: float, topology_coverage: float, rms_error: float, score: float)

Bases: object

A candidate translation supported by atomic correspondences.

For each source atom i in atom_map, translating its position by vector places it near a chemically compatible periodic image of the stored atom atom_map[i]:

position[i] + vector
    ~= position[atom_map[i]] + image_shift_by_atom[i] @ box

atom_map identifies the matching atom in the stored structure. Matched atoms have compatible chemistry and complete local bonded-neighbor signatures, preventing finite translations from merging differently coordinated boundary and interior atoms. image_shift_by_atom identifies which image of the target atom is matched. Image shifts use the three input-PBC box vectors, not the subsequently detected primitive repeat basis. They are zero for nonperiodic inputs.

A match may cover only part of a finite or imperfect network. atom_coverage records the matched atom fraction and topology_coverage records how much of the matched bond topology is preserved. rms_error measures the positional mismatch, while score provides a combined value for comparing candidate translations. Repeat detection may combine several compatible matches to construct a primitive translation basis.

Parameters:

• vector (numpy.ndarray) – Candidate Cartesian translation vector in angstroms

• atom_map (collections.abc.Mapping[int, int]) – Matched stored atom for each translated source atom

• image_shift_by_atom (collections.abc.Mapping[int, tuple[int, int, int]]) – Input-PBC image of each matched target atom

• atom_coverage (float) – Fraction of stored atoms matched by the translation

• topology_coverage (float) – Fraction of matched bond topology preserved

• rms_error (float) – Root-mean-square Cartesian matching error in angstroms

• score (float) – Combined quality score used to compare translations

vector: ndarray

atom_map: Mapping[int, int]

image_shift_by_atom: Mapping[int, Tuple[int, int, int]]

atom_coverage: float

topology_coverage: float

rms_error: float

score: float

__init__(vector: ndarray, atom_map: Mapping[int, int], image_shift_by_atom: Mapping[int, Tuple[int, int, int]], atom_coverage: float, topology_coverage: float, rms_error: float, score: float) → None

class schrodinger.application.matsci.network_cg_mapping.model.PeriodicEdge(site1: int, site2: int, image_shift: Sequence[int], bond_order: float, support: int)

Bases: object

A bond in the translation-labeled quotient graph.

Each site represents a translation orbit: an equivalence class of atoms related by primitive lattice translations. This is not necessarily an orbit under the crystal’s full space group. image_shift identifies the primitive-cell image containing site2 relative to the cell containing site1. Its dimensionality equals the rank of the detected primitive repeat basis.

Parameters:

• site1 (int) – First quotient-site ID

• site2 (int) – Second quotient-site ID

• image_shift (Cell) – Primitive-cell image containing site2 relative to site1

• bond_order (float) – Chemical bond order

• support (int) – Number of stored atomic edges represented by this edge

site1: int

site2: int

image_shift: Sequence[int]

bond_order: float

support: int

__init__(site1: int, site2: int, image_shift: Sequence[int], bond_order: float, support: int) → None

class schrodinger.application.matsci.network_cg_mapping.model.RepeatModel(rank: int, winding_rank: int, vectors: ndarray, site_by_atom: Mapping[int, int], cell_by_atom: Mapping[int, Sequence[int]], core_sites: FrozenSet[int], quotient_edges: Sequence[PeriodicEdge], translations: Sequence[TranslationMatch], supercell_matrix: ndarray, confidence: float, is_periodic_input: bool, diagnostics: Sequence[str] = ())

Bases: object

A detected translation lattice and its finite quotient representation.

The model decomposes each stored atom into a representative quotient site and an integer primitive-cell coordinate:

atom -> (site_by_atom[atom], cell_by_atom[atom])

Atoms assigned the same site belong to the same translation orbit. rank is the complete repeat rank, while winding_rank counts only directions in which bonded cycles traverse the input PBC. The repeat rank may therefore exceed the winding rank when a structure has additional finite but well-supported repeat directions. vectors contains the Cartesian primitive translations, with shape (rank, 3), while every value in cell_by_atom has length rank. Consequently, an atom position can be reconstructed, up to the chosen site and lattice gauges, as its representative site position plus its cell coordinate multiplied by vectors.

core_sites identifies the well-supported repeated motif; finite boundaries, defects, or sparse decorations need not belong to that core. quotient_edges records the motif’s bonds, including primitive-cell shifts for bonds crossing its boundary. Together these fields represent the infinite repeated connectivity with a finite translation-labeled graph.

translations contains the validated matches supporting the detected basis. supercell_matrix has shape (winding_rank, rank) and expresses the input periodic windings in that primitive basis. It has zero rows for a finite, non-PBC structure. is_periodic_input therefore describes the input boundary conditions, whereas rank describes the dimensionality of the detected repeat. confidence summarizes the supporting matches, and diagnostics records repeat-detection fallbacks or limitations.

Parameters:

• rank (int) – Number of independent primitive translation directions

• winding_rank (int) – Number of repeat directions with nonzero input-PBC cycle winding

• vectors (numpy.ndarray) – Cartesian primitive translations stored as rows

• site_by_atom (collections.abc.Mapping[int, int]) – Quotient-site ID assigned to each stored atom

• cell_by_atom (collections.abc.Mapping[int, Cell]) – Primitive-cell coordinate assigned to each stored atom

• core_sites (frozenset[int]) – Well-supported quotient sites in the repeated motif

• quotient_edges (collections.abc.Sequence[PeriodicEdge]) – Translation-labeled bonds between quotient sites

• translations (collections.abc.Sequence[TranslationMatch]) – Validated matches supporting the repeat lattice

• supercell_matrix (numpy.ndarray) – Input-PBC windings expressed in the primitive repeat basis

• confidence (float) – Aggregate quality of the selected basis translations

• is_periodic_input (bool) – Whether the atomic input had a periodic box

• diagnostics (collections.abc.Sequence[str]) – Repeat-detection fallbacks or limitations

rank: int

winding_rank: int

vectors: ndarray

site_by_atom: Mapping[int, int]

cell_by_atom: Mapping[int, Sequence[int]]

core_sites: FrozenSet[int]

quotient_edges: Sequence[PeriodicEdge]

translations: Sequence[TranslationMatch]

supercell_matrix: ndarray

confidence: float

is_periodic_input: bool

diagnostics: Sequence[str] = ()

__init__(rank: int, winding_rank: int, vectors: ndarray, site_by_atom: Mapping[int, int], cell_by_atom: Mapping[int, Sequence[int]], core_sites: FrozenSet[int], quotient_edges: Sequence[PeriodicEdge], translations: Sequence[TranslationMatch], supercell_matrix: ndarray, confidence: float, is_periodic_input: bool, diagnostics: Sequence[str] = ()) → None

class schrodinger.application.matsci.network_cg_mapping.model.MappingPartition(groups: Sequence[Sequence[int]], template_group_ids: Sequence[Optional[int]], mapping_cell: Sequence[Sequence[int]] = (), mapping_origin: Sequence[int] = (), template_groups: Sequence[Sequence[Tuple[int, Sequence[int]]]] = (), score: float = 0.0, diagnostics: Sequence[str] = ())

Bases: object

Connected atom groups and their relationship to the repeat template.

groups is the final partition of stored atom IDs into CG beads. template_groups describes the corresponding abstract partition of one mapping cell using (quotient site, primitive-cell coordinate) nodes. Lifting those template groups through a RepeatModel produces complete translated groups in groups.

template_group_ids is aligned with groups. An integer identifies the template group from which a concrete atom group was lifted; translated groups with the same ID therefore come from the same template group. None identifies a residual group partitioned directly from unmatched atoms, such as an incomplete boundary region of a finite network.

mapping_cell gives the lower-triangular row-Hermite basis of the repeat block in primitive-cell coordinates. Its determinant is the number of primitive cells in that block. mapping_origin gives its phase in primitive- cell coordinates. They are empty for a rank-zero direct graph partition, where all groups are residual and template_groups is also empty. score ranks candidate partitions, while diagnostics records fallbacks or limitations.

Parameters:

• groups (collections.abc.Sequence[AtomGroup]) – Final partition of stored atoms into CG groups

• template_group_ids (collections.abc.Sequence[int or None]) – Template-group ID associated with each concrete group, or None for a residual group

• mapping_cell (MappingCell) – Integer row-basis of the repeat block in primitive- cell coordinates

• mapping_origin (Cell) – Phase of the mapping cell in primitive coordinates

• template_groups (collections.abc.Sequence[TemplateGroup]) – Abstract partition of one mapping cell

• score (float) – Quality score for this partition

• diagnostics (collections.abc.Sequence[str]) – Partitioning fallbacks or limitations

groups: Sequence[Sequence[int]]

template_group_ids: Sequence[Optional[int]]

mapping_cell: Sequence[Sequence[int]] = ()

mapping_origin: Sequence[int] = ()

template_groups: Sequence[Sequence[Tuple[int, Sequence[int]]]] = ()

score: float = 0.0

diagnostics: Sequence[str] = ()

property residual_groups

Return groups that were not lifted from a repeat template.

__init__(groups: Sequence[Sequence[int]], template_group_ids: Sequence[Optional[int]], mapping_cell: Sequence[Sequence[int]] = (), mapping_origin: Sequence[int] = (), template_groups: Sequence[Sequence[Tuple[int, Sequence[int]]]] = (), score: float = 0.0, diagnostics: Sequence[str] = ()) → None

class schrodinger.application.matsci.network_cg_mapping.model.NetworkMapping(repeat: RepeatModel, partition: MappingPartition, bead_type_by_group: Sequence[int], diagnostics: Sequence[str] = ())

Bases: object

Neutral result of mapping one selected atomic network.

repeat describes the detected translation lattice and finite quotient, while partition contains the concrete atom groups produced from that representation. bead_type_by_group is aligned with partition.groups and assigns each group a neutral integer type ID. These IDs describe chemical bead equivalence; they are distinct from MappingPartition.template_group_ids, which describe how groups were generated. Different template groups may therefore share a bead type, and residual groups without a template ID still receive one.

This result contains no final particle names, atom grouping properties, or materialized CG structure. A downstream output layer can translate its type IDs and atom groups into those representations. diagnostics records information about the completed mapping as a whole. Messages specific to repeat detection or partitioning remain on their respective objects.

Parameters:

• repeat (RepeatModel) – Detected translation lattice and quotient representation

• partition (MappingPartition) – Concrete and template CG atom groups

• bead_type_by_group (collections.abc.Sequence[int]) – Neutral bead-type ID aligned with each concrete group

• diagnostics (collections.abc.Sequence[str]) – Messages about the completed network mapping

repeat: RepeatModel

partition: MappingPartition

bead_type_by_group: Sequence[int]

diagnostics: Sequence[str] = ()

property groups

Return the mapped atom groups.

__init__(repeat: RepeatModel, partition: MappingPartition, bead_type_by_group: Sequence[int], diagnostics: Sequence[str] = ()) → None