Skip to content

Migrate the public API from 1-indexed (Julia convention) to 0-indexed #2

Description

@shinaoka

Problem

As a port of QuanticsGrids.jl, this crate inherited Julia's 1-indexed convention for grid indices and quantics digits. In a Rust crate this is a foreign convention, and it propagates: tensor4all-rs's tensor4all-quanticstci exposes 1-indexed &[i64] grid indices on its public surface (interpolation callbacks, evaluate, initial_pivots, cachedata keys) purely because this dependency is 1-indexed, while every other tensor4all-rs crate is 0-indexed. The resulting mixed convention is the single worst user trap in that workspace: a Rust user who has just internalized "sites are 0-indexed here" is betrayed by exactly one crate (documented in tensor4all/tensor4all-rs#363, and re-flagged by the 2026-08 AX audit as the top silent-wrong-answer risk for users and coding agents arriving from ITensors.jl or plain Rust).

quanticstci currently pays for the mismatch with five explicit plus/minus-one conversion sites at the TCI boundary (quantics_tci.rs lines 178, 478, 523, 774, 811 at the audited rev).

Proposal

Migrate the public API to 0-indexed grid indices and quantics digits throughout:

  • Grid indices: 0..N instead of 1..=N; the first grid point is [0, 0, ...].
  • Quantics digits: 0/1 bit values and 0-indexed digit positions where applicable.
  • Prefer usize for index-typed parameters where negative values are impossible, making the convention visible in the type.

Compatibility with the Julia ecosystem is a real constraint, but it belongs at the interop boundary, not in the Rust core: a Julia caller crossing FFI (or a test comparing against QuanticsGrids.jl output) converts once at the boundary. Keeping the Rust core 1-indexed inverts that cost onto every pure-Rust user.

Migration strategy

  • This is a breaking change; land it as a version bump with a clear CHANGELOG entry stating the old and new conventions.
  • Coordinated downstream update: tensor4all-rs pins this crate by rev, so land the quanticstci adoption (removal of the conversion sites and of its 1-indexed documentation) in the same coordinated change set. Follow-up issue on tensor4all-rs side.
  • Provide a conversion note for users porting QuanticsGrids.jl scripts: subtract 1 from grid indices at the call boundary.

Acceptance criteria

  • No public API accepts or returns 1-indexed grid indices or digits.
  • README and docs state the 0-indexed convention and the QuanticsGrids.jl porting note.
  • Doctests and tests assert 0-indexed semantics (first grid point [0, ...]).

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