Skip to content

Docs: fallback behaviour is documented incorrectly and there are no examples #19

Description

@Panadestein

Problem

1. The documented fallback behaviour is wrong

The README states:

NOTE: the current implementation targets tensor networks with 3 or more
sites. For smaller networks, the corresponding Quimb primitive with
randomized SVD is dispatched, with a warning.

The code dispatches a plain, deterministic SVD — not a randomized one:

# apply.py
return left_tensor.apply(right_tensor, compress=True, max_bond=chi_out, method="svd")
# compress.py
compressed_tensor.compress(max_bond=chi_out, method="svd")

2. The fallback silently drops three arguments

On the nsites < 3 path, cutoff, seed and device are accepted and then
ignored. A caller asking for device="gpu" with a 2-site network gets CPU
execution with no indication; a caller passing cutoff=1e-8 gets no adaptive
truncation. The warning that is emitted mentions none of this.

The apply() fallback also tests only left_tensor.nsites, so a mismatched
right_tensor slips straight through to the same opaque failure described in
the validation issue.

3. There are no examples

The only tutorial in the repository was a template placeholder (an empty
"Sample Tutorial" notebook), which has been removed. For a package whose whole
value proposition is "this is faster and more accurate than the obvious
quimb call", shipping zero worked examples is the single biggest barrier to
adoption. Someone evaluating the library has nothing to run.

Proposed fix

  • Correct the README and the docstrings to describe the fallback accurately,
    and state plainly which arguments it honours.
  • Make the fallback respect cutoff where quimb supports it, and warn
    explicitly when device="gpu" is requested but the fallback path is taken.
  • Write a real tutorial notebook under docs/tutorials/ that:
    • builds a representative MPO/MPS problem,
    • compares src_method.apply against the equivalent quimb call for both
      wall-clock time and accuracy,
    • shows the effect of chi_out and cutoff on the error,
    • demonstrates the GPU path.
  • Add a short, copy-pasteable example to the top of the README — the first
    thing a visitor sees should be working code, not installation instructions.
  • Note that docs/index.md and README.md currently duplicate each other
    almost verbatim; consider including one from the other via a snippet so they
    cannot drift.

Acceptance criteria

  • No documented behaviour contradicts the implementation.
  • The fallback either honours cutoff/device or warns clearly that it does not.
  • A runnable tutorial notebook exists and is executed by the docs build.
  • The README opens with a working quick-start example including benchmark numbers.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions