schrodinger.application.matsci.network_cg_mapping.automapping module¶

Connect neutral network mapping to automated CG Structure workflows.

The network mapping modules identify repeat symmetry and construct atom partitions without assigning user-facing particle names. This module passes completed groups to the shared automated CG bead-typing API, writes the standard grouping properties consumed by CGMapper, and restores PBC bond labels from explicit atomic image shifts after materialization.

class schrodinger.application.matsci.network_cg_mapping.automapping.MappingGroupTypeAssignment(bead_type_by_group, bead_names, particle_info)¶

Bases: tuple

bead_names¶: Alias for field number 1

bead_type_by_group¶: Alias for field number 0

particle_info¶: Alias for field number 2

class schrodinger.application.matsci.network_cg_mapping.automapping.NetworkComponentMappingResult(component_index: int, network: AtomicNetwork, mapping: NetworkMapping, tagged_groups: Sequence[Sequence[int]])¶

Bases: object

Tag-only mapping result for one classified network component.

mapping retains the heavy-atom partition used by the neutral algorithm. tagged_groups is aligned with mapping.groups and additionally contains the explicit hydrogens assigned to each heavy-atom bead.

Parameters:

component_index – Component index from classification
network – Heavy-atom network supplied to repeat partitioning
mapping – Neutral repeat, partition, and bead-type result
tagged_groups – Concrete atom groups written to Structure properties

component_index: int¶

network: AtomicNetwork¶

mapping: NetworkMapping¶

tagged_groups: Sequence[Sequence[int]]¶

__init__(component_index: int, network: AtomicNetwork, mapping: NetworkMapping, tagged_groups: Sequence[Sequence[int]]) → None¶

class schrodinger.application.matsci.network_cg_mapping.automapping.TaggedNetworkMappingResult(components: Sequence[NetworkComponentMappingResult], bead_names: Sequence[str], particle_info: tuple, tagged_structure: object)¶

Bases: object

Network mappings and metadata written by the tag-only API.

components contains only components routed to network mapping. bead_names and particle_info describe the shared automated-CG type table used by all those components. tagged_structure is an atomistic copy with the new network grouping properties; properties on other components are retained.

Parameters:

components – Per-component neutral and tagged mapping results
bead_names – Particle name for each integer bead-type ID
particle_info – SMARTS and charge metadata for each bead type
tagged_structure – Atomistic Structure carrying the combined tags

components: Sequence[NetworkComponentMappingResult]¶

bead_names: Sequence[str]¶

particle_info: tuple¶

tagged_structure: object¶

__init__(components: Sequence[NetworkComponentMappingResult], bead_names: Sequence[str], particle_info: tuple, tagged_structure: object) → None¶

class schrodinger.application.matsci.network_cg_mapping.automapping.NetworkComponentPartition(classification, network, partition, tagged_groups)¶

Bases: tuple

classification¶: Alias for field number 0

network¶: Alias for field number 1

partition¶: Alias for field number 2

tagged_groups¶: Alias for field number 3

schrodinger.application.matsci.network_cg_mapping.automapping.groups_with_attached_hydrogens(struct, groups, component_atom_ids)¶

Return heavy-atom mapping groups with their hydrogens attached.

A hydrogen inherits the bead containing its bonded heavy atom. Hydrogens bonded to heavy atoms in more than one bead are ambiguous and are rejected.

Parameters:

struct (Structure) – Complete atomistic Structure
groups (collections.abc.Sequence[model.AtomGroup]) – Heavy-atom mapping groups
component_atom_ids (collections.abc.Collection[int]) – All atom IDs in the classified component

Return type:

tuple(model.AtomGroup)

Returns:

Groups including hydrogens assigned to their heavy-atom bead

Raises:

NetworkMappingError – If a non-heavy atom cannot be assigned unambiguously

schrodinger.application.matsci.network_cg_mapping.automapping.append_grouping_tags(struct, groups, type_assignment, first_group_number=1, mark_network=False)¶

Append CGMapper grouping properties to selected atom groups.

Parameters:

struct (Structure) – Atomistic Structure to modify in place
groups (collections.abc.Sequence[model.AtomGroup]) – Concrete atom groups to tag
type_assignment (MappingGroupTypeAssignment) – Automated bead types aligned with groups
first_group_number (int) – Number assigned to the first new group
mark_network (bool) – Whether to mark atoms as handled by network mapping

schrodinger.application.matsci.network_cg_mapping.automapping.next_group_number(struct)¶

Return a grouping number that cannot collide with existing tags.

Parameters:: struct (Structure) – Atomistic Structure whose grouping tags should be inspected
Return type:: int
Returns:: One greater than the largest existing group number

schrodinger.application.matsci.network_cg_mapping.automapping.validate_available_tag_atoms(struct, atom_ids)¶

Reject network atoms that already belong to a mapped group.

Parameters:

struct (Structure) – Atomistic Structure containing the selected atoms
atom_ids (collections.abc.Collection[int]) – Atoms that will receive network grouping properties

Raises:

NetworkMappingError – If a selected atom is already tagged

schrodinger.application.matsci.network_cg_mapping.automapping.assign_mapping_group_types(struct, groups, name_generator, known_bead_names=None)¶

Assign automated bead types and metadata to network mapping groups.

Parameters:

struct (Structure) – Atomistic Structure containing the mapped groups
groups (collections.abc.Sequence[model.AtomGroup]) – Complete groups to type and name
name_generator (collections.abc.Callable[[str], str]) – Function receiving canonical SMARTS
known_bead_names (collections.abc.Mapping[str, str] or None) – Established particle name keyed by detailed SMARTS

Return type:

MappingGroupTypeAssignment

Returns:

Automated bead type IDs, names, and particle metadata

Raises:

NetworkMappingError – If known bead names do not map strings to strings

schrodinger.application.matsci.network_cg_mapping.automapping.partition_structure(struct, scale, atom_ids=None, repeat_model=None)¶

Convert and partition a Structure or atom selection.

Parameters:

struct (Structure) – Structure containing the network to partition
scale (int) – Requested number of atoms per CG bead
atom_ids (collections.abc.Collection[int] or None) – Atom indices to include, or None to include every atom
repeat_model (RepeatModel or None) – Precomputed repeat model, or None to detect it

Return type:

tuple[AtomicNetwork, RepeatModel, MappingPartition]

Returns:

Converted network, repeat model, and network partition

schrodinger.application.matsci.network_cg_mapping.automapping.network_mapping_classifications(struct, classifications=None)¶

Return component classifications eligible for network mapping.

Classifications generated here already honor protein-mapping priority. Supplied classifications are checked against the current Structure so that newly identified protein atoms remain on the protein route.

Parameters:

struct (Structure) – Complete atomistic Structure containing all components
classifications (collections.abc.Sequence[ ComponentClassification] or None) – Precomputed component classifications, or None to classify the Structure

Return type:

tuple(ComponentClassification)

Returns:

Classifications selected for network mapping

schrodinger.application.matsci.network_cg_mapping.automapping.partition_network_components(struct, scale, classifications)¶

Partition classified network components and attach their hydrogens.

Parameters:

struct (Structure) – Complete atomistic Structure containing the components
scale (int) – Requested number of heavy atoms per network CG bead
classifications (collections.abc.Sequence[ ComponentClassification]) – Components selected for network mapping

Return type:

tuple(NetworkComponentPartition)

Returns:

Heavy-atom partitions and hydrogen-complete tagging groups

Raises:

NetworkMappingError – If a selected component has no repeat model or its hydrogens cannot be assigned unambiguously

schrodinger.application.matsci.network_cg_mapping.automapping.build_component_mapping_results(component_partitions, type_assignment)¶

Build typed mapping results for individually partitioned components.

The shared bead-type assignment is sliced in component and group order so each result receives the type IDs corresponding to its own partition.

Parameters:

component_partitions (collections.abc.Sequence[ NetworkComponentPartition]) – Network component partitions in typing order
type_assignment (MappingGroupTypeAssignment) – Combined bead types aligned with all groups

Return type:

tuple(NetworkComponentMappingResult)

Returns:

Typed mapping result for each network component

schrodinger.application.matsci.network_cg_mapping.automapping.tag_network_components(struct, scale, name_generator, classifications=None, known_bead_names=None)¶

Map and tag only the components routed to network mapping.

Repeat detection and partitioning operate on each component’s heavy-atom network. Automated CG mapping assigns detailed-SMARTS bead types and names to those groups, and explicit hydrogens inherit the bead of their bonded heavy atom. Mapped network atoms receive the standard grouping properties and a pre-mapped marker so the general mapper can leave them unchanged. Existing grouping properties on other components are preserved.

Parameters:

struct (Structure) – Complete atomistic Structure containing all mapping regions
scale (int) – Requested number of heavy atoms per network CG bead
name_generator (collections.abc.Callable[[str], str]) – Function receiving canonical SMARTS
classifications (collections.abc.Sequence[ ComponentClassification] or None) – Precomputed component classifications, or None to classify the Structure
known_bead_names (collections.abc.Mapping[str, str] or None) – Established particle name keyed by detailed SMARTS

Return type:

TaggedNetworkMappingResult

Returns:

Network mappings, shared bead metadata, and tagged Structure copy

Raises:

NetworkMappingError – If a selected network component cannot be partitioned, typed, or tagged unambiguously

schrodinger.application.matsci.network_cg_mapping.automapping.group_image_offsets(group, adjacency)¶

Assign one contiguous input-PBC image to every atom in a bead.

Parameters:

group (collections.abc.Collection[int]) – Connected atom IDs belonging to one CG bead
adjacency (collections.abc.Mapping[int, collections.abc.Sequence]) – Oriented intra-group edges keyed by atom ID

Return type:

dict[int, numpy.ndarray]

Returns:

Input-box image offset for each atom

Raises:

NetworkMappingError – If the group contains a nonzero PBC winding or is disconnected

schrodinger.application.matsci.network_cg_mapping.automapping.cg_atom_indices_by_group(cg_structure, groups)¶

Return the materialized CG atom index for every mapping group.

Parameters:

cg_structure (Structure) – Materialized coarse-grained Structure
groups (collections.abc.Sequence[model.AtomGroup]) – Concrete atom groups used to create cg_structure

Return type:

tuple(int)

Returns:

CG atom indices aligned with partition.groups

Raises:

NetworkMappingError – If CGMapper did not preserve the parent atom sets

schrodinger.application.matsci.network_cg_mapping.automapping.bead_frame_shift(network, group, offsets, cg_position, image_search)¶

Return the CG atom image aligned with its contiguous atomic group.

Parameters:

network (AtomicNetwork) – Atomic network containing the group
group (collections.abc.Collection[int]) – Atom IDs belonging to one CG bead
offsets (collections.abc.Mapping[int, numpy.ndarray]) – Contiguous input-box image offset for each group atom
cg_position (numpy.ndarray) – Stored Cartesian position of the CG atom
image_search (PeriodicImageSearch or None) – Reusable input-box image geometry

Return type:

numpy.ndarray

Returns:

Input-box image shift aligning the CG atom to the group

schrodinger.application.matsci.network_cg_mapping.automapping.cg_edge_shifts(network, groups, cg_structure, cg_atoms_by_group, image_search)¶

Return explicit input-PBC shifts for every inter-bead edge.

Parameters:

network (AtomicNetwork) – Atomic network containing explicit edge image shifts
groups (collections.abc.Sequence[model.AtomGroup]) – Concrete atom-to-bead groups
cg_structure (Structure) – Materialized coarse-grained Structure
cg_atoms_by_group (tuple(int)) – CG atom indices aligned with partition groups
image_search (PeriodicImageSearch or None) – Reusable input-box image geometry

Return type:

dict[tuple[int, int], set[tuple[int, int, int]]]

Returns:

Image shifts keyed by canonically ordered mapping-group IDs

Raises:

NetworkMappingError – If a bead is bonded to an image of itself

schrodinger.application.matsci.network_cg_mapping.automapping.reconstruct_cg_bonds(network, groups, cg_structure)¶

Replace CGMapper bonds using explicit atomic-network image shifts.

Structure represents a regular bond, one or more nearest periodic-image bonds, or both using one bond record and PBC labels. The requested shifts are checked against that compact geometric representation before the bond is created; unrepresentable multiplicity raises an error rather than being silently discarded.

Parameters:

network (AtomicNetwork) – Atomic network containing explicit edge image shifts
groups (collections.abc.Sequence[model.AtomGroup]) – Concrete atom-to-bead groups
cg_structure (Structure) – Materialized CG Structure to update in place

Raises:

NetworkMappingError – If the CG periodic connectivity cannot be represented by Structure bond records

schrodinger.application.matsci.network_cg_mapping.automapping.network_groups_from_tags(struct)¶

Return concrete network groups encoded on a mapped Structure.

Parameters:: struct (Structure) – Atomistic Structure carrying network mapping tags
Return type:: tuple(model.AtomGroup)
Returns:: Network atom groups in deterministic atom-index order
Raises:: NetworkMappingError – If a network atom does not have exactly one complete set of grouping properties

schrodinger.application.matsci.network_cg_mapping.automapping.reconstruct_tagged_network_bonds(mapped_structure, cg_structure)¶

Restore network PBC bonds in a combined coarse-grained Structure.

Network groups are recovered from the standard grouping properties and the network marker on mapped_structure. Bonds whose two endpoints are network particles are rebuilt from the explicit atomic PBC image shifts. All other CG bonds are retained.

Parameters:

mapped_structure (Structure) – Fully tagged atomistic Structure used by CGMapper
cg_structure (Structure) – Combined CG Structure to update in place

Raises:

NetworkMappingError – If the tagged network connectivity cannot be represented by Structure bond records