forge_sequencing_catalog.hpp

Go to the documentation of this file.

#pragma once
 
// Sequencing — bake-layer catalog nodes for the CV/trigger domain.
//
// The home for `modular_sequencing.hpp`: the pulse-count stage sequencer, the
// 2-D Cartesian walk, the Hordijk rungler, the scale quantizer, and the two
// gate combinators. These are CONTROL nodes — every port carries CV or a gate,
// not sound — so they belong upstream of the audio nodes, feeding a `vca`, a
// `filter_cv`, or an oscillator's pitch. The `lofi` catalog's `lfo` node
// established that an audio port may carry CV; this file is the rest of that
// layer.
//
// ── PORTS carry patch cables; PARAMS carry transport ──────────────────────
//
// The one rule that decides every port list here. An input port exists so
// ANOTHER NODE can drive it — a clock from a divider, a reset from a second
// sequencer's end-of-cycle, a CV to quantize, a gate to combine. Those are
// signals with a source inside the graph.
//
// `run` and `reset` are TRANSPORT, and in a baked artifact transport comes from
// the host: a `run` level is a sample-accurate automation lane, which is exactly
// what a baked param is, and a `reset` is a momentary action a user or an
// automation lane fires. So `run` is a param on every node here.
//
// `reset` is the deliberate exception: it is a param on the two pure PROCESSORS
// (`quantize_scale`, `prob_gate`), where it only clears a latch, and an input
// PORT on all three SEQUENCERS, because the classic patch — one sequencer's
// gate resetting another to build a polymeter — needs a cable, not an
// automation lane. That asymmetry is the topology talking, not an oversight.
//
// ── REALIZATION vs INJECTABLE PARAM, applied per node ─────────────────────
//
// The series rule is that anything moving `latency_samples()` must be frozen at
// registration. **That lever is inert in this module**: every block reports 0
// unconditionally, a slide is a continuous smoother rather than a delay, and no
// setting can change it. So the realizations here are forced by the other two
// reasons, and it is worth being explicit about which:
//
//   - **Seeds are realizations, always** (series law 2: "seeds never
//     automated/macro-exposed"). A seed is not a knob — it is which performance
//     you are playing. `stage_seq`'s random-direction seed, `rungler`'s seed
//     pattern and `prob_gate`'s seed are all construction arguments. NOTE that
//     the spec's own §10 tables list them as baked-param rows *annotated* "not
//     automatable", which is self-contradictory: a baked-param row IS an
//     automation lane. Resolved in favour of law 2.
//   - **Pattern data is a realization** — per-stage pitch/pulse/mode/slide/skip,
//     and the Cartesian grid. The spec says so directly ("array config, not
//     automatable params"), and the shape is right: a baked artifact plays a
//     composed pattern and automates how it is traversed.
//   - **A genuine topology change is a realization.** Two here:
//       * `rungler`'s REGISTER LENGTH. Not a stylistic call — the DSP reloads
//         the seed pattern when the length changes, because a shift register
//         whose length moves mid-orbit has no meaningful "same state" to keep.
//         As a param it would therefore re-pin the sequence every sample and
//         the node would emit one constant. `dac_bits` by contrast only
//         re-quantizes the same register, so it injects.
//       * `cartesian_walk`'s ACCESS MODE, split into two registered type ids
//         exactly as the diode-bridge member splits on detection topology. In
//         row-major an X wrap carries into Y and INPUT PORT 1 IS NOT READ AT
//         ALL. A node whose port silently stops being a port is a different
//         node, not a mode of one.
//   - **Everything else injects**, including the stepped switches: direction,
//     gate op, quantizer mode, grid dimensions, CV offsets. They are front-panel
//     selectors over an unchanged signal path with invariant latency.
//
// ── Levels ────────────────────────────────────────────────────────────────
//
// Gates in and out are 0/1, which sits inside the trigger kit's default
// hysteresis window (rising above 0.5, falling below 0.25) — so any gate output
// here drives any clock or reset input here with no level negotiation, which is
// what makes the chaining patches work. Pitch CV is volts on the 1 V/octave
// standard, so `stage_seq` → `quantize_scale` → an oscillator needs no
// conversion.
 
#include <pulp/host/forge_param_descriptor.hpp>
#include <pulp/host/custom_node_type.hpp>
 
#include <pulp/signal/modular_sequencing.hpp>
 
#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>
 
namespace pulp::host::sequencing {

inline constexpr float kGateHigh = 1.0f;
inline constexpr float kGateLow = 0.0f;

inline bool param_high(float v) { return v >= static_cast<float>(signal::kTriggerHighThreshold); }
 
// ══════════════════════════════════════════════════════════════════════════
//  Stage sequencer — the pulse-count (M-185 / Metropolis lineage) sequencer
// ══════════════════════════════════════════════════════════════════════════
namespace stage_seq {
 
inline constexpr const char* kTypeId = "sequencing.stage_seq";
 
// Node-local ids; the framework namespaces per node, so these restart at 1 in
// every namespace below without colliding.
inline constexpr state::ParamID kRun = 1;             // stepped 0/1 — transport level
inline constexpr state::ParamID kNumStages = 2;       // count
inline constexpr state::ParamID kDirection = 3;       // stepped 0 fwd/1 rev/2 ping/3 rand
inline constexpr state::ParamID kSlideMs = 4;         // ms
inline constexpr state::ParamID kRepeatDutyPct = 5;   // %
 
using Seq = signal::StageSeq;

struct Stage {
    float pitch_v = 0.0f;
    int pulse_count = 1;
    signal::StageGateMode gate_mode = signal::StageGateMode::single;
    bool slide = false;
    bool skip = false;
};
 
using Pattern = std::array<Stage, static_cast<std::size_t>(Seq::kMaxStages)>;

inline Pattern default_pattern() {
    Pattern p{};
    const int degrees[] = {0, 2, 4, 5, 7, 9, 11, 12};
    for (std::size_t i = 0; i < p.size(); ++i) {
        const int semitone = degrees[i % 8] + 12 * static_cast<int>(i / 8);
        p[i].pitch_v = static_cast<float>(semitone) /
                       static_cast<float>(signal::units::kSemitonesPerOctave);
        p[i].pulse_count = 1;
        p[i].gate_mode = signal::StageGateMode::repeat;
        p[i].slide = false;
        p[i].skip = false;
    }
    return p;
}
 
struct Instance {
    signal::StageSeq seq;
    signal::TransportEdge transport;
};

float stage_seq_worst_case_gain();

float stage_seq_pitch_bound_v(const Pattern& pattern);

CustomNodeType make_stage_seq_node(Pattern pattern = default_pattern(),
                                   std::uint32_t seed = Seq::kRandomSeed);
 
inline ForgeNodeDescriptor descriptor() {
    return {"stage_seq", "Stage Sequencer", "A clocked stage sequencer with direction, slide, and repeated-gate shaping.",
            {}, {{"default", kTypeId}},
            {{"run", kRun, "Run", "", "Enables clocked advancement.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"stopped", "Stopped", 0}, {"running", "Running", 1}}},
             {"num_stages", kNumStages, "Stages", "", "Sets the active pattern length.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"direction", kDirection, "Direction", "", "Selects stage traversal.", ForgeParamKind::stepped, ForgeParamCurve::linear,
              {{"forward", "Forward", 0}, {"reverse", "Reverse", 1}, {"ping_pong", "Ping Pong", 2}, {"random", "Random", 3}}},
             {"slide_ms", kSlideMs, "Slide", "ms", "Sets pitch glide between stages.", ForgeParamKind::continuous, ForgeParamCurve::logarithmic},
             {"repeat_duty_pct", kRepeatDutyPct, "Repeat Duty", "%", "Sets repeated-gate pulse width.", ForgeParamKind::continuous, ForgeParamCurve::linear}}};
}
 
}  // namespace stage_seq
 
// ══════════════════════════════════════════════════════════════════════════
//  Cartesian walk — the 2-D (René lineage) sequencer
// ══════════════════════════════════════════════════════════════════════════
namespace cartesian {

inline constexpr const char* kTypeId = "sequencing.cartesian_walk";
inline constexpr const char* kRowMajorTypeId = "sequencing.cartesian_walk_row_major";
 
inline constexpr state::ParamID kRun = 1;       // stepped 0/1
inline constexpr state::ParamID kGridW = 2;     // cells
inline constexpr state::ParamID kGridH = 3;     // cells
inline constexpr state::ParamID kXOffset = 4;   // cells, added to the X counter
inline constexpr state::ParamID kYOffset = 5;   // cells, added to the Y counter
 
using Walk = signal::CartesianWalk;
 
using Grid = std::array<float, static_cast<std::size_t>(Walk::kMaxDim * Walk::kMaxDim)>;

inline Grid default_grid() {
    Grid g{};
    for (std::size_t i = 0; i < g.size(); ++i)
        g[i] = static_cast<float>(i) / static_cast<float>(signal::units::kSemitonesPerOctave);
    return g;
}
 
struct Instance {
    signal::CartesianWalk walk;
    signal::TransportEdge transport;          // run + reset + the X clock
    signal::HystereticTriggerDetectT<float> y_detect;   // the second clock, same edge definition
};

float cartesian_walk_worst_case_gain();

float cartesian_walk_cv_bound_v(const Grid& grid);

CustomNodeType make_cartesian_walk_node(Grid grid = default_grid(), bool row_major = false);
 
inline ForgeNodeDescriptor descriptor() {
    return {"cartesian_walk", "Cartesian Walk", "Walks a two-dimensional value grid from independent clock inputs.",
            {{"order", "Order", "Selects Cartesian or row-major traversal.",
              {{"cartesian", "Cartesian", 0}, {"row_major", "Row Major", 1}}}},
            {{"cartesian", kTypeId, {{"order", "cartesian"}}},
             {"row_major", kRowMajorTypeId, {{"order", "row_major"}}}},
            {{"run", kRun, "Run", "", "Enables grid traversal.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"stopped", "Stopped", 0}, {"running", "Running", 1}}},
             {"grid_width", kGridW, "Grid Width", "cell", "Sets the active grid width.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"grid_height", kGridH, "Grid Height", "cell", "Sets the active grid height.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"x_offset", kXOffset, "X Offset", "cell", "Offsets the horizontal counter.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"y_offset", kYOffset, "Y Offset", "cell", "Offsets the vertical counter.", ForgeParamKind::continuous, ForgeParamCurve::linear}}};
}
 
}  // namespace cartesian
 
// ══════════════════════════════════════════════════════════════════════════
//  Rungler — the Hordijk shift-register / DAC chaos source
// ══════════════════════════════════════════════════════════════════════════
namespace rungler {
 
inline constexpr const char* kTypeId = "sequencing.rungler";
 
inline constexpr state::ParamID kRun = 1;            // stepped 0/1
inline constexpr state::ParamID kDacBits = 2;        // bits → 2^D levels
inline constexpr state::ParamID kFeedbackTap = 3;    // register index
inline constexpr state::ParamID kRangeV = 4;         // volts
inline constexpr state::ParamID kExternalData = 5;   // stepped 0/1
inline constexpr state::ParamID kDataIn = 6;         // stepped 0/1 — the steering bit
 
using Rung = signal::Rungler;
 
struct Instance {
    signal::Rungler rungler;
    signal::TransportEdge transport;
};

float rungler_worst_case_gain();

float rungler_output_bound_v();

CustomNodeType make_rungler_node(int reg_bits = Rung::kDefaultBits,
                                 std::uint32_t seed_pattern = Rung::kSeedPattern);
 
inline ForgeNodeDescriptor descriptor() {
    return {"rungler", "Rungler", "A clocked shift-register sequencer producing stepped pseudo-random control voltage.",
            {}, {{"default", kTypeId}},
            {{"run", kRun, "Run", "", "Enables register advancement.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"stopped", "Stopped", 0}, {"running", "Running", 1}}},
             {"dac_bits", kDacBits, "DAC Bits", "bit", "Sets the output quantization depth.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"feedback_tap", kFeedbackTap, "Feedback Tap", "", "Selects the register bit fed back into the sequence.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"range_v", kRangeV, "Range", "V", "Sets the output voltage span.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"external_data", kExternalData, "External Data", "", "Selects an external steering bit.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"internal", "Internal", 0}, {"external", "External", 1}}},
             {"data_in", kDataIn, "Data In", "", "Sets the external steering bit.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"low", "Low", 0}, {"high", "High", 1}}}}};
}
 
}  // namespace rungler
 
// ══════════════════════════════════════════════════════════════════════════
//  Quantizer — CV to scale, on the 1 V/octave standard
// ══════════════════════════════════════════════════════════════════════════
namespace quantize {
 
inline constexpr const char* kTypeId = "sequencing.quantize_scale";
 
inline constexpr state::ParamID kMode = 1;        // stepped 0 = EDO-N, 1 = scale mask
inline constexpr state::ParamID kEdoN = 2;        // steps per octave
inline constexpr state::ParamID kScaleMask = 3;   // 12-bit pitch-class mask
inline constexpr state::ParamID kRootPc = 4;      // pitch class
inline constexpr state::ParamID kHystCents = 5;   // cents
inline constexpr state::ParamID kReset = 6;       // stepped 0/1 — clears the latch
 
using Quant = signal::QuantizeScale;
 
struct Instance {
    signal::QuantizeScale quant;
    signal::HystereticTriggerDetectT<float> reset_detect;
};

float quantize_scale_worst_case_gain();

float quantize_scale_mask_offset_bound_v();
 
CustomNodeType make_quantize_scale_node();
 
inline ForgeNodeDescriptor descriptor() {
    return {"quantize_scale", "Scale Quantizer", "Quantizes a control voltage to equal divisions or a pitch-class scale.",
            {}, {{"default", kTypeId}},
            {{"mode", kMode, "Mode", "", "Selects equal divisions or a pitch-class mask.", ForgeParamKind::stepped, ForgeParamCurve::linear,
              {{"equal_divisions", "Equal Divisions", 0}, {"scale_mask", "Scale Mask", 1}}},
             {"edo_n", kEdoN, "Divisions", "", "Sets equal divisions per octave.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"scale_mask", kScaleMask, "Scale Mask", "", "Selects enabled pitch classes as a bit mask.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"root_pc", kRootPc, "Root", "", "Sets the root pitch class.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"hysteresis_cents", kHystCents, "Hysteresis", "cent", "Prevents chatter near quantization boundaries.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"reset", kReset, "Reset", "", "Clears the quantizer latch.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"idle", "Idle", 0}, {"reset", "Reset", 1}}}}};
}
 
}  // namespace quantize
 
// ══════════════════════════════════════════════════════════════════════════
//  Gate logic — the Boolean combinator
// ══════════════════════════════════════════════════════════════════════════
namespace gate_logic {
 
inline constexpr const char* kTypeId = "sequencing.gate_logic";
 
inline constexpr state::ParamID kOp = 1;  // stepped 0 AND/1 OR/2 XOR/3 NAND/4 NOR/5 XNOR
 
using Logic = signal::GateLogic;
 
struct Instance {
    signal::GateLogic logic;
};

float gate_logic_worst_case_gain();

CustomNodeType make_gate_logic_node();
 
inline ForgeNodeDescriptor descriptor() {
    return {"gate_logic", "Gate Logic", "Combines two gate signals with selectable Boolean logic.",
            {}, {{"default", kTypeId}},
            {{"operation", kOp, "Operation", "", "Selects the Boolean gate operation.", ForgeParamKind::stepped, ForgeParamCurve::linear,
              {{"and", "AND", 0}, {"or", "OR", 1}, {"xor", "XOR", 2}, {"nand", "NAND", 3}, {"nor", "NOR", 4}, {"xnor", "XNOR", 5}}}}};
}
 
}  // namespace gate_logic
 
// ══════════════════════════════════════════════════════════════════════════
//  Probability gate — deterministic chance
// ══════════════════════════════════════════════════════════════════════════
namespace prob_gate {
 
inline constexpr const char* kTypeId = "sequencing.prob_gate";
 
inline constexpr state::ParamID kProbabilityPct = 1;  // %
inline constexpr state::ParamID kReset = 2;           // stepped 0/1 — clears the latch
 
using Prob = signal::ProbGate;
 
struct Instance {
    signal::ProbGate gate;
    signal::HystereticTriggerDetectT<float> reset_detect;
};

float prob_gate_worst_case_gain();

CustomNodeType make_prob_gate_node(std::uint32_t seed = Prob::kProbSeed);
 
inline ForgeNodeDescriptor descriptor() {
    return {"prob_gate", "Probability Gate", "Passes incoming gates according to a deterministic probability decision.",
            {}, {{"default", kTypeId}},
            {{"probability_pct", kProbabilityPct, "Probability", "%", "Sets the chance that each gate passes.", ForgeParamKind::continuous, ForgeParamCurve::linear},
             {"reset", kReset, "Reset", "", "Clears the gate latch and random sequence.", ForgeParamKind::stepped, ForgeParamCurve::linear, {{"idle", "Idle", 0}, {"reset", "Reset", 1}}}}};
}
 
}  // namespace prob_gate
 
}  // namespace pulp::host::sequencing