Create comprehensive copilot-instructions.md file

Co-authored-by: ricardoV94 <[email protected]>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,119 @@
+# PyTensor Copilot Instructions
+
+## Overview
+
+**PyTensor**: Python library for defining, optimizing, and evaluating mathematical expressions with multi-dimensional arrays. Computational backend for PyMC with extensible graph framework. Supports C, JAX, and Numba compilation backends. ~27MB, 492 Python files, Python 3.11-3.13, uses NumPy, SciPy, pytest, Sphinx.
+
+## Critical: Environment & Commands
+
+**ALWAYS use micromamba environment**: PyTensor is pre-installed in `.github/workflows/copilot-setup-steps.yml`. 
+
+All commands MUST use: `micromamba run -n pytensor-test <command>`
+
+Example: `micromamba run -n pytensor-test python -m pytest tests/`
+
+## Testing & Building
+
+### Running Tests (ALWAYS use micromamba)
+
+```bash
+micromamba run -n pytensor-test python -m pytest tests/              # All tests (10-20 min)
+micromamba run -n pytensor-test python -m pytest tests/test_updates.py -v  # Single file (<2 min)
+micromamba run -n pytensor-test python -m pytest tests/ --runslow    # Include slow tests
+```
+
+### Code Style
+
+**DO NOT run pre-commit/ruff locally** - they're not in copilot environment. CI handles style validation via `.github/workflows/test.yml`.
+
+### Documentation
+
+```bash
+micromamba run -n pytensor-test python -m sphinx -b html ./doc ./html  # Build docs (2-3 min)
+```
+**Never commit `html` directory**.
+
+### MyPy
+
+```bash
+micromamba run -n pytensor-test python ./scripts/run_mypy.py --verbose
+```
+**PyTensor incompatible with strict mypy**. Liberal `type: ignore[rule]` and file exclusions are acceptable.
+
+## PyTensor Design Principles
+
+### API Differences from NumPy
+
+1. **Lazy evaluation**: Expressions are symbolic until `pytensor.function()` compiles or `.eval()` evaluates
+2. **Pure semantics**: Use `new_x = x[idx].set(y)` instead of `x[idx] = y`
+3. **Immutable/hashable**: `a == b` tests identity (`a is b`), not equality
+4. **Static shapes**: Broadcasting requires static shape of 1. Valid: `pt.add(pt.vector("x", shape=(1,)), pt.vector("y"))`. Invalid: `pt.add(pt.vector("x", shape=(None,)), pt.vector("y"))` with x.shape=1.
+
+### Config Flags
+
+Tests run with `config.floatX == "float32"` and `config.mode = "FAST_COMPILE"`:
+- Cast values: `test_value.astype(symbolic_var.type.dtype)`
+- Set custom mode or skip tests in `FAST_COMPILE` if needed
+
+## Code Style
+
+- **Comments**: Very sparingly, only for complex logic
+- **Testing**: Very succinct
+  - Prefer `tests.unittest_tools.assert_equal_computations` over numerical evaluation
+  - Test multiple inputs on one compiled function vs multiple compilations
+  - Minimize conditions; if compiled, always evaluate once
+  - Integrate with existing tests via parametrization
+
+## Repository Structure
+
+### Root
+`.github/` (workflows), `pyproject.toml` (config), `setup.py` (Cython build), `conftest.py` (pytest config), `environment.yml` (conda env)
+
+### Source (`pytensor/`)
+- `configdefaults.py`: Config system (floatX, mode)
+- `gradient.py`: Auto-differentiation
+- `compile/`: Function compilation
+- `graph/`: IR and optimization (`graph/rewriting/`)
+- `link/`: Backends (`c/`, `jax/`, `numba/`, `pytorch/`)
+- `tensor/`: Tensor ops (largest module, subdirs: `random/`, `rewriting/`, `conv/`)
+- `scalar/`: Scalar ops
+- `scan/`: Loop operations (`scan_perform.pyx` Cython)
+- `sparse/`: Sparse tensors
+
+### Tests (`tests/`)
+Mirrors source structure. `unittest_tools.py` has testing utilities.
+
+## CI/CD Pipeline
+
+### Workflows (`.github/workflows/`)
+1. **test.yml**: Main suite - Python 3.11/3.12/3.13, fast-compile (0/1), float32 (0/1), 7 test parts + backend jobs (numba, jax, torch)
+2. **mypy.yml**: Type checking
+3. **copilot-setup-steps.yml**: Environment setup
+
+### PR Requirements
+1. Style check (pre-commit: ruff, debug statements)
+2. All test matrix configurations pass
+3. MyPy passes (with exclusions)
+
+Test partitioning: 7 parts for parallelization (general, scan, tensor splits)
+
+## Common Issues
+
+### Import Errors
+Always use: `micromamba run -n pytensor-test python <command>`
+
+### Cython Rebuild
+If modifying `scan_perform.pyx`: `micromamba run -n pytensor-test pip install -e .`
+
+### BLAS Verification
+```bash
+micromamba run -n pytensor-test python -c 'import pytensor; assert pytensor.config.blas__ldflags != ""'
+```
+
+### Config Test Failures
+- Cast dtypes: `value.astype(var.type.dtype)`
+- Skip FAST_COMPILE if test depends on optimizations
+
+## Trust These Instructions
+
+Comprehensive and tested. Search only if: (1) incomplete, (2) incorrect, or (3) need deeper implementation details.