Naming conventions

How things are named in T3Toolbox, so you can predict a name you have never seen — and find the function you want from the name alone. The conventions exist to help the reader; where a convention would have hurt more than helped, we broke it deliberately, and the exceptions are cataloged at the end. (The rules contributors must follow when naming new things — including which of these conventions are rename-invariant — are in contributor/naming_rules.md.)

The two layers

• Frontend (t3toolbox/*.py): thin object-oriented classes over frozen dataclasses. Methods carry no family prefix — the class is the namespace (x.probe(...), v.apply_derivatives(...)).

• Backend (t3toolbox/backend/*.py): stateless functions on raw .data tuples / supercores. Public backend functions carry a family prefix naming their primary operand’s representation. Backend users import submodules explicitly (from t3toolbox.backend import probing); nothing is re-exported flat.

The family prefix grammar

[w][u]<family>_ — modifiers stack in order weighted → uniform → family.

Prefix	Operand	Example
t3_	ragged Tucker tensor train data (tucker_cores, tt_cores)	t3_probe, t3_to_dense, t3_inner_product
ut3_	uniform T3 data (tucker_supercore, tt_supercore, shape, masks)	ut3_probe, ut3_squash_tails
tv_	tangent vector: a (frame, variations) pair treated as the sum of its terms	tv_apply, tv_retract, tv_to_t3
utv_	uniform tangent vector	utv_apply, utv_retract, utv_to_ut3
fv_	frame / variations data as indexed pieces (coarse: frame-only and variations-only ops share it)	fv_to_t3 (single indexed term), fv_variations_zeros, fv_frame_reverse
ufv_	uniform frame / variations	ufv_apply_frame_masks, ufv_variations_reverse
tt_	a bare TT core chain (no Tucker, no masks)	tt_reverse, tt_squash_tails, tt_left_orthogonalize
dense_	a dense (full) tensor operand	dense_probe, dense_t3svd
(none)	representation-agnostic infrastructure	common, contractions, stacking, linalg, ranks

w (weighted) exists only on t3/tv; the weighted layer is parked pending a redesign. The founding disambiguation example: fv_to_t3(index, frame, variations) materializes ONE indexed term of the pair, while tv_to_t3(frame, variations) is the efficient SUM of all terms — distinct math on the same data, told apart by the prefix alone.

Polymorphism: the ragged name is the polymorphic name

Many backend ops accept ragged or uniform operands and dispatch internally (is_ndarray on the input — a tuple of cores is ragged, one stacked supercore is uniform). Such a function lives unadorned in the base family; there is no separate u-twin. The tt_ chain family is fully polymorphic (tt_reverse, tt_squash_tails, tt_left_orthogonalize serve both layers — utt_ is reserved but has no members); t3_apply and t3_entries likewise take either representation. A u-prefix therefore signals uniform-specific logic (masks, supercore packing), not merely “works on uniform”.

The module map (family × operation kind)

Backend modules tile a matrix of (family) × (operation kind: constructors · conversions · operations · linalg · orthogonalization · svd · sampling · masking):

	constructors	conversions	operations	linalg	orthogonalization	svd	masking
t3	t3_constructors	t3_conversions	t3_operations	t3_linalg	t3_orthogonalization	t3_svd	—
ut3	ut3_constructors	ut3_conversions	ut3_operations	ut3_linalg	ut3_orthogonalization	ut3_svd	ut3_masking
tv / utv	—	—	tv_operations / utv_operations	—	—	—	—
fv / ufv	—	fv_conversions / ufv_conversions	fv_operations / ufv_operations	—	—	—	ufv_masking
tt	—	—	tt_operations	—	tt_orthogonalization	—	—

Outside the matrix: the unprefixed infrastructure (common, contractions, stacking, linalg, ranks) and the fitting/optimization stack (fitting, optimizers, uniform_fitting), which is organized by role, not by operand family.

Sampling is the deliberate exception — the ragged sampling modules are grouped by sampling type, not by family: apply.py, entries.py, probing.py each hold their type’s t3 + tv + dense ops, transposes, and frame sweeps, plus one sampling_derivatives.py for all the jet (derivative) machinery. Why: for one sampling type the t3 evaluation, the tangent 𝒥/𝒥ᵀ, and the sweeps form a single connected algorithm (presented together in the paper), and the containment probe ⊃ apply ⊃ entries gives the three files parallel structure — apply.py and entries.py import the general machinery from probing.py, never the reverse. The family axis survives inside each file through the function prefixes (t3_apply, tv_apply, dense_apply_derivatives, …).

The uniform sampling modules (ut3_sampling.py, utv_sampling.py) are instead grouped by object type — deliberately asymmetric. The uniform sampling functions are not independent mathematical algorithms: each is a thin wrapper (mask once, pack, delegate to the shared polymorphic ragged machinery, re-mask) whose few real operations are tied to its object’s structure, not to the sampling math. Grouping wrappers by the object they wrap is what helps the reader; the algorithm story lives in the ragged type files they delegate to.

Converters encode the operand type

Within the uniform classes, t3-flavored names mean “the ragged layer”: UniformTuckerTensorTrain.from_t3(x, ...) converts a ragged T3 to uniform, and UT3Frame.from_t3frame / UT3Tangent.to_t3tangent are the cross-layer converters, while from_ut3/to_ut3 are same-layer. On the ragged classes there is no such ambiguity, so T3Frame.from_t3/to_t3 are same-layer. The names carry the types.

Some frontend modules also export a same-named function pair with the backend: e.g. frame_variations_format.t3_orthogonal_representations (returns T3Frame/T3Variations objects) wraps backend.fv_conversions.t3_orthogonal_representations (returns raw data), and likewise ut3_orthogonal_representations. Same name = same operation; the module tells you which layer you are holding.

Parameter names carry representation too

• x — ragged T3 data; data — uniform UT3 data (supercores + shape + masks).

• xx — a collection of ragged objects; uxx — a collection of uniform objects.

• frame/variations (frontend objects) vs frame_data/variations_data (raw tuples).

• ww — probe/apply vectors; pp — perturbation vectors; index — entry indices.

• Batch blocks are single capital letters — C (frame stack), W (probe stack), K (tangent stack), frame-inner order W+K+C — and body locals encode their axis layout as a name suffix (mu_WCa, C_aib); see docs/batching_and_stacking.md and docs/contributor/signature_style.md.

Semantic markers (load-bearing — you can trust them)

• corewise — coordinate-space math on the core arrays, never Hilbert–Schmidt / tensor space. sum_stack (true tensor sum; rank-growing) vs sum_stack_corewise (elementwise core sum; rank-preserving, NOT the tensor sum); corewise_dot / utv_corewise_inner (coordinate metric) vs t3_inner_product / MANIFOLD.inner (HS); t3_corewise_randn (iid core entries) vs MANIFOLD.randn (tangent-space Gaussian).

• numerically_ — an SVD-grade numerical check, vs bare structural integer arithmetic (has_minimal_ranks vs has_numerically_minimal_ranks).

• _trs suffix (sampling-derivative jets) — the dense binomial-tensor implementation, kept as a reference twin of the standard recurrence/scan form that owns the bare name. compute_mu_jets (the standard, memory-lean, call-site-wired form) vs compute_mu_jets_trs (contracts the trs binomial tensor as a dense einsum operand: numerically equal to tolerance, higher peak memory, occasionally faster in tiny/memory-abundant regimes). The bare name is always the recommended default; _trs is opt-in. (trs = the binomial convolution tensor trs[t,r,s] = C(t,r)·[r+s=t], the module’s own term.)

• Capability-honest tails — ut3_full_sum (all modes only, vs ragged t3_sum(axis=...)), ut3_norm_orthogonalized (always orthogonalizes). The uniform twin is not renamed to match the ragged name when it genuinely supports less.

Why “frame”, not “basis”

The orthogonal representation of a tangent space (T3Frame, the fv_/ufv_ families) is deliberately not called a basis. “Basis” implies minimality — a linearly independent spanning set — and the orthogonal representation does not require minimal ranks: at a non-minimal-rank point it is overcomplete, and the library supports that on purpose (see the numerical-contracts material: minimal rank is a precondition for essentially nothing). “Frame” is the idiomatic term in manifold optimization for exactly this kind of possibly-redundant orthogonal spanning system. (The T4S paper names the object neither way, so there is no paper conflict to worry about.)

Cataloged exceptions (deliberate)

• Sampling modules are grouped by type, not family (above).

• Brand names: t3svd, t3m (and compounds like t3m_swap) are algorithm names, exempt from prefix-position rules.

• Chain helpers keep descriptive names: tt_zipper_left_to_right, tucker_change_core_shapes, and the uniform supercore-pair workers (up_orthogonalize_tt_supercores, ut3svd_supercores) — the name states the operand better than a bare family prefix would.

• Fitting/optimization is role-named: uniform_minimal, uniform_least_squares_problem, the uniform_*_kind seam builders, pack_sample/pack_data, and the packedness utilities (is_packed, pack_if_ragged) are fitting infrastructure, not family data ops.

• MANIFOLD / COREWISE are the frontend geometry singletons; the backend GeometryOps singletons are MANIFOLD_OPS / COREWISE_OPS.

• Frontend methods stay unprefixed even when a same-named backend function exists at a different level (e.g. the method x.rank_adjustment_sweep() vs backend t3_rank_adjustment_sweep); the class namespace disambiguates.

• Frontend free functions DO carry the family prefix — they have no class namespace, so the prefix does that job instead. It is the same rule as the bullet above, not an exception to it: whatever disambiguates, disambiguates. Examples: t3_orthogonal_representations / ut3_orthogonal_representations, and the weighted layer’s t3_absorb_weights / ut3_absorb_weights / fv_absorb_weights / ufv_absorb_weights (+ t3_/ut3_weighted_norm, _weighted_inner).

  • Sharing a name with the backend twin is fine, and intended — t3_orthogonal_representations exists in both frame_variations_format (objects) and backend/fv_conversions (raw .data). Same operation, two levels; the module namespace tells them apart, and the backend is never re-exported flat, so they never meet.

  • The prefix is what makes the root export possible. Ragged/uniform × tensor/tangent gives four distinct “absorb the weights” operations; unprefixed they would all be absorb_weights and could not coexist in t3toolbox/__init__.py (the second import would silently shadow the first). The weighted free functions were briefly unprefixed and hit exactly this; prefixing them was the fix (2026-07-15). The classes never had the problem — T3Weights / UT3Weights / T3FrameWeights / UT3FrameWeights are already distinct.

• require_concrete_masks is a jit guard (infrastructure), unprefixed by design — and lives in backend/common.py for the same reason, beside the ValueHashedMasks mixin and prefix_mask: those three are the uniform mask-representation contract (concrete host arrays · value-based hash/eq · the canonical prefix form), which every uniform object’s masks obey — plain, frame, variations, and weights. They are not part of any one object’s ut3_*/ufv_* family.

Intended asymmetries (uniform vs ragged)

Where a uniform class or method offers less surface than its ragged twin, the gap is a design decision, not an unfinished port — do not read these as TODOs:

• UT3Tangent has no save/load/to_vector/from_vector (all four exist on T3Tangent). A varying-rank uniform stack has no single flat-vector signature to reconstruct from; jax-native optimization works on the pytree directly, and flat-vector interop (e.g. scipy) routes through the ragged layer.

• UniformTuckerTensorTrain.sum_stack() takes no axis (ragged: sum_stack(axis=None)).

• UniformTuckerTensorTrain.to_dense() takes no squash_tails (ragged has it).

• UniformTuckerTensorTrain.t3svd(...) has no rtol/atol — uniform truncation is structural (max-rank masks), never numerical; per-element numerical truncation could give different ranks per stack element, which the uniform shape cannot represent (see uniform_equivalence_contract.md).

The capability-honest-tails rule (above) is the same principle at the function level.