Skip to content

Fix the tutorial example that crashes on GPU, and the PyPI logo - #263

Open
gomezzz wants to merge 2 commits into
developfrom
docs/tutorial-cuda-and-deps
Open

Fix the tutorial example that crashes on GPU, and the PyPI logo#263
gomezzz wants to merge 2 commits into
developfrom
docs/tutorial-cuda-and-deps

Conversation

@gomezzz

@gomezzzgomezzz commented Aug 29, 2026

Copy link
Copy Markdown
Collaborator

Three documentation defects found while validating the 0.6.0 release on real
hardware. Docs only — no library code changes.

  • The vectorized-integrand tutorial example crashed on every CUDA machine.
    It built its helper tensors with the legacy torch.Tensor(...) constructor,
    which ignores the torch.set_default_device("cuda") that set_up_backend
    performs, while torch.tensor(...) honours it. The helpers stayed on the CPU,
    the sample points were on the GPU, and the example died in torch.einsum with
    RuntimeError: Expected all tensors to be on the same device. Reproduced on an
    RTX 4060 Ti, then confirmed fixed — the example now prints the True it claims.
    A note was added because this bites in user code exactly as readily.
  • The tutorial's import block failed after the documented install. It imports
    matplotlib.pyplot, but matplotlib is only in the dev extra, so a user who
    ran the README's pip install torchquad torch hit ModuleNotFoundError on the
    first code block. Called out as a prerequisite rather than promoted to a runtime
    dependency — 0.6.0 deliberately dropped it as one.
  • The README logo did not render on the PyPI project page. It used a
    repository-relative <img src="logos/...">; PyPI cannot resolve relative paths
    in a long description. Now an absolute ?raw=true URL, matching what the seven
    performance figures already do. Pre-existing — 0.5.0's project page has the same
    broken image.

Related to #258.

Numerical behaviour

None. The example's computed values are unchanged; only where its helper tensors
are allocated changed.

Test plan

  • Reproduced the GPU crash with the example exactly as published, then ran the
    corrected version on the same machine: all close -> True, with grid,
    result and result_vectorized all on cuda:0 in float64.
  • sphinx-build -W -b html docs/source — build succeeded, no warnings.
  • Verified the new logo URL returns HTTP 200.

Note for merging

This touches CHANGELOG.md's [Unreleased] section, as does #262, so whichever
lands second will have a small conflict there. The two entries are independent.

What changed after review

  • The logo was not the only broken link.environment.yml,
    environment_all_backends.yml (twice), benchmarking/genz_functions.py and
    CONTRIBUTING.md are all repository-relative and 404 on the PyPI project page
    for the same reason. All five are now absolute; fixing only the logo would have
    shipped the same class of bug this PR is named after.
  • **:func:set_up_backend was unqualified**, and `tutorial.rst` has no `py:module` context, so Sphinx silently rendered it as plain text — unresolved Python xrefs are not warnings, which is why the `-W` gate stayed green. Now `:func:`torchquad.set_up_backend, and verified to emit a real anchor in the
    built HTML.
  • The device note moved into reach. It sat at the end of section 7 while the
    trap is hit from section 1. It now carries a label, and the set_up_backend
    block near the top links to it. Both the label target and the :ref: link were
    confirmed present in the generated HTML.

Not addressed here

Nothing executes the tutorial's code blocks, which is why this survived several
releases, and the failure is GPU-only so no CI job would catch it either. A
two-line version of this example belongs in release_testing/, which already
runs on a GPU box during release validation. Worth its own issue rather than
widening a docs PR.

The vectorized-integrand example built its helper tensors with the legacy
torch.Tensor(...) constructor, which ignores the torch.set_default_device("cuda")
that set_up_backend performs. On any CUDA machine the helpers stayed on the CPU
while the sample points were on the GPU, so the example died in einsum with
"Expected all tensors to be on the same device". Switched to torch.tensor and
torch.stack, and added a note, since the distinction bites in user code just as
easily.
The import block pulled in matplotlib, which is not a runtime dependency, so it
failed after the installation the README documents. Flagged as a prerequisite
rather than promoted to a dependency.
The README logo was a repository-relative path and so did not render on the PyPI
project page; it now uses an absolute URL like the performance figures already do.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YP9oDLmw636HhPSAD6Nv3p
@github-actions

github-actionsBot commented Aug 29, 2026

Copy link
Copy Markdown

Overall Coverage

Coverage Report
FileStmtsMissCoverMissing
torchquad
__init__.py26292%69–70
torchquad/integration
base_integrator.py49786%28, 71–74, 78, 113, 117, 122
boole.py30390%54, 73–76
gaussian.py56395%97, 121, 143
grid_integrator.py97397%50, 164, 268
integration_grid.py49492%64–65, 132, 135
monte_carlo.py93397%79, 101, 230
qmc.py20195%67
rng.py60788%71–74, 93–94, 102
simpson.py29390%52, 71–74
utils.py1311192%35–36, 102, 173, 177, 184, 196, 198, 204, 299, 306
vegas.py167498%106–107, 212, 359
vegas_map.py103892%247–257
vegas_result.py25196%22
torchquad/utils
deployment_test.py1926367%53–55, 65–66, 69–70, 78–79, 91–93, 164, 175–176, 180–181, 183–184, 196–199, 211–213, 221, 232–234, 237, 247, 250, 253, 256–259, 267–275, 280–288, 297–306, 316–323
enable_cuda.py15660%17–22
set_log_level.py18478%56–57, 72–73
set_precision.py34974%35–38, 50–51, 70–72
TOTAL129014289%

TestsSkippedFailuresErrorsTime
1930 💤0 ❌0 🔥2m 25s ⏱️

Review follow-up. The logo was not the only relative link that breaks on the PyPI
project page: environment.yml, environment_all_backends.yml (twice),
benchmarking/genz_functions.py and CONTRIBUTING.md all resolve against pypi.org
and 404 there. Fixing only the logo would have shipped the same class of bug the
PR is named after.
The device note referenced :func:`set_up_backend` unqualified. tutorial.rst has
no py:module context, so Sphinx could not resolve it and rendered it as plain
text -- silently, since unresolved python xrefs are not warnings, which is why
the -W gate stayed green. Now qualified, and verified to emit a real link in the
built HTML.
The note also sat at the end of section 7 while the trap is reachable from
section 1. It gains a label, and the set_up_backend block near the top now points
at it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YP9oDLmw636HhPSAD6Nv3p
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@gomezzz