flux-ffi

FFI bindings for the SuperInstance shared LLVM backend — Eisenstein integers, Laman rigidity, holonomy, and Pythagorean encoding

Part of the SuperInstance music constraint theory ecosystem. Provides Rust FFI bindings exposing the C-level mathematical primitives used across the SuperInstance toolchain: Eisenstein integer arithmetic, Laman graph rigidity testing, holonomy checks, Manhattan distance on lattices, and Pythagorean 48-cell spectral encoding.

What It Does

The SuperInstance ecosystem spans 50+ repos across 9 languages, all sharing a common LLVM backend for performance-critical math. flux-ffi is the Rust side of that bridge — it exposes C-implemented mathematical functions to Rust code via extern "C" FFI, and provides safe Rust wrappers around the raw bindings.

These aren't arbitrary math functions — they're specifically chosen for music constraint theory. Eisenstein integers (complex numbers of the form a + bω where ω = e^{2πi/3}) model triadic harmony because their lattice structure naturally captures voice-leading distances between chords. Laman graph rigidity determines whether a set of musical constraints over-constrains the system (a rigid graph) or leaves creative freedom (a flexible one). Pythagorean 48-cell encoding maps spectral content into 48 discrete frequency bands rooted in Pythagorean tuning.

Key Features

• Eisenstein integer norm — compute |a + bω| for harmonic distance calculations
• Laman graph rigidity — test if a constraint graph is rigid (2n - 3 edges test)
• Holonomy check — verify path-independence of constraint chains
• Manhattan distance — lattice distance for voice-leading computations
• Pythagorean 48-cell encoding — map spectral content to 48 Pythagorean bands
• Safe Rust wrappers — extern "C" bindings with idiomatic Rust API on top

Building

git clone https://github.com/SuperInstance/flux-ffi.git
cd flux-ffi
cargo build                # Debug build (links against C backend)
cargo build --release      # Optimized
cargo test                 # Run tests

Prerequisites

• Rust 1.70+ (edition 2021)
• Clang/LLVM (for C interop)
• The SuperInstance C shared library (automatically linked)

Quick Start

Eisenstein Integer Norm

use flux_ffi::eisenstein_norm;

// |3 + 2ω| where ω = e^{2πi/3}
let norm = eisenstein_norm(3, 2);
println!("Eisenstein norm: {}", norm);

Laman Graph Rigidity

use flux_ffi::{laman_graph, is_rigid};

let graph = laman_graph(vec![
    (0, 1), (1, 2), (2, 0),  // Triangle (3 edges, 3 vertices → rigid)
]);

if is_rigid(&graph) {
    println!("Constraint graph is rigid — no creative freedom remaining");
}

Pythagorean 48-Cell Encoding

use flux_ffi::pythagorean_encode;

let spectrum = vec![0.1, 0.5, 0.3, 0.8, 0.2, 0.0, 0.4];
let encoded = pythagorean_encode(&spectrum);
println!("48-cell encoding: {:?}", encoded);

Manhattan Distance

use flux_ffi::manhattan_distance;

let dist = manhattan_distance(&[0, 0, 0], &[3, 2, -1]);
println!("Voice-leading distance: {}", dist);

Architecture

src/
├── lib.rs           # Public API + re-exports
├── eisenstein.rs    # Eisenstein integer operations
├── laman.rs         # Laman graph rigidity
├── holonomy.rs      # Holonomy checking
├── manhattan.rs     # Manhattan/lattice distance
├── pythagorean.rs   # 48-cell spectral encoding
└── ffi/
    └── bindings.rs  # Raw extern "C" bindings (auto-generated)

FFI Layer

┌──────────────────────┐
│  Safe Rust API       │  ← What you use
├──────────────────────┤
│  Rust wrappers       │  ← Error handling, type conversion
├──────────────────────┤
│  extern "C" bindings │  ← Raw FFI calls
├──────────────────────┤
│  C shared library    │  ← LLVM-compiled backend
└──────────────────────┘

API Reference

Function	Signature	Description
eisenstein_norm	(i32, i32) → f64	Norm of Eisenstein integer a + bω
laman_graph	Vec<(u32,u32)> → LamanGraph	Construct graph from edge list
is_rigid	&LamanGraph → bool	Test 2n-3 rigidity condition
holonomy_check	&Path → bool	Verify path-independence
manhattan_distance	&[i32], &[i32] → i32	L1 distance on lattice
pythagorean_encode	&[f64] → [f64; 48]	Map spectrum to 48 Pythagorean cells

Testing

cargo test                     # All tests
cargo test eisenstein          # Eisenstein-specific
cargo test laman               # Rigidity tests

Related Repos

• creative-engine-c — C implementation of creative dynamics (consumed via FFI)
• creative-engine-rust — Rust creative dynamics (uses these bindings)
• constraint-toolkit — Uses rigidity testing for constraint validation
• flux-genome — Uses Eisenstein norms in fitness functions
• flux-hyperbolic — Hyperbolic tradition embeddings

License

MIT