Michael Winter
b20f02b60f
- Change normalization from sum to max: visit_count / max^2 - This gives stronger discrimination toward unvisited nodes - Weight 1 now gives 66.2% coverage (vs 63.6% baseline) - Rename CLI: --weight-dca -> --weight-dca-voice-movement - Rename CLI: --weight-hamiltonian -> --weight-dca-hamiltonian - Restore DCA Hamiltonian display in analysis output - Update README with new CLI names and factor descriptions
91 lines
3.4 KiB
Markdown
91 lines
3.4 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 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-dca-hamiltonian` - Weight for DCA Hamiltonian (favors unvisited nodes, default: 1)
|
|
- `--weight-dca-voice-movement` - Weight for DCA voice movement (favors voice changes, default: 1)
|
|
- `--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
|
|
- **DCA Hamiltonian**: Boosts edges to nodes that haven't been visited recently (favors covering new nodes)
|
|
- **DCA Voice Movement**: Boosts edges where voices change/move rather than staying on same pitch
|
|
- **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 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
|
|
|
|
# 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
|
|
- `graph_path.json` - Hashes of graph nodes visited (for DCA Hamiltonian analysis)
|