Metadata-Version: 2.4
Name: popcorn
Version: 0.1.0
Summary: Kernel dispatch for PyTorch: torch references, optimized backends, autogenerated correctness and benchmarks.
Author: Tilde Research
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/tilde-research/popcorn
Project-URL: Issues, https://github.com/tilde-research/popcorn/issues
Keywords: pytorch,kernels,triton,cuda,gpu,dispatch,benchmark
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: torch>=2.5
Requires-Dist: jaxtyping>=0.2.36
Requires-Dist: packaging>=23.0
Requires-Dist: einops>=0.8
Requires-Dist: pyarrow>=15.0
Requires-Dist: huggingface-hub>=0.34
Provides-Extra: fa3
Requires-Dist: flash-attn-3<=3.0.0,>=3.0.0; extra == "fa3"
Provides-Extra: fla
Requires-Dist: flash-linear-attention<=0.4.2,>=0.4.0; extra == "fla"
Provides-Extra: liger
Requires-Dist: liger-kernel<=0.7.0,>=0.6.0; extra == "liger"
Provides-Extra: quack
Requires-Dist: quack-kernels<=0.5.0,>=0.5.0; extra == "quack"
Provides-Extra: unsloth
Requires-Dist: unsloth<=2026.7.5,>=2026.7.1; extra == "unsloth"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/tilde-research/popcorn/main/images/popcorn-banner.png" alt="Popcorn"/>
</p>

<!-- popcorn:badges -->
<p align="center">
  <img src="https://img.shields.io/badge/kernels-96-blue" alt="kernels"/>
  <img src="https://img.shields.io/badge/backends-6-blue" alt="backends"/>
  <img src="https://img.shields.io/badge/implementations-224-blue" alt="implementations"/>
  <img src="https://img.shields.io/badge/grid%20rows-31%2C176-blue" alt="grid rows"/>
</p>
<!-- /popcorn:badges -->

--------------------------------------------------------------------------------

<h3 align="center">
  <a href="https://tilde-research.github.io/popcorn/docs">Documentation</a>
  &nbsp;|&nbsp;
  <a href="https://tilde-research.github.io/popcorn/kernels">Kernel Explorer</a>
</h3>

<!-- * [About](#about)
* [Installation](#installation)
    * [Installing Backends](#installing-backends)
    * [Updating](#updating)
* [Limitations](#limitations)
* [Contributing](#contributing)
* [Acknowledgement](#acknowledgement) -->

## About
***Popcorn*** 🍿 is a development and dispatch library for high-performance machine learning kernels. It unifies **96 kernels** and more than **100 optimized implementations** behind a single API, then selects among eligible backends using hardware-specific benchmark records. Each implementation is checked against a PyTorch reference; failed and unmeasured cases remain visible evidence rather than being presented as successful validation.
Popcorn also ships a growing collection of first-party kernels, along with the environment and harness to build, test, benchmark, and deploy new kernels and backends. Contributions are welcome.

## Installation

Install Popcorn from PyPI using `uv`:
```bash
uv pip install popcorn           # first-party only
uv pip install "popcorn[liger]"  # + Liger-Kernel backends
uv pip install "popcorn[fla]"    # + FLA backends
```

> [!NOTE]
> Add `--torch-backend=auto` to let `uv` select a PyTorch build for your hardware.

> [!WARNING]
> `pip install popcorn` may work but is not generally supported. Install the desired PyTorch build for your hardware first, then install Popcorn with pip.

Add one extra per backend you want. There is no "everything" extra: the backends pin mutually exclusive requirements, so installing them together does not resolve.

Installing also fetches the benchmark cache that dispatch selects implementations with, from the [popcorn-reports](https://huggingface.co/datasets/tilde-research/popcorn-reports) dataset at the revision this version pins. Set `POPCORN_SKIP_REPORTS=1` to install without it; popcorn then falls back to the reference for every call and says so. Refresh it at any time with:
```bash
uv run python -m popcorn.bench pull
```

A backend is eligible only when its package is installed at a declared supported version: auto-dispatch skips unavailable ones, and forcing one raises with the install hint or version error. First-party kernels (the `popcorn` backend) are always included.

### Benchmarking on your own hardware
The shipped cache covers the hardware it was recorded on. To measure the combinations your machine has no timing for and add them to your local cache:
```bash
uv run python -m popcorn.bench fill            # every op; --limit N to subsample large grids
```
Already-cached combinations are skipped; pass `--force` to re-measure them. Dispatch picks these up on the next call.

### Installing Backends
To install the prerequisites for an additional backend:
```bash
uv pip install "popcorn[<new_extra>]"
```

### Updating
Upgrade Popcorn and refresh its pinned report cache with:
```bash
uv pip install --upgrade popcorn
```
## Limitations

### Correctness

Popcorn validates implementations across a broad grid of inputs and does its best to warn when an exact case has not been validated. This reduces the risk of numerical errors but does not guarantee correctness for every possible input. Every comparison also assumes that the registered reference is correct: Popcorn measures agreement with that reference, not correctness in the abstract, therefore "correctness" here is the measure of similarity to the reference. Validate representative production inputs, particularly unusual shapes, dtypes, and optional arguments.

### Performance
Popcorn benchmarks kernels in isolation. This is useful for comparing implementations in an apples-to-apples fashion, but these results do not necessarily predict end-to-end model performance. PyTorch and `torch.compile` may fuse or rewrite surrounding native operations, while a backend call or custom-op boundary can limit those optimizations. Tensor layouts, memory traffic, synchronization, and compilation overhead can also change the result in a real workload.
It's important to keep in mind that dispatch currently optimizes recorded execution time, not peak memory. For some workloads, we may prefer a slower implementation with a smaller memory footprint. Benchmark representative model code and explicitly tune or select a backend when latency and memory requirements are both important.

## Contributing
New kernels and backends follow a guided flow: [CONTRIBUTING.md](CONTRIBUTING.md). Benchmarks come from contributors' machines; run the grid on your hardware and include its matrix rows for review. Maintainers publish accepted report evidence to the pinned dataset.

## Acknowledgement

Popcorn stands on the shoulders of the open-source kernel ecosystem. The optimized backends it dispatches to are built and maintained by their authors:

- [flash-linear-attention](https://github.com/fla-org/flash-linear-attention)
- [Liger-Kernel](https://github.com/linkedin/Liger-Kernel)
- [quack](https://github.com/Dao-AILab/quack)
- [flash-attention](https://github.com/Dao-AILab/flash-attention)
- [Unsloth](https://github.com/unslothai/unsloth)

The agent optimization loop (`python -m popcorn.bench.loop`) is inspired by [AutoKernel](https://github.com/RightNow-AI/autokernel)'s edit–evaluate–keep/revert cycle for autonomous kernel search.

## Citation

```bibtex
@software{popcorn,
  author = {{Tilde Research}},
  title  = {Popcorn: kernel dispatch for PyTorch},
  url    = {https://github.com/tilde-research/popcorn},
  year   = {2026}
}
```

## License

[Apache-2.0](LICENSE).
