[Docs] Add downstream-usage guidance for tensor4all-rs

[shinaoka]

Context

This is the tensor4all-rs counterpart to tensor4all/tenferro-rs#1610. The downstream-usage guidance should cover tensor4all-rs-specific APIs and failure modes rather than only linking to the lower-level tenferro documentation.

Problem

A downstream user who wants to apply tensor-network operations currently has to discover several non-obvious facts from source code:

• the chain-facing TensorTrain, MPS, and MPO names share the same underlying representation;
• MPO–MPO contraction exists in both tensor4all-simplett and tensor4all-treetn, but these are different API layers;
• the TreeTN route is the canonical/general path used by the higher-level tensor4all APIs;
• the contraction method changes both cost and reliability;
• ACI tolerance options are easy to misinterpret.

Please add a bundled downstream-usage skill/guide (and link it from the README) following the direction of tenferro-rs#1610. Keep the generic tenferro material reusable, but make the tensor4all-specific examples compile as doctests or through the repository's snippet-test mechanism.

Tensor4all-specific pitfalls to document

1. ACI tolerance scaling

Document the exact option name scale_tolerance (not rescale_tolerance) and show when to enable it.

The guide should explain:

• the difference between absolute and scale-relative convergence;
• why scale_tolerance = true is generally the appropriate choice for scale-independent ACI tolerances;
• that this option is not an independent accuracy certificate: held-out samples and per-sweep diagnostics are still needed;
• the current early-convergence/held-out-accuracy caveat tracked in #572.

2. MPO–MPO contraction has two layers

Explicitly distinguish:

• SimpleTT: low-level tensor4all-simplett::mpo routines such as contract_naive, contract_zipup, and contract_fit;
• TreeTN: the topology-aware implementation in tensor4all-treetn, exposed to chain users through tensor4all-itensorlike::TensorTrain::contract and ContractOptions.

The guide should say that the TreeTN path is the normal/canonical downstream path. SimpleTT should be presented as a lower-level implementation/testing API, not as a second interchangeable public path.

Also call out that TensorContractionLike::contract is not the method to use for TensorTrain; users should call TensorTrain::contract (or the free contract function).

The two representations must not be silently conflated: MPS and MPO are aliases at the type level, so the physical input/output index convention remains the caller's responsibility.

3. Choosing zip-up, fit, and naive

Provide a short decision table:

Method	Intended use
zip-up	Default production path for large TT/TreeTN contractions; one pass and scalable, with local/partial-environment truncation.
fit	Use the TreeTN implementation when variational refinement is worth extra sweeps; document nfullsweeps/with_nsweeps, convergence, and the cost of full sweeps.
naive	Dense/reference path for small bond dimensions and correctness tests only; require an explicit dense-size limit where applicable. Never use it as the production algorithm.

The guide must mention #571: the current SimpleTT contract_fit implementation is not equivalent to the TreeTN fit path and must not be used as the canonical performance/correctness example until that issue is resolved.

Minimal example

Include a compiling example for the canonical TreeTN-backed API, for example:

use tensor4all_core::truncation::SvdTruncationPolicy;
use tensor4all_itensorlike::{ContractOptions, Result, TensorTrain};

fn multiply(a: &TensorTrain, b: &TensorTrain, chi: usize, tol: f64) -> Result<TensorTrain> {
    let options = ContractOptions::zipup()
        .with_max_rank(chi)
        .with_svd_policy(SvdTruncationPolicy::new(tol));

    a.contract(b, &options)
}

Also show the corresponding fit and small-reference naive option construction, and a short ACI example demonstrating scale_tolerance.

Acceptance criteria

• A downstream-usage skill or guide exists in the standard in-repository location and is linked from README.md.
• The guide contains the four sections above and links to tenferro-rs#1610, tensor4all-rs#571, and tensor4all-rs#572.
• The canonical TreeTN-backed MPO–MPO example compiles.
• The method-selection guidance makes the dense-only/testing role of naive explicit.
• The SimpleTT/TreeTN split and the current SimpleTT fit caveat are visible before users copy an example.
• The ACI section uses the exact scale_tolerance spelling and recommends held-out validation for convergence-sensitive workflows.

[shinaoka]

Rayon thread-count and affinity follow-up

The current tensor4all-rs dependency pins tenferro-rs at 9182bff11c29ef77ef94f9940b7ef5463fd160ac (2026-07-17).

At that pinned revision:

• CpuContext::try_from_env() first checks RAYON_NUM_THREADS.
• When it is absent, it calls tenferro_cpu::available_parallelism().
• available_parallelism() first queries the Linux process affinity mask via sched_getaffinity, then falls back to std::thread::available_parallelism().
• CpuContext::with_threads(n) creates an n)-worker Rayon pool, but the normal with_threadspath leavespinned_cpus = None`. Thus affinity affects the worker count, not worker CPU pinning. Explicit pinned contexts are a separate API.
• faer::Par::rayon(0) inherits the current tenferro Rayon pool.

On the benchmark host, the process affinity is 0-63 (64 CPUs), so with no RAYON_NUM_THREADS the effective pool is 64 workers. The default build uses tenferro-cpu-faer, so external BLAS thread variables are not the main control here.

This is also confirmed by the gw-rs R=5, T=0.1, MU=0.5 run:

setting	forward FT	reflection	backward FT	total
RAYON_NUM_THREADS unset (64 workers)	24.4 s	12.7 s	22.6 s	about 92 s
RAYON_NUM_THREADS=1	0.6 s	0.3 s	0.6 s	about 8.6 s

The sanity values match, so this is an execution-policy/per-kernel parallelism issue rather than a numerical difference. The downstream guide should document both the affinity-based default and the need to benchmark an appropriate explicit thread count for small QTT kernels.

[shinaoka]

Now that the tenferro counterpart has landed (tensor4all/tenferro-rs#1610 and tensor4all/tenferro-rs#1613, both closed by merged PRs tensor4all/tenferro-rs#1633-1635 adding a downstream compute skill, an llms.txt index, and crate preludes), two suggestions for this issue: (1) reuse the merged tenferro-compute skill layout (SKILL.md + references/) as the template; (2) include an llms.txt for https://tensor4all.org/tensor4all-rs/ in scope here or as a sibling issue, generated from the mdBook SUMMARY.md so it cannot drift. Related new issues from the same audit: #577 (README doctest wiring), #578 (architecture.md routing gaps), #579 (preludes), #580 (error remedy clauses).

[shinaoka]

Scope additions from the 2026-08-08 persona discussion (maintainer decisions, now tracked in the AX/conventions umbrella):

• simplett vs treetn positioning is decided: treetn is the default stack going forward; simplett is kept for compatibility with the older Julia ecosystem. The guide should state this explicitly and route new users to the TreeTN-backed path (consistent with this issue's existing 'TreeTN is canonical' direction).
• Add an 'arriving from ITensors.jl' section: the rtol = sqrt(cutoff) trap written as a warning (porting cutoff values verbatim silently truncates at the squared tolerance); a function-level mapping table (maxdim -> max_bond_dim per Unify the bond-dimension cap vocabulary on max_bond_dim: Option<usize> (today: max_bond_dim/max_rank/maxbonddim) #583, orthogonalize! / inner / apply / dmrg -> their counterparts); 0- vs 1-indexing (single 0-indexed convention once Migrate the public API from 1-indexed (Julia convention) to 0-indexed quanticsgrids-rs#2 and quanticstci: adopt 0-indexed grid indices once quanticsgrids-rs migrates (removes the workspace's only mixed indexing convention) #582 land); A * B -> a.contract(&b) and the Result-returning surface; norm() taking &mut self.
• ITensors.jl priors mostly help (index-identity contraction, column-major, MPS/MPO vocabulary), which is exactly why the few 'similar but different' points above deserve warning-shaped treatment: they fail silently.
• Verification: an ITensors.jl-persona source-blind run (porting a small QuanticsTCI.jl/ITensors.jl script) as the acceptance test, mirroring tenferro-rs#1641.

[shinaoka]

Resolved by PR #599 (merged; issue #566 remediation follow-up).

• skills/use-tensor4all-rs/ is the bundled downstream-usage skill, linked from README, with compile-checked examples (updated for the SimpleTensorTrain rename in PR3: API vocabulary, stack seam, and architecture (issue #566) #595).
• PR Resolve related issue #583/#578/#580/#573/#551/#588 acceptance criteria #599 adds a "Common pitfalls" section covering: scale_tolerance (not rescale_tolerance, with the [ACI] scale_tolerance=true can report convergence before held-out accuracy is reached #572 caveat), MPO-MPO contraction two layers, contraction method cost/reliability, TensorTrain/MPS/MPO sharing one representation, TensorTrainError collision, 0- vs 1-indexing (incl. quanticstci grid), and the max_bond_dim / rtol vocabulary.

Acceptance criteria met; closing.