Update README with complete CLI docs and rename args

- 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

README.md

@@ -14,49 +14,77 @@ python -m src.io --dims 4 --chord-size 3
 
 ## CLI Options
 
-### Graph Parameters
+### Graph Structure
-- `--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)
+--symdiff-min N     Minimum symmetric difference between chords (default: 2)
-These factors eliminate edges that don't meet the criteria.
+--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)
 
-- `--voice-crossing` - Allow edges where voices cross (default: rejected)
+### Path Generation
-- `--direct-tuning` - Require edges to be directly tunable (default: enabled)
 
-### Voice Leading Weights (Soft Factors)
+--max-path N       Maximum number of chords in path (default: 50)
-These factors weigh edges without eliminating them. Set weight to 0 to disable.
+--seed N           Random seed for reproducibility (default: random)
 
-- `--weight-melodic` - Weight for melodic threshold (default: 1)
+### Hard Constraints
-- `--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
+These constraints eliminate edges that fail the criteria.
-- `--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
+--allow-voice-crossing     Allow edges where voices cross (default: reject)
+--disable-direct-tuning    Disable direct tuning requirement (default: require)
 
-### Hard Factors (Eliminate edges)
+### Soft Constraints
-- **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)
+These constraints weigh edges. Set weight to 0 to disable.
-- **Melodic threshold**: Penalizes edges with voice movements outside the melodic range
+
-- **Contrary motion**: Boosts edges where some voices move up and others move down
+--weight-melodic N             Weight for melodic threshold (default: 1, 0=off)
-- **DCA Hamiltonian**: Boosts edges to nodes that haven't been visited recently (favors covering new nodes)
+--weight-contrary-motion N     Weight for contrary motion (default: 0, 0=off)
-- **DCA Voice Movement**: Boosts edges where voices change/move rather than staying on same pitch
+--weight-dca-hamiltonian N    Weight for visiting unvisited nodes (default: 1, 0=off)
-- **Target range**: Boosts edges that move toward the target register
+--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
 
@@ -73,8 +101,20 @@ python -m src.io --target-range 2 --weight-target-range 10 --weight-dca-voice-mo
 # Disable DCA Hamiltonian (allow revisiting nodes freely)
 python -m src.io --weight-dca-hamiltonian 0
 
-# Enable voice crossing
+# Allow voice crossing
-python -m src.io --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

src/io.py

@@ -280,15 +280,14 @@ def main():
         help="Target range in octaves for rising register (default: disabled, 2 = two octaves)",
     )
     parser.add_argument(
-        "--voice-crossing",
+        "--allow-voice-crossing",
         action="store_true",
         help="Allow edges where voices cross (default: reject)",
     )
     parser.add_argument(
-        "--direct-tuning",
+        "--disable-direct-tuning",
         action="store_true",
-        default=True,
+        help="Disable direct tuning requirement (default: require)",
-        help="Require edges to be directly tunable (default: enabled)",
     )
     parser.add_argument(
         "--weight-melodic",
@@ -429,8 +428,8 @@ def main():
     weights_config = path_finder._default_weights_config()
     weights_config["melodic_threshold_min"] = args.melodic_min
     weights_config["melodic_threshold_max"] = args.melodic_max
-    weights_config["voice_crossing_allowed"] = args.voice_crossing
+    weights_config["voice_crossing_allowed"] = args.allow_voice_crossing
-    weights_config["direct_tuning"] = args.direct_tuning
+    weights_config["direct_tuning"] = not args.disable_direct_tuning
 
     # Soft factor weights
     weights_config["weight_melodic"] = args.weight_melodic