vidmag 0.2.0__tar.gz

vidmag-0.2.0/.claude/rules/development-practices.md

@@ -0,0 +1,87 @@
+# Development Practices (binding)
+
+These rules govern **how** every step of `docs/dev/PLAN.md` is implemented. They are
+section 3d of that plan, committed here so every session loads them. They are not advice.
+
+## 1. Test-driven — the check comes before the thing it checks
+
+- Start each plan step by writing, or pointing at, the failing check named in that phase's
+  success criteria. No implementation file is created before that check exists.
+- The check is a real command, not a claim. Examples in this repo:
+  `.venv/bin/python -m pytest tests/ -q -p no:randomly` (300 passed, 102 skipped on 2026-08-18),
+  `pytest tests/cuda/ -q` on a GPU host, `scripts/dev/verify_install.sh` for packaging work.
+- Non-Python work gets a check too: a `src/vidmag/cuda/CMakeLists.txt` change is tested by a scripted
+  fresh-venv install, a docs change by `mkdocs build --strict` plus running its snippets.
+- Phase 0 exists to build this net (golden fixtures, `tests/test_reference_lock.py`, recorded
+  baselines in `benches/`). Later red-green cycles run inside it.
+
+## 2. KISS — two sanctioned abstraction layers, no third
+
+- The only abstractions this restructure may introduce are `vidmag.backend.Ops` and
+  `vidmag.backend.Pipelines` (plan section 3c) plus the backend registry. Base classes, config
+  objects, plugin hooks or dispatch layers beyond those need the operator's approval first.
+- Prefer a plain function to a class, a frozen dict to a config system, a copy-pasteable
+  example to a helper framework. `vidmag/` is written that way — match it.
+
+## 3. YAGNI — build exactly the current step
+
+- No speculative parameters, no "while I'm here" generality, no Phase 4 code smuggled into
+  Phase 1. If the plan looks wrong or incomplete, stop and surface the gap to the operator
+  instead of quietly building extra.
+- Touch only the files your step names. No reformatting or refactoring of neighbouring code.
+
+## 4. DRY — one source of truth, one named exception
+
+- Single-sourced by design: the version string, the preset table, `tests/cuda/conftest.py:TOL`,
+  the conformance suite, the backend registry, and the reference constants
+  (`DROP_LAST`, `EXAGGERATION_FACTOR`, `BINOM5`, `BINOM5_SUM1`). Import them; never retype a
+  literal that can be imported. New duplication needs a stated reason in the commit message.
+- **The named exception:** the FP32/FP16 pipeline bodies in `src/vidmag/cuda/batched.py` and the
+  templated kernels may stay duplicated where merging them risks numeric drift — the README's
+  accuracy claims (motion FP16 vs FP32 RMSE 0.00140) are load-bearing. Correctness outranks
+  DRY. Comment the exception at the site.
+
+## 5. Fail loud
+
+- No silent fallbacks and no silently skipped work. Backend selection is always printed; a
+  missing backend reports *why* (missing extra, no driver, no device). A ~700x CPU/GPU cliff
+  must never be reached by accident.
+- No bare `except`. Every CUDA runtime call is wrapped in `CUDA_CHECK`
+  (`src/vidmag/cuda/include/evm_check.cuh`), which throws `std::runtime_error` so pybind11 surfaces it as
+  a catchable Python exception — "a silent error can never propagate into a tolerance
+  failure". Keep that posture in Python: raise, don't degrade.
+- Report skip counts, never just passes. On this Mac the honest line is
+  "300 passed, 102 skipped" — those skips include the whole NVIDIA suite and prove
+  nothing about it. No single machine runs every backend.
+- `tests/cuda/conftest.py:TOL` and `tests/test_against_mit_reference.py` are append-only.
+  Loosening a tolerance is its own separately reviewed commit carrying the measurement.
+
+## 6. Verify, then claim; land one plan step per commit
+
+- A step is done only when its named command has actually run and its output is recorded in
+  the report. "Should work" and "looks right" are not results.
+- One plan step = one commit, full suite green, the step named in the message
+  (e.g. `Phase 1 step 1.6: make CUDA optional in CMake`), so history maps one-to-one onto
+  `docs/dev/PLAN.md`. Unrelated changes in that commit are not permitted.
+- Do not commit unless the operator asked for it; the orchestrating session commits.
+
+## 7. The NVIDIA GPU code leads; the other backends follow it
+
+- Performance work starts in the NVIDIA GPU code — `src/vidmag/cuda/kernels/*.cu` and `src/vidmag/cuda/bindings.cpp`.
+  That is what this project exists to make fast, and it is where a measurement is worth taking.
+- **A change to the NVIDIA code is not finished when it lands.** Once it is accepted, check
+  whether the same change applies to every other backend, and apply it where it does:
+
+  | Backend | Where its kernels live |
+  |---|---|
+  | OpenCL | `src/vidmag/opencl/kernels.cl` |
+  | Apple Metal | `src/vidmag/metal/kernels.metal` |
+  | Vulkan | `src/vidmag/vulkan/shaders/*.comp` |
+  | PyTorch | `src/vidmag/torch_backend/ops.py` (tensor operations, no kernels) |
+  | Processor (Python) | `src/vidmag/cpu/pyramids.py`, `src/vidmag/cpu/filters.py` |
+
+- State which backends the change was carried to and which it does not apply to, with the
+  reason. "Does not apply, because that backend has no separate upsample kernel" is a complete
+  answer; saying nothing is not.
+- Carry it in its own commit, separate from the NVIDIA change, so a numeric regression on one
+  backend cannot be mistaken for a fault in the original.

vidmag-0.2.0/.editorconfig

@@ -0,0 +1,30 @@
+# Editor defaults, matching the formatter this project already runs so that
+# saving a file in any editor produces what `ruff format` would produce.
+# Settings live in pyproject.toml under [tool.ruff]; these mirror them.
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{py,pyi}]
+max_line_length = 88
+
+# CUDA, C++ and the shader languages follow the same four-space style as the
+# Python, which is what the existing kernel sources use.
+[*.{cu,cuh,cpp,h,hpp,cl,metal,comp,glsl}]
+indent_size = 4
+
+[*.{yml,yaml,json,toml}]
+indent_size = 2
+
+[*.md]
+# Two trailing spaces are a hard line break in Markdown; do not eat them.
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

vidmag-0.2.0/.gitattributes

@@ -0,0 +1,35 @@
+# Line endings and binary detection, declared rather than guessed.
+#
+# Git infers "binary" from content, and gets it right most of the time. The
+# cost of the rare miss is high here: a compiled Vulkan shader or a test
+# fixture that had line endings rewritten on checkout is silently corrupt, and
+# the failure surfaces far from the cause. So the file types are stated.
+
+# Text files: normalise to LF in the repository, whatever the editor wrote.
+* text=auto eol=lf
+
+# Shell scripts and Makefiles break outright with CRLF, so pin them.
+*.sh          text eol=lf
+Makefile      text eol=lf
+
+# GPU kernel sources are text and read by a compiler at build or run time.
+*.cu          text eol=lf
+*.cuh         text eol=lf
+*.cl          text eol=lf
+*.metal       text eol=lf
+*.comp        text eol=lf
+*.glsl        text eol=lf
+
+# Binary. Never converted, never diffed as text.
+*.spv         binary
+*.npz         binary
+*.mp4         binary
+*.gif         binary
+*.png         binary
+*.jpg         binary
+*.ipynb       binary linguist-language=Python
+
+# Keep the language statistics on the shelf honest: generated, vendored and
+# non-source material should not count as the project's implementation.
+docs/**       linguist-documentation
+benches/**    linguist-generated

vidmag-0.2.0/.github/ISSUE_TEMPLATE/bug.md

@@ -0,0 +1,33 @@
+---
+name: Something is wrong
+about: Report incorrect behaviour
+title: ""
+labels: bug
+---
+
+**What happened, and what you expected instead**
+
+**How to reproduce it**
+
+The smallest script that shows the problem. If it needs a video, say which one
+and where to get it.
+
+```python
+```
+
+**What it printed**
+
+Errors in full, please, not just the last line.
+
+**Your setup**
+
+- Version (`python -c "import vidmag; print(vidmag.__version__)"`):
+- Backend (`python -c "from vidmag import backend; print(backend.select('auto')[0])"`):
+- Operating system and Python version:
+
+**Before you file: is the output identical to the input?**
+
+That is usually the frequency band rather than a defect — a band narrower than
+your clip can resolve selects nothing. The library warns when this happens.
+[What can go wrong](../../docs/concepts/pitfalls.md) covers it and several
+similar cases.

vidmag-0.2.0/.github/ISSUE_TEMPLATE/hardware-result.md

@@ -0,0 +1,32 @@
+---
+name: Result from hardware we cannot test
+about: Report running the suite on an AMD, Intel or other device
+title: "Hardware result: "
+labels: hardware-report
+---
+
+This project has an NVIDIA card and an Apple machine to test on, and nothing
+else. Support for other hardware is described as expected rather than verified
+because nobody has run it. A report here changes that.
+
+**The device**
+
+- Name as reported (`python -c "from vidmag.opencl import runtime; print(runtime.device_name())"`):
+- Operating system and version:
+- Driver version:
+
+**Test suite**
+
+```
+python -m pytest tests/ -q
+```
+
+Paste the output, including the skip count.
+
+**Anything that failed**
+
+Paste the failure in full.
+
+**Speed, if you measured it**
+
+The steps are in `benches/apple_m2_max_opencl_2026-08-10.md`.

vidmag-0.2.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+## What this changes, and why
+
+<!-- What the change does, and the problem it solves. If it fixes an issue, link it. -->
+
+## How it was verified
+
+<!-- The commands you actually ran, with their output. Not "tests pass" — the
+     numbers. This project reports skip counts alongside pass counts, because no
+     single machine can run every backend: a machine without an NVIDIA card
+     skips that whole suite, and a machine with one has no Apple or OpenCL
+     driver. Say which machine you ran on. -->
+
+- [ ] `python -m pytest tests/ -q -p no:randomly` — passed / skipped:
+- [ ] `ruff check .` and `ruff format --check .`
+- [ ] `mypy`
+- [ ] Ran on (operating system, and graphics hardware if relevant):
+
+## For performance changes
+
+<!-- Delete if not applicable. -->
+
+- [ ] Measured, with the before and after numbers and how they were taken
+- [ ] Said which backends the change reached, and which it does not apply to
+      and why (see rule 7 in `.claude/rules/development-practices.md`)
+
+## For changes that alter numerical output
+
+<!-- Delete if not applicable. -->
+
+- [ ] Compared against the NumPy baseline, which is the correctness oracle
+- [ ] No tolerance in `tests/cuda/conftest.py` was loosened. Loosening one is a
+      separate pull request carrying the measurement that justifies it.

vidmag-0.2.0/.github/actionlint.yaml

@@ -0,0 +1,10 @@
+# Config for actionlint (https://github.com/rhysd/actionlint).
+#
+# Without this, actionlint rejects `runs-on: [self-hosted, linux, x64, cuda]` in
+# gpu.yml with "label \"cuda\" is unknown" — it has no way to know which custom
+# labels this project's self-hosted runners carry. Declaring the label here is
+# also the one place that says a runner must be registered with it; see
+# docs/dev/gpu-runner.md.
+self-hosted-runner:
+  labels:
+    - cuda

vidmag-0.2.0/.github/dependabot.yml

@@ -0,0 +1,31 @@
+# Keeps the two things this project pins from going stale.
+#
+# The workflow actions are pinned to commit hashes, which is what stops a moved
+# tag from running unreviewed code with this repository's credentials. The cost
+# of that is that nothing updates them; this is what updates them, as a pull
+# request that can be read before it is merged.
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "ci"
+    labels: ["dependencies"]
+
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: monthly
+    commit-message:
+      prefix: "deps"
+    labels: ["dependencies"]
+    # ruff and mypy are pinned exactly on purpose (see pyproject.toml): a new
+    # release adds rules, and a lint gate that turns red without anybody
+    # editing code is one people learn to ignore. Let Dependabot propose those
+    # bumps, but as their own pull request so the rule churn is reviewed alone.
+    groups:
+      runtime:
+        patterns: ["*"]
+        exclude-patterns: ["ruff", "mypy"]