Data model and conventions

TMol stores molecular state in PyTorch tensors and metadata in Python objects.

Tensor shapes

Tensor axes represent poses, blocks, atoms, score terms, or rotamers:

Data	Typical shape	Meaning
Pose coordinates	[n_poses, max_n_atoms, 3]	Cartesian coordinates with padding for heterogeneous systems.
Block types	[n_poses, max_n_blocks]	Index of each block’s chemical type, with sentinel padding.
Whole-pose scores	[n_poses] or [n_terms, n_poses]	Weighted totals or a score-term decomposition.
Block-pair scores	[n_poses, n_blocks, n_blocks]	Directed block-pair accounting for analysis and reweighting.

Boolean masks identify real atoms or selected coordinates. Integer tensors encode topology, block types, connections, and kinematic indices. Do not infer valid entries from coordinate values alone.

Device and dtype

All tensors participating in one operation must use compatible devices and dtypes. A PoseStack, its PackedBlockTypes, rendered scoring modules, and movement data normally live on the same CPU or CUDA device.

TMol APIs commonly accept a device-like value and normalize it through tmol.utility.resolve_device(). Preserve the input coordinate dtype unless an API documents a stronger requirement; silently mixing float32 and float64 changes performance and can invalidate comparisons.

Python data objects

Metadata, database records, I/O contexts, and protocol settings use attrs classes and typed containers. Many are immutable; extension operations return a new object.

NumPy arrays handle third-party interfaces and string/object data. Converting through NumPy breaks PyTorch autograd.

Public typing helpers

The tmol.types package provides runtime conversion, validation, tensor shape annotations, and TensorGroup helpers used throughout the codebase. The tmol.utility package contains device, cumulative-sum, units, and other implementation helpers. Most workflow users interact with the molecular objects in tmol.pose, tmol.io, and tmol.score instead.

See Terminology and modeling choices for the difference between poses, blocks, deposited atoms, and built atoms.