100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
# 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
|