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 Structure

--symdiff-min N     Minimum symmetric difference between chords (default: 2)
--symdiff-max N     Maximum symmetric difference between chords (default: 2)
--dims N            Number of prime dimensions: 4, 5, 7, or 8 (default: 7)
--chord-size N      Number of voices per chord (default: 3)

### Path Generation

--max-path N       Maximum number of chords in path (default: 50)
--seed N           Random seed for reproducibility (default: random)

### Hard Constraints

These constraints eliminate edges that fail the criteria.

--allow-voice-crossing     Allow edges where voices cross (default: reject)
--disable-direct-tuning    Disable direct tuning requirement (default: require)

### Soft Constraints

These constraints weigh edges. Set weight to 0 to disable.

--weight-melodic N             Weight for melodic threshold (default: 1, 0=off)
--weight-contrary-motion N     Weight for contrary motion (default: 0, 0=off)
--weight-dca-hamiltonian N    Weight for visiting unvisited nodes (default: 1, 0=off)
--weight-dca-voice-movement N Weight for moving voices (default: 1, 0=off)
--weight-target-range N       Weight for target register (default: 1, 0=off)

### Melodic Range

--melodic-min N      Minimum cents any voice must move (default: 0 = disabled)
--melodic-max N      Maximum cents any voice can move (default: 500)

### Target Register

--target-range N    Target register in octaves (default: disabled, 2 = 2 octaves rise)

### Output Options

--output-dir PATH    Where to write output files (default: output/)
--stats              Show analysis statistics after generation
--cache-dir PATH     Directory for graph cache (default: cache/)
--rebuild-cache      Force rebuild of graph cache
--no-cache           Disable caching

## Factor Explanations

### Direct Tuning

An edge is directly tunable if any pitches that change can be tuned directly to a pitch that remains the same from chord to chord. This ensures smooth voice-leading where moving voices connect to stationary ones.

### Melodic Range

Controls the minimum and maximum distance any single voice can move between consecutive chords. The melodic-min prevents voices from staying too still, while melodic-max prevents leaps that are too large.

### DCA Hamiltonian

DCA (Dynamic Constraint Adaptation) Hamiltonian factor favors edges that connect to nodes not visited recently. This promotes coverage of the harmonic space, encouraging the path to visit as many unique chords as possible.

### DCA Voice Movement

DCA Voice Movement factor favors edges where voices change pitch rather than staying stationary. This encourages active voice-leading where all voices contribute to the harmonic motion.

### Contrary Motion

Contrary motion occurs when some voices move up while others move down. This factor boosts such edges, creating more interesting and balanced harmonic motion.

### Target Register

The average pitch of all voices should rise toward the target (specified in octaves) over the course of the path. This factor encourages upward or downward register movement depending on the target.

## 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 voice movement
python -m src.io --target-range 2 --weight-target-range 10 --weight-dca-voice-movement 0

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

# Allow voice crossing
python -m src.io --allow-voice-crossing

# Disable direct tuning requirement
python -m src.io --disable-direct-tuning

# Stricter melodic constraints (max 200 cents per voice)
python -m src.io --melodic-max 200

# Require at least 30 cents movement per voice
python -m src.io --melodic-min 30 --melodic-max 200

# Use 4 voices with 4 dimensions
python -m src.io --dims 4 --chord-size 4
```

## 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
- `graph_path.json` - Hashes of graph nodes visited (for DCA Hamiltonian analysis)