pytorch-shape-lab / README.md
nityanandmathur's picture
Attribute optional referrals and record hosted checks (#2)
87fa0ff
|
Raw History Blame Contribute Delete
4.08 kB
---
title: PyTorch Shape Lab
emoji: 🧮
colorFrom: green
colorTo: gray
sdk: static
app_file: index.html
pinned: false
license: mit
short_description: Follow a CNN's shapes without losing the batch dimension.
thumbnail: https://raw.githubusercontent.com/tensorviz-org/tensorviz-examples/6e5cdcfc8ec3ab39c0bb1264bf534210ae5c1981/assets/tensorviz-logo-white.png
tags:
- pytorch
- education
- tensor-shapes
---
# PyTorch shape lab
A small interactive lesson by **tensorViz**. Change the batch and image size,
follow a fixed convolution/pooling stack, and find a mismatch at `Linear`.
Compare a correctly sized fixed head with an explicit architecture change using
adaptive average pooling. See how `reshape(-1, 128)` can silently change the
number of samples.
**This is shape arithmetic, not model execution.** The browser runs no Python,
inference, training or tensorViz backend. Compatible shapes do not establish
prediction quality or numerical equivalence. The lesson code has no tracking,
third-party script, iframe, runtime fetch or account requirement. External
resources load only when the reader follows a link. This describes the lesson
code, not the hosting platform's ordinary request handling or platform analytics.
The original executable example is
[available with its checks and explanation](https://github.com/tensorviz-org/tensorviz-examples/blob/1baecebf25ff1067a9112bde382c0a398fb99747/examples/shape-mismatch/README.md).
The static arithmetic was independently checked against actual CPU PyTorch
operations; see [validation](VALIDATION.md).
## Run locally
No package installation or build is needed. Serve this folder using an existing
Python installation:
```sh
python3 -m http.server 4177 --bind 127.0.0.1
```
Open `http://127.0.0.1:4177`. ES modules need an HTTP server; opening `index.html`
as a local `file:` URL is not the supported preview path.
## Lesson boundaries
- The fixed feature stack is `Conv2d(3, 8, kernel_size=3, padding=1)`, `ReLU`,
`MaxPool2d(2)`, then `Flatten(start_dim=1)`.
- Inputs are NCHW with three channels. This teaching UI accepts batch 1–64 and
integer height/width 2–256. These UI bounds are not a general PyTorch limit.
- Pooling uses the default stride of two, padding zero and `ceil_mode=False`.
Odd spatial dimensions round down.
- The original head expects 128 features. A 16 × 16 image yields 512. A fixed
512-feature head fits that example, but not every other input size.
- The optional adaptive pool reduces each of the eight spatial channels to one
value and uses an eight-feature head. That changes computation and parameters;
it is not an interchangeable pretrained checkpoint repair.
- The unsafe reshape demonstration uses the original feature map before any
adaptive pool and the original 128-feature head.
For real model exploration, [tensorViz's recorded browser examples](https://tensorviz.dev/explore/?utm_source=huggingface&utm_medium=referral&utm_campaign=shape_lab_202610&utm_content=shape_lab_recorded_models)
are an optional next step. Capturing your own PyTorch model requires the separate
tensorViz extension and your model environment. This repository contains only
the lesson, not extension implementation.
## Validate changes
Use existing Node.js and a Python environment with PyTorch installed. Nothing in
the checks downloads dependencies or enables telemetry.
```sh
node --test shape-math.test.mjs
python verify_pytorch.py
```
`verify_pytorch.py` also invokes Node.js to compare the JavaScript results with
PyTorch. Visual and accessibility acceptance remain separate from these checks.
The intended layout and review cases are in [design notes](DESIGN.md).
## License and attribution
Original lesson code and documentation are [MIT licensed](LICENSE), including
the small test model derived from the public tensorViz example linked above.
PyTorch is a separate dependency under its own license. The supplied tensorViz
logo identifies the project; this license does not grant trademark rights.
The extension and its dependencies retain their own licenses.