Michael Winter
24709c3eda
- Rename --voice-crossing to --allow-voice-crossing - Change --direct-tuning to --disable-direct-tuning (defaults to require) - Add explicit documentation for every CLI parameter - Add detailed explanations for each factor - Add more examples
131 lines
4.6 KiB
Markdown
131 lines
4.6 KiB
Markdown
# 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)
|