README.md

Examples

Every example is self-contained, runnable from the repository root, and checked against an oracle that is not this package: an analytic formula, a dense or sparse rebuild of the same problem, or a published table with the paper named in the docstring. The acceptance versions live in tests/test_examples.py.

Gallery

qtt_divgrad_cross (code) — variable-coefficient diffusion $-\nabla\cdot(k\nabla u)=1$ on a $256^2$ QTT grid: the contrast-100 coefficient sampled at flux faces by TT-cross, solved by amen_solve with no preconditioner; the animation is the iterate after every sweep. Oracle: scipy.sparse assembly of the same scheme.	henon_heiles_ksl_paper (code) — Fig. 3 of Lubich–Oseledets–Vandereycken (SINUM 2015) end to end: the 10-D Hénon–Heiles spectrum by KSL time integration, sine-DVR, complex absorbing potential; 877 s where the paper reports 4425 s (and 54354 s for MCTDH); the frames are the run's real log. The resulting spectrum is here. Oracle: the paper's own figure; f=2 pinned against dense expm.
henon_heiles_spectrum (code) — the same spectral method with the eigensolver as the cross-check, at $d=8$ ($10^8$ states, beyond any dense oracle): coherent packet, autocorrelation, windowed FFT; the ground state agrees with eigb to 4.4e-6 and the 8-fold multiplet at 4.96–4.98 sits under one peak, matching to 5.8e-5. 100 s end to end, eigb's 12 levels in 29 s. Oracle: eigb on the same operator — two TT methods checking each other where neither has a dense referee.	fokker_planck_dumbbell (code) — the polymer dumbbell in shear flow of Dolgov–Khoromskij–Oseledets (SISC 2012): Crank–Nicolson in TT, Kramers viscometric functions reaching the paper's Table 3 ($\eta$ 1.03291 vs 1.03281). Oracles: analytic $\beta=0$ stationary state, sparse propagator, the $\alpha=0$ Lyapunov solution.
sir_network_cme (code) — the SIR master equation on a network (Dolgov–Savostyanov, AMC 2024): the $3^N$-state distribution in TT, rare-event tails as one dot product with an explicit indicator train — down to $10^{-12}$, where SSA would need $\sim 5\cdot 10^{13}$ trajectories. Oracles: brute-force propagator at small N, Gillespie SSA.	robust_completion (code) — completion with 2% outliers at 100x the scale: the square loss (the only one ALS can have) chases the corruption; Riemannian descent with a log-cosh loss (tt.rgd, torch autodiff through the tangent parametrization) recovers the tensor — six orders of magnitude apart on held-out entries. Oracle: dense ground truth on unobserved entries.
allen_cahn_ksl_deim (code) — Dektor's interpolatory projector-splitting integrator (tt.ksl_deim, ported from ttpy PR #102) on the 3D Allen–Cahn equation of his paper (LAA 2025, sec. 7.2): the cubic nonlinearity $u-u^3$ is evaluated only on QDEIM-selected cross fibers — the case the orthogonal-projector KSL cannot afford — with the paper's Fourier pseudospectral Laplacian as a rank-2 TT-matrix; the animation is the central slice separating into the $\pm 1$ phases. Oracle: dense solve_ivp of the same ODE at small n, plus monotone decay of the Ginzburg–Landau energy along the whole run.	sample_dirt_banana (code) — a sample-only probit bridge from the uniform square to a thin banana: seven low-rank residual TT densities fitted by orthogonal ALS, with exact TT square integrals and exact inverse Rosenblatt conditionals. The same reference cloud sharpens layer by layer; physical sliced $W_2$ falls from 0.439 to 0.052 (sampling floor 0.025), using 1,912 parameters in about 1.8 s. Oracle: the held-out analytic banana density for KL/TV, independent target samples for sliced Wasserstein, and the exact forward/inverse round trip.
qtt_fem_triangle (code) — Poisson on a triangle, a domain no single tensor-product grid fits: three glued QTT patches, z-order finite-element assembly with TT-cross Jacobian fields, one amen_solve on the coupled block train; the energies published with qtt-laplace (JCP 2021) reproduced to 1.5e-9. Oracle: the FEniCS energy curve shipped in that repository, approached from above as a Galerkin energy must.	smoluchowski (code) — the multicomponent Smoluchowski coagulation equation of Matveev–Zheltkov–Tyrtyshnikov–Smirnov (JCP 2016): the gain term is a lower-triangular convolution, so it is an FFT on every TT core and never leaves the format. The paper's $1000^2$ reference point — error 2.2e-3 at TT rank 13 — in 4.5 s, against the 215 580 s (2.5 days) it reports for the direct implementation of the same scheme; the frames are the run's real log. The paper's non-separable ballistic kernel (its eq. 17) is built too — a TT-cross of the $2d$-dimensional $K$, cut along the one bond that separates $\bar u$ from $\bar v$ — and lands on its Table 5 to the last digit printed from $N = 400$ up, in 16 s against the 4.9 days that row costs directly. Oracle: the analytic solution of the paper's eq. (18) and the exact total density $1/(1+t/2)$, every step; Table 5 of the paper for the ballistic kernel.
cross_approximation (code) — the package's two TT-cross engines side by side on identical black-box quadrature: greedy DMRG cross (dmrg_cross) vs rectangular-maxvol cross (rect_cross) on the Ising susceptibility integrals. At equal accuracy the greedy spends 5–9x fewer function evaluations on these smooth integrands, and its compiled path runs 1.6–2.0x faster than the original Fortran ttcross; medians over 5 seeds. Oracle: the analytic integral values of Bailey–Borwein–Crandall, known to hundreds of digits.

All examples

example	what it shows	oracle
qtt_divgrad_cross.py (code)	div–grad assembly by TT-cross, AMEn animation	scipy.sparse rebuild
amen_laplace.py	the AMEn linear solver on the QTT Laplacian	residual + dense solve
bpx_elliptic.py	BPX preconditioning: $4^d$ conditioning tamed, and why $CAC$ must never be assembled	analytic solution
qtt_fem_triangle.py (code)	Poisson on a triangle: three glued QTT patches (qtt-laplace)	the repository's FEniCS curve + its TT energies
iga_ring.py	isogeometric ring domain in QTT	manufactured solution
ising_integrals.py	Ising susceptibility integrals $C_m$ by greedy DMRG cross, racing the original Fortran ttcross	published values (Bailey–Borwein–Crandall)
cross_engines.py (code)	dmrg_cross vs rect_cross on identical integrands: 5–9x fewer evaluations at equal accuracy	analytic integral values
robust_completion.py (code)	the loss ALS structurally cannot have	dense ground truth
henon_heiles_spectrum.py (code)	spectra from one trajectory (autocorrelation method)	eigb on the same operator
henon_heiles_ksl_paper.py (code)	[LOV15] Fig. 3, quantum dynamics at paper scale	the paper; dense expm at f=2
fokker_planck_dumbbell.py (code)	[DKO12] sec. 4.2, polymer rheology in TT	three independent oracles
sir_network_cme.py (code)	[DS24] epidemics on networks, rare events	brute force + SSA
allen_cahn_ksl_deim.py (code)	Dektor's interpolatory KSL (tt.ksl_deim) on his paper's 3D Allen–Cahn	dense solve_ivp at small n + energy monotonicity
sample_dirt_banana.py (code)	sample-only residual TT transports learned by orthogonal ALS	analytic banana density + independent samples + exact round trip
smoluchowski/ (code)	[MZTS16] multicomponent coagulation: the gain term as an FFT on every TT core; the ballistic kernel separated by a cross of the $2d$-dimensional $K$	the paper's analytic eq. (18) + exact total density; Table 5 for the ballistic kernel