Generative

Generative#

biotuner.harmonic_geometry.generative#

Phase 5: generative fractal structures derived from harmonic inputs.

Functions#

lsystem_from_ratios – L-system branching plant driven by ratio-derived angles recursive_polygon – Koch-like self-similar polygon boundary self_similar_tuning – pitch lattice at multiple equave levels (harmonic spiral) geometry_sequence – map a geometry function over every frame of a HarmonicSequence

lsystem_from_ratios(input: HarmonicInput, depth: int = 4, axiom: str = 'F', rules: Dict[str, str] | None = None, step_size: float = 1.0) → GeometryData[source]#

L-system branching plant parameterised by harmonic ratios.

The base turning angle θ is derived from the first non-unison ratio as 360 / (p + q) for ratio p/q. The number of side-branches equals n_components - 1, mapping each interval of the chord to a branch direction. Override both with explicit rules.

Parameters:

  • input (HarmonicInput)

  • depth (int, default=4) – Rewriting depth. Keep ≤ 6 to avoid very large strings.

  • axiom (str, default=’F’) – Starting L-system string.

  • rules (dict, optional) – Symbol → replacement string. Defaults to a ratio-derived plant rule.

  • step_size (float, default=1.0) – Forward step length per F symbol.

Returns:

GeometryData – geom_type='graph' with all turtle segments as edges. metadata['lstring_preview'] holds the first 120 characters of the rewritten string.

recursive_polygon(input: HarmonicInput, depth: int = 4, n_sides: int | None = None, scale_factor: float | None = None) → GeometryData[source]#

Koch-like self-similar polygon boundary driven by harmonic ratios.

Each edge is recursively replaced by four sub-edges forming an outward triangular bump. The bump scale and rotation angle are derived from the first non-unison ratio.

Parameters:

  • input (HarmonicInput)

  • depth (int, default=4) – Subdivision steps. Edge count grows as 4^depth * n_sides.

  • n_sides (int, optional) – Number of polygon sides. Defaults to n_components (min 3).

  • scale_factor (float, optional) – Fraction of the edge length occupied by each outer sub-edge. Defaults to 1 / (p + 1) for the first non-trivial ratio p/q.

Returns:

GeometryData – geom_type='curve_2d' with the closed fractal boundary.

self_similar_tuning(input: HarmonicInput, n_levels: int = 4, equave: float = 2.0) → GeometryData[source]#

Self-similar pitch lattice at multiple equave levels.

Starting from the input ratios as generators, each subsequent level is formed by multiplying every pitch in the previous level by every generator and reducing back to [1, equave). The result is the free abelian group generated by the ratios, truncated to n_levels generations.

Pitches are arranged on concentric circles — the k-th circle has radius (k + 1) / n_levels — at angular positions proportional to log_equave(pitch). Edges connect each pitch to its parent (the closest pitch at the previous level that generated it).

Parameters:

  • input (HarmonicInput)

  • n_levels (int, default=4) – Number of generative levels (generations). Level 0 is the seed.

  • equave (float, default=2.0) – Interval of equivalence (2.0 = octave).

Returns:

GeometryData – geom_type='graph' with nodes on concentric circles and edges tracing the generative lineage.

geometry_sequence(input_seq: HarmonicSequence | Iterable[HarmonicInput], fn: Callable[[...], GeometryData], **kwargs) → List[GeometryData][source]#

Map a geometry function over every frame of a HarmonicSequence.

Parameters:

  • input_seq (HarmonicSequence or Iterable[HarmonicInput])

  • fn (callable taking a HarmonicInput as first argument)

  • **kwargs (forwarded to fn for every frame)

Returns:

list of GeometryData

Raises:

ValueError – If input_seq contains no frames.

Contents