Analysis Operations#

Lightweight masks and cross-mask interaction accounting are exposed from tmol.ops. For fragment-aware accounting that depends on score-layer metadata, use tmol.score.calculate_fragment_interactions().

High-level batched scoring operations.

tmol.ops.block_energies(score_function: ScoreFunction, pose_stack: PoseStack, score_type: ScoreType, pose: int, blocks: list) → list[source]#

Weighted energy of one term involving each block.

Each value is that block’s row plus column of the block-pair matrix for score_type, i.e. every interaction the block participates in (including with itself), counted once.

tmol.ops.build_coord_mask_for_mask_and_interacting_atoms(pose_stack: PoseStack, mask: Tensor[slice(None, None, None), slice(None, None, None)], interaction_distance: float = 5.0, *, max_workspace_bytes: int | None = None) → Tensor[slice(None, None, None), slice(None, None, None)][source]#

Select masked blocks and nearby side-chain atoms.

Parameters:

  • pose_stack – Poses containing coordinates shaped [n_poses, n_atoms, 3].

  • mask – Selected blocks shaped [n_poses, n_blocks].

  • interaction_distance – Maximum atom-to-selected-atom distance in Angstroms.

  • max_workspace_bytes – Temporary-memory cap for batched pairwise differences. Defaults to 256 MiB; smaller values use more chunks.

Returns:

Coordinate mask shaped [n_poses, n_atoms]. All atoms in selected blocks are included; only side-chain atoms are added from other blocks.

Raises:

ValueError – If max_workspace_bytes is not positive.

tmol.ops.build_coord_mask_for_mask_and_nearby_blocks(pose_stack: PoseStack, mask: Tensor[slice(None, None, None), slice(None, None, None)]) → Tensor[slice(None, None, None), slice(None, None, None)][source]#

Select masked blocks and side chains of centroid-adjacent blocks.

Parameters:

  • pose_stack – Poses to select from.

  • mask – Selected blocks shaped [n_poses, n_blocks].

Returns:

Coordinate mask shaped [n_poses, max_n_atoms].

tmol.ops.build_sidechain_coord_mask(pose_stack: PoseStack) → Tensor[slice(None, None, None), slice(None, None, None)][source]#

Select side-chain atoms in each pose.

Parameters:

pose_stack – Poses supplying block types and coordinate layout.

Returns:

Mask shaped [n_poses, max_n_atoms]. Non-polymers contribute all real atoms; polymers exclude their declared main-chain atoms.

tmol.ops.calculate_block_pair_ddg(pose_stack: PoseStack, mask: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor, mask2: Tensor[slice(None, None, None), slice(None, None, None)] | None = None, sfxn: ScoreFunction | None = None, sum_terms: bool = True, minimize: bool = True, pack: bool = False, database: ParameterDatabase | None = None, return_pose_stack: bool = False, *, memory_efficient: bool = False, max_workspace_bytes: int | None = None) → Tensor | tuple[Tensor, PoseStack][source]#

Score interactions between two block sets in each pose.

Parameters:

  • pose_stack – Poses to score.

  • mask – First set shaped [n_poses, n_blocks]. For single-site scans, integer indices shaped [n_poses] avoid a dense pair-mask reduction.

  • mask2 – Optional second block set. The complement of mask is used by default.

  • sfxn – Score function; defaults to beta2016 on the pose device.

  • sum_terms – Sum score terms into one value per pose.

  • minimize – Minimize selected and nearby side-chain atoms before scoring.

  • pack – Repack selected and adjacent blocks before minimization.

  • database – Parameter database used to construct the Dunbrack sampler.

  • return_pose_stack – Return the packed/minimized poses with their scores.

  • memory_efficient – Use a lower-memory Boolean-mask reduction. Its floating- point summation order may differ from the default path.

  • max_workspace_bytes – Optional temporary-memory cap for the batched nearby-atom search used by minimization. Defaults to 256 MiB.

Returns:

Scores shaped [n_poses] or [n_terms, n_poses]. When requested, returns (scores, scored_pose_stack).

tmol.ops.compute_block_adjacency(block_centroids: Tensor[slice(None, None, None), slice(None, None, None), 3], block_furthest_dist: Tensor[slice(None, None, None), slice(None, None, None)], constant: float = 5.0) → Tensor[slice(None, None, None), slice(None, None, None), slice(None, None, None)][source]#

Find blocks whose enclosing spheres are within a fixed gap.

Parameters:

  • block_centroids – Centroids shaped [n_poses, n_blocks, 3].

  • block_furthest_dist – Enclosing radii shaped [n_poses, n_blocks].

  • constant – Maximum gap between two enclosing spheres.

Returns:

Adjacency shaped [n_poses, n_blocks, n_blocks] with a false diagonal and false entries for padding blocks.

tmol.ops.compute_block_centroids_and_furthest_dist(pose_stack: PoseStack) → tuple[Tensor[slice(None, None, None), slice(None, None, None), 3], Tensor[slice(None, None, None), slice(None, None, None)]][source]#

Compute each block’s centroid and enclosing radius.

Parameters:

pose_stack – Poses to summarize.

Returns:

Centroids shaped [n_poses, n_blocks, 3] and maximum distances shaped [n_poses, n_blocks]. Padding blocks contain NaNs.

tmol.ops.get_chain_mask(pose_stack: PoseStack, chain: str) → Tensor[source]#

Boolean mask shaped [n_poses, max_n_blocks], true where a block belongs to the given chain label.

tmol.ops.per_residue_block_pair_energies(block_pair_scores: Tensor) → Tensor[source]#

Reduce block-pair scores to one energy per residue.

Each off-diagonal block-pair entry is split evenly between its two partner residues, so the per-residue sum reconciles exactly with the pairwise total. The reduction only touches the trailing two (block) dimensions, so a leading score-type dimension – present when the block-pair scores came from a scoring module called with sum_terms=False – passes through unsummed.

Parameters:

block_pair_scores – Block-pair scores shaped [n_poses, n_blocks, n_blocks], or [n_terms, n_poses, n_blocks, n_blocks] if the score-type dimension has not been summed.

Returns:

Per-residue energies with the same leading dimension(s) as the input: [n_poses, n_blocks] or [n_terms, n_poses, n_blocks].

tmol.ops.res_mask_to_coord_mask(pose_stack: PoseStack, mask: Tensor[slice(None, None, None), slice(None, None, None)]) → Tensor[slice(None, None, None), slice(None, None, None)][source]#

Expand a block-level selection into an atom coordinate mask.

Parameters:

  • pose_stack – Poses supplying the block-to-coordinate layout.

  • mask – Selected blocks shaped [n_poses, n_blocks]. It may live on any device; it is moved to the pose’s device.

Returns:

Selected real atoms shaped [n_poses, max_n_atoms].