Skip to content

Commit 002b340

Browse files
ricardoV94ricardoV94
authored
Revise PyTensor Copilot instructions
Updated PyTensor instructions to clarify environment usage, testing commands, and design principles.
1 parent fbca3d6 commit 002b340

File tree

1 file changed

+70
-73
lines changed

1 file changed

+70
-73
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 70 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -2,72 +2,42 @@
22

33
## Overview
44

5-
**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.
6-
7-
## Critical: Environment & Commands
8-
9-
**ALWAYS use micromamba environment**: PyTensor is pre-installed in `.github/workflows/copilot-setup-steps.yml`.
10-
11-
All commands MUST use: `micromamba run -n pytensor-test <command>`
12-
13-
Example: `micromamba run -n pytensor-test python -m pytest tests/`
14-
15-
## Testing & Building
16-
17-
### Running Tests (ALWAYS use micromamba)
18-
19-
```bash
20-
micromamba run -n pytensor-test python -m pytest tests/ # All tests (10-20 min)
21-
micromamba run -n pytensor-test python -m pytest tests/test_updates.py -v # Single file (<2 min)
22-
micromamba run -n pytensor-test python -m pytest tests/ --runslow # Include slow tests
23-
```
24-
25-
### Code Style
26-
27-
**DO NOT run pre-commit/ruff locally** - they're not in copilot environment. CI handles style validation via `.github/workflows/test.yml`.
28-
29-
### Documentation
30-
31-
```bash
32-
micromamba run -n pytensor-test python -m sphinx -b html ./doc ./html # Build docs (2-3 min)
33-
```
34-
**Never commit `html` directory**.
35-
36-
### MyPy
37-
38-
```bash
39-
micromamba run -n pytensor-test python ./scripts/run_mypy.py --verbose
40-
```
41-
**PyTensor incompatible with strict mypy**. Liberal `type: ignore[rule]` and file exclusions are acceptable.
5+
**PyTensor**: Python library for defining, optimizing, and evaluating mathematical expressions with multi-dimensional arrays. Focus on hackable graph analysis and manipulation. Supports C, JAX, and Numba compilation backends. ~27MB, 492 Python files, Python support as per numpy NEP 29, uses NumPy, SciPy, pytest.
426

437
## PyTensor Design Principles
448

9+
Graph manipulation in Python, graph evaluation out of Python.
10+
Emulate NumPy user-facing API as much as possible.
11+
4512
### API Differences from NumPy
4613

4714
1. **Lazy evaluation**: Expressions are symbolic until `pytensor.function()` compiles or `.eval()` evaluates
48-
2. **Pure semantics**: Use `new_x = x[idx].set(y)` instead of `x[idx] = y`
49-
3. **Immutable/hashable**: `a == b` tests identity (`a is b`), not equality
15+
2. **Pure semantics**: `new_x = x[idx].set(y)` instead of `x[idx] = y`
16+
3. **Immutable/hashable**: PyTensor variables are hashable. `a == b` tests identity (`a is b`), not elemntwise equality.
5017
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.
18+
5. **Static rank and type**. PyTensor functions accepts variables with a specfic dtype and number of dimensions. Length of each dimension can be static or dynamic.
5119

52-
### Config Flags
20+
## Code Style
5321

54-
Tests run with `config.floatX == "float32"` and `config.mode = "FAST_COMPILE"`:
55-
- Cast values: `test_value.astype(symbolic_var.type.dtype)`
56-
- Set custom mode or skip tests in `FAST_COMPILE` if needed
22+
**Uses pre-commit with ruff**
5723

58-
## Code Style
24+
**Comments**: Should be used sparingly, only for complex logic
5925

60-
- **Comments**: Very sparingly, only for complex logic
61-
- **Testing**: Very succinct
62-
- Prefer `tests.unittest_tools.assert_equal_computations` over numerical evaluation
63-
- Test multiple inputs on one compiled function vs multiple compilations
64-
- Minimize conditions; if compiled, always evaluate once
65-
- Integrate with existing tests via parametrization
26+
**Testing**: Should be succinct
27+
- Prefer `tests.unittest_tools.assert_equal_computations` over numerical evaluation
28+
- Test multiple inputs on one compiled function vs multiple compilations
29+
- Minimize test conditions. Be smart, not fearful
30+
- Integrate with similar existing tests
6631

6732
## Repository Structure
6833

6934
### Root
70-
`.github/` (workflows), `pyproject.toml` (config), `setup.py` (Cython build), `conftest.py` (pytest config), `environment.yml` (conda env)
35+
- `.github/` (workflows),
36+
- `doc/` (docs)
37+
- `pyproject.toml` (config),
38+
- `setup.py` (Cython build),
39+
- `conftest.py` (pytest config),
40+
- `environment.yml` (conda env)
7141

7242
### Source (`pytensor/`)
7343
- `configdefaults.py`: Config system (floatX, mode)
@@ -79,41 +49,68 @@ Tests run with `config.floatX == "float32"` and `config.mode = "FAST_COMPILE"`:
7949
- `scalar/`: Scalar ops
8050
- `scan/`: Loop operations (`scan_perform.pyx` Cython)
8151
- `sparse/`: Sparse tensors
52+
- `xtensor/` Tensor Ops with dimensions (lowers to Tensor ops)
8253

8354
### Tests (`tests/`)
8455
Mirrors source structure. `unittest_tools.py` has testing utilities.
8556

86-
## CI/CD Pipeline
57+
## Critical: Environment & Commands
8758

88-
### Workflows (`.github/workflows/`)
89-
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)
90-
2. **mypy.yml**: Type checking
91-
3. **copilot-setup-steps.yml**: Environment setup
59+
**ALWAYS use micromamba environment**: PyTensor is pre-installed as editable in `.github/workflows/copilot-setup-steps.yml`.
9260

93-
### PR Requirements
94-
1. Style check (pre-commit: ruff, debug statements)
95-
2. All test matrix configurations pass
96-
3. MyPy passes (with exclusions)
61+
All commands MUST use: `micromamba run -n pytensor-test <command>`
9762

98-
Test partitioning: 7 parts for parallelization (general, scan, tensor splits)
63+
Example: `micromamba run -n pytensor-test python -c 'import pytensor; print(pytensor.__version__)'`
9964

100-
## Common Issues
65+
## Testing & Building
10166

102-
### Import Errors
103-
Always use: `micromamba run -n pytensor-test python <command>`
67+
### Running Tests (ALWAYS use micromamba)
10468

105-
### Cython Rebuild
106-
If modifying `scan_perform.pyx`: `micromamba run -n pytensor-test pip install -e .`
69+
```bash
70+
micromamba run -n pytensor-test python -m pytest tests/ # All tests
71+
micromamba run -n pytensor-test python -m pytest tests/test_updates.py -v # Single file
72+
micromamba run -n pytensor-test python -m pytest tests/ --runslow # Include slow tests
73+
```
74+
75+
Tests are run with `config.floatX == "float32"` and `config.mode = "FAST_COMPILE"`. If needed:
76+
- Cast numerical values `test_value.astype(symbolic_var.type.dtype)`
77+
- Use custom function mode `get_default_mode().excluding("fusion")` or skip tests in `FAST_COMPILE`
78+
79+
Alternative backends (JAX, NUMBA, ...) are optional. Use `pytest.importorskip` to fail gracefully.
80+
81+
### Pre-commit
10782

108-
### BLAS Verification
10983
```bash
110-
micromamba run -n pytensor-test python -c 'import pytensor; assert pytensor.config.blas__ldflags != ""'
84+
micromamba run -n pytensor-test pre-commit
11185
```
11286

113-
### Config Test Failures
114-
- Cast dtypes: `value.astype(var.type.dtype)`
115-
- Skip FAST_COMPILE if test depends on optimizations
87+
### MyPy
11688

117-
## Trust These Instructions
89+
```bash
90+
micromamba run -n pytensor-test python ./scripts/run_mypy.py --verbose
91+
```
92+
**PyTensor incompatible with strict mypy**. Type-hints are for users/developers not to appease mypy. Liberal `type: ignore[rule]` and file exclusions are acceptable.
11893

119-
Comprehensive and tested. Search only if: (1) incomplete, (2) incorrect, or (3) need deeper implementation details.
94+
### Documentation
95+
96+
```bash
97+
micromamba run -n pytensor-test python -m sphinx -b html ./doc ./html # Build docs (2-3 min)
98+
```
99+
**Never commit `html` directory**.
100+
101+
102+
## CI/CD Pipeline
103+
104+
### Workflows (`.github/workflows/`)
105+
1. **test.yml**: Main suite - Several Python versions, fast-compile (0/1), float32 (0/1), 7 test parts + backend jobs (numba, jax, torch)
106+
2. **mypy.yml**: Type checking
107+
3. **copilot-setup-steps.yml**: Environment setup
108+
109+
110+
## Trust These Instructions
111+
These instructions are comprehensive and tested. Only search for additional information if:
112+
1. Instructions are incomplete for your specific task
113+
2. Instructions are found to be incorrect
114+
3. You need deeper understanding of an implementation detail
115+
116+
For most coding tasks, these instructions provide everything needed to build, test, and validate changes efficiently.

0 commit comments

Comments
 (0)