Utilities#

General-purpose helpers used throughout TMol.

class tmol.utility.AttrMapping[source]#

Bases: Mapping

Mixin adding Mapping interface to attr classes.

class tmol.utility.AttrMutableMapping[source]#

Bases: AttrMapping, MutableMapping

Mixin adding a subset of the mutable mapping interface to attr classes.

As the keys of an attrs-based class are based on defined properties, this mixin does not support __delitem__-based components of the MutableMapping interface, (eg. m.pop(key), del m[key], …)

class tmol.utility.AutoNumber(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: Enum

Enum base that assigns consecutive integer values in declaration order.

class tmol.utility.LoggerMixin[source]#

Bases: object

Provide a lazily constructed logger named for the concrete class.

tmol.utility.bind_to_args(f, *args, **kwargs)[source]#: Bind args/kwargs for function into positional arguments.

tmol.utility.classlogger_for(instance: object) → Logger[source]#: Get {module}.{class name} named logger for object.

tmol.utility.exclusive_cumsum(inds: NDArray) → NDArray[source]#: Calculate exclusive cumulative sum over input array

tmol.utility.exclusive_cumsum1d(inds: Tensor | Tensor) → Tensor | Tensor[source]#: Compute a one-dimensional exclusive cumulative sum.

tmol.utility.exclusive_cumsum2d(inds: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)]) → Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)][source]#: Compute an exclusive cumulative sum along the second dimension.

tmol.utility.exclusive_cumsum2d_w_totals(inds: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)]) → Tuple[Tensor[slice(None, None, None), slice(None, None, None)], Tensor] | Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[source]#: Return row-wise exclusive cumulative sums and inclusive row totals.

tmol.utility.get_all_residue_positions(array)[source]#: Return the residue index of each atom in a Biotite atom array.

tmol.utility.get_all_segment_positions(starts, length)[source]#: Return the segment index of each position from exclusive segment starts.

tmol.utility.ignore_unused_kwargs(func)[source]#

Ignore kwargs not present in func signature.

Decorate func with wrapper dropping any kwargs not present in the func signature.

Example

Allows function invocation with kwargs bags that are a superset of required args:

>>> @ignore_unused_kwargs(lambda a, b: a + b)(a=1, b=2, c=5)
3

tmol.utility.just_one(vals)[source]#: Extract a single value from a length one collection of values.

tmol.utility.logger_for_class(cls: type) → Logger[source]#: Get {module}.{name} named logger for class.

tmol.utility.nvtx_range(name)[source]#: Annotate a CUDA operation range when CUDA is available.

tmol.utility.qualified_name(obj: Type | Callable) → QualifiedName[source]#: The fully qualified <module>.<name> for a class/function.

tmol.utility.resolve_device(device: device) → device[source]#: Resolve an unindexed CUDA device to the current device.

tmol.utility.u(input_string: str, case_sensitive: bool | None = None, **values: Any) → QuantityT#

Parse a mathematical expression including units and return a quantity object.

Numerical constants can be specified as keyword arguments and will take precedence over the names defined in the registry.

Parameters:

input_string
case_sensitive – If true, a case sensitive matching of the unit name will be done in the registry. If false, a case INsensitive matching of the unit name will be done in the registry. (Default value = None, which uses registry setting)
optional – If true, a case sensitive matching of the unit name will be done in the registry. If false, a case INsensitive matching of the unit name will be done in the registry. (Default value = None, which uses registry setting)
**values – Other string that will be parsed using the Quantity constructor on their corresponding value.

tmol.utility.unique_val(vals)[source]#: Extract a single, unique value from a collection of values.

Public aliases and units#

`Angle`	NewType creates simple unique types with almost zero runtime overhead.
`BondAngle`	NewType creates simple unique types with almost zero runtime overhead.
`ClassLogger`	Intermediate representation of attributes that uses a counter to preserve the order in which the attributes have been defined.
`DihedralAngle`	NewType creates simple unique types with almost zero runtime overhead.
`ureg`	The unit registry stores the definitions and relationships between units.

Tensor utilities#

PyTorch tensor utility operations.

tmol.utility.tensor.cat_differently_sized_tensors(tensors: Sequence[Tensor]) → tuple[Tensor, Tensor[slice(None, None, None), slice(None, None, None)], Tensor[slice(None, None, None), slice(None, None, None)]][source]#

Concatenate padded tensors along dimension zero and report metadata.

Parameters:: tensors – Same-rank tensors with a shared dtype and device.
Returns:: The padded concatenation, original trailing sizes, and output strides.

tmol.utility.tensor.exclusive_cumsum1d(inds: Tensor | Tensor) → Tensor | Tensor[source]#

Compute an exclusive prefix sum over a one-dimensional integer tensor.

Parameters:: inds – Values to accumulate.
Returns:: Same-shaped prefix sums where each value is the sum of preceding elements. An empty input remains empty.

tmol.utility.tensor.exclusive_cumsum2d(inds: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)]) → Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)][source]#

Compute exclusive prefix sums along each row of an integer tensor.

Parameters:: inds – Values to accumulate along dimension one.
Returns:: Same-shaped row-wise prefix sums where each value is the sum of preceding columns. Zero-width inputs remain zero-width.

tmol.utility.tensor.exclusive_cumsum2d_and_totals(inds: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)]) → tuple[Tensor[slice(None, None, None), slice(None, None, None)], Tensor] | tuple[Tensor[slice(None, None, None), slice(None, None, None)], Tensor][source]#

Compute row-wise exclusive prefix sums and inclusive row totals.

Parameters:: inds – Values to accumulate along dimension one.
Returns:: The same-shaped exclusive prefix sums and the sum of each row. A zero-width row has a total of zero.

tmol.utility.tensor.invert_mapping(a_2_b: Tensor | Tensor, n_elements_b: int | Tensor | None = None, sentinel: int = -1) → Tensor | Tensor[source]#

Create the inverse mapping b_2_a for an input mapping a_2_b.

Parameters:

a_2_b – One-dimensional integer mapping from A indices to B indices.
n_elements_b – Output size, inferred from a_2_b when omitted.
sentinel – Value assigned to B indices without a corresponding A index.

Returns:

A mapping from B indices back to A indices.

tmol.utility.tensor.join_tensors_and_report_real_entries(tensors: Sequence[Tensor], sentinel: int = -1) → tuple[Tensor, Tensor[slice(None, None, None), slice(None, None, None)], Tensor][source]#

Pad tensors along dimension zero and identify their real entries.

Parameters:

tensors – Tensors with matching trailing dimensions, dtype, and device.
sentinel – Value used to pad missing entries.

Returns:

Per-tensor lengths, a validity mask, and the padded tensor batch.

tmol.utility.tensor.nplus1d_tensor_from_list(tensors: Sequence[Tensor]) → tuple[Tensor, Tensor[slice(None, None, None), slice(None, None, None)], Tensor[slice(None, None, None), slice(None, None, None)]][source]#

Pad tensors into a new leading dimension and report shape metadata.

Parameters:: tensors – Same-rank tensors with a shared dtype and device.
Returns:: The padded tensor, original sizes, and strides into the padded tensor.

tmol.utility.tensor.print_row_numbered_tensor(tensor: Tensor) → None[source]#: Print a one- or two-dimensional tensor with zero-based row indices.

tmol.utility.tensor.stretch(t: Tensor | Tensor, count: int | Tensor) → Tensor | Tensor[source]#

Repeat each element of a one-dimensional integer tensor.

Parameters:

t – Values to repeat.
count – Number of repeats, as an integer or scalar integer tensor.

Returns:

A flattened tensor with each input element repeated count times.

tmol.utility.tensor.stretch2(t: Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)], count: int | Tensor) → Tensor[slice(None, None, None), slice(None, None, None)] | Tensor[slice(None, None, None), slice(None, None, None)][source]#

Repeat each element along the second dimension of an integer tensor.

Parameters:

t – Two-dimensional values to repeat.
count – Number of repeats, as an integer or scalar integer tensor.

Returns:

A tensor with each row element repeated count times.