Initial ntops.lab operators

Author: whjthu

.gitattributes

@@ -0,0 +1,4 @@
+* text=auto eol=lf
+
+*.bat text eol=crlf
+*.ps1 text eol=crlf

.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  metadata:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install package
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Validate manifest
+        run: python scripts/check_manifest.py
+      - name: Run tests
+        run: pytest

.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+build/
+dist/
+*.egg-info/
+.ninetoothed/
+*.log
+htmlcov/
+.coverage

CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0
+
+- Initial `ntops.lab` repository layout.
+- Added canonical operator catalog with 468 unique operator entries.
+- Added 371 runnable NineToothed operator implementations.
+- Added 97 todo/scaffold entries with support analysis.
+- Added CLI, manifest validation, metadata tests, and GPU smoke helpers.

CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# Contributing
+
+`ntops.lab` welcomes focused operator improvements.
+
+Before opening a pull request:
+
+1. Keep each operator in a separate file.
+2. Add or update the PyTorch reference in the same module.
+3. Update `src/ntops_lab/operator_manifest.json`.
+4. Run:
+
+```bash
+python scripts/check_manifest.py
+pytest
+```
+
+If you add a runnable GPU kernel, also run:
+
+```bash
+ntops-lab check <operator-name>
+```
+
+For blocked operators, leave a precise `REASON` explaining whether the blocker
+is a missing NineToothed interface, a missing math primitive, or just manual
+lowering work.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 InfiniTensor and ntops.lab contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,17 @@
+.PHONY: check test summary smoke-one smoke-pointwise
+
+check:
+	python scripts/check_manifest.py
+	python -m compileall -q src scripts tests
+
+test:
+	python -m pytest
+
+summary:
+	python -m ntops_lab.cli summary
+
+smoke-one:
+	python scripts/run_operator.py add
+
+smoke-pointwise:
+	python scripts/run_smoke_suite.py --category pointwise --limit 10 --continue-on-error

README.md

@@ -0,0 +1,159 @@
+# ntops.lab
+
+`ntops.lab` is an experimental operator lab for
+[NineToothed](https://github.com/InfiniTensor/ninetoothed). It collects
+generated and hand-shaped NineToothed kernels, keeps a runnable operator
+catalog, and records the current gaps that need compiler/runtime support.
+
+The project is intentionally a lab: many kernels are produced with LLM-assisted
+operator development, then smoke-tested against PyTorch on CUDA.
+
+## Current Coverage
+
+The canonical catalog contains:
+
+- 250 runnable NineToothed implementations
+- 0 unsupported/scaffold source files included in the commit-ready tree
+- gap analysis retained in documentation only
+
+Primary categories:
+
+- `pointwise`
+- `reduction`
+- `linear`
+- `layout`
+- `creation`
+- `normalization`
+- `fused/general`
+- `fused/fla`
+- `fused/dsa`
+- `fused/mhc`
+
+See [docs/operator-coverage.md](docs/operator-coverage.md) for the full list.
+
+## Repository Layout
+
+```text
+src/ntops_lab/
+  catalog.py                 # manifest loading and query helpers
+  cli.py                     # ntops-lab CLI
+  operator_manifest.json     # canonical runnable operator catalog
+  operators/                 # generated NineToothed kernels
+docs/
+  operator-coverage.md       # runnable coverage
+  runnable-operators.md      # runnable operator list
+  unrunnable-operators.md    # excluded unsupported operator notes
+  support-analysis.md        # missing capability analysis
+tests/
+  test_catalog.py            # CPU-only metadata tests
+scripts/
+  run_operator.py            # run one operator's check()
+  check_manifest.py          # validate manifest/file consistency
+```
+
+## Install
+
+For metadata inspection and CPU-only tests:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+For running kernels, use an environment that already has CUDA, PyTorch, and
+NineToothed installed:
+
+```bash
+pip install -e ".[dev]"
+```
+
+NineToothed and PyTorch are kept as optional GPU dependencies because this
+repository is often inspected on machines without a GPU.
+
+## Use The Catalog
+
+```bash
+ntops-lab summary
+ntops-lab list --status done
+ntops-lab list --category reduction
+```
+
+From Python:
+
+```python
+from ntops_lab import list_operators, runnable_operators
+
+print(len(runnable_operators()))
+print(list_operators(category="linear"))
+```
+
+## Run A Kernel Smoke Test
+
+On a CUDA machine with NineToothed available:
+
+```bash
+ntops-lab check add
+python scripts/run_operator.py softmax
+```
+
+Most runnable operator modules expose:
+
+```python
+make_inputs()
+run_ninetoothed(...)
+run_pytorch(...)
+check()
+```
+
+`check()` generates representative inputs, runs the NineToothed kernel, runs
+the PyTorch reference, and compares results.
+
+## Run Repository Tests
+
+CPU-only catalog checks:
+
+```bash
+python -m pytest
+python scripts/check_manifest.py
+python -m compileall -q src scripts tests
+```
+
+GPU smoke checks should be run selectively:
+
+```bash
+ntops-lab check add
+ntops-lab check mm
+ntops-lab check moe_sum
+```
+
+Running every GPU check can take a while because many operators compile kernels
+on first use.
+
+## What Is Not Included Yet?
+
+Unsupported scaffold source files are intentionally excluded from this commit-ready tree. Remaining gaps mostly need one of these capabilities:
+
+- complex manual layout/indexing
+- dynamic gather/scatter, cache writes, or masked updates
+- top-k/sort/histogram/atomic primitives
+- cross-tile scan, recurrent state, or triangular solve
+- RNG/stateful random distribution support
+- normalization backward or running-stat APIs
+
+See [docs/support-analysis.md](docs/support-analysis.md).
+
+## Project Philosophy
+
+This is a practical operator workshop:
+
+- keep each operator in its own file
+- keep PyTorch references close to implementations
+- make every runnable operator independently smoke-testable
+- record why excluded operators are blocked
+- prefer clear templates over pretending incomplete kernels are done
+
+## License
+
+Standard MIT License. The MIT license is not versioned, so the repository uses
+the canonical MIT text and SPDX-compatible `MIT` package metadata.

docs/README.md

@@ -0,0 +1,7 @@
+# Documentation
+
+- [Operator coverage](operator-coverage.md)
+- [Runnable operators](runnable-operators.md)
+- [Unrunnable operators](unrunnable-operators.md)
+- [Support analysis](support-analysis.md)
+- [Development guide](development-guide.md)

docs/development-guide.md

@@ -0,0 +1,56 @@
+# Development Guide
+
+## Add A New Operator
+
+1. Choose a category under `src/ntops_lab/operators`.
+2. Create one file per operator.
+3. Include these module-level fields:
+
+```python
+OP_NAME = "my_op"
+IMPLEMENTATION_STATUS = "implemented_ninetoothed"
+SOURCE_PATH = "source/or/reference"
+```
+
+4. Implement the standard functions:
+
+```python
+def make_inputs(...): ...
+def run_ninetoothed(*inputs): ...
+def run_pytorch(*inputs): ...
+def check(...): ...
+```
+
+5. Add the operator to `src/ntops_lab/operator_manifest.json`.
+6. Run:
+
+```bash
+python scripts/check_manifest.py
+ntops-lab check my_op
+```
+
+## Mark A Todo Operator
+
+Todo files should stay importable and explain the blocker:
+
+```python
+OP_NAME = "blocked_op"
+IMPLEMENTATION_STATUS = "needs_manual_ninetoothed_implementation"
+REASON = "Needs dynamic scatter/gather support."
+```
+
+## Naming
+
+- Use source-facing operator names in the manifest, such as `add_` or
+  `softmax_out`.
+- Use filesystem-safe names for modules, such as `add_inplace.py`.
+- Keep category names stable; coverage tooling depends on them.
+
+## Validation Levels
+
+- **Catalog validation**: no GPU required; checks manifest/file consistency.
+- **Single-op smoke**: compiles and runs one NineToothed kernel.
+- **Batch smoke**: run selected representative operators by category.
+
+Full GPU coverage is intentionally not part of default `pytest`, because kernel
+compilation requires a CUDA/NineToothed environment.