schrodinger.application.matsci.cg_backmapping module¶

Coarse-Grained (CG) to All-Atom (AA) backmapping.

class schrodinger.application.matsci.cg_backmapping.PARTICLE_DATA(cg_particle, cg_particle_name, aa_fragment, indices, bonds, idx_map, heavy_atoms, heavy_atoms_h_map, stereo, capping_struct, capping_site_name, capping_bonds, capping_idx_map, capping_connecting_bond)¶

Bases: tuple

aa_fragment¶: Alias for field number 2

bonds¶: Alias for field number 4

capping_bonds¶: Alias for field number 11

capping_connecting_bond¶: Alias for field number 13

capping_idx_map¶: Alias for field number 12

capping_site_name¶: Alias for field number 10

capping_struct¶: Alias for field number 9

cg_particle¶: Alias for field number 0

cg_particle_name¶: Alias for field number 1

heavy_atoms¶: Alias for field number 6

heavy_atoms_h_map¶: Alias for field number 7

idx_map¶: Alias for field number 5

indices¶: Alias for field number 3

stereo¶: Alias for field number 8

class schrodinger.application.matsci.cg_backmapping.MOLECULE_DATA(fragments, indices, bonds, stereo)¶

Bases: tuple

bonds¶: Alias for field number 2

fragments¶: Alias for field number 0

indices¶: Alias for field number 1

stereo¶: Alias for field number 3

exception schrodinger.application.matsci.cg_backmapping.StructureTypeError¶

Bases: Exception

Unsupported input structure type.

exception schrodinger.application.matsci.cg_backmapping.ValidationError¶

Bases: StructureTypeError

Validation errors for input structure and properties.

exception schrodinger.application.matsci.cg_backmapping.BackmappingError¶

Bases: Exception

Base exception for CG→AA backmapping failures.

exception schrodinger.application.matsci.cg_backmapping.TopologyError¶

Bases: ValueError

Errors related to missing or inconsistent topology information during backmapping.

schrodinger.application.matsci.cg_backmapping.get_CG_parent_structure(cg_struct)¶

Gets the parent all-atom structure from a coarse-grained structure.

Parameters:: cg_struct (Structure) – The CG structure containing the parent structure.
Returns:: The parent all-atom structure corresponding to the CG structure.
Return type:: Structure

schrodinger.application.matsci.cg_backmapping.get_parent_atom_indices(cg_struct)¶

Collect every parent AA atom index referenced by any CG particle’s INDICES topology property.

Parameters:: cg_struct (Structure) – The CG structure to scan.
Returns:: All parent atom indices owned by some CG particle.
Return type:: set(int)

schrodinger.application.matsci.cg_backmapping.unique_aa_fragments(cg_struct)¶

Get AA fragment in the parent structure corresponding to each unique CG particle key. Each fragment contains only the atoms that map to that particle (one molecule per CG bead for small molecules; one residue per CG bead for polysaccharides and other multi-particle molecules).

Parameters:: cg_struct (Structure) – The CG structure for which to find unique AA fragments.
Returns:: Corresponding AA fragment for each unique CG particle key.
Return type:: dict

schrodinger.application.matsci.cg_backmapping.str_to_int_dict(str_key_dict)¶

Convert a string representation of a dictionary with integer keys to an actual dictionary with integer keys.

Parameters:: str_key_dict (dict) – The dictionary in string format, where keys are integers represented as strings.
Returns:: A dictionary with integer keys.
Return type:: dict or None

schrodinger.application.matsci.cg_backmapping.get_parent_atom_index(atom)¶

Get the parent structure atom index from an extracted structure atom.

Parameters:: atom (structure._StructureAtom) – Atom from an extracted structure that may carry a parent index property.
Returns:: The parent atom index, or None if not found.
Return type:: int or None

class schrodinger.application.matsci.cg_backmapping.GeometryUtils¶

Bases: object

Structure geometry utilities for backmapping, including translation and rotation operations.

static translateFragment(cg_particle, aa_fragment)¶

Translates the AA fragment to CG particle position.

Parameters:

cg_particle (structure._StructureAtom) – The CG particle for which to translate the AA fragment.
aa_fragment (Structure) – The AA template structure to be translated.

Returns:

Translated AA fragment structure.

Return type:

Structure

static translateToOriginalPosition(original_fragment, updated_fragment, atom_idx)¶

Translates the updated AA fragment to the original position based on a reference atom.

Parameters:

original_fragment (Structure) – The original AA fragment structure.
updated_fragment (Structure) – The updated AA fragment structure to be translated.
atom_idx (int) – The translation will happen based on the position of this atom index in the original and updated fragment.

Returns:

Translated AA fragment structure.

Return type:

Structure

static getEulerAngleGrid()¶

Generates a Cartesian product of Euler angles.

Returns:: An iterator of (phi, theta, psi) in radians.
Return type:: Iterator of tuples

static generateSpherePoints(count, radius)¶

Distribution of particles on sphere surface, get the center coordinates of internal spheres for a minimum enclosing sphere.

Parameters:

count (int) – The number of points to generate on the sphere surface.
radius (float) – The radius of the sphere.

Returns:

Molecule center coordinates.

Return type:

list

static rotateFragmentPair(fixed_particle, mobile_particle, shared_bond)¶

Rotate the mobile AA fragment around the shared bond to optimize connectivity with the fixed AA fragment.

Parameters:

fixed_particle (namedtuple) – The PARTICLE_DATA for the fixed CG particle.
mobile_particle (namedtuple) – The PARTICLE_DATA for the mobile CG particle.
shared_bond (tuple) – The shared bond info (atom indices and bond order) between the two AA fragments corresponding to the CG particles.

Returns:

The rotated AA fragment for the mobile CG particle.

Return type:

Structure

static rotateFragment(fixed_frag, mobile_frag, mobile_idx)¶

Rotation operation to optimize the CG_ij particles connectivity. To avoid rotations that causes overlaps, we look for the minimum distance between the fixed and mobile fragment atoms after rotation, while ensuring that the minimum distance is above a certain threshold.

Parameters:

fixed_frag (Structure) – The AA fragment structure for fixed fragment.
mobile_frag (Structure) – The AA fragment structure for mobile fragment.
mobile_idx (int) – AA index in mobile fragment.

Returns:

Translated/rotated AA fragment structure.

Return type:

Structure

static getSharedAABonds(atom_bonds, neighbor_bonds)¶

Shared AA bonds of between atoms belonging to connected CG particles (i,j).

Parameters:

atom_bonds (tuple) – The parent bonds/bond order in the fixed fragment.
neighbor_bonds (tuple) – The parent bonds/bond order in the fixed fragment neighbors.

Returns:

The parent AA bonds connecting given CG particles (i,j).

Return type:

tuple

static getRingPlaneNormal(struct, ring_indexes)¶

Compute the unit normal vector to the best-fit plane of a ring using SVD, and the ring centroid.

Parameters:

struct (Structure) – The structure containing the ring.
ring_indexes (list[int]) – Atom indices of the ring.

Returns:

Unit normal vector and ring centroid coordinates.

Return type:

tuple[numpy.ndarray, numpy.ndarray]

class schrodinger.application.matsci.cg_backmapping.RestraintsAssigner(struct, target_stereo, stereo_centers)¶

Bases: object

Generates ASL strings and restraint information to restrain stereocenters that were corrected during structure updating.

IMPROPER = 'improper'¶

STRETCH = 'stretch'¶

__init__(struct, target_stereo, stereo_centers)¶

Initialize the StereoRestraintsAssigner class.

Parameters:

struct (Structure) – The updated AA model.
target_stereo (dict) – The target stereochemistry information.
stereo_centers (dict) – The information of the corrected stereocenters to be used for generating restraints.

getAllRestraints()¶

Get the restraints for all corrected chiralities.

Parameters:: stereo_centers (dict) – The information of the corrected stereocenters to be used for generating restraints.

addImproperRestraintsInfo()¶: Assigns improper restraints for corrected R/S centers.

addStretchRestraintsInfo(corrected_indices, target_neighbor_idx)¶

Assigns stretch restraints for corrected chiral centers with improper dihedrals (e.g. E/Z, P/M).

Parameters:

corrected_indices (list) – Atom indices for corrected chiral centers.
target_neighbor_idx (int) – The neighbor index to use for stretch restraint for the E/Z or P/M centers.

getNonChiralASL()¶

Get the ASL string for the non-chiral atoms.

Returns:: ASL string for atoms.
Return type:: str or None

updateStretchRestraints(atom1_idx, atom2_idx, dist)¶

Gather the generated restraints information for the corrected chiral centers.

Parameters:

atom1_idx (int) – Atom index for the first atom in the stretch restraint.
atom2_idx (int) – Atom index for the second atom in the stretch restraint.
dist (float) – The distance between the two atoms to be restrained.

updateImproperRestraints(atom_indices, phi0)¶

Gather the generated improper restraints information for the corrected chiral centers.

Parameters:

atom_indices (list) – Atom indices for the improper dihedral restraint.
phi0 (float) – The target dihedral angle for the improper restraint.

class schrodinger.application.matsci.cg_backmapping.StereoRefiner(struct, target_stereo)¶

Bases: object

Analyzes and corrects stereochemistry (R/S, E/Z, P/M) for backmapped All-Atom structure by comparing current geometries against the target reference and enforcing the target chirality by adjusting dihedrals.

__init__(struct, target_stereo)¶

Initialize the StereoRefiner class.

Parameters:

struct (Structure) – The AA model for which to enforce dihedral angles.
target_stereo (dict) – The target stereochemistry information for the AA structure.

getChirality()¶

Get the chirality information for the AA structure.

Returns:: A mapping of atom indices to their chirality information.
Return type:: dict

getUniqueStereo()¶

Get the unique stereochemistry information from the target reference.

Returns:: A mapping of atom indices to their unique stereochemistry information.
Return type:: dict

routeStereoMismatches(stereo_mismatches)¶

Routes to the appropriate geometric fixers based on the types of stereochemistry mismatches detected. Collects the restraints information for the corrected chiral centers.

Parameters:: stereo_mismatches (set) – A set of detected stereochemistry mismatches.

enforceOriginalChirality()¶: Detects mismatches and routes the structure to the appropriate geometric fixers.

fixPointChirality()¶: Enforces R/S point chirality by inverting improper dihedrals. Also handles chiral centers that are undefined in the current geometry but have target stereo information.

fixNonPointChirality(chirality_type)¶

Applies the stereo refinement to the structures with E/Z isomerism and P/M helicity and returns the corrected structure along with the restraints information.

Parameters:: chirality_type (str) – The type of chirality to be refined (E/Z or P/M).

class schrodinger.application.matsci.cg_backmapping.CGParticleReader(cg_particle, unique_fragments, all_parent_indices=None)¶

Bases: object

Reads properties from a single CG particle and retrieves AA template.

RESIDUE_PROPS = ['s_m_pdb_residue_name', 'i_m_residue_number', 's_m_chain_name']¶

__init__(cg_particle, unique_fragments, all_parent_indices=None)¶

Initialization of the CGParticleReader class.

Parameters:

cg_particle (structure._StructureAtom) – The CG particle for which to read properties and get AA fragment.
unique_fragments (dict) – A mapping of unique particle keys to their corresponding AA fragments.
all_parent_indices (set(int) or None) – All parent AA atom indices owned by some CG particle.

getCGParticleProp(prop_key)¶

Get the property value for a given key from a CG particle.

Parameters:: prop_key (str) – The key for the property to retrieve.
Returns:: The value of the specified property for the CG particle.
Return type:: str or None

getAAFragment()¶

Get the AA template fragment for a CG particle.

Returns:: AA molecule fragment corresponding to the CG particle.
Return type:: Structure

getParticleTopology()¶

Get the topology information for the CG particle, including parent AA indices, bonds, mapping, and stereochemistry.

Returns:: AA topology information corresponding to the CG particle.
Return type:: dict

getTopologyPropValue(topology_details)¶

Topology details with evaluated property values for indices, mapping, bonds, and stereo.

Parameters:: topology_details (dict) – The topology details for the CG particle.
Returns:: Topology details for the CG particle.
Return type:: dict

getParticleResidue()¶

Get the per-instance residue identity (residue name, residue number, chain name) for this CG particle. These are the authoritative values for the multimer instance the bead belongs to and are used to stamp the assembled AA atoms.

Returns:: Residue property values for the CG particle, in RESIDUE_PROPS order.
Return type:: list

getCappingBonds()¶

Parse and normalize capping bond info from a CG particle property string. The frontmapping may store a single flat tuple (e.g. '(1, None, 1)') or a list of tuples. Entries with None endpoints are filtered out since they lack resolvable parent atom indices.

Returns:: Normalized list of (idx_i, idx_j, bond_order) tuples.
Return type:: list[tuple] or None

getCappingProperties()¶

Read capping group properties for a CG particle.

Returns:: Capping site name and capping bond info.
Return type:: tuple

static orderIndicesByFragment(indices, idx_map)¶

Order the parent atom indices so their positions match the fragment’s local atom order, using the authoritative parent-to-local mapping. Falls back to the original order when the mapping is missing or does not cover the same atoms, so the behavior is unchanged for already-aligned beads.

Parameters:

indices (list(int)) – Parent atom indices for the CG particle fragment.
idx_map (dict(int, int)) – Mapping of parent atom index to local fragment atom index.

Returns:

Parent atom indices ordered by local fragment position.

Return type:

list(int)

getCGParticleData()¶

Get the data information for CG particle. The data information includes AA fragment, indices, bonds, mapping, parent residue name, and stereochemistry for the CG particle.

Returns:: Mapping details for the CG particle.
Return type:: namedtuple[PARTICLE_DATA]

processMappingDetails(residue_info)¶

Process the mapping details for the CG particle. This includes identifying heavy atoms and heavy-H bonds in the AA fragment, getting rotatable bonds for the AA fragment, translating the AA fragment to the CG particle position, and setting residue information for the translated AA fragment.

Parameters:: residue_info (list) – Per-instance residue identity from the CG bead, in RESIDUE_PROPS order ([res_name, res_number, chain_name]).
Returns:: The processed AA fragment, heavy atom indices, and heavy-H bond mapping.
Return type:: tuple

getFragmentHeavyAtoms(aa_fragment)¶

Identify the heavy atoms and heavy-H bonds in the AA fragment structure of the CG particle.

Parameters:: aa_fragment (Structure) – The AA fragment structure for which to identify heavy atoms and heavy-H bonds.
Returns:: The heavy atom indices mapped to list of bonded H atom indices
Return type:: tuple[dict, tuple]

getAttachedHAtoms(heavy_atom, frag_atom_indices)¶

Get the indices of the H atoms attached to the heavy atoms in the AA fragment.

Parameters:

heavy_atom (structure._StructureAtom) – The heavy atom for which to find attached H atoms.
frag_atom_indices (set) – Indices of atoms in the fragment.

Returns:

The indices of H atoms attached to the given heavy atom.

Return type:

list

getRotatableBonds()¶

Rotatable AA bonds between two fragments of two CG particles (fixed and neighbor) that are connected by CG_ij bond, these bonds are cut in the front mapping.

Returns:: CG particle indices, neighbor particle indices, and the rotatable parent AA bonds connecting given CG particles (i,j).
Return type:: tuple[list, list, list]

getCappingIdxMap()¶

Map parent atom indices to local cap atom indices for the capping structure.

Returns:: Mapping where key is parent_atom_index and value is cap_atom_index for every atom in the capping structure.
Return type:: dict(int, int)

findFragmentToCapBond(cap_bonds, cap_idx_map)¶

Locate a single bond connecting the AA fragment of this CG particle to its capping structure. Three-tier search: explicit capping bond info, parent fragment bonds, then parent fragment bonds against cap atoms not owned by any CG particle.

Parameters:

cap_bonds (list(tuple) or None) – Capping bond info parsed from the CG particle property, or None.
cap_idx_map (dict(int, int)) – Mapping of parent atom indices to local cap atom indices.

Returns:

A single bond ordered (fragment_parent_idx, cap_parent_idx, bond_order) or None if no connecting bond is resolvable.

Return type:

tuple or None

filterCapToAdjacentComponent(cap_struct, cap_idx_map, cap_connecting_bond)¶

Restrict the capping structure to only the connected component that is directly bonded to this CG particle’s AA fragment.

The encoded capping structure may contain capping groups for multiple segments of the same chain. Only the group adjacent to the current fragment should be used; the others belong to different CG molecules.

Parameters:

cap_struct (Structure) – Full (chain-filtered) capping structure.
cap_idx_map (dict(int, int)) – Mapping of parent atom indices to local cap atom indices.
cap_connecting_bond (tuple or None) – (fragment_parent_idx, cap_parent_idx, bond_order) identifying the bond that links this fragment to its cap, or None if no connecting bond was found.

Returns:

Filtered cap structure and updated index map.

Return type:

tuple(Structure, dict(int, int))

setFragmentResProp(aa_fragment, residue_info)¶

Set per-instance residue identity onto every atom of the translated AA fragment.

Parameters:

aa_fragment (Structure) – The translated AA fragment for which to set residue properties.
residue_info (list) – Per-instance residue identity from the CG bead, in RESIDUE_PROPS order [res_name, res_number, chain_name]. Empty values are skipped so existing non-protein behaviour is preserved.

Returns:

The AA fragment with updated residue properties.

Return type:

Structure

class schrodinger.application.matsci.cg_backmapping.RefineFragments(cg_molecule_map, parent_struct, unique_fragments, global_key_counts=None, placed_count=None)¶

Bases: object

Builds the AA topology based on the CG particle mapping data. Handles shared atoms between CG particles by removing duplicates and, adds water molecules for CG particles representing water.

__init__(cg_molecule_map, parent_struct, unique_fragments, global_key_counts=None, placed_count=None)¶

Initialize the RefineFragments class.

Parameters:

cg_molecule_map (namedtuple[PARTICLE_DATA]) – A mapping of CG particles indices to its corresponding PARTICLE_DATA.
parent_struct (Structure) – The original AA structure before CG mapping.
unique_fragments (dict) – A mapping of unique particle keys to their corresponding AA fragments.
global_key_counts (dict(str, int) or None) – System-wide count of CG beads per CG_PARTICLE_KEY across all molecules. Used to distribute the deletion total across every bead of a given key. When None, the count falls back to the per-molecule bead map (legacy behavior).
placed_count (dict or None) – Shared accumulator tracking how many beads of a given (particle_key, prop_key) have already received their share of the deletion total. Must be shared across all RefineFragments instances of a single backmapping run so the remainder is distributed exactly once across the whole system. When None, a local accumulator is used (legacy behavior).

identifySharedAtoms()¶

Check for shared atoms between CG particles. Create a map of CG particle index to AA atom indices that are shared (duplicated) between CG particles.

Returns:: Duplicate atom indices mapped to CG particle index.
Return type:: dict

removeSharedAtoms()¶

Iterates through a CG molecule and processes it to create AA fragment. Remove duplicate atoms in the assembled AA fragment. Add water molecules, set stereochemistry.

Returns:: The AA fragments, indices, bonds and stereo information mapped to CG particle index.
Return type:: namedtuple

removeDuplicateAtoms(particle_data)¶

Remove duplicate atoms in the AA fragment of a CG particle. Filter the bonds and adjust the indices to reflect the removed atoms.

Parameters:: particle_data (namedtuple) – PARTICLE_DATA object containing AA fragment and indices to be processed.
Returns:: The AA fragment, updated indices, and bonds with duplicates removed.
Return type:: tuple

addRemovedFragments(particle_data, mol_fragment)¶

Add the molecule fragments back to the AA fragment of the CG particle, that were removed during frontmapping.

Parameters:

particle_data (namedtuple) – PARTICLE_DATA object containing AA fragment and indices to be processed.
mol_fragment (Structure) – The molecule fragment which the removed molecules will be added back to.

Returns:

The AA fragment with the removed molecules added back.

Return type:

Structure

getMoleculeFragments(particle_data)¶

Get the molecule structure and number of molecules to be added to the AA fragment based on the CG particle properties.

Parameters:: particle_data (namedtuple) – PARTICLE_DATA object containing AA fragment.
Returns:: The molecule structure and number of molecules to be added to the AA structure.
Return type:: dict or None

getPositionedMoleculeFragments(particle_data, mol_fragment, mol_count)¶

Get molecules to be added back to the AA fragment positioned based on the CG particle van der Waals radius.

Parameters:

particle_data (namedtuple) – PARTICLE_DATA object containing CG particle.
mol_fragment (Structure) – The molecule structure to generate.
mol_count (int) – The number of molecules to generate.

Returns:

Translated AA molecule fragments for the CG particle.

Return type:

list

addCappingGroups(particle_data, all_parent_indices)¶

Reconstruct capping groups (e.g., ACE, NME) that were removed during CG frontmapping. Capping structures are decoded from properties on CG atoms and added to the molecule data before final assembly.

Parameters:

particle_data (namedtuple) – PARTICLE_DATA object containing AA fragment, capping structure, and capping site name.
all_parent_indices (set) – Set of all parent atom indices across CG particles.

Returns:

The positioned capping structure to be added to the AA fragment.

Return type:

Structure or None

getCappingBonds(particle_data, all_parent_indices)¶

Find bonds connecting a CG particle’s AA fragment to its capping group. Uses explicit capping bond info as the primary source, falling back to parent bond topology.

Parameters:

particle_data (namedtuple) – PARTICLE_DATA object containing AA fragment, capping structure, and capping site name.
all_parent_indices (set) – Set of all parent atom indices across CG particles.

Returns:

List of (frag_parent_idx, cap_parent_idx, bond_order) tuples for bonds connecting the fragment to the cap.

Return type:

list

getCapperConnectingBonds(particle_bonds, fragment_indices, capping_indices)¶

Match bonds that cross between capping fragment and non-capping fragment.

Parameters:

particle_bonds (list) – Bond tuples to scan.
fragment_indices (set) – Set of parent atom indices.
capping_indices (set) – Set of parent atom indices in the capping fragment.

Returns:

List of bonds between capping and non-capping fragments.

Return type:

list

class schrodinger.application.matsci.cg_backmapping.MoleculeAssembler(fragment_data)¶

Bases: object

Assembles the clean fragments into All-Atom molecule.

__init__(fragment_data)¶

Initialize the MoleculeAssembler class.

Parameters:: fragment_data (namedtuple[MOLECULE_DATA]) – The CG molecule data containing fragments, indices, bonds, and stereo information for each CG particle.

flattenAAFragmentData()¶: Flatten the hierarchical data for AA fragments into a single list to create the molecule structure.

buildMolecules()¶

Build a single molecule structure from the list of fragments and bonds.

Returns:: A single molecule structure combining all fragments and molecule stereo.
Return type:: tuple[Structure, dict]

addMissingMoleculeStereo(aa_molecule, mol_stereo)¶

Detect chirality on the assembled molecule and add stereo information for chiral centers not already present in the stereo map. This covers atoms from molecule copies added back during backmapping that lack per-particle stereo properties.

Parameters:

aa_molecule (Structure) – The assembled AA molecule structure.
mol_stereo (dict) – The existing stereo map for the molecule.

Returns:

Updated stereo map including detected chiral centers.

Return type:

dict

getIndicesMap(fragment, current_atom_count)¶

Get the mapping of new atom indices to original atom indices for a given fragment.

Parameters:

fragment (Structure) – The AA fragment for which to create the index mapping.
current_atom_count (int) – The current count of atoms processed so far, used to calculate new indices.

Returns:

Mapped indices and the updated current atom count.

Return type:

tuple[list, int]

getUpdatedBondIndices()¶

Translates bond indices from the parent structure to the new backmapped structure.

Returns:: Bonds present in the AA molecule structure.
Return type:: list[tuple]

addInterFragmentBonds(molecule, mapped_bonds)¶

Add inter-fragment AA bonds to the backmapped structure.

Parameters:

molecule (Structure) – The combined AA fragment structure to which bonds will be added.
mapped_bonds (list) – The list of bonds with indices mapped to the combined molecule.

Returns:

The molecule structure with inter-fragment bonds added.

Return type:

Structure

getMoleculeStereo()¶

Parses parent stereochemistry data and maps it to the backmapped structure.

Returns:: Chiral centers in the molecule and their stereochemistry tags.
Return type:: dict

mapMoleculeStereo(stereo_str)¶

Parses a stereo string (e.g., “10_11_R”) and maps integer indices to the new structure’s numbering.

Parameters:: stereo_str (str) – The stereo string to parse and map.
Returns:: A list of mapped components.
Return type:: list

updateStereoMap(mapped_components, stereo_map, neighbors, defining_indices, tag_index)¶

Update the stereo map with the given mapped components and stereochemistry tag.

Parameters:

mapped_components (list) – The mapped components from the stereo string.
stereo_map (dict) – The stereo map for the backmapped structure.
neighbors (list) – The indices of the neighboring atoms that define the stereochemistry.
defining_indices (tuple) – The indices in the mapped components that define the stereochemistry.
tag_index (int) – The index in the mapped components where the stereochemistry tag is located.

updateStereoAtomIndices(mol_stereo, atom_offset)¶

Update the atom indices in the stereochemistry for the backmapped structure.

Parameters:

mol_stereo (dict) – The stereo information for the molecule to be updated.
atom_offset (int) – The offset to be added to the original atom indices to get the new atom indices in the backmapped structure.

Returns:

The updated stereo information with shifted atom indices.

Return type:

dict or None

class schrodinger.application.matsci.cg_backmapping.RingSpearResolver(aa_struct)¶

Bases: object

Detects and resolves ring spears in backmapped all-atom structures. A ring spear occurs when a bond passes through the face of a ring. Uses translation along ring plane normals and Euler rotation to stabilize the structure.

MAX_PASSES = 5¶

MAX_BFS_DEPTH = 3¶

__init__(aa_struct)¶

Initialize the RingSpearResolver.

Parameters:: aa_struct (Structure) – The backmapped all-atom structure to check and fix.

detectSpears()¶

Detect ring spears in the backmapped structure.

Returns:: List of detected spear objects.
Return type:: list

getSpearFragmentAtoms(spear_idx1, spear_idx2, ring_indexes)¶

Identify a local fragment around the spear atoms using BFS up to depth 3. Ring atoms act as barriers so the fragment stays on the spear side of the topology.

Parameters:

spear_idx1 (int) – First atom index of the spearing bond.
spear_idx2 (int) – Second atom index of the spearing bond.
ring_indexes (list[int]) – Atom indices of the speared ring.

Returns:

Sorted atom indices of the local fragment.

Return type:

list[int]

resolveByTranslation(frag_atoms, ring_normal, spear_ring, original_xyz)¶

Attempt to resolve a ring spear by translating the fragment along the ring plane normal at various distances.

Parameters:

frag_atoms (list(int)) – Atom indices of the local fragment.
ring_normal (numpy.ndarray) – Normal vector of the ring plane.
spear_ring (SpearRing) – The SpearRing object for checking resolution.
original_xyz (numpy.ndarray) – Original coordinates of the full structure.

Returns:

True if the spear was resolved, False otherwise.

Return type:

bool

resolveByRotation(frag_atoms, spear_ring, original_xyz)¶

Attempt to resolve a ring spear by rotating the fragment through an Euler angle grid around its centroid.

Parameters:

frag_atoms (list(int)) – Atom indices of the local fragment.
spear_ring (SpearRing) – The SpearRing for checking resolution.
original_xyz (numpy.ndarray) – Original coordinates of the fragment.

Returns:

True if the spear was resolved, False otherwise.

Return type:

bool

fixRingSpear(ring_indexes, spear_idx1, spear_idx2)¶

Fix the given ring spear by attempting translation and rotation of the local fragment around the spear atoms.

Parameters:

ring_indexes (list[int]) – Atom indices of the speared ring.
spear_idx1 (int) – First atom index of the spearing bond.
spear_idx2 (int) – Second atom index of the spearing bond.

Returns:

True if the spear was resolved, False otherwise.

Return type:

bool

resolveSpears()¶

Attempt to fix detected ring spears using translation and rotation. Iterates through multiple passes until all spears are resolved or no further progress can be made.

Returns:: List of remaining unresolved spear objects.
Return type:: list

class schrodinger.application.matsci.cg_backmapping.BackMappingValidator(cg_struct)¶

Bases: object

Validates the input CG structure and its properties before backmapping.

REQUIRED_TOPOLOGY_PROPS = {'indices': 's_matsci_cg_particle_parent_indices', 'mapping': 's_m_backendhidden_parent_atom_mapping'}¶

__init__(cg_struct)¶

Initialize the BackMappingValidator class.

Parameters:: cg_struct (Structure) – The CG structure to validate

checkStructureType()¶

Check if the input structure is a coarse-grained model.

Returns:: True if valid CG structure, False otherwise.
Return type:: tuple[bool, str or None]

checkParentStructure()¶

Check if the parent all-atom structure is available in the CG structure properties.

Returns:: True if parent structure is available, False otherwise.
Return type:: tuple[bool, str or None]

checkTopologyProperties()¶

Check if the required CG topology properties are set on all atoms in the CG structure.

Returns:: True if all properties are set, False otherwise.
Return type:: tuple[bool, str or None]

checkLatticeProperties()¶

Check if the lattice properties are set for the CG structure.

Returns:: True if lattice properties are set, False otherwise.
Return type:: tuple[bool, str or None]

validate()¶

Run all validation checks on the CG structure.

Raises:

StructureTypeError – If the structure is not a CG model.
ValidationError – If required properties are missing.

class schrodinger.application.matsci.cg_backmapping.BackMapper(cg_struct)¶

Bases: object

Build the AA structure from the coarse-grained structure.

__init__(cg_struct)¶

Initialize the BackMapper class.

Parameters:

cg_struct (Structure) – The coarse-grained structure to backmap

Raises:

StructureTypeError – If the structure is not a CG model.
ValidationError – If required CG properties are missing from the structure.

buildAAStructure()¶: Run the AA structure building process.

extractCGMappingData()¶: Get the forward mapping details for the CG structure. This includes the AA fragment, topology, and residue information for each CG particle. Adjust the AA fragment to CG particle position and set residue information for the AA fragment based on CG molecule properties.

registerCapPhantom(particle_data, real_idx)¶

Register a synthetic phantom CG particle for a capping group so that optimizeConnectivity treats the cap like any other CG-pair rotation. Also pre-translates the cap to a sensible position so the cap stays near the connecting atom even if the rotation step is skipped (e.g., non-single bond order).

Parameters:

particle_data (PARTICLE_DATA) – The real CG particle’s data, which carries the capping structure and the resolved connecting bond.
real_idx (int) – Index of the real CG particle that owns the cap.

Returns:

The updated particle_data with its capping_struct translated to the new position.

Return type:

PARTICLE_DATA

optimizeConnectivity()¶: Perform rotational optimization based on the rotatable bonds between the parent AA fragments of the CG particles. The optimization is performed for all molecules.

getRotatedFragments()¶

Iterates through rotatable bonds and optimizes the alignment of connected AA fragments.

Returns:: Mapping of CG particle index to the optimized AA fragment structure.
Return type:: dict

cleanOverlappingFragments()¶: Processes and refines the mapped AA fragments for each CG molecule prior to final assembly. This step cleans up boundary overlaps by identifying and removing duplicated shared atoms between connected CG particles. It also unpacks special CG particles (e.g., water) into explicit AA molecules.

addCappingFragments()¶: For each CG particle in the molecule, check if it has a capping group. Position the capping group based on the original parent structure and get the bonds connecting the capping group to the main fragment.

setLatticeProp()¶

Setup the lattice properties on a new structure from the CG structure. The backmapped AA fragments will be added to this structure.

Returns:: Structure with lattice properties.
Return type:: Structure

createBackmappedStructure()¶: Orchestrates the full backmapping process: retrieves data, assembles molecules, and merges them into the final simulation box. Updates the stereochemistry information in the process.

resolveRingSpears()¶: Detect and resolve ring spears in the backmapped all-atom structure.

propCleanUp()¶: Clean up CG frontmapping properties in the backmapped structure.