Skip to content

Unify the bond-dimension cap vocabulary on max_bond_dim: Option<usize> (today: max_bond_dim/max_rank/maxbonddim) #583

Description

@shinaoka

Problem

The bond-dimension cap has three spellings in the workspace:

  • max_bond_dim: usize with a usize::MAX sentinel: tensor4all-simplett CompressionOptions
  • max_rank: Option<usize>: tensor4all-treetn TruncationOptions (with_max_rank)
  • maxbonddim: Option<usize>: tensor4all-quanticstci options, which translates its own field into its dependency's spelling (options.rs:287)

treetn and simplett each contain two of the three. Every user crossing crates relearns the name, and a user or agent arriving from ITensors.jl has no stable target for maxdim. This was identified as a vocabulary decision in the 2026-08-02 audit umbrella (#566, Phase 2); this issue splits it out because it does not depend on tensor4all-agent-rules#6 and now has an additional motivation (ITensors.jl persona mapping, see #573).

Decision

Adopt max_bond_dim: Option<usize> workspace-wide (None = unlimited):

  • max_bond_dim over max_rank: rank is overloaded in TCI context; bond dimension is the unambiguous tensor-network term and the closest cousin of ITensors.jl maxdim.
  • Option<usize> over a usize::MAX sentinel: idiomatic, and the unlimited case is explicit at call sites.

Proposed direction

  1. simplett CompressionOptions: max_bond_dim: usize becomes Option<usize>; remove the sentinel.
  2. treetn TruncationOptions: rename max_rank/with_max_rank to max_bond_dim/with_max_bond_dim.
  3. quanticstci: rename maxbonddim to max_bond_dim; drop the translation shim once spellings match.
  4. Early development policy applies (no backward compatibility, remove old names immediately); include a CHANGELOG mapping table old name to new name, plus the ITensors.jl row (maxdim maps to max_bond_dim).
  5. Coordinate with the tolerance-vocabulary decision in Umbrella: 2026-08-02 origin/main audit remediation and shared-rules adoption #566 Phase 2 (SvdTruncationPolicy as the shared tolerance type); this issue deliberately covers only the bond cap and does not preempt that work.

Acceptance criteria

  • grep -rn "max_rank\|maxbonddim" crates/ returns nothing outside CHANGELOG.
  • One spelling and one type for the cap across simplett, treetn, quanticstci, and any options struct that forwards it.
  • conventions.md (or the ITensors mapping documentation) states maxdim maps to max_bond_dim and cutoff maps to rtol*rtol.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions