compact_sets/README.md

# Compact Sets

A rational theory of harmony based on Michael Winter's theory of conjunct connected sets in harmonic space, combining ideas from Tom Johnson, James Tenney, and Larry Polansky.

## Installation

```bash
# Activate virtual environment
source venv/bin/activate

# Run
python -m src.io --dims 4 --chord-size 3
```

## CLI Options

### Graph Parameters
- `--dims 4|5|7|8` - Number of prime dimensions (default: 7)
- `--chord-size 3|4` - Size of chords (default: 3)
- `--max-path` - Maximum path length (default: 50)
- `--symdiff-min`, `--symdiff-max` - Symmetric difference range (default: 2-2)
- `--seed` - Random seed (default: random)
- `--cache-dir` - Graph cache directory (default: ./cache)
- `--output-dir` - Output directory (default: output)
- `--rebuild-cache` - Force rebuild graph
- `--no-cache` - Disable caching

### Voice Leading Constraints (Hard Factors)
These factors eliminate edges that don't meet the criteria.

- `--voice-crossing` - Allow edges where voices cross (default: rejected)
- `--direct-tuning` - Require edges to be directly tunable (default: enabled)

### Voice Leading Weights (Soft Factors)
These factors weigh edges without eliminating them. Set weight to 0 to disable.

- `--weight-melodic` - Weight for melodic threshold (default: 1)
- `--weight-contrary-motion` - Weight for contrary motion (default: 0)
- `--weight-hamiltonian` - Weight for Hamiltonian path (default: 1)
- `--weight-dca` - Weight for DCA
- `--weight-target-range` - Weight for target register range (default: 1)

### Target Range
- `--target-range` - Target range in octaves for rising register (default: disabled)
  - When set, enables target_range factor with weight 1
  - Use `--weight-target-range` to adjust the weight

## Weight Factor Details

### Hard Factors (Eliminate edges)
- **Direct tuning**: If enabled, eliminates edges that are not directly tunable
- **Voice crossing**: If not allowed (default), eliminates edges with voice crossing

### Soft Factors (Weigh edges)
- **Melodic threshold**: Penalizes edges with voice movements outside the melodic range
- **Contrary motion**: Boosts edges where some voices move up and others move down
- **Hamiltonian**: Penalizes edges that revisit nodes already in the path
- **DCA**: Boosts edges where voices change/move (rather than staying)
- **Target range**: Boosts edges that move toward the target register

## Examples

```bash
# Basic usage
python -m src.io

# Rising register to 2 octaves
python -m src.io --target-range 2

# Heavy target range, no DCA
python -m src.io --target-range 2 --weight-target-range 10 --weight-dca 0

# Disable Hamiltonian (allow revisiting nodes)
python -m src.io --weight-hamiltonian 0

# Enable voice crossing
python -m src.io --voice-crossing
```

## Legacy

The `legacy/` folder contains earlier versions of this code, used to create the musical works published at [unboundedpress.org/works/compact_sets_1_3](https://unboundedpress.org/works/compact_sets_1_3).

## Output

Generated files go to `output/`:
- `output_chords.json` - Chord data
- `output_chords.txt` - Human-readable chords
- `output_frequencies.txt` - Frequencies in Hz