> ## Documentation Index > Fetch the complete documentation index at: https://docs.nomn.jp/llms.txt > Use this file to discover all available pages before exploring further. # Perforation Engine > 7 perforation methods that create gaps in the musical texture # Perforation Engine The Perforation Engine is RESERVOIR's defining feature. After the Rhythm Engine generates a stream of events, the Perforation Engine decides which events are **kept** and which are **removed** — creating holes, gaps, and silence within the texture. This is not random muting. Each perforation method uses a distinct mathematical structure to determine its pattern of presence and absence, producing characteristic textural signatures. ## Perforation Methods | Method | What It Does | Lineage | | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Euclidean** | Distributes gaps as evenly as possible across the event stream using the Bjorklund/Bresenham algorithm. Produces maximally-even perforation patterns — the most uniform distribution of silence achievable for a given density. | *Bjorklund (2003). The same algorithm that generates traditional rhythms also generates their inverse — maximally-even rest patterns.* | | **Prime Sieve** | Removes events at positions divisible by prime numbers, using the Sieve of Eratosthenes. Configurable prime basis (2–13). Creates quasi-periodic patterns with long-range structure determined by prime factorization. | *Eratosthenes (3rd century BC). Xenakis, sieves (Nomos Alpha, 1966) — logical operations on periodic sets applied to pitch and time.* | | **Fibonacci** | Filters events based on their Zeckendorf representation — the unique decomposition of each event's index into non-consecutive Fibonacci numbers. Events with fewer Fibonacci terms are more protected from removal, creating genuine self-similar filtering at all scales. | *Zeckendorf's theorem (1972). Fibonacci structure applied to musical filtering — events whose positions have "simpler" Fibonacci representations persist longer.* | | **Modular** | Keeps events whose index satisfies a modular congruence (index mod N = offset). Creates perfectly periodic patterns with configurable modulus and phase offset. | *Modular arithmetic, number theory. Regular intervallic sieving — the simplest deterministic perforation pattern.* | | **Golden Ratio** | Quasiperiodic lattice based on phi (1.618...). Two modes: Phi mode creates beating patterns between irrational and integer ratios; Golden Angle mode uses the golden angle fraction (2−φ ≈ 0.382) for maximally uniform distribution — the same phyllotactic spiral that arranges sunflower seeds. | *Golden ratio in nature and architecture. Phyllotaxis — the mathematics of leaf arrangement. Aperiodic tiling (Penrose).* | | **Automata** | 1D elementary cellular automaton (Wolfram rules 0–255) generates binary patterns. The automaton state evolves each cycle, producing complex emergent perforation structures from simple local rules. Rule 30 (default) generates chaotic, non-repeating patterns. | *Wolfram, A New Kind of Science (2002). Elementary cellular automata as generators of complex behavior from minimal rules.* | | **Corpus Density** | Rest patterns derived from a statistical phrase-density model. Phrase-level density curves bias perforation decisions toward musically natural rest placement. Context-aware — considers note length, pitch direction, and repetition. Falls back to Euclidean behavior if no corpus data is loaded. | *Statistical learning of rest patterns from symbolic-music corpora.* | A captured MIDI performance via [MIR Capture](/reservoir/features/capture) can additionally morph any of the seven methods toward your own phrasing — the Perforation amount blends between the algorithm's choices and the captured rest pattern. This is a morph mode, not a separate method. ## Parameters | Parameter | ID | Range | Default | Description | | ------------------ | ------------- | ------- | ------- | ------------------------------------------------------------------- | | Perforation | `perforation` | 0.0–1.0 | 0.3 | Gap density — 0 = no gaps, 1 = maximum removal | | Perforation Method | `perfType` | 0–6 | 0 | Algorithm selection | | Spiral Holes | `goldenAngle` | On/Off | Off | Golden Ratio mode: Phi vs Golden Angle | | Corpus Bias | `corpusBias` | 0.0–1.0 | 0.7 | How strongly corpus data influences decisions (Corpus Density only) | ## Layer Interaction Modes Perforation can operate independently per layer or coordinate across layers: | Mode | What It Does | Lineage | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | **Independent** | Each layer's perforation pattern is unrelated to other layers. Maximum textural complexity. | *Free counterpoint — each voice follows its own logic.* | | **Inverse** | Layers become more active when other layers are quiet, and quieter when others are busy. Creates natural breathing between voices. | *Complementary motion in orchestration. Density compensation.* | | **Complementary** | Layers actively fill each other's gaps, producing interlocking patterns where silence in one voice is filled by another. | *African hocket technique — melodic lines distributed across multiple performers. Machaut's isorhythmic motets.* | | **Synchronized** | Perforation holes appear at similar times across all layers. Creates collective silence — the entire texture breathes together. | *Tutti rests in orchestral writing. Collective phrasing.* | | **Monophonic** | Single-voice priority across layers — only the most recently triggered layer sustains at any moment. Older notes are cut off when a new attack occurs, distributing one sequential line across the layer pool. | *Last-note-priority monosynth tradition.* | The layer interaction mode is set globally via the `coordMode` parameter (see [Layers](/reservoir/features/layers)). The Perforation amount of 0.3 (30%) means roughly 30% of generated events are removed. At 0.0, every event plays; at 1.0, maximum removal is applied (the exact amount depends on the method — some methods are inherently denser than others at the same setting).