Design decisions

Architecture decision records: the choices that shape the whole library, and the alternatives they rejected.

An architecture decision record (ADR) captures one decision: the context that forced it, the options considered, the choice and its consequences. These records explain why kael looks the way it does. Read them after the chapters they affect, or before you propose a change that touches the same trade-off.

New decisions in the library get a record in the library repository first. This section explains each record in more depth.

  1. Runtime data type Why the element type of a kael tensor is a runtime value checked by a switch, not a template parameter of the Tensor class.
  2. Tensor as a shared handle Why copying a kael Tensor shares its data, how the three layers Tensor, TensorImpl and Storage divide the work, and what that sharing costs.
  3. Type promotion Why kael picks the result dtype of mixed operations with PyTorch's category-based rules, and where it deliberately departs from them.
  4. A PyTorch-shaped API with typed errors Why kael copies PyTorch's names and semantics, how numbers mix with tensors in C++, and why failures are typed exceptions that map to Python exceptions.
  5. Define-by-run autograd graph Why kael records the autograd graph while operations run, how nodes and edges own each other, and which restrictions keep the backward pass correct.