Skip to content

Add Warp tutorial notebooks#185

Open
nv-snidhan wants to merge 14 commits into
NVIDIA:mainfrom
nv-snidhan:snidhan/reorg-warp-notebooks
Open

Add Warp tutorial notebooks#185
nv-snidhan wants to merge 14 commits into
NVIDIA:mainfrom
nv-snidhan:snidhan/reorg-warp-notebooks

Conversation

@nv-snidhan

Copy link
Copy Markdown
Contributor

Summary

This PR moves the Warp material out of the Accelerated Python guide into a dedicated tutorials/warp tutorial and expands it from two chapter notebooks into a four-notebook sequence.

Changes

  • Move the existing Warp intro and Ising notebooks to tutorials/warp/notebooks/01_intro_to_warp.ipynb and tutorials/warp/notebooks/02_ising_model.ipynb, remove the old Accelerated Python README entries, and add tutorials/warp/README.md with notebook descriptions and Colab links.
  • Rework notebook 01 from the old Chapter 12 material into a broader introduction to Warp. The notebook now walks through kernels, typed arguments, kernel cache behavior, array creation and transfer, language restrictions, Python-scope versus kernel-scope APIs, user functions, structs, and automatic differentiation.
  • Replace the old introductory particle walkthrough in notebook 01 with a galaxy simulation capstone. The capstone ties together NumPy initialization, wp.array data movement, wp.launch, wp.vec3 particle state, fused versus non-fused kernel structure, and result visualization.
  • Add notebook 03, a 2-D Navier-Stokes solver that teaches finite-difference vorticity updates, fused stencil kernels, Warp tile FFTs, a Fourier-space Poisson solve, full solver assembly, and CUDA graph capture.
  • Add notebook 04, a differentiable simulation tutorial using the Navier-Stokes solver for target matching and optimal perturbation examples. It covers the practical changes needed for Warp autodiff, including avoiding in-place updates, recording with wp.Tape(), using warp.optim, and interoperability with PyTorch.
  • Add helper packages and image assets for the intro, Ising, Navier-Stokes, and differentiable Navier-Stokes notebooks.

@copy-pr-bot

copy-pr-bot Bot commented Jun 11, 2026

Copy link
Copy Markdown

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

@github-actions

Copy link
Copy Markdown
Contributor

👋 Thank you for your contribution!

This pull request is from a forked repository so GitHub Actions will not be able to run CI. A maintainer will review your changes shortly and manually trigger the CI.

@maintainers Please review this PR when you have a chance and follow the instructions in the CONTRIBUTING.md file to trigger the CI.

@nv-snidhan

Copy link
Copy Markdown
Contributor Author

@jnbntz @tscudiero can you please add one of the people from your team and @shi-eric as the reviewers for this PR?

@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch 2 times, most recently from 0482240 to 92834aa Compare June 11, 2026 21:29
@jnbntz jnbntz requested a review from shi-eric June 12, 2026 13:07
@brycelelbach

Copy link
Copy Markdown
Collaborator

ok to test

@brycelelbach

Copy link
Copy Markdown
Collaborator

/ok to test 92834aa

Just to confirm, are you adding the images with Git LFS? That's required to keep the repo size from getting very large.

This looks nice at a glance - can you add the docker compose definitions for this tutorial? You should be able to take the config for the accelerated Python tutorial as a starting point.

@brycelelbach brycelelbach force-pushed the snidhan/reorg-warp-notebooks branch from 92834aa to 98687ca Compare June 18, 2026 22:55
@brycelelbach

Copy link
Copy Markdown
Collaborator

/ok to test 92834aa

@copy-pr-bot

copy-pr-bot Bot commented Jun 18, 2026

Copy link
Copy Markdown

/ok to test 92834aa

@brycelelbach, there was an error processing your request: E2

See the following link for more information: https://docs.gha-runners.nvidia.com/cpr/e/2/

@brycelelbach

Copy link
Copy Markdown
Collaborator

/ok to test 98687ca

@brycelelbach

Copy link
Copy Markdown
Collaborator

@nv-snidhan can you please sign your commits?

@github-actions

Copy link
Copy Markdown
Contributor

❌ Git Signature Check Failed

🔗 View workflow run logs

Found 10 unsigned commit(s):

Unsigned commits
  • 98687ca: Tutorials/Warp: Use media URLs and fix review issues. (unsigned)
  • ca8ac26: Keep Advanced Warp topics heading (unsigned)
  • 483354a: Consolidate Warp notebook cleanup (unsigned)
  • 386c3fc: Add Warp notebook copyright headers (unsigned)
  • 2137960: Update Warp install guidance (unsigned)
  • b7fb9ac: Organize Warp notebook helpers (unsigned)
  • 1c5bc23: Add Warp Navier-Stokes tutorials (unsigned)
  • be06efe: Move Warp notebooks to tutorials (unsigned)
  • 3cf4bae: Refine Warp intro notebook (unsigned)
  • 2e6be7f: Tutorials/Accelerated Python: Reconcile Warp intro with GTC DLI notebook. (unsigned)

How to fix:

  1. Configure commit signing (if not already done):

    # For GPG signing
    git config --global commit.gpgsign true
    
    # Or for SSH signing (Git 2.34+)
    git config --global gpg.format ssh
    git config --global user.signingkey ~/.ssh/id_ed25519.pub
  2. Re-sign your commits:

    git rebase -i origin/main --exec "git commit --amend --no-edit -S"
    git push --force-with-lease

📚 GitHub documentation on signing commits

@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch from 98687ca to fa6854e Compare June 26, 2026 20:32
@nv-snidhan

Copy link
Copy Markdown
Contributor Author

@brycelelbach

Just to confirm, are you adding the images with Git LFS? That's required to keep the repo size from getting very large.

Yes, we are using Git LFS for images

This looks nice at a glance - can you add the docker compose definitions for this tutorial? You should be able to take the config for the accelerated Python tutorial as a starting point.

Done

can you please sign your commits?

Done

nv-snidhan and others added 10 commits June 26, 2026 15:28
…ook.

Signed-off-by: snidhan <snidhan@nvidia.com>
The notebook previously opened with a particle simulation before
introducing kernels and arrays, which made the chapter feel more
like a reference pass than a guided introduction. It also aliased
Warp float64 as double and included a large scalar type table in
the array section.

Reframe the overview around the core programming model, add the
galaxy teaser, remove the redundant particle walkthrough, and start
the kernel section with a Celsius-to-Fahrenheit elementwise example.
The deeper topics are now grouped after the core model, and
explicit double precision examples use wp.float64 directly.

Signed-off-by: snidhan <snidhan@nvidia.com>
The Warp notebooks no longer fit the Accelerated Python User Guide
chapter layout. Keeping them under that path also forced chapter-based
file names and image directories that are awkward for future tutorial
notebooks.

Move the Warp notebooks into tutorials/warp with numbered notebook
names and notebook-specific image directories. Add a tutorial README
with local and Colab links, and remove the old Chapter 12 entries from
the Accelerated Python notebook index.

Signed-off-by: snidhan <snidhan@nvidia.com>
The Warp tutorial area previously contained only the introductory and
Ising notebooks. The Navier-Stokes classroom materials lived outside
this repository, so the tutorial README could not point readers to the
next solver-focused lessons.

Add the Navier-Stokes and differentiable Navier-Stokes notebooks under
tutorials/warp, along with their helper modules and image assets. Update
local asset imports and documentation links so the notebooks work from
their new home, and track copied binary assets through Git LFS.

Signed-off-by: snidhan <snidhan@nvidia.com>
The Warp notebook directory had helper modules mixed directly with the
notebooks. That made the tutorial area harder to scan and left little
room for more notebook-specific support code.

Move the helpers into importable subpackages under notebooks/helpers,
split by notebook family. Update notebook imports and prose references
to the new package paths while preserving the existing helper
implementations.

Signed-off-by: snidhan <snidhan@nvidia.com>
The intro notebook still showed CUDA-version-specific conda selector
examples for Warp. Those examples age quickly and can make the setup
section look stale even when the generic package install is enough.

Replace the conda examples with the current generic conda-forge install
form and keep PyPI as the primary installation path. Also simplify the
nightly package wording while preserving the warning that nightlies are
less tested than release packages.

Signed-off-by: snidhan <snidhan@nvidia.com>
The Navier-Stokes Warp notebooks still carried course-specific header markup from the original GTC material, and they did not include the copyright block used by the other tutorial notebooks.

They now start with the 2026 NVIDIA copyright and license header and use plain markdown titles that match the intro notebook style.

Signed-off-by: snidhan <snidhan@nvidia.com>
Recent Warp notebook edits were split across several small cleanup commits. Keeping them separate made the branch history noisy without adding useful review boundaries.

Combine the documentation wording, setup-cell consistency, and notebook polish into one commit while preserving the final notebook contents exactly. Earlier commits that add and organize the tutorials remain separate.

Signed-off-by: snidhan <snidhan@nvidia.com>
Signed-off-by: snidhan <snidhan@nvidia.com>
Signed-off-by: snidhan <snidhan@nvidia.com>
@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch 2 times, most recently from 2e54e9c to b5189ff Compare June 26, 2026 22:40
Add the per-tutorial brev/ config (dockerfile, docker-compose.yml,
requirements.txt) so the Warp tutorial builds and serves on Brev,
matching the self-registering pattern the other tutorials use. Link
the compose file from the root README table and add a Brev/Colab
deploy section to the tutorial README.

Trim the dependency set to what the notebooks and helpers actually
import: warp-lang, numpy, scipy, matplotlib, ipympl, Pillow, plus the
Jupyter stack. Drop RAPIDS, cupy, cuda-python, and MPI versus
accelerated-python; none are used here. Omit the nsys/ncu profiling
services since the notebooks embed pre-captured Nsight images rather
than running profilers live.

Do not install PyTorch. Notebook 04 references the Warp <-> PyTorch
autograd bridge only in prose; no notebook or helper imports torch in
executable code. Verified notebook 04 runs error-free without it. This
keeps the shipped image about 5 GB smaller (9.85 GB vs 14.7 GB).
@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch from b5189ff to 6a01bbc Compare June 26, 2026 22:49
@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch from 41eb2fd to 1d65fe5 Compare June 26, 2026 23:13
Colab's markdown math renderer does not support the calligraphic
\mathcal font, so every equation using \mathcal{F} or \mathcal{L}
displayed as raw LaTeX text. Replace \mathcal{F} -> \mathbf{F} and
\mathcal{L} -> \mathbf{L} (\mathbf renders in Colab and keeps the
operator's visual weight). Also single-line the two display-math
blocks whose opening $$ sat alone on a line, and drop \! / \bigl in
the optimal-perturbation objective, for broader renderer
compatibility. No change to the mathematics.

Set OPTIMIZER_STEPS to 100 in Example 1 to match Example 2.
Make the GPU check in 02_ising_model raise RuntimeError when no
CUDA device is present, matching notebooks 01, 03, and 04. The old
code only printed a warning and continued, so a CPU-only Colab
runtime would crash mid-kernel instead of failing fast with a clear
message.

Point the three SVG diagrams in 01_intro_to_warp at absolute
raw.githubusercontent.com/.../main/ URLs instead of relative paths.
That notebook has no Colab clone cell, so the relative paths did not
resolve on Colab; SVGs are not LFS-tracked, so the raw host (not the
media LFS host) is correct.
@nv-snidhan nv-snidhan force-pushed the snidhan/reorg-warp-notebooks branch from 1d65fe5 to f2ff889 Compare June 26, 2026 23:36
Sign up for free to 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.

3 participants