Architecture#

TMol is centered on two core representations: batched molecular state in tmol.pose and term-specific scoring machinery in tmol.score. Structure I/O in tmol.io builds PoseStack objects from PDB/mmCIF files and model outputs.

These components operate over a shared chemical vocabulary defined in tmol.database.chemical, with additional term-specific data given in tmol.database.scoring.

+------+       +------+          +---------+
|      |       |      |          |         |
|  io  +------>+ pose +----------o scoring |
|      |       |      |          |         |
+------+       +--+---+          +--+----+-+
                  |                 |    |
                  | +---------------v-+  |
                  | |                 |  |
                  | | database.scoring|  |
                  | |                 |  |
                  | +--------+--------+  |
                  |          |           |
                  | +--------v--------+  |
                  | |                 |  |
                  +->database.chemical<-+
                    |                 |
                    +-----------------+

Modeling lifecycle#

A typical TMol application moves through four explicit stages:

structure records or model tensors
               |
               v
      I/O and chemical typing
               |
               v
    PoseStack + build context
        |              |
        v              v
 rendered scorers   packing / movement setup
        |              |
        +-------+------+
                v
     score, optimize, or analyze
                |
                v
     Biotite structure or PDB output

The ParameterDatabase supplies chemical and scoring definitions. I/O chooses compatible block types and constructs a PackedBlockTypes collection on the requested device. The resulting PoseStack owns coordinates, topology, block indices, and references to those packed types.

Packing may return a new stack when chemical identities or atom counts change. Cartesian or kinematic minimization usually changes coordinates while keeping the same layout. That distinction determines whether an existing rendered scoring module can be reused.

tmol.pose and tmol.score meet when a ScoreFunction renders a scoring module for a PoseStack, for example with render_whole_pose_scoring_module(). Score terms annotate PackedBlockTypes and then render torch.nn.Module objects for repeated evaluation.

Scoring Overview#

Scoring is managed by rendered PyTorch modules that evaluate configured energy terms over a PoseStack. Coordinates have shape [n_poses, max_n_atoms, 3]; real_atoms distinguishes molecular atoms from padding, while block-type and connection tensors describe residue and polymer topology.

PoseStack + ScoreFunction
           |
           +--> whole-pose module --> [n_poses]
           |
           +--> block-pair module --> [n_poses, n_blocks, n_blocks]
           |
           +--> rotamer module -----> packer candidate energies

The score function implementation is partitioned into score term classes, each covering a logically distinct component of the energy function. Each term annotates residue and block data before rendering its coordinate-dependent module. Calls may return either the weighted total or a leading score-term axis when sum_terms=False. The complete score-type-to-term map is documented in Score Terms.

Where to continue#