compact_sets/AGENTS.md

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:

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:

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

  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