- Add ratchet method

Author: Simon Holliday

README.md

@@ -204,6 +204,26 @@ bias = [1.0 - i / 15 for i in range(16)]
 p.thin(strategy=bias, amount=swell, grid=16, rng=p.rng)
 ```
 
+### Ratchet
+
+Ratcheting is a hardware sequencer technique heard on some hardware sequencers - where a single step fires as a rapid burst of repeated hits rather than one note. `p.ratchet(subdivisions, pitch, probability, velocity_start, velocity_end, shape, gate, steps)` is a post-placement transform: it takes notes already in the pattern and replaces each one with `subdivisions` evenly-spaced sub-hits within the original note's duration window. Call it after note-placement methods and before swing or groove.
+
+Velocity across sub-hits is shaped by multipliers (`velocity_start` → `velocity_end`) interpolated via an easing curve - the same easing vocabulary used by `cc_ramp()`. `gate` (0–1) sets sub-note duration as a fraction of each slot: `0.5` is staccato, `1.0` is legato. Use `pitch` to target a single instrument; use `steps` (a list of grid indices) to only ratchet specific positions; use `probability` for chance-based subdivision.
+
+```python
+# Triplet roll on every hi-hat
+p.euclidean("hh_closed", 8).ratchet(3, pitch="hh_closed")
+
+# Crescendo snare roll: quiet → loud over 4 sub-hits
+p.hit_steps("snare", [12]).ratchet(4, velocity_start=0.3, velocity_end=1.0, shape="ease_in")
+
+# Probabilistic 2× ratchet with tight gate
+p.euclidean("hh_closed", 12).ratchet(2, probability=0.4, gate=0.25)
+
+# Ratchet only the downbeat and midpoint (steps 0 and 8 of 16)
+p.euclidean("kick_1", 6).ratchet(2, pitch="kick_1", steps=[0, 8])
+```
+
 ### Cellular automaton
 
 John von Neumann and Stanislaw Ulam conceived cellular automata in the 1940s as models of self-replicating systems. Stephen Wolfram systematically explored 1D elementary automata in the 1980s, cataloguing all 256 rules - discovering that Rule 110 is Turing-complete and Rule 30 produces output indistinguishable from randomness. `p.cellular_1d(pitch, rule, velocity)` generates rhythm from a 1D automaton where each generation evolves from the previous, so patterns self-organise, grow, glide, and die. `p.cellular_2d(parts, rule, density, velocity)` runs a 2D Life-like CA where rows map to instruments and columns to time steps.
@@ -2504,8 +2524,6 @@ Planned features, roughly in order of priority.
 
 ### Medium priority
 
-- **Ratcheting & Subdivisions.** A unified `p.ratchet()` transform to take existing notes and subdivide them into rolls or ratchets based on probability or secondary patterns, allowing dynamic micro-timing and subdivision of primary algorithmic rhythms without manual coding.
-
 - **MIDI File Import & Analysis.** Allow users to load existing `.mid` files and extract their rhythmic or harmonic content to feed into Subsequence algorithms (e.g., generating Markov chains trained on a Bach invention MIDI file).
 
 - **Visual Dashboard / Web UI.** A lightweight local web dashboard to provide real-time visual feedback of the current Chord Graph, global Conductor signals, and active patterns.

subsequence/pattern_algorithmic.py

@@ -9,6 +9,7 @@
 
 import subsequence.constants
 import subsequence.constants.velocity
+import subsequence.easing
 import subsequence.melodic_state
 import subsequence.pattern
 import subsequence.sequence_utils
@@ -1425,6 +1426,176 @@ def thin (
 			del self._pattern.steps[pulse]
 		return self
 
+	def ratchet (
+		self,
+		subdivisions: int = 2,
+		pitch: typing.Optional[typing.Union[int, str]] = None,
+		probability: float = 1.0,
+		velocity_start: float = 1.0,
+		velocity_end: float = 1.0,
+		shape: typing.Union[str, typing.Callable[[float], float]] = "linear",
+		gate: float = 0.5,
+		steps: typing.Optional[typing.List[int]] = None,
+		grid: typing.Optional[int] = None,
+		rng: typing.Optional[random.Random] = None,
+	) -> "PatternAlgorithmicMixin":
+
+		"""Subdivide existing notes into rapid repeated hits (rolls/ratchets).
+
+		A post-placement transform: takes notes already in the pattern and
+		replaces each one with ``subdivisions`` evenly-spaced sub-hits within
+		the original note's duration window.  The velocity of each sub-hit is
+		interpolated from ``velocity_start`` to ``velocity_end`` (as multipliers
+		on the original velocity) using the ``shape`` easing curve, so crescendo
+		rolls, decrescendo buzzes, and flat repeats are all one parameter apart.
+
+		Call ``ratchet()`` after note-placement methods (``euclidean``,
+		``hit_steps``, ``arpeggio``, etc.) and before ``swing`` or ``groove``
+		so that the subdivisions sit inside the original note slot and swing
+		displacement still affects the parent position.
+
+		Parameters:
+			subdivisions: Number of sub-hits replacing each note (default 2).
+				If the note's duration is shorter than ``subdivisions`` pulses,
+				subdivisions are clamped to ``note.duration`` so they never
+				stack on the same pulse.
+			pitch: Only ratchet notes matching this pitch (MIDI number or drum
+				name).  ``None`` (default) ratchets all notes regardless of
+				pitch — useful for melodic patterns such as arpeggios.
+			probability: Chance (0.0–1.0) that each note gets ratcheted.  Notes
+				that fail the check are left completely unchanged.  Default 1.0
+				(every note is ratcheted).
+			velocity_start: Velocity multiplier for the first sub-hit (0.0–2.0).
+				Default 1.0 (same as the original).
+			velocity_end: Velocity multiplier for the last sub-hit (0.0–2.0).
+				Default 1.0.  Set ``velocity_start=0.3, velocity_end=1.0`` for
+				a crescendo roll; ``1.0, 0.2`` for a decrescendo buzz.
+			shape: Easing curve applied to the velocity interpolation across
+				sub-hits.  Accepts any name from ``subsequence.easing`` (e.g.
+				``"ease_in"``, ``"ease_out"``, ``"s_curve"``) or a custom
+				callable ``f(t) → t`` for t ∈ [0, 1].  Default ``"linear"``.
+			gate: Sub-note duration as a fraction of each subdivision slot
+				(0.0–1.0).  ``1.0`` = legato (sub-hits touch), ``0.5`` =
+				staccato (half the slot).  Default 0.5.
+			steps: Grid positions to ratchet (e.g. ``[0, 4, 12]``).  Notes are
+				classified to grid zones the same way ``thin()`` works — swing-
+				shifted notes remain in their original zone.  ``None`` (default)
+				applies ratchet to all eligible notes.
+			grid: Grid resolution used for ``steps`` zone classification.
+				Defaults to the pattern's ``default_grid``.
+			rng: Random number generator.  Defaults to ``self.rng``.
+
+		Examples:
+			```python
+			# Subdivide every hi-hat into a triplet roll
+			p.euclidean("hh_closed", 8).ratchet(3, pitch="hh_closed")
+
+			# Crescendo roll into a snare
+			p.hit_steps("snare", [12]).ratchet(4, velocity_start=0.3,
+			                                      velocity_end=1.0,
+			                                      shape="ease_in")
+
+			# Probabilistic 2× ratchet on hi-hats only
+			p.euclidean("hh_closed", 12).ratchet(2, pitch="hh_closed",
+			                                        probability=0.4, gate=0.3)
+
+			# Ratchet only steps 0 and 8 (downbeats)
+			p.euclidean("kick_1", 6).ratchet(2, pitch="kick_1", steps=[0, 8])
+			```
+		"""
+
+		if rng is None:
+			rng = self.rng
+
+		if grid is None:
+			grid = self._default_grid
+
+		midi_pitch = self._resolve_pitch(pitch) if pitch is not None else None
+		ease_fn = subsequence.easing.get_easing(shape)
+
+		# Build zone set for steps mask (zone-based, matching thin()'s approach).
+		target_zones: typing.Optional[typing.Set[int]] = None
+		if steps is not None:
+			target_zones = set(steps)
+
+		total_pulses = self._pattern.length * subsequence.constants.MIDI_QUARTER_NOTE
+		step_pulses = total_pulses / grid
+
+		new_steps: typing.Dict[int, subsequence.pattern.Step] = {}
+
+		for pulse, step in self._pattern.steps.items():
+
+			# Zone classification for steps mask.
+			if target_zones is not None:
+				zone = int(pulse / step_pulses)
+				if zone >= grid:
+					zone = grid - 1
+				in_zone = zone in target_zones
+			else:
+				in_zone = True
+
+			# Separate targeted notes from passthrough notes.
+			if midi_pitch is None:
+				targets = list(step.notes) if in_zone else []
+				passthrough = [] if in_zone else list(step.notes)
+			else:
+				if in_zone:
+					targets = [n for n in step.notes if n.pitch == midi_pitch]
+					passthrough = [n for n in step.notes if n.pitch != midi_pitch]
+				else:
+					targets = []
+					passthrough = list(step.notes)
+
+			# Passthrough notes keep their original pulse position.
+			if passthrough:
+				if pulse not in new_steps:
+					new_steps[pulse] = subsequence.pattern.Step()
+				new_steps[pulse].notes.extend(passthrough)
+
+			for note in targets:
+
+				# Probability gate — failed notes are kept unchanged.
+				if probability < 1.0 and rng.random() >= probability:
+					if pulse not in new_steps:
+						new_steps[pulse] = subsequence.pattern.Step()
+					new_steps[pulse].notes.append(note)
+					continue
+
+				# Clamp subdivisions so sub-hits never stack on the same pulse.
+				effective_subdivs = min(subdivisions, note.duration)
+				if effective_subdivs < 1:
+					effective_subdivs = 1
+
+				slot_pulses = note.duration / effective_subdivs
+
+				for i in range(effective_subdivs):
+					sub_pulse = pulse + int(round(i * slot_pulses))
+
+					# Velocity interpolation via easing.
+					if effective_subdivs == 1:
+						t = 0.0
+					else:
+						t = i / (effective_subdivs - 1)
+					eased_t = ease_fn(t)
+					vel_mul = velocity_start + (velocity_end - velocity_start) * eased_t
+					sub_velocity = max(1, min(127, int(round(note.velocity * vel_mul))))
+
+					sub_duration = max(1, int(round(slot_pulses * gate)))
+
+					sub_note = subsequence.pattern.Note(
+						pitch=note.pitch,
+						velocity=sub_velocity,
+						duration=sub_duration,
+						channel=note.channel,
+					)
+
+					if sub_pulse not in new_steps:
+						new_steps[sub_pulse] = subsequence.pattern.Step()
+					new_steps[sub_pulse].notes.append(sub_note)
+
+		self._pattern.steps = new_steps
+		return self
+
 	def evolve (
 		self,
 		pitches: typing.List[typing.Union[int, str]],

tests/test_pattern_algorithmic.py

@@ -240,3 +240,174 @@ def test_branch_cycle_path_advances() -> None:
 
 	# Each path should produce a unique sequence.
 	assert len(variations) == 2 ** depth, f"Expected {2**depth} unique variations, got {len(variations)}"
+
+
+# ---------------------------------------------------------------------------
+# ratchet()
+# ---------------------------------------------------------------------------
+
+PPQN = subsequence.constants.MIDI_QUARTER_NOTE  # 24
+
+
+def test_ratchet_basic_subdivision() -> None:
+	"""A single note with subdivisions=3 becomes exactly 3 evenly-spaced notes."""
+	pattern, builder = _make_builder(length=4)
+	# Place one note at beat 0 with duration 1 beat (24 pulses).
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.ratchet(3)
+
+	notes = [(pulse, n) for pulse, step in sorted(pattern.steps.items()) for n in step.notes]
+	assert len(notes) == 3
+
+	pulses = [p for p, _ in notes]
+	slot = PPQN / 3  # 8 pulses per slot
+	assert pulses[0] == 0
+	assert pulses[1] == round(slot)
+	assert pulses[2] == round(2 * slot)
+
+
+def test_ratchet_velocity_linear_shaping() -> None:
+	"""velocity_start/end with linear shape interpolates evenly across sub-hits."""
+	pattern, builder = _make_builder(length=4)
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.ratchet(4, velocity_start=0.5, velocity_end=1.0, shape="linear")
+
+	notes = [n for pulse, step in sorted(pattern.steps.items()) for n in step.notes]
+	assert len(notes) == 4
+
+	velocities = [n.velocity for n in notes]
+	# t values: 0/3, 1/3, 2/3, 3/3 → multipliers: 0.5, 0.667, 0.833, 1.0
+	assert velocities[0] == round(100 * 0.5)
+	assert velocities[3] == 100
+
+
+def test_ratchet_pitch_filter_leaves_other_notes_unchanged() -> None:
+	"""With pitch filter, non-matching notes are untouched."""
+	drum_map = {"kick": 36, "hh": 42}
+	pattern, builder = _make_builder(length=4)
+	builder._drum_note_map = drum_map
+
+	# Place kick at beat 0, hh at beat 1 — both 1-beat duration.
+	builder.note(36, beat=0, velocity=100, duration=1.0)
+	builder.note(42, beat=1, velocity=80, duration=1.0)
+
+	builder.ratchet(3, pitch=42)
+
+	all_notes = [(pulse, n) for pulse, step in sorted(pattern.steps.items()) for n in step.notes]
+	kick_notes = [(p, n) for p, n in all_notes if n.pitch == 36]
+	hh_notes = [(p, n) for p, n in all_notes if n.pitch == 42]
+
+	# Kick: unchanged — still 1 note at pulse 0.
+	assert len(kick_notes) == 1
+	assert kick_notes[0][0] == 0
+	assert kick_notes[0][1].velocity == 100
+
+	# HH: subdivided into 3.
+	assert len(hh_notes) == 3
+
+
+def test_ratchet_probability_zero_leaves_all_unchanged() -> None:
+	"""probability=0.0 — no note is ratcheted."""
+	pattern, builder = _make_builder(length=4)
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.note(60, beat=1, velocity=100, duration=1.0)
+	builder.ratchet(4, probability=0.0)
+
+	notes = [n for pulse, step in pattern.steps.items() for n in step.notes]
+	assert len(notes) == 2
+
+
+def test_ratchet_probability_one_ratchets_all() -> None:
+	"""probability=1.0 — every note is ratcheted."""
+	pattern, builder = _make_builder(length=4)
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.note(60, beat=1, velocity=100, duration=1.0)
+	builder.ratchet(2, probability=1.0)
+
+	notes = [n for pulse, step in pattern.steps.items() for n in step.notes]
+	assert len(notes) == 4
+
+
+def test_ratchet_gate_controls_duration() -> None:
+	"""gate parameter sets sub-note duration as fraction of subdivision slot."""
+	pattern, builder = _make_builder(length=4)
+	# 1-beat note = 24 pulses, ratchet(2) → slot = 12 pulses
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.ratchet(2, gate=1.0)
+
+	notes = [n for pulse, step in sorted(pattern.steps.items()) for n in step.notes]
+	# gate=1.0 → duration = max(1, round(12 * 1.0)) = 12
+	assert all(n.duration == 12 for n in notes)
+
+	# Reset and test gate=0.5
+	pattern2, builder2 = _make_builder(length=4)
+	builder2.note(60, beat=0, velocity=100, duration=1.0)
+	builder2.ratchet(2, gate=0.5)
+
+	notes2 = [n for pulse, step in sorted(pattern2.steps.items()) for n in step.notes]
+	assert all(n.duration == 6 for n in notes2)
+
+
+def test_ratchet_short_note_clamping() -> None:
+	"""Subdivisions are clamped to note.duration so sub-hits never stack."""
+	pattern, builder = _make_builder(length=4)
+	# Place a note with duration=2 pulses (very short) — use pattern.add_note directly.
+	pattern.add_note(0, pitch=60, velocity=100, duration=2)
+	builder.ratchet(8)
+
+	notes = [n for pulse, step in pattern.steps.items() for n in step.notes]
+	# Clamped to 2 subdivisions (= note.duration).
+	assert len(notes) == 2
+
+
+def test_ratchet_steps_mask_targets_correct_positions() -> None:
+	"""steps mask only ratchets notes at specified grid zones."""
+	pattern, builder = _make_builder(length=4)  # default_grid=16
+	# Three notes at beat 0, 1, 2 (grid steps 0, 4, 8 in a 16-step bar).
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	builder.note(60, beat=1, velocity=100, duration=1.0)
+	builder.note(60, beat=2, velocity=100, duration=1.0)
+
+	# Only ratchet grid step 0 (beat 0) and step 8 (beat 2).
+	builder.ratchet(2, steps=[0, 8])
+
+	notes = [(pulse, n) for pulse, step in sorted(pattern.steps.items()) for n in step.notes]
+	# Beat 0 → 2 subdivisions; beat 1 → 1 note unchanged; beat 2 → 2 subdivisions = 5 total.
+	assert len(notes) == 5
+
+
+def test_ratchet_chainable() -> None:
+	"""ratchet() returns self so it can be chained."""
+	pattern, builder = _make_builder(length=4)
+	builder.note(60, beat=0, velocity=100, duration=1.0)
+	result = builder.ratchet(2).ratchet(1)
+	assert result is builder
+
+
+def test_ratchet_deterministic_with_seed() -> None:
+	"""Same RNG seed + probability < 1.0 produces identical output across calls."""
+	import random
+
+	def run():
+		pattern, builder = _make_builder(length=4)
+		builder.note(60, beat=0, velocity=100, duration=1.0)
+		builder.note(60, beat=1, velocity=100, duration=1.0)
+		builder.note(60, beat=2, velocity=100, duration=1.0)
+		builder.ratchet(3, probability=0.5, rng=random.Random(42))
+		return tuple(
+			(pulse, n.velocity, n.duration)
+			for pulse, step in sorted(pattern.steps.items())
+			for n in step.notes
+		)
+
+	assert run() == run()
+
+
+def test_ratchet_velocity_preserved_without_shaping() -> None:
+	"""Default velocity_start=1.0, velocity_end=1.0 keeps original velocity."""
+	pattern, builder = _make_builder(length=4)
+	builder.note(60, beat=0, velocity=80, duration=1.0)
+	builder.ratchet(4)
+
+	notes = [n for pulse, step in pattern.steps.items() for n in step.notes]
+	assert all(n.velocity == 80 for n in notes)