# AGENTS.md - Codebase Guidelines

## Project Overview

This repository contains research code for musical set theory and tonal space analysis, primarily implemented as a Jupyter notebook (`compact_sets_optimized_2.ipynb`). The code deals with harmonic series, pitch class sets, and related musical computations.

## Build, Lint, and Test Commands

### Jupyter Notebooks
- **Run notebook**: `jupyter notebook compact_sets_optimized_2.ipynb` or `jupyter lab`
- **Execute single cell**: Select cell and press `Shift+Enter`
- **Run all cells**: `Cell > Run All` in Jupyter menu

### Python Environment
No formal build system or package manager is configured. To run Python code:
```bash
python3 -m notebook compact_sets_optimized_2.ipynb
# or convert to script:
jupyter nbconvert --to python compact_sets_optimized_2.ipynb
```

### Testing
No test framework is configured. Manual testing is done within the notebook using assert statements and cell-by-cell verification.

### Linting
No linter is configured. For Python files, you may optionally use:
```bash
ruff check .
# or
pylint **/*.py
```

## Code Style Guidelines

### General Principles
- Write clear, readable code with meaningful variable names
- Add comments for complex mathematical or music theory operations
- Keep functions focused on single responsibilities

### Python Code Style (for any .py files)
- **Formatting**: Follow PEP 8
- **Line length**: Maximum 100 characters
- **Indentation**: 4 spaces (no tabs)
- **Naming**:
  - Functions/variables: `snake_case` (e.g., `hs_array_to_fr`, `expand_pitch`)
  - Constants: `UPPER_SNAKE_CASE` (e.g., `MAX_OCTAVES`)
  - Classes: `PascalCase` (if applicable)
- **Imports**: Standard library first, then third-party
  ```python
  from itertools import chain, combinations
  from math import prod, log
  import networkx as nx
  from fractions import Fraction
  ```
- **Type hints**: Use when beneficial for clarity
- **Error handling**: Use specific exception types, provide meaningful messages

### Jupyter Notebook Style
- Keep cells relatively small and focused
- Use markdown cells to explain music theory concepts
- Name notebook cells for navigation (view > collapse pnl)
- Restart kernel and run all before sharing

### Key Patterns in This Codebase

#### Pitch Representation
- Pitches stored as tuples: `(octave, harmonic_series_index, ...)`
- Example: `(0, 1, 5)` represents the 5th partial of the fundamental

#### Functions
- `hs_array_to_fr`: Convert harmonic series array to frequency ratio
- `hs_array_to_cents`: Convert to cents (1200 per octave)
- `expand_pitch`/`collapse_pitch`: Manage pitch octave normalization
- `transpose_pitch`: Apply pitch transformations

### File Organization
- Main code: `compact_sets_optimized_2.ipynb`
- Data: `sirens.txt` (likely reference data for sonic examples)
- Audio: `compact_sets_play_siren.scd` (SuperCollider patch)

## Notes for Agents

1. **Backup before edits**: The notebook is complex; make backups before major changes
2. **Verify calculations**: Musical intervals and frequency calculations should be verified
3. **No CI/CD**: This is a research sketch repository; no automated pipelines exist
4. **Dependencies**: Key libraries used include `networkx`, `itertools`, `math`, `fractions`

## Extending This Codebase

If adding Python files:
1. Create a `src/` directory for modules
2. Add `pyproject.toml` for package management if needed
3. Consider adding `pytest` for testing
4. Add type hints to new functions

If adding notebooks:
1. Follow existing naming: `{topic}_optimized_{version}.ipynb`
2. Import from shared modules rather than duplicating code
3. Use clear markdown headers