Copilot instructions

1# PyTorch Copilot Instructions
2 
3This is the PyTorch machine learning framework codebase. These instructions help AI agents navigate and contribute effectively.
4 
5## Architecture Overview
6 
7### Core Components
8 
9- **c10/** - Core library (C++-10 compatible) for essential, binary-size-conscious functionality
10- **aten/** - ATen tensor library (C++), PyTorch's foundation without autograd
11  - `aten/src/ATen/native/` - Modern operator implementations (CPU/CUDA/MPS/sparse)
12  - `aten/src/ATen/native/native_functions.yaml` - **Critical**: Declarative operator registry
13- **torch/** - Python bindings and public API
14  - `torch/csrc/` - C++ Python bindings (hand-written and generated)
15  - `torch/csrc/autograd/` - Reverse-mode automatic differentiation
16  - `torch/csrc/jit/` - TorchScript JIT compiler
17- **torchgen/** - Code generation tooling that reads `native_functions.yaml`
18- **tools/** - Build scripts, autograd derivatives, code generation
19 
20### The Code Generation Workflow
21 
22**Most operator changes require editing `native_functions.yaml`**, not direct C++ files. This YAML file:
231. Declares operator signatures, variants (function/method), and dispatch behavior
242. Gets processed by `torchgen/` to generate C++/Python bindings
253. Produces headers in `build/aten/src/ATen/` during compilation
26 
27Example entry structure:
28```yaml
29- func: my_op(Tensor self, Scalar alpha=1) -> Tensor
30  variants: function, method
31  dispatch:
32    CPU: my_op_cpu
33    CUDA: my_op_cuda
34```
35 
36After editing `native_functions.yaml`, implement kernels in `aten/src/ATen/native/` (see `aten/src/ATen/native/README.md`).
37 
38## Development Workflows
39 
40### Building from Source
41 
42**Never run `setup.py` directly** - use pip with editable install:
43```bash
44python -m pip install --no-build-isolation -v -e .
45```
46 
47Speed up builds:
48- `DEBUG=1` - Debug symbols with `-g -O0`
49- `USE_CUDA=0` - Skip CUDA compilation
50- `BUILD_TEST=0` - Skip C++ test binaries
51- Install `ninja` (`pip install ninja`) for faster builds
52- Use `ccache` for incremental compilation caching
53 
54Rebuild specific targets: `(cd build && ninja <target>)`
55 
56### Testing
57 
58**Critical**: DO NOT run entire test suites. Run specific tests only:
59```bash
60python test/test_torch.py TestTorch.test_specific_case
61```
62 
63**Test structure**: All tests use `torch.testing._internal.common_utils`:
64```python
65from torch.testing._internal.common_utils import run_tests, TestCase
66 
67class TestFeature(TestCase):
68    def test_something(self):
69        # Use self.assertEqual for tensor comparisons
70        pass
71 
72if __name__ == "__main__":
73    run_tests()
74```
75 
76**For bug fixes**: Create a standalone reproduction script first, verify it fails, then fix and add to appropriate test file.
77 
78### Linting
79 
80Run linter (not pre-commit): `lintrunner -a` (auto-applies fixes)
81 
82## Project-Specific Conventions
83 
84### Memory and Storage
85- **Storage is never nullptr** (but `StorageImpl.data` may be nullptr for unallocated outputs)
86- CUDA device info lives in storage objects
87 
88### Python-C++ Integration (`torch/csrc/`)
89- Always include `Python.h` **first** to avoid `_XOPEN_SOURCE` redefinition errors
90- Use `pybind11::gil_scoped_acquire` before calling Python API or using `THPObjectPtr`
91- Wrap entry points with `HANDLE_TH_ERRORS` / `END_HANDLE_TH_ERRORS` for exception conversion
92 
93### Dispatch System
94- PyTorch uses operator dispatch to route calls to backend-specific kernels
95- Prefer `CompositeExplicitAutograd` dispatch when writing device-agnostic compound ops
96- See `aten/src/ATen/native/README.md` for dispatch keyword guidance
97 
98## Git Workflow (AI Agent Specific)
99 
100When preparing PRs from this environment:
101```bash
102git stash -u
103git reset --hard $(cat /tmp/orig_work.txt)  # Reset to LOCAL branch
104git stash pop
105# Resolve conflicts if necessary
106```
107 
108## Common Gotchas
109 
1101. **Editing generated files** - If it's in `build/`, don't edit it. Edit the source template or `native_functions.yaml`
1112. **NVCC template compilation** - NVCC is stricter about C++ than gcc/clang; code working on Linux may fail Windows CI
1123. **Windows symbol visibility** - Use `TORCH_API` macros for exported symbols (required on Windows, optional on Linux)
1134. **No internet access** - DO NOT attempt to install dependencies during development
114 
115## Key Files Reference
116 
117- `AGENTS.md` - Instructions specific to AI coding agents
118- `CONTRIBUTING.md` - Comprehensive human contributor guide
119- `GLOSSARY.md` - Terminology (ATen, kernels, operations, JIT, TorchScript)
120- `aten/src/ATen/native/README.md` - Operator implementation guide
121- `tools/autograd/derivatives.yaml` - Gradient definitions for autograd
122 
123## Performance Debugging
124 
125Use `TORCH_SHOW_CPP_STACKTRACES=1` for C++ traces in Python errors. For profiling, prefer `py-spy` over manual instrumentation.
126