Packing#

Packing tasks select which blocks may repack or design. Rotamer samplers define the conformations considered by the packer.

Side-chain packing tasks, energy tables, and annealing.

class tmol.pack.PackerEnergyTables(max_n_rotamers_per_pose: int, pose_n_res: Tensor, pose_n_rotamers: Tensor, pose_rotamer_offset: Tensor, nrotamers_for_res: Tensor[slice(None, None, None), slice(None, None, None)], oneb_offsets: Tensor[slice(None, None, None), slice(None, None, None)], res_for_rot: Tensor, chunk_size: int, neighbor_row_offsets: Tensor, neighbor_blocks: Tensor, neighbor_chunk_offset_offsets: Tensor, chunk_offsets: Tensor, energy1b: Tensor, energy2b: Tensor)[source]#

Bases: TensorGroup, ConvertAttrs

One- and two-body energy tables plus their packed rotamer indexing.

class tmol.pack.PackerPalette(noncanonical_design: bool = False)[source]#

Bases: object

Define which residue types may replace each original residue type.

Parameters:: noncanonical_design – Also offer noncanonical residue types (such as AIB) as replacements for other residues. Off by default, so a noncanonical type is considered only where the input already has it.

block_types_from_original(pbt: PackedBlockTypes, orig: Tensor[slice(None, None, None), slice(None, None, None)]) → tuple[Tensor[slice(None, None, None), slice(None, None, None)], Tensor[slice(None, None, None), slice(None, None, None), slice(None, None, None)], Tensor[slice(None, None, None), slice(None, None, None), slice(None, None, None)]][source]#

Return residue-type choices allowed by the default palette.

Parameters:

pbt – Packed residue-type collection shared by the poses.
orig – Original residue-type index for each pose and block.

Returns:

The number of choices, padded choice indices, and a mask marking each original residue type.

create_restrict_to_repacking_mask(pbt: PackedBlockTypes, orig: Tensor[slice(None, None, None), slice(None, None, None)]) → Tensor[slice(None, None, None), slice(None, None, None), slice(None, None, None)][source]#: Return choices that preserve each block’s original residue name.

default_conformer_samplers()[source]#

All positions must build one rotamer, even if they are not being optimized.

Each block must have coordinates represented in the tensor with the other rotamers, and the easiest way to do that is to create a rotamer with the DOFs of the input conformation. The FallbackSampler copies these DOFs from the inverse-folded coordinates of the starting Pose’s blocks, but only for positions where no other sampler provides rotamers (e.g. residue types not covered by DunbrackChiSampler). Positions with at least one other sampler are left to that sampler exclusively. Future versions of PackerPalette have the option to override this method.

class tmol.pack.PackerPalleteAnnotation(max_n_allowed: int, n_allowed_block_types_for_block_type: Tensor, allowed_block_types_for_block_type: Tensor[slice(None, None, None), slice(None, None, None)], allowed_block_type_is_orig: Tensor[slice(None, None, None), slice(None, None, None)], restrict_to_repacking_masks: Tensor[slice(None, None, None), slice(None, None, None)])[source]#

Bases: object

Cached residue-type compatibility tensors for a packer palette.

class tmol.pack.PackerTask(systems: PoseStack, palette: PackerPalette)[source]#

Bases: object

Configure residue identities, conformers, and movable sites for packing.

set_chi_sample_budget(expanded_limit: int, limit: int)[source]#

Set expansion/fallback budgets without mutating reusable samplers.

Groups count one rotamer per member per conformer, including current. A required library that cannot fit is rejected before the group product is allocated. Sampler-specific defaults apply until this setter is used. The combined count across samplers and allowed types at each physical residue must also fit the larger limit before rows/coordinates merge.

restrict_to_repacking(block_mask: Tensor[slice(None, None, None), slice(None, None, None)] | None = None)[source]#

Restrict selected blocks to the original residue name.

If block_mask is omitted, restrict every block for backward compatibility. Otherwise, only True pose/block entries are changed.

restrict_absent_name3s(name3s: Collection[str], block_mask: Tensor[slice(None, None, None), slice(None, None, None)] | None = None)[source]#

Restrict selected blocks to block types with the given name3s.

If block_mask is omitted, restrict every block for backward compatibility. This operation only disables choices and may therefore be composed safely with other task restrictions.

Raises:: ValueError – A block selected by block_mask had allowed block types and none of them has one of name3s (for example, a residue bonded to a metal, which only its own variant can replace).

add_conformer_sampler(sampler) → None[source]#

Enable this sampler everywhere, registering its identity once.

A sampler bundle – anything exposing expand_into_task – registers the samplers it is composed of instead, so callers can declare what they want sampled without composing it themselves.

add_conformer_sampler_by_block_mask(sampler: ConformerSampler, block_type_mask: Tensor[torch.bool][:, :]) → None[source]#: Enable this sampler in the mask, extending any existing selection.

or_expand_chi(chi_ind: int) → None[source]#: Request one extra standard-deviation sample for a chi torsion.

or_expand_chi_to(chi_ind: int, sample_level: int) → None[source]#: Raise a chi torsion’s expansion level without lowering it.

disable_sampler_by_block_mask(sampler, block_mask: Tensor[slice(None, None, None), slice(None, None, None)])[source]#: Stop one sampler building rotamers for the masked blocks.

disable_packing_by_block_mask(block_type_mask: Tensor[slice(None, None, None), slice(None, None, None)]) → None[source]#: Disable packing at selected pose/block entries.

or_bump_check(setting: bool = True) → None[source]#: Enable bump checking without allowing later calls to disable it.

property bump_check#

bump_check eliminates rotamers from consideration if they have a high interaction energy with “the background,” which is computed by taking the best energy a rotamer has with each neighbor across all the neighbor’s rotamers.

bump_check removes ~40% of all rotamers and can significantly improve running time, but, this comes at the expense of eliminating rotamers that are sometimes the best option when all others are bad in ways that bump-check’s rosie estimation cannot predict. In ~10% of tested crystal structures packed with only the base rotamers (no ex flags), bump_check increased the energy of the final rotamer rotamer assignment by >20 kcal/mol.

bump_check’s logic: eliminate a rotamer if it has a best possible energy with its neighbors and itself >5 kcal/mol and at least one other rotamer of the same block type at that residue has an energy less than 5 kcal/mol.

class tmol.pack.SetPackerTask[source]#

Bases: object

Set as in concrete. Once everything wrt the desired packing task has been determined, pack_rotamers will construct this object to create and hold the many mappings that the various members of the packer need.

tmol.pack.build_missing_sidechains(pose_stack: PoseStack, sfxn: ScoreFunction, dunbrack_sampler: DunbrackChiSampler, block_has_missing_atoms: Tensor[slice(None, None, None), slice(None, None, None)], no_optH: bool = False, na_sampler: NaChiRotamerSampler = None, has_missing_atoms: bool | None = None, seed: int | None = None) → PoseStack[source]#

Build missing sidechains and place hydrogens using per-block sampler assignment.

Assigns samplers on a per-block basis in a single packing run:

Blocks with missing non-leaf (heavy) atoms: DunbrackChiSampler + FixedAAChiSampler for amino acids, NaChiRotamerSampler for nucleotides. The input conformation is not included as a rotamer because the sidechain is incomplete.
Complete blocks supported by OptHSampler: keep heavy atoms fixed while sampling proton chi angles and NHQ flips. The two sets are disjoint: NaChiRotamerSampler expands the RNA 2’-OH itself, exactly as DunbrackChiSampler expands protein proton chis, so a block must never be given both.
Complete blocks that OptHSampler cannot change (ALA, GLY, etc.) are frozen instead of becoming one-rotamer packing positions.

When no_optH=True the old behavior is preserved: only Dunbrack runs for blocks with missing heavy atoms; all other blocks are frozen.

Note: IncludeCurrentSampler is intentionally not used. For Dunbrack blocks the native conformation is broken and must not appear as a rotamer. For OptH blocks, OptH includes native as rotamer-0 for NHQ residues.

Parameters:

pose_stack – The pose stack to process.
sfxn – Score function used for packing.
dunbrack_sampler – DunbrackChiSampler configured from the parameter DB.
na_sampler – NaChiRotamerSampler configured from the parameter DB; when omitted, nucleotides with missing atoms get no rotamers.
block_has_missing_atoms – Boolean tensor [n_poses, max_n_blocks]; True for blocks that have missing non-leaf (heavy) atoms.
no_optH – When True, skip OptH and preserve old Dunbrack-only behavior.
has_missing_atoms – Cached value of block_has_missing_atoms.any(). Supplying it avoids a device synchronization in repeated builds.
seed – Packer seed, as for pack_rotamers().

Returns:

PoseStack with missing sidechains built and (by default) hydrogens placed and optimized.

tmol.pack.impose_top_rotamer_assignments(orig_pose_stack: PoseStack, rotamer_set: RotamerSet, rotamer_for_nonmolten_block: Tensor[slice(None, None, None), slice(None, None, None)], n_molten_blocks_per_pose: Tensor, bc_rot_offset_for_molten_block: Tensor[slice(None, None, None), slice(None, None, None)], bc_rot_to_orig_rot: Tensor, bc_assignment: Tensor[slice(None, None, None), slice(None, None, None), slice(None, None, None)])[source]#: Impose the lowest-energy rotamer assignemnt to each pose in the original PoseStack.

tmol.pack.pack_rotamers(pose_stack: PoseStack, sfxn: ScoreFunction, task: PackerTask, verbose: bool = False, seed: int | None = None) → PoseStack[source]#

Optimize side-chain conformers for a pose stack.

The annealer draws from torch’s generator on the pose device, so torch.manual_seed controls it on the CPU as on CUDA.

Parameters:

pose_stack – Poses whose task-enabled blocks will be packed.
sfxn – Score function used to rank rotamer assignments.
task – Allowed block types, conformers, and packing positions.
verbose – Print synchronized stage timings when true.
seed – Seed for this call only, leaving torch’s global random state unchanged.

Returns:

A new pose stack containing the lowest-ranked assignment per pose.

tmol.pack.set_compare(x, y)[source]#: Treat the collections x and y as if they are sets. Return true if they contain the same elements and false otherwise

Rotamer sampling#

Rotamer sampling, construction, and coordinate transfer.

class tmol.pack.rotamer.AtomFingerprint(mc_ind: int, mc_bond_dist: int, chirality: int, element: int, duplicate_index: int = 0)[source]#

Bases: object

Backbone position, tree distance, side of its frame and atomic number.

Chirality is 0 when unclassified, 1/2 on opposite sides, and 3 in-plane. This distinguishes even glycine’s equivalent hydrogens. Duplicate indices disambiguate atoms with the same descriptor independently of sampler roots.

class tmol.pack.rotamer.ChiSampler[source]#

Bases: ConformerSampler

Base class for samplers that define conformers through chi angles.

classmethod sampler_name() → str[source]#: Return the stable name used for chi-sampler annotations.

annotate_residue_type(rt: RefinedResidueType) → None[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types: PackedBlockTypes) → None[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType) → bool[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt_name: str) → tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

create_samples_for_poses(pose_stack: PoseStack, task: PackerTask) → tuple[Tensor, Tensor, dict[str, Any]][source]#: Create chi samples and preserve their defining atoms and angles.

fill_dofs_for_samples(pose_stack: PoseStack, task: PackerTask, orig_kinforest: KinForest, orig_dofs_kto: Tensor[slice(None, None, None), 9], gbt_for_conformer: Tensor, block_type_ind_for_conformer: Tensor, n_dof_atoms_offset_for_conformer: Tensor, conformer_built_by_sampler: Tensor, conf_inds_for_sampler: Tensor, sampler_n_rots_for_gbt: Tensor, sampler_gbt_for_rotamer: Tensor, sample_dict: dict[str, Any], conf_dofs_kto: Tensor[slice(None, None, None), 9]) → None[source]#: Write this sampler’s conformer degrees of freedom in place.

class tmol.pack.rotamer.ConformerSampler[source]#

Bases: object

Interface for creating and applying packing conformer samples.

samples_after_other_samplers: ClassVar[bool] = False#: Sample only after every other sampler has run, receiving the rotamer counts they actually produced. A sampler that fills gaps left by others must measure what was built rather than trust what was declared: a sampler may report that it covers a block type and still return no rotamers for a particular block, which would otherwise leave that position with nothing to pack.

classmethod sampler_name() → str[source]#: Return the stable name used for sampler-specific annotations.

annotate_residue_type(rt: RefinedResidueType) → None[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types: PackedBlockTypes) → None[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType) → bool[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt: RefinedResidueType) → tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

create_samples_for_poses(pose_stack: PoseStack, task: PackerTask) → tuple[Tensor, Tensor, dict[str, Any]][source]#

Return counts, considered-block index per rotamer, and sampler data.

A sampler that sets samples_after_other_samplers is called with an extra built_rotamer_counts keyword holding the per considered-block total produced by every other sampler.

A producer of joint conformers declares correlated_gbts in its data: a tuple of considered-block-index tuples, one per joint group. Rotamer k must correspond across all members. Merging rejects additional states from other samplers on those blocks. Without a declaration, samples are independent even when their residues are covalently connected.

Producers of unchanged input conformers may set copy_input_coordinates=True. Their rows must use the original block type; Cartesian coordinates are copied exactly after DOF construction to avoid rounding from an unnecessary inverse/forward kinematics cycle.

fill_dofs_for_samples(pose_stack: PoseStack, task: PackerTask, orig_kinforest: KinForest, orig_dofs_kto: Tensor[slice(None, None, None), 9], gbt_for_conformer: Tensor, block_type_ind_for_conformer: Tensor, n_dof_atoms_offset_for_conformer: Tensor, conformer_built_by_sampler: Tensor, conf_inds_for_sampler: Tensor, sampler_n_rots_for_gbt: Tensor, sampler_gbt_for_rotamer: Tensor, sample_dict: dict[str, Any], conf_dofs_kto: Tensor[slice(None, None, None), 9]) → None[source]#: Write this sampler’s conformer degrees of freedom in place.

class tmol.pack.rotamer.ConjugatedSCSampler(sidechain: SidechainSampler)[source]#

Bases: object

Sample side chains while keeping covalently linked groups together.

A residue with something bonded to its side chain has to be sampled as one unit; moving the two apart would break the bond. This wraps a side-chain bundle so that grouping is applied without the caller repeating the exclusion bookkeeping.

Examples

>>> task.add_conformer_sampler(
...     ConjugatedSCSampler(
...         SidechainSampler.from_database(database, pose_stack.device)
...     )
... )

expand_into_task(task) → None[source]#: Register the side-chain bundle, then group conjugated residues.

class tmol.pack.rotamer.FallbackSampler[source]#

Bases: ConformerSampler

Include the input conformation as a rotamer only for positions that have no rotamers from any other sampler.

This is the default sampler in PackerPalette. Unlike IncludeCurrentSampler, it does not unconditionally add a rotamer for every position; instead it activates only where the other samplers actually produced no rotamers, ensuring that positions covered by, e.g., DunbrackChiSampler do not accumulate an extra current-conformation rotamer.

The trigger is measured rather than declared. A sampler may report through defines_rotamers_for_bts that it handles a block type and still build no rotamers for a given block; trusting the declaration would leave that position with nothing to pack. Sampling last and counting what was built also means a new sampler needs no special registration here.

The disable_packing case (all block types disallowed) is also handled: a rotamer from the input conformation is always produced so the packer has something to represent for fixed residues.

samples_after_other_samplers: ClassVar[bool] = True#: Sample only after every other sampler has run, receiving the rotamer counts they actually produced. A sampler that fills gaps left by others must measure what was built rather than trust what was declared: a sampler may report that it covers a block type and still return no rotamers for a particular block, which would otherwise leave that position with nothing to pack.

classmethod sampler_name()[source]#: Return the stable name used for sampler-specific annotations.

annotate_residue_type(rt: RefinedResidueType)[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types: PackedBlockTypes)[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType)[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt: RefinedResidueType) → Tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

create_samples_for_poses(pose_stack: PoseStack, task: SetPackerTask, *, built_rotamer_counts: Tensor = None) → Tuple[Tensor, Tensor, dict][source]#

Create rotamers for blocks the other samplers left uncovered.

A rotamer of the input conformation is built where the block either (1) has no allowed block types, so the residue is fixed, or (2) received no rotamers from any other sampler.

Parameters:: built_rotamer_counts – Rotamers actually produced per considered block by every other sampler. Supplied by the rotamer builder, which runs this sampler last. None means no other sampler ran.

fill_dofs_for_samples(pose_stack: PoseStack, task: PackerTask, orig_kinforest: KinForest, orig_dofs_kto: Tensor[slice(None, None, None), 9], gbt_for_conformer: Tensor, block_type_ind_for_conformer: Tensor, n_dof_atoms_offset_for_conformer: Tensor, conformer_built_by_sampler: Tensor, conf_inds_for_sampler: Tensor, sampler_n_rots_for_gbt: Tensor, sampler_gbt_for_rotamer: Tensor, sample_dict: dict, conf_dofs_kto: Tensor[slice(None, None, None), 9])#: Write this sampler’s conformer degrees of freedom in place.

class tmol.pack.rotamer.FixedAAChiSampler[source]#

Bases: ChiSampler

Generate one ideal side-chain conformer for fixed amino acids.

classmethod sampler_name()[source]#: Return the stable name used for chi-sampler annotations.

defines_rotamers_for_rt(rt: RefinedResidueType)[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt: RefinedResidueType) → Tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

annotate_residue_type(block_type)[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types)[source]#: Attach optional sampler metadata to packed block types.

class tmol.pack.rotamer.IncludeCurrentSampler[source]#

Bases: ConformerSampler

Add each packable residue’s current conformation to its rotamer set.

classmethod sampler_name()[source]#: Return the stable name used for sampler-specific annotations.

annotate_residue_type(rt: RefinedResidueType)[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types: PackedBlockTypes)[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType)[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt: RefinedResidueType) → Tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

create_samples_for_poses(pose_stack: PoseStack, task: SetPackerTask) → Tuple[Tensor, Tensor, dict][source]#

Return counts, considered-block index per rotamer, and sampler data.

A sampler that sets samples_after_other_samplers is called with an extra built_rotamer_counts keyword holding the per considered-block total produced by every other sampler.

fill_dofs_for_samples(pose_stack: PoseStack, task: PackerTask, orig_kinforest: KinForest, orig_dofs_kto: Tensor[slice(None, None, None), 9], gbt_for_conformer: Tensor, block_type_ind_for_conformer: Tensor, n_dof_atoms_offset_for_conformer: Tensor, conformer_built_by_sampler: Tensor, conf_inds_for_sampler: Tensor, sampler_n_rots_for_gbt: Tensor, sampler_gbt_for_rotamer: Tensor, sample_dict: dict, conf_dofs_kto: Tensor[slice(None, None, None), 9])[source]#: Write this sampler’s conformer degrees of freedom in place.

class tmol.pack.rotamer.MCFingerprint(mc_ats: NDArray, mc_at_fingerprints: Tuple[AtomFingerprint, ...], fingerprint: Tuple[AtomFingerprint, ...], at_for_fingerprint: Mapping[AtomFingerprint, int])[source]#

Bases: object

Main-chain atom fingerprint and its residue-local atom mapping.

class tmol.pack.rotamer.NaChiRotamerSampler(params: NaTorsionParams, element_for_atom_type: dict, chi_sample_level: int = 0, sample_syn: bool = True, device: device = device(type='cpu'), chi_sample_expanded_limit: int = 100, chi_sample_limit: int = 1000)[source]#

Bases: ChiSampler

Glycosidic chi rotamers for DNA and RNA, taken from the na_torsion tables.

Every chi generated sits at a minimum of the term that will score it: the anti rotamer is the per-base, per-pucker mean and the syn rotamer is the fixed syn mean, each expanded in units of that term’s own sdev_chi. The pucker comes from the input sugar, which is not itself a packing degree of freedom.

The 2’-OH proton chi is expanded here rather than left to OptHSampler, which is applied to disjoint blocks; see DunbrackChiSampler, which folds proton chis in the same way.

classmethod from_database(param_db: ParameterDatabase, device: device, chi_sample_level: int = 0, sample_syn: bool = True) → NaChiRotamerSampler[source]#

Create a nucleic-acid chi sampler on a concrete device.

Parameters:

param_db – Source scoring and chemical parameters.
device – Target device. Unindexed CUDA resolves to the current GPU.
chi_sample_level – Number of standard-deviation expansion levels.
sample_syn – Include eligible syn rotamers when true.

Returns:

A sampler whose parameters and device metadata agree.

classmethod sampler_name()[source]#: Return the stable name used for chi-sampler annotations.

annotate_residue_type(rt: RefinedResidueType)[source]#: Attach optional sampler metadata to one residue type.

annotate_packed_block_types(packed_block_types: PackedBlockTypes)[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType)[source]#: Return whether this sampler supports a residue type.

first_sc_atoms_for_rt(rt: RefinedResidueType) → Tuple[str, ...][source]#: Return side-chain roots used to transfer main-chain geometry.

Bases: object

Padded batch of residue-local kinematic trees.

class tmol.pack.rotamer.RotamerKintree(kinforest_idx: NDArray, id: NDArray, doftype: NDArray, parent: NDArray, frame_x: NDArray, frame_y: NDArray, frame_z: NDArray, nodes: NDArray, scans: NDArray, gens: NDArray, n_scans_per_gen: NDArray, dofs_ideal: NDArray)[source]#

Bases: object

Residue-local kinematic tree and scan ordering in NumPy form.

class tmol.pack.rotamer.RotamerSet(n_rots_for_pose: Tensor, rot_offset_for_pose: Tensor, n_rots_for_block: Tensor[slice(None, None, None), slice(None, None, None)], rot_offset_for_block: Tensor[slice(None, None, None), slice(None, None, None)], pose_for_rot: Tensor, block_type_ind_for_rot: Tensor, block_ind_for_rot: Tensor, coord_offset_for_rot: Tensor, coords: Tensor[slice(None, None, None), 3], correlated_groups: tuple[CorrelatedBlockGroup, ...] = (), group_for_block: Tensor[slice(None, None, None), slice(None, None, None)] = NOTHING, first_rot_block_type: Tensor[slice(None, None, None), slice(None, None, None)] = NOTHING, max_n_rots_per_pose: int = NOTHING, pose_ind_for_atom: Tensor = NOTHING)[source]#

Bases: ValidateAttrs

Packed coordinates and pose/block indexing for generated rotamers.

class tmol.pack.rotamer.SidechainSampler(samplers: tuple[ConformerSampler, ...])[source]#

Bases: object

Every sampler needed to move an ordinary protein side chain.

Declaring sampling should not require knowing which sampler covers which residue. A rotamer library handles the residues it has entries for and a fixed-chi sampler handles the rest; callers who just want “sample side chains reasonably” should not have to compose that themselves.

Examples

>>> task.add_conformer_sampler(
...     SidechainSampler.from_database(database, pose_stack.device)
... )

classmethod from_database(database, device) → SidechainSampler[source]#: Bundle the rotamer-library and fixed-chi samplers for database.

expand_into_task(task) → None[source]#: Register each bundled sampler on task.

tmol.pack.rotamer.assign_chi_dofs_from_samples(pbt: PackedBlockTypes, block_type_ind_for_rot: Tensor, conf_inds_for_sampler: Tensor, sampler_n_rots_for_bt: Tensor, sampler_gbt_for_rotamer: Tensor, n_dof_atoms_offset_for_rot: Tensor, chi_atoms: Tensor[slice(None, None, None), slice(None, None, None)], chi: Tensor[slice(None, None, None), slice(None, None, None)], rot_dofs_kto: Tensor[slice(None, None, None), 9]) → None[source]#

Write sampled chis into packed [n_rotamer_atoms + 1, 9] DOFs.

chi_atoms and chi share shape [n_rotamers, max_n_chi]; negative atom indices mark unused chi columns.

tmol.pack.rotamer.build_rotamers(poses: PoseStack, task: SetPackerTask, chem_db: ChemicalDatabase) → tuple[PoseStack, RotamerSet][source]#

Build coordinates and indexing for every task-allowed conformer.

Parameters:

poses – Input poses supplying backbone geometry and current conformers.
task – Finalized packing choices and conformer samplers.
chem_db – Chemical definitions used to annotate residue types.

Returns:

The input poses and a device-resident rotamer set grouped by pose and block.

tmol.pack.rotamer.calculate_rotamer_coords(pbt: PackedBlockTypes, n_atoms_total: int, rot_kinforest: KinForest, nodes: NDArray, scans: NDArray, gens: NDArray, rot_dofs_kto: Tensor[slice(None, None, None), 9]) → Tensor[slice(None, None, None), 3][source]#

Fold conformer DOFs and restore residue-type atom ordering.

Parameters:

pbt – Packed block types defining the target device.
n_atoms_total – Number of real atoms across all conformers.
rot_kinforest – Coalesced conformer kinematic forest.
nodes – Kinematic nodes in generation order.
scans – Segmented-scan starts.
gens – Generation boundaries.
rot_dofs_kto – Conformer DOFs in kinematic-tree order.

Returns:

Rotamer coordinates shaped [n_atoms_total, 3] in residue-type order.

tmol.pack.rotamer.construct_single_residue_kinforest(restype: RefinedResidueType)[source]#

Create a kinforest for a single residue and its scan ordering data.

The kinforest data structure on its own is incomplete and before it can be stored will need to be left-padded with 0s. In particular, the id, doftype, parent, frame_x, _y and _z data all require the 0th position to be occupied by the “root” atom.

tmol.pack.rotamer.measure_pose_dofs(poses: PoseStack) → tuple[KinForest, Tensor[slice(None, None, None), 9]][source]#

Measure the internal coordinates of every real residue in a pose stack.

Parameters:: poses – Poses providing residue topology and Cartesian coordinates.
Returns:: A residue-local kinematic forest and its measured degrees of freedom.

tmol.pack.rotamer.merge_conformer_samples(conformer_samples: list[tuple[Tensor, Tensor, dict[str, Any]]]) → tuple[Tensor, Tensor, Tensor, list[Tensor], list[Tensor]][source]#

Merge sampler rows in considered-type, sampler, then source-row order.

Each sampler supplies a count per considered type and its source rows in ascending considered-type order. Prefix offsets locate each row directly; the returned destinations map original sampler rows into the merged arrays.

Dunbrack backbone-dependent rotamer sampling.

class tmol.pack.rotamer.dunbrack.DunSamplerPBTCache(bbdihe_uaids: Tensor[slice(None, None, None), 2, 4, 3], chi_defining_atom: Tensor[slice(None, None, None), slice(None, None, None)], non_dunbrack_sample_counts: Tensor[slice(None, None, None), slice(None, None, None), 2], non_dunbrack_samples: Tensor[slice(None, None, None), slice(None, None, None), 2, slice(None, None, None)], defines_rotamers_for_bts: Tensor, rottable_set_for_bt: Tensor, frozen_chi: tuple = ())[source]#

Bases: object

Data needed for chi sampling and for reporting how the chi are to be assigned to atoms

class tmol.pack.rotamer.dunbrack.DunSamplerRTCache(bbdihe_uaids: NDArray[2, 4, 3], chi_defining_atom: NDArray, non_dunbrack_sample_counts: NDArray[slice(None, None, None), 2], non_dunbrack_samples: NDArray[slice(None, None, None), 2, slice(None, None, None)], rottable_set_for_bt: int, frozen_chi: tuple = ())[source]#

Bases: object

Data to store in RefinedResidueType that will be reused repeatedly in the creation of the DunSamplerPBTCache

class tmol.pack.rotamer.dunbrack.DunbrackChiSampler(dun_param_resolver: DunbrackParamResolver, chi_sample_expanded_limit: int = 1000, chi_sample_limit: int = 1000)[source]#

Bases: ChiSampler

Sample amino-acid side-chain conformers from Dunbrack libraries.

classmethod sampler_name()[source]#: Return the stable name used for chi-sampler annotations.

annotate_residue_type(restype: RefinedResidueType)[source]#: TEMP TEMP TEMP: assume the dihedrals we care about are phi and psi

annotate_packed_block_types(packed_block_types: PackedBlockTypes)[source]#: Attach optional sampler metadata to packed block types.

defines_rotamers_for_rt(rt: RefinedResidueType)[source]#

Whether a rotamer library reaches this residue type.

A library resolving answers it for most residues: glycine and alanine have nothing to rotate and no library, and a noncanonical has one only where a reference names it. A residue that samples heavy chi of its own is built from those alone.

first_sc_atoms_for_rt(rt: RefinedResidueType) → Tuple[str, ...][source]#

The atom chi1 rotates, which is where the sidechain starts.

Read off the residue rather than named, so a noncanonical whose sidechain does not begin at an atom called CB still transfers its rotamers correctly. Empty for a residue with no chi to rotate.

tmol.pack.rotamer.dunbrack.create_dunbrack_sampler_from_database(param_db: ParameterDatabase, device: device) → DunbrackChiSampler[source]#

Create a DunbrackChiSampler from the default database.

Parameters:

param_db – The parameter database containing Dunbrack parameters
device – The device to use for the sampler. An unindexed CUDA device resolves to the current CUDA device.

Returns:

Configured sampler for rotamer building

Return type:

DunbrackChiSampler