Best Use & Engineering Application Guide

Engineering Category: Deterministic Sovereign Compute Kernel

Best Use in Production: Pure-Rust C64-bounded integer transformation kernel verified across 64 canonical test vectors for deterministic Snap-Circuit composition.

When to Select This Capsule: Holds the #1 Equivalence Crown across 2 functionally identical implementations (fastest verified hardware _rdtsc). Low-latency L1-resident kernel (2740867/100000 cyc/op); well-suited for high-frequency pipeline stages.

Snap-Circuit Wiring Role: Specialized Multi-Pin Stage `(i64,i64,i64)->i64` — wire matching input pins via `snap_dag` or `snap_pipeline`.

Hardware _rdtsc: 2740867/100000 cycles/op
Latency: 3427541/400000 ns/op
Throughput: 400000000/3427541 ops/us
Compiled ELF64 .text: 606 B (172 x86_64 insns)
C64 64KB RAM Budget: 1399/32768 (2798 B source)
Ternary Vote: + (score 1) | Salience: 3743695/42588
Pure-Rust Capsule Source Code (2798 B)
/// Q16.16 exponential decay by closed-form [3/3] Padé, integer-only.
///
/// `out = variance * exp(-elapsed / half_life)`, elapsed and half_life in
/// world ticks, amplitude Q16.16.
///
/// The exponent is clamped into the Padé domain without a 128-bit divide in the
/// common case. `((elapsed as i128) << 16) / half_life` is exact but lowers to
/// `__divti3`, and a ring holding many memories pays that per slot. Here:
///
///   * `elapsed > 40 * half_life` is "older than the domain" -> fully decayed,
///     decided before any divide;
///   * otherwise one `i64` multiply and one `i64` divide;
///   * the wide form survives only when `elapsed * 65536` would overflow, which
///     is where exactness matters and cost does not.
///
/// Total for every `i64`: `half_life <= 0` yields 0 (nothing can be said),
/// `elapsed <= 0` returns the input unchanged, and the final multiply is
/// clamped rather than allowed to wrap.
pub fn decay_pade(variance_q16: i64, elapsed: i64, half_life_ticks: i64) -> i64 {
    const RATE_ONE: i128 = 1 << 16;
    const INV_LN2_Q16: i128 = 94548;
    const LN2_Q16: i128 = 45426;
    const PADE_X_MAX: i64 = 40 << 16;

    if half_life_ticks <= 0 {
        return 0;
    }
    if elapsed <= 0 {
        return variance_q16;
    }

    // Older than the Padé domain: the amplitude is exactly zero, and saying so
    // here skips the divide -- the common case for a long-lived ring.
    let x_q16 = if let Some(limit) = half_life_ticks.checked_mul(PADE_X_MAX >> 16) {
        if elapsed >= limit {
            PADE_X_MAX
        } else {
            match elapsed.checked_mul(1 << 16) {
                Some(scaled) => (scaled / half_life_ticks).min(PADE_X_MAX),
                None => {
                    (((elapsed as i128) << 16) / i128::from(half_life_ticks))
                        .min(i128::from(PADE_X_MAX)) as i64
                }
            }
        }
    } else {
        match elapsed.checked_mul(1 << 16) {
            Some(scaled) => (scaled / half_life_ticks).min(PADE_X_MAX),
            None => {
                (((elapsed as i128) << 16) / i128::from(half_life_ticks))
                    .min(i128::from(PADE_X_MAX)) as i64
            }
        }
    };

    let x = i128::from(x_q16);
    let k = (x * INV_LN2_Q16) >> 32;
    let r = x - k * LN2_Q16;
    let r2 = (r * r) >> 16;
    let r3 = (r2 * r) >> 16;
    let num = 120 * RATE_ONE - 60 * r + 12 * r2 - r3;
    let den = 120 * RATE_ONE + 60 * r + 12 * r2 + r3;
    if den <= 0 || k >= 64 {
        return 0;
    }
    let amplitude = ((num << 16) / den) >> k;
    let out = (i128::from(variance_q16) * amplitude) >> 16;
    if out > i128::from(i64::MAX) {
        i64::MAX
    } else if out < i128::from(i64::MIN) {
        i64::MIN
    } else {
        out as i64
    }
}
rustc -C opt-level=3 x86_64 Disassembly (606 B .text / 172 insns)
decay_pade:
    push    r14
    push    rbx
    push    rax
    test    rdx, rdx
    jle    .LBB7_13
    mov    rbx, rdi
    test    rsi, rsi
    jle    .LBB7_14
    imul    rax, rdx, 40
    jo    .LBB7_15
    mov    edi, 2621440
    cmp    rsi, rax
    jae    .LBB7_10
    mov    rax, rsi
    shr    rax, 47
    jne    .LBB7_18
    shl    rsi, 16
    mov    rax, rsi
    mov    rcx, rdx
    or    rax, rdx
    shr    rax, 32
    je    .LBB7_8
    mov    rax, rsi
    xor    edx, edx
    div    rcx
    jmp    .LBB7_9
.LBB7_8:
    mov    eax, esi
    xor    edx, edx
    div    ecx
.LBB7_9:
    cmp    rax, 2621440
    cmovb    rdi, rax
.LBB7_10:
    mov    ecx, 94548
    mov    rax, rdi
    mul    rcx
    mov    r14, rdx
    shld    r14, rax, 32
    mov    rcx, -45426
    mov    rax, r14
    imul    rcx
    mov    rcx, rdx
    mov    r8, rax
    add    r8, rdi
    adc    rcx, 0
    mov    r9, r8
    mov    rax, r8
    mul    r8
    mov    rsi, rax
    imul    r9, rcx
    add    r9, r9
    add    r9, rdx
    shrd    rsi, r9, 16
    shr    r9, 16
    mov    rdi, rsi
    imul    rdi, rcx
    mov    rax, rsi
    mul    r8
    mov    r10, r9
    imul    r10, r8
    add    r10, rdx
    add    r10, rdi
    mov    r11, r10
    sar    r11, 16
    shld    r10, rax, 48
    mov    edx, 60
    mov    rax, r8
    mul    rdx
    mov    r8, rax
    mov    rdi, rdx
    imul    rax, rcx, 60
    add    rdi, rax
    shl    r9, 2
    lea    rcx, [r9 + 2*r9]
    mov    edx, 12
    mov    rax, rsi
    mul    rdx
    add    rax, 7864320
    adc    rdx, rcx
    mov    r9, rax
    add    r9, r8
    mov    rcx, rdx
    adc    rcx, rdi
    add    r9, r10
    adc    rcx, r11
    cmp    r9, 1
    mov    rsi, rcx
    sbb    rsi, 0
    jl    .LBB7_13
    add    r8, r10
    adc    rdi, r11
    sub    rax, r8
    sbb    rdx, rdi
    shld    rdx, rax, 16
    shl    rax, 16
    mov    rdi, rax
    mov    rsi, rdx
    mov    rdx, r9
    call    qword ptr [rip + __divti3@GOTPCREL]
    mov    rdi, rax
    mov    rsi, rdx
    mov    ecx, r14d
    shrd    rdi, rdx, cl
    mov    rax, rdx
    sar    rax, cl
    sar    rsi, 63
    test    r14b, 64
    cmove    rsi, rax
    cmovne    rdi, rax
    mov    rax, rdi
    mul    rbx
    imul    rsi, rbx
    sar    rbx, 63
    imul    rbx, rdi
    add    rsi, rdx
    add    rsi, rbx
    mov    rcx, rsi
    sar    rcx, 16
    shld    rsi, rax, 48
    movabs    rbx, 9223372036854775807
    xor    eax, eax
    cmp    rbx, rsi
    sbb    rax, rcx
    jl    .LBB7_14
    movabs    rbx, -9223372036854775808
    cmp    rbx, rsi
    mov    rax, -1
    sbb    rax, rcx
    cmovl    rbx, rsi
    jmp    .LBB7_14
.LBB7_13:
    xor    ebx, ebx
.LBB7_14:
    mov    rax, rbx
    add    rsp, 8
    pop    rbx
    pop    r14
    ret
.LBB7_15:
    mov    rax, rsi
    shr    rax, 47
    jne    .LBB7_20
    shl    rsi, 16
    mov    rax, rsi
    mov    rcx, rdx
    or    rax, rdx
    shr    rax, 32
    je    .LBB7_19
    mov    rax, rsi
    xor    edx, edx
    div    rcx
    mov    rdi, rax
    jmp    .LBB7_10
.LBB7_18:
    mov    rdi, rsi
    shl    rdi, 16
    shr    rsi, 48
    xor    ecx, ecx
    call    qword ptr [rip + __udivti3@GOTPCREL]
    mov    rdi, rax
    cmp    rax, 2621440
    mov    eax, 2621440
    cmovae    rdi, rax
    test    rdx, rdx
    cmovne    rdi, rax
    jmp    .LBB7_10
.LBB7_19:
    mov    eax, esi
    xor    edx, edx
    div    ecx
    mov    edi, eax
    jmp    .LBB7_10
.LBB7_20:
    mov    rdi, rsi
    shl    rdi, 16
    shr    rsi, 48
    xor    ecx, ecx
    call    qword ptr [rip + __udivti3@GOTPCREL]
    mov    rdi, rax
    jmp    .LBB7_10

Head-to-Head Functional Equivalence Class Peers (2 Implementation(s) Matching 64 Test Vectors)

Global RankCapsule & DomainHardware _rdtscLatencyThroughputELF .textTernary VoteAuthor Aye
#1672decay_pade (THIS CAPSULE)
domain: decay | id: 42764f8a71d071b2c7c180772068caab
2740867/100000 cyc/op3427541/400000 ns/op400000000/3427541 ops/us606 B .text (172 insns)+ (1)aye::Peter+Omni(0+1)::aarch64 @ 432Hz
#1713decay_pade
domain: decay | id: 8c57c8977eaecf67d331b469f2dedf27
6901067/100000 cyc/op1725883/80000 ns/op80000000/1725883 ops/us496 B .text (141 insns)+ (1)aye::Peter+Omni(0+1)::aarch64 @ 432Hz