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
-- `--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
+### Graph Structure
 
-### Voice Leading Constraints (Hard Factors)
-These factors eliminate edges that don't meet the criteria.
+--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)
 
-- `--voice-crossing` - Allow edges where voices cross (default: rejected)
-- `--direct-tuning` - Require edges to be directly tunable (default: enabled)
+### Path Generation
 
-### Voice Leading Weights (Soft Factors)
-These factors weigh edges without eliminating them. Set weight to 0 to disable.
+--max-path N       Maximum number of chords in path (default: 50)
+--seed N           Random seed for reproducibility (default: random)
 
-- `--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)
+### Hard Constraints
 
-### 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
+These constraints eliminate edges that fail the criteria.
 
-## 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)
-- **Direct tuning**: If enabled, eliminates edges that are not directly tunable
-- **Voice crossing**: If not allowed (default), eliminates edges with voice crossing
+### Soft Constraints
 
-### 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
+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
 
@@ -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
-python -m src.io --voice-crossing
+# 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

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="Require edges to be directly tunable (default: enabled)",
+        help="Disable direct tuning requirement (default: require)",
     )
     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["direct_tuning"] = args.direct_tuning
+    weights_config["voice_crossing_allowed"] = args.allow_voice_crossing
+    weights_config["direct_tuning"] = not args.disable_direct_tuning
 
     # Soft factor weights
     weights_config["weight_melodic"] = args.weight_melodic