# generative
algorithmic pitch sequencers - deterministic processes that unfold rule-based, evolving patterns from compact parameter seeds.

## introduction
the generative domain lives in the pitch layer, parallel to `tonal` and `atonal`.
while those domains expose static pitch sets, `generative` produces time-extended sequences whose internal logic is encoded entirely in two parameters `a, b ∈ [0,1]`.
 all sequences are pre-computed*: once `a` and `b` are fixed, the full pitch stream is deterministically known.
* no randomness or feedback is used; apparent complexity arises from algorithmic recursion, state traversal, or chaotic iteration.

## overview
four irreducible forms cover the major algorithmic archetypes:

### 0. `markov_chain`
 behavior:* generates a first-order markov walk over a pitch class set synthesised from parameters.
 parameters*
   `a` → state count* (2 – 12). defines how many pitch classes are in the chain.
   `b` → directional bias* (0 = always downward, 1 = always upward). interpolates the transition matrix between descending and ascending tendencies.

### 1. `state_machine`
 behavior:* steps through a finite deterministic state graph whose edges add fixed pitch intervals.
 parameters*
   `a` → node count* (2 – 8). sets the graph size.
   `b` → edge rule* (0 = left-rotate, 1 = right-rotate). chooses one of two canonical traversal patterns.

### 2. `grammar_expand`
 behavior:* expands an l-system–style rewrite grammar and maps each symbol to a pitch offset.
 parameters*
   `a` → branching factor* (1 – 4). controls the number of production alternatives.
   `b` → expansion depth* (1 – 6). sets how many rewrite generations are performed.

### 3. `chaos_map`
 behavior:* iterates a logistic map and quantises the resulting orbit to pitch indices, yielding quasi-chaotic but repeatable melodies.
 parameters*
   `a` → map parameter* `r` (2.5 – 4.0). governs orbit complexity.
   `b` → initial value* `x₀` (0 – 1). selects the starting point on the attractor.

## parameter behavior summary
 *markov\_chain**
  * `a`: how many distinct pitch states exist.
  * `b`: skew of transition probabilities toward ascending vs. descending motion.
 *state\_machine**
  * `a`: size of the state set.
  * `b`: choice between two deterministic edge-rotation patterns.
 *grammar\_expand**
  * `a`: number of symbols introduced at each rewrite.
  * `b`: total generations before the sequence is frozen.
 *chaos\_map**
  * `a`: non-linear growth rate `r` controlling orbit stability or chaos.
  * `b`: seed value determining which branch of the orbit is taken.

## why these were chosen
 archetypal breadth:* the four forms cover stochastic-looking walks (`markovchain`), rule-driven state cycling (`statemachine`), recursive grammar growth (`grammarexpand`), and deterministic chaos (`chaosmap`).
 irreducibility:* each algorithm embodies a distinct generative principle that cannot be reproduced by parameter tuning of another form.
 compact control:* despite rich output, every form remains fully navigable with exactly two normalized parameters, sustaining the project's parametric purity.
 deterministic expressivity:* long, intricate pitch sequences emerge without runtime randomness, aligning with the engine's requirement for full pre-computation and repeatability.

## what is not included
 higher-order stochastic models or adaptive learning:* would require runtime probability updates, violating determinism.
 input-reactive or feedback-driven algorithms:* excluded by the “no post-processing, no side-effects” rule.
 rhythmic or onset generation:* handled in the onset layer (`grid`, `field`, etc.), not here.
 pitch-to-frequency mapping:* deferred to the `tuning` domain.

## conclusion
`generative` supplies the system with an expandable palette of algorithmic pitch engines.
by capturing four fundamental paradigms - markov, finite-state traversal, recursive grammar, and chaotic mapping - the domain supports evolving melodic and harmonic behaviors that remain wholly deterministic, parameter-driven, and stylistically unbound, fulfilling the project's mandate to construct the full space of structured sonic possibility.