API reference

The library has two documented layers (see User guide “Frontend and backend”):

• the frontend – classes re-exported at the package root (import t3toolbox);

• the backend – stateless functions on raw .data tuples, imported explicitly by submodule (from t3toolbox.backend import probing). The backend is a first-class surface: everything the frontend does is available here.

The frontend surface

Everything below is importable directly from t3toolbox.

Tensors

• TuckerTensorTrain – the keystone class (ragged); .data = (tucker_cores, tt_cores).

• UniformTuckerTensorTrain – the uniform (supercores + masks) mirror; its masks holder UT3Masks is module-level (not at the root).

Frames, variations, tangents

• T3Frame, T3Variations, t3_orthogonal_representations() – the orthogonal frame + gauged variations of a tangent direction; t3svd_orthogonal_representations() – the same frame in the T3-SVD gauge together with its singular values (what a singular-value metric pairs with).

• T3Tangent – a tangent vector: one (frame, variations) pair.

• UT3Frame, UT3Variations, ut3_orthogonal_representations(), UT3Tangent – the uniform mirrors.

• Module-level (not at the root): the pair guards check_fv_pair / check_ufv_pair / check_fw_pair / check_ufw_pair, and fv_to_t3() (substitute one variation core into the frame – the single-term tangent word).

Geometries

• MANIFOLD / COREWISE (in manifold) – the Hilbert-Schmidt manifold geometry and the Euclidean coordinate geometry.

• UNIFORM_MANIFOLD / UNIFORM_COREWISE (in uniform_manifold) – their uniform twins.

• shared() with the shorthands shared_manifold() / shared_corewise() – wrap any of the four geometries to constrain the Tucker factors equal within groups of modes (Shared Tucker factors (SF-T3)).

• Module-level (not at the root): the classes behind the singletons and shared(...) – ManifoldGeometry / CorewiseGeometry, UniformManifoldGeometry / UniformCorewiseGeometry, SharedGeometry – and manifold_dim() (the tangent-space dimension).

Weights

• T3Weights / UT3Weights – diagonal edge weights on a T3 as a tensor; T3FrameWeights / UT3FrameWeights – a metric on a tangent’s coordinates (Weighting (edge weights)).

• The free functions t3_absorb_weights / ut3_absorb_weights / fv_absorb_weights / ufv_absorb_weights, and t3_weighted_norm / t3_weighted_inner (+ the ut3_ twins).

Fitting and optimization

• GaussNewtonModel – the geometry-generic local model (one class for both the ragged and the uniform representation).

• The six model factories (in fitting): entries_model(), apply_model(), probe_model(), entries_derivatives_model(), apply_derivatives_model(), probe_derivatives_model().

• The four optimizers (in optimizers): gradient_descent(), mc_sgd(), adam(), newton_cg(). Ragged vs uniform is inferred from the initial guess x0.

• Regularizer / IdentityRegularizer – the optional objective term ρ(x) (Fitting & optimization §4.9). These are the one exception to the rule above: they are not re-exported at the package root, so import them from the module – import t3toolbox.optimizers as topt; topt.IdentityRegularizer(1e-3) (defined in regularization).

Safety

• safety with the safe() / unsafe() context managers – the ambient numerical-precondition mode. Module-level helpers: SafetyTolerances, set_default_safety, current_safety, effective_rtol, comparison_rtol, checks_active, require, frames_equal, frames_equal_or_skip, is_tracing, and the DEFAULT_RTOL_* constants.

The backend surface

Backend modules follow the family-prefix grammar (t3_ ragged tensor, ut3_ uniform tensor, tv_/utv_ tangent-variations, fv_/ufv_ frame-variations, tt_ bare TT chains, dense_ dense reference) – the complete grammar, module map, and deliberate exceptions are in Naming conventions. By area:

• Core families: t3_constructors, t3_conversions, t3_operations, t3_linalg, t3_orthogonalization, t3_svd, and the uniform mirrors (ut3_constructors, ut3_conversions, ut3_operations, ut3_linalg, ut3_orthogonalization, ut3_svd, ut3_masking), plus tt_operations and tt_orthogonalization for bare TT chains.

• Frames, variations, tangents: fv_conversions, fv_operations, tv_operations, and the uniform mirrors (ufv_conversions, ufv_masking, ufv_operations, utv_operations).

• Sampling (grouped by sampling type, the deliberate exception): probing, apply, entries, sampling_derivatives, and the uniform object-type wrappers ut3_sampling, utv_sampling.

• Fitting and optimization: fitting, optimizers, geometry (the value-typed geometries the optimizers consume), uniform_fitting, regularization (the ρ(x) objective term) and optimizer_display (the Newton-CG diagnostic display, so a backend user gets the identical output).

• Shared Tucker factors: sharing – partition validation, the tied-factor checkers, the shared-frame companion and the tied post-passes (Shared Tucker factors (SF-T3)); the frontend geometry wrapper lives in shared_geometry.

• Infrastructure: common, corewise (the layer-agnostic tree arithmetic on core tuples – a backend-style module that lives at the top level), contract() (the grouped-einsum interpreter – Grouped einsum — the contract interpreter), stacking, linalg, ranks.

Note

The rendered signatures on the module pages are regenerated from the parsed source, so each function page also shows the verbatim source signature – including the trailing shape-contract comments, which are the real type contract (Signature style — shape comments as the real type system).

Complete module pages

• t3toolbox
  • Submodules