RustKernels

GPU-accelerated kernel library for financial services, compliance, and enterprise analytics

Version 0.4.0 | RingKernel 0.4.2 | 106 kernels | 14 domains | 19 crates

Overview

RustKernels provides 106 GPU-accelerated algorithms across 14 domain-specific crates, engineered for financial services, regulatory compliance, and enterprise analytics workloads. Built on RingKernel 0.4.2, it delivers both CPU-orchestrated batch execution and GPU-persistent ring execution with sub-microsecond message latency.

Key Features

Execution Model

Kernels operate in one of two modes, selected based on latency and throughput requirements:

Batch kernels implementing BatchKernel<I, O> can be executed directly via typed calls or through the type-erased BatchKernelDyn interface used by REST and gRPC endpoints. Ring kernels require the RingKernel persistent actor runtime.

Domains at a Glance

Quick Start

Add to your Cargo.toml:

[dependencies]
rustkernels = "0.4.0"

Basic usage:

use rustkernels::prelude::*;
use rustkernels::graph::centrality::{BetweennessCentrality, BetweennessCentralityInput};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let kernel = BetweennessCentrality::new();
    println!("Kernel: {}", kernel.metadata().id);

    let input = BetweennessCentralityInput {
        num_nodes: 4,
        edges: vec![(0, 1), (1, 2), (2, 3), (0, 3)],
        normalized: true,
    };

    let result = kernel.execute(input).await?;
    for (node, score) in result.scores.iter().enumerate() {
        println!("  Node {}: {:.4}", node, score);
    }
    Ok(())
}

Feature Flags

# Default domains (graph, ml, compliance, temporal, risk)
rustkernels = "0.4.0"

# Selective compilation
rustkernels = { version = "0.4.0", features = ["graph", "accounting"] }

# All 14 domains
rustkernels = { version = "0.4.0", features = ["full"] }

# Service deployment
rustkernel-ecosystem = { version = "0.4.0", features = ["axum", "grpc"] }

Enterprise Features

Version 0.4.0 provides production-ready enterprise capabilities with deep RingKernel 0.4.2 integration:

See Enterprise Features for detailed documentation.

Requirements

• Rust 1.85 or later
• RingKernel 0.4.2 (from crates.io)
• CUDA toolkit (optional; falls back to CPU execution)

Project Structure

crates/
├── rustkernels/             # Facade crate — re-exports all domains
├── rustkernel-core/         # Core traits, registry, enterprise modules
│   ├── security/            # Auth, RBAC, multi-tenancy
│   ├── observability/       # Metrics, tracing, logging
│   ├── resilience/          # Circuit breaker, retry, health
│   ├── runtime/             # Lifecycle, configuration
│   ├── memory/              # Pooling, reductions
│   └── config/              # Production configuration
├── rustkernel-ecosystem/    # Service integrations (Axum, gRPC, Actix)
├── rustkernel-derive/       # Procedural macros
├── rustkernel-cli/          # Command-line interface
└── rustkernel-{domain}/     # 14 domain-specific crates

Building

# Build entire workspace
cargo build --workspace

# Run all tests (895 tests)
cargo test --workspace

# Test a single domain
cargo test --package rustkernel-graph

# Lint with warnings as errors
cargo clippy --all-targets --all-features -- -D warnings

# Generate API documentation
cargo doc --workspace --no-deps --open

License

Licensed under Apache-2.0. See LICENSE for details.

Installation

This guide covers installing RustKernels and its dependencies.

Prerequisites

Rust Toolchain

RustKernels requires Rust 1.85 or later:

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Update to latest stable
rustup update stable

# Verify version
rustc --version  # Should be 1.85.0 or higher

RingKernel Framework

RustKernels depends on RingKernel 0.4.2 for GPU execution. RingKernel is published on crates.io and is resolved automatically by Cargo — no manual installation is required.

CUDA Toolkit (Optional)

For GPU acceleration, install the CUDA toolkit:

• Linux: Install via your package manager or from NVIDIA’s website
• Windows: Download the installer from NVIDIA
• macOS: Not supported for CUDA (CPU fallback only)

# Verify CUDA installation
nvcc --version
nvidia-smi

If CUDA is not available, RustKernels falls back to CPU execution automatically.

Adding RustKernels to Your Project

Basic Installation

Add to your Cargo.toml:

[dependencies]
rustkernels = "0.4.0"

This includes the default feature set: graph, ml, compliance, temporal, risk.

Selective Installation

Include only the domains you need to reduce compile time and binary size:

[dependencies]
rustkernels = { version = "0.4.0", default-features = false, features = ["graph", "accounting"] }

Full Installation

Include all 14 domains:

[dependencies]
rustkernels = { version = "0.4.0", features = ["full"] }

Service Deployment

For deploying kernels as REST or gRPC services:

[dependencies]
rustkernel-ecosystem = { version = "0.4.0", features = ["axum", "grpc"] }

Available Features

Building from Source

Clone and build the entire workspace:

# Clone the repository
git clone https://github.com/mivertowski/RustKernels.git
cd RustKernels

# Build all crates
cargo build --workspace

# Build in release mode
cargo build --workspace --release

# Run all tests (895 tests)
cargo test --workspace

# Lint
cargo clippy --all-targets --all-features -- -D warnings

Verifying Installation

Create a simple test file:

// src/main.rs
use rustkernels::prelude::*;

fn main() {
    println!("RustKernels v0.4.0 installed successfully!");
    println!("RingKernel 0.4.2 — GPU-native persistent actor runtime");
}

Run with:

cargo run

Troubleshooting

CUDA Not Detected

If GPU execution is not working:

1. Verify CUDA installation with nvcc --version
2. Check GPU availability with nvidia-smi
3. Ensure CUDA libraries are in your PATH
4. RustKernels falls back to CPU automatically if CUDA is not available

Compilation Errors

For Rust version issues:

# Ensure you are on the correct toolchain
rustup override set stable
rustup update

Dependency Resolution

RingKernel 0.4.2 is resolved from crates.io. If you encounter resolution issues:

# Update the Cargo registry index
cargo update

# Clear the build cache if needed
cargo clean && cargo build --workspace

Next Steps

• Quick Start — Run your first kernel
• Execution Modes — Understand Batch vs Ring modes
• Kernel Catalogue — Browse available kernels

Quick Start

Get up and running with RustKernels in minutes.

Your First Kernel

Run a betweenness centrality calculation on a simple graph.

Step 1: Create a New Project

cargo new my-analytics
cd my-analytics

Step 2: Add Dependencies

Edit Cargo.toml:

[package]
name = "my-analytics"
version = "0.1.0"
edition = "2024"

[dependencies]
rustkernels = { version = "0.4.0", features = ["graph"] }
tokio = { version = "1", features = ["full"] }

Step 3: Write Your Code

Edit src/main.rs:

use rustkernels::prelude::*;
use rustkernels::graph::centrality::{BetweennessCentrality, BetweennessCentralityInput};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create the kernel
    let kernel = BetweennessCentrality::new();

    // Print kernel metadata
    let metadata = kernel.metadata();
    println!("Kernel: {}", metadata.id);
    println!("Domain: {:?}", metadata.domain);
    println!("Mode:   {:?}", metadata.mode);

    // Prepare input: a simple 4-node graph
    let input = BetweennessCentralityInput {
        num_nodes: 4,
        edges: vec![(0, 1), (1, 2), (2, 3), (0, 3)],
        normalized: true,
    };

    // Execute the kernel
    let result = kernel.execute(input).await?;

    // Print results
    println!("\nBetweenness Centrality Scores:");
    for (node, score) in result.scores.iter().enumerate() {
        println!("  Node {}: {:.4}", node, score);
    }

    Ok(())
}

Step 4: Run

cargo run

Using the Registry

For production deployments, use the KernelRegistry to manage kernels centrally:

use rustkernels::prelude::*;
use rustkernel_core::registry::KernelRegistry;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create the registry and register all domains
    let registry = Arc::new(KernelRegistry::new());
    rustkernels::register_all(&registry)?;

    // Execute via type-erased interface (same path REST/gRPC uses)
    let input_json = serde_json::to_vec(&serde_json::json!({
        "num_nodes": 4,
        "edges": [[0, 1], [1, 2], [2, 3], [0, 3]],
        "normalized": true
    }))?;

    let output_json = registry.execute_batch(
        "graph/betweenness-centrality",
        &input_json,
    ).await?;

    let result: serde_json::Value = serde_json::from_slice(&output_json)?;
    println!("Result: {}", serde_json::to_string_pretty(&result)?);

    Ok(())
}

Deploying as a REST Service

Expose kernels via HTTP using the Axum integration:

use rustkernel_ecosystem::axum::{KernelRouter, RouterConfig};
use rustkernel_core::registry::KernelRegistry;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let registry = Arc::new(KernelRegistry::new());
    rustkernels::register_all(&registry).unwrap();

    let router = KernelRouter::new(registry, RouterConfig::default());
    let app = router.into_router();

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    println!("Listening on http://0.0.0.0:8080");
    axum::serve(listener, app).await.unwrap();
}

Then call it:

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "kernel_id": "graph/betweenness-centrality",
    "input": {
      "num_nodes": 4,
      "edges": [[0, 1], [1, 2], [2, 3], [0, 3]],
      "normalized": true
    }
  }'

Kernel Configuration

Most kernels accept configuration through their input types:

use rustkernels::ml::clustering::{KMeans, KMeansInput};

let kernel = KMeans::new();
let input = KMeansInput {
    data: vec![/* data points */],
    k: 5,
    max_iterations: 300,
    tolerance: 1e-4,
};

let result = kernel.execute(input).await?;

Batch vs Ring Mode

Batch Mode (Default)

CPU-orchestrated execution — best for periodic computations:

// Batch kernels implement BatchKernel<I, O>
let kernel = BetweennessCentrality::new();
let result = kernel.execute(input).await?;

Ring Mode

GPU-persistent actors for streaming workloads. Ring kernels require the RingKernel runtime:

// Ring kernels implement RingKernelHandler<M, R>
// They maintain persistent state in GPU memory and communicate
// via lock-free ring buffers with sub-microsecond latency.
// See architecture/execution-modes.md for setup details.

See Execution Modes for a detailed comparison.

Error Handling

RustKernels uses standard Rust error handling:

use rustkernel_core::error::KernelError;

match kernel.execute(input).await {
    Ok(result) => println!("Success: {:?}", result),
    Err(KernelError::ValidationError(msg)) => {
        eprintln!("Invalid input: {}", msg);
    }
    Err(KernelError::Timeout(duration)) => {
        eprintln!("Timed out after {:?}", duration);
    }
    Err(e) => eprintln!("Error: {}", e),
}

Next Steps

• Architecture Overview — Understand the system design
• Kernel Catalogue — Explore all 106 kernels across 14 domains
• Service Deployment — Deploy as REST/gRPC services
• Accounting Network Generation — Deep-dive article

Architecture Overview

RustKernels is a modular, high-performance GPU kernel library for financial and enterprise workloads. This document describes the system architecture and key design decisions.

System Design

┌─────────────────────────────────────────────────────────────────┐
│                       rustkernels (facade)                       │
│                    Re-exports all domain crates                  │
└─────────────────────────────────────────────────────────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
          ▼                       ▼                       ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│ rustkernel-core │   │rustkernel-derive│   │  rustkernel-cli │
│                 │   │                 │   │                 │
│ - Traits        │   │ - #[gpu_kernel] │   │ - CLI tool      │
│ - Registry      │   │ - #[derive(...)]│   │ - Management    │
│ - K2K messaging │   │                 │   │                 │
│ - Enterprise    │   │                 │   │                 │
│   modules       │   │                 │   │                 │
└─────────────────┘   └─────────────────┘   └─────────────────┘
          │
          ├──────────────────────────────────────┐
          │                                      │
          ▼                                      ▼
┌───────────────────────────────────┐   ┌─────────────────┐
│          14 Domain Crates         │   │   rustkernel-   │
│                                   │   │   ecosystem     │
│  graph │ ml │ compliance │ risk  │   │                 │
│  temporal │ banking │ procint    │   │ - Axum REST     │
│  behavioral │ orderbook │ ...   │   │ - Tower         │
│                                   │   │ - Tonic gRPC    │
│  Each implements domain-specific  │   │ - Actix actors  │
│  kernels using core traits        │   │                 │
└───────────────────────────────────┘   └─────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│                    RingKernel 0.4.2 (crates.io)                  │
│          GPU-native persistent actor runtime framework           │
└─────────────────────────────────────────────────────────────────┘

Workspace Structure

The workspace contains 19 crates organized by concern:

Infrastructure Crates

Domain Crates

14 domain-specific crates, each containing kernels for a particular business area:

crates/
├── rustkernel-graph/        # Graph analytics (28 kernels)
├── rustkernel-ml/           # Statistical ML (17 kernels)
├── rustkernel-compliance/   # AML/KYC (11 kernels)
├── rustkernel-temporal/     # Time series (7 kernels)
├── rustkernel-risk/         # Risk analytics (5 kernels)
├── rustkernel-banking/      # Banking (1 kernel)
├── rustkernel-behavioral/   # Behavioral (6 kernels)
├── rustkernel-orderbook/    # Order matching (1 kernel)
├── rustkernel-procint/      # Process intelligence (7 kernels)
├── rustkernel-clearing/     # Clearing/settlement (5 kernels)
├── rustkernel-treasury/     # Treasury (5 kernels)
├── rustkernel-accounting/   # Accounting (9 kernels)
├── rustkernel-payments/     # Payments (2 kernels)
└── rustkernel-audit/        # Audit (2 kernels)

Core Traits

All kernels are built on a set of core traits defined in rustkernel-core:

GpuKernel

The base trait for all kernels:

pub trait GpuKernel: Send + Sync + Debug {
    /// Returns kernel metadata (ID, domain, mode, performance targets)
    fn metadata(&self) -> &KernelMetadata;

    /// Validates kernel configuration
    fn validate(&self) -> Result<()>;

    /// Health check (enterprise)
    fn health_check(&self) -> HealthStatus { HealthStatus::Healthy }

    /// Graceful shutdown
    async fn shutdown(&self) -> Result<()> { Ok(()) }

    /// Hot-reload configuration
    fn refresh_config(&mut self, config: &KernelConfig) -> Result<()> { Ok(()) }
}

BatchKernel

For CPU-orchestrated batch execution:

pub trait BatchKernel<I, O>: GpuKernel {
    /// Execute the kernel with typed input
    async fn execute(&self, input: I) -> Result<O>;

    /// Execute with auth, tenant, and tracing context
    async fn execute_with_context(&self, ctx: &ExecutionContext, input: I) -> Result<O>;

    /// Validate input before execution
    fn validate_input(&self, input: &I) -> Result<()> { Ok(()) }
}

BatchKernelDyn and TypeErasedBatchKernel

For type-erased execution via REST/gRPC:

/// Dynamic dispatch trait — JSON bytes in, JSON bytes out
pub trait BatchKernelDyn: GpuKernel {
    async fn execute_dyn(&self, input: &[u8]) -> Result<Vec<u8>>;
}

/// Bridges typed BatchKernel<I,O> to BatchKernelDyn via JSON serialization
pub struct TypeErasedBatchKernel<K, I, O> { /* ... */ }

Kernels registered via register_batch_typed() are automatically wrapped in TypeErasedBatchKernel, enabling execution through the ecosystem service layer without compile-time knowledge of input and output types.

RingKernelHandler

For GPU-persistent actor execution:

pub trait RingKernelHandler<M, R>: GpuKernel
where
    M: RingMessage,
    R: RingMessage,
{
    /// Handle a message and produce a response
    async fn handle(&self, ctx: &mut RingContext, msg: M) -> Result<R>;

    /// Handle with security context
    async fn handle_secure(&self, ctx: &mut SecureRingContext, msg: M) -> Result<R>;
}

IterativeKernel

For multi-pass algorithms (PageRank, K-Means, etc.):

pub trait IterativeKernel<S, I, O>: GpuKernel {
    /// Create initial state from input
    fn initial_state(&self, input: &I) -> S;

    /// Perform one iteration
    async fn iterate(&self, state: &mut S, input: &I) -> Result<IterationResult<O>>;

    /// Check convergence
    fn converged(&self, state: &S, threshold: f64) -> bool;
}

Additional Traits

Kernel Registration

The KernelRegistry provides three registration methods:

Example:

pub fn register_all(registry: &KernelRegistry) -> Result<()> {
    // Full execution support — callable via REST/gRPC
    registry.register_batch_typed(BetweennessCentrality::new)?;

    // Metadata-only — discoverable but not directly executable via REST
    registry.register_batch_metadata_from(GraphDensity::new)?;

    // Ring kernel — requires RingKernel runtime
    registry.register_ring_metadata_from(PageRankRing::new)?;

    Ok(())
}

Kernel Metadata

Every kernel carries associated metadata:

pub struct KernelMetadata {
    pub id: String,                  // e.g., "graph/pagerank"
    pub mode: KernelMode,           // Batch or Ring
    pub domain: Domain,             // Business domain
    pub description: String,        // Human-readable description
    pub expected_throughput: u64,    // Operations per second
    pub target_latency_us: f64,     // Target latency in microseconds
    pub requires_gpu_native: bool,  // GPU-only or CPU fallback available
    pub version: u32,               // Kernel implementation version
}

K2K (Kernel-to-Kernel) Messaging

Cross-kernel coordination patterns for complex multi-stage computations:

Example: Iterative Coordination

use rustkernel_core::k2k::IterativeState;

let mut state = IterativeState::new(max_iterations);

while !state.converged() {
    let results = execute_iteration(&mut state).await?;
    state.update(results.delta);
}

Domain Crate Structure

Each domain crate follows a consistent structure:

rustkernel-{domain}/
├── Cargo.toml
└── src/
    ├── lib.rs           # Module exports, register_all()
    ├── messages.rs      # Batch kernel input/output types
    ├── ring_messages.rs # Ring message types with #[derive(RingMessage)]
    ├── types.rs         # Common domain types
    └── {feature}.rs     # Kernel implementations

Example: Graph Analytics Crate

rustkernel-graph/
└── src/
    ├── lib.rs
    ├── messages.rs
    ├── ring_messages.rs
    ├── types.rs
    ├── centrality.rs    # PageRank, Betweenness, Closeness, etc.
    ├── community.rs     # Louvain, Label Propagation
    ├── similarity.rs    # Jaccard, Cosine, Adamic-Adar
    ├── metrics.rs       # Density, Clustering Coefficient
    ├── motif.rs         # Triangle counting, k-cliques
    ├── topology.rs      # Connected components, cycles, paths
    └── gnn.rs           # GNN inference, graph attention

Ring Message Type IDs

Each domain has a reserved range for Ring message type IDs, aligned with ringkernel_core::domain::Domain base offsets (0.4.2):

RingKernel 0.4.2 Integration

RustKernels 0.4.0 deeply integrates with RingKernel 0.4.2:

Domain Conversion

Bidirectional conversion between RustKernels and RingKernel domain types:

use rustkernel_core::domain::Domain;

let domain = Domain::TemporalAnalysis;
let ring_domain = domain.to_ring_domain();  // → ringkernel_core::domain::Domain::TimeSeries
let back = Domain::from_ring_domain(ring_domain);  // → Domain::TemporalAnalysis

Re-exports from RingKernel

Submodule Re-exports

Licensing System

Enterprise licensing in rustkernel-core/src/license.rs:

• DevelopmentLicense: All features enabled (default for local development)
• ProductionLicense: Domain-based feature gating
• Validation occurs at kernel registration and activation time

use rustkernel_core::license::{LicenseValidator, DevelopmentLicense};

let validator = DevelopmentLicense::new();
assert!(validator.is_domain_licensed(Domain::GraphAnalytics));

Fixed-Point Arithmetic

For GPU-compatible exact financial calculations, Ring messages use fixed-point arithmetic:

// 8 decimal places (standard kernels)
fn to_fixed_point(value: f64) -> i64 { (value * 100_000_000.0) as i64 }
fn from_fixed_point(fp: i64) -> f64 { fp as f64 / 100_000_000.0 }

// 18 decimal places (accounting kernels)
const SCALE: i128 = 1_000_000_000_000_000_000;

pub struct FixedPoint128 {
    pub value: i128,
}

Next Steps

• Execution Modes — Deep dive into Batch vs Ring
• Kernel Catalogue — Browse available kernels
• Quick Start — Run your first kernel

Execution Modes

RustKernels supports two execution modes with different performance characteristics. Understanding these modes is essential for choosing the right approach for your workload.

Overview

Batch Mode

Batch mode provides CPU-orchestrated kernel execution. The kernel is launched on-demand, executes on the GPU, and returns results to the CPU.

Characteristics

• Launch overhead: 10-50μs per invocation
• State management: State lives in CPU memory between calls
• Execution model: Synchronous request/response
• Data transfer: Input copied to GPU, output copied back

When to Use Batch Mode

• Heavy computational tasks (matrix operations, large graph processing)
• Periodic batch jobs (nightly risk calculations, weekly reports)
• Tasks where launch overhead is negligible compared to computation time
• When you need to process a complete dataset at once

Implementation

Batch kernels implement the BatchKernel trait:

use rustkernel_core::traits::{GpuKernel, BatchKernel};
use rustkernel_core::kernel::KernelMetadata;

pub struct MyBatchKernel {
    metadata: KernelMetadata,
}

impl GpuKernel for MyBatchKernel {
    fn metadata(&self) -> &KernelMetadata {
        &self.metadata
    }
}

impl BatchKernel<MyInput, MyOutput> for MyBatchKernel {
    async fn execute(&self, input: MyInput) -> Result<MyOutput> {
        // GPU computation here
        Ok(output)
    }
}

Usage Example

use rustkernel::graph::centrality::PageRank;

let kernel = PageRank::new();

// Prepare large graph input
let input = PageRankInput {
    num_nodes: 1_000_000,
    edges: load_edges_from_file()?,
    damping_factor: 0.85,
    max_iterations: 100,
    tolerance: 1e-6,
};

// Execute - may take seconds for large graphs
let result = kernel.execute(input).await?;

println!("Top node: {} with score {:.4}",
    result.top_node(),
    result.scores[result.top_node()]
);

Ring Mode

Ring mode provides GPU-persistent actors. The kernel maintains state on the GPU and processes messages with minimal latency.

Characteristics

• Message latency: 100-500ns per message
• State persistence: State remains on GPU between messages
• Execution model: Asynchronous actor messages
• Data transfer: Only message payloads transferred

When to Use Ring Mode

• High-frequency operations (order matching, real-time scoring)
• Streaming workloads (continuous data feeds)
• When sub-millisecond latency is critical
• Incremental updates to persistent state

Implementation

Ring kernels implement the RingKernelHandler trait:

use rustkernel_core::traits::{GpuKernel, RingKernelHandler};
use rustkernel_core::ring::{RingContext, RingMessage};

pub struct MyRingKernel {
    metadata: KernelMetadata,
}

impl GpuKernel for MyRingKernel {
    fn metadata(&self) -> &KernelMetadata {
        &self.metadata
    }
}

impl RingKernelHandler<MyRequest, MyResponse> for MyRingKernel {
    async fn handle(
        &self,
        ctx: &mut RingContext,
        msg: MyRequest,
    ) -> Result<MyResponse> {
        // Process message, update GPU state
        Ok(response)
    }
}

Ring Message Definition

Ring messages use fixed-point arithmetic and rkyv serialization:

use ringkernel_derive::RingMessage;
use rkyv::{Archive, Serialize, Deserialize};

#[derive(Debug, Clone, Archive, Serialize, Deserialize, RingMessage)]
#[archive(check_bytes)]
#[message(type_id = 200)]  // Unique within domain range
pub struct ScoreQueryRequest {
    #[message(id)]
    pub id: MessageId,
    pub node_id: u32,
}

#[derive(Debug, Clone, Archive, Serialize, Deserialize, RingMessage)]
#[archive(check_bytes)]
#[message(type_id = 201)]
pub struct ScoreQueryResponse {
    #[message(id)]
    pub id: MessageId,
    pub score_fp: i64,  // Fixed-point score
}

Usage Example

use rustkernel::graph::centrality::PageRankRing;

// Create ring kernel (initializes GPU state)
let ring = PageRankRing::new();

// Stream of edge updates
for edge in incoming_edges {
    // Low-latency edge addition
    ring.add_edge(edge.from, edge.to).await?;
}

// Query current scores (sub-millisecond)
let scores = ring.query_scores().await?;

// Trigger re-computation if needed
ring.recalculate().await?;

Choosing Between Modes

Decision Matrix

Hybrid Approach

Many applications combine both modes:

// Batch: Initial heavy computation
let graph_kernel = GraphBuilder::new();
let initial_graph = graph_kernel.build(edges).await?;

// Ring: Real-time updates
let ring_kernel = GraphRing::from(initial_graph);

loop {
    // Process streaming updates with low latency
    let update = receive_update().await;
    ring_kernel.handle(update).await?;

    // Periodically sync state back for batch analysis
    if should_sync() {
        let snapshot = ring_kernel.snapshot().await?;
        batch_analysis(snapshot).await?;
    }
}

Performance Considerations

Batch Mode Optimization

1. Batch your inputs: Process multiple items in one call
2. Minimize data transfer: Only send required fields
3. Use async: Don’t block on kernel completion

// Good: Process many items at once
let results = kernel.execute_batch(items).await?;

// Avoid: Processing one at a time
for item in items {
    let result = kernel.execute(item).await?;  // High overhead
}

Ring Mode Optimization

1. Keep messages small: Only transfer deltas
2. Batch when possible: Group related messages
3. Use K2K for coordination: Avoid CPU round-trips

// Good: Small incremental update
ring.update_score(node_id, delta).await?;

// Avoid: Transferring full state
ring.set_all_scores(full_score_vector).await?;  // Large transfer

Iterative Kernels

Some algorithms naturally span multiple iterations (PageRank, K-Means). These implement IterativeKernel:

pub trait IterativeKernel<S, I, O>: GpuKernel {
    fn initial_state(&self, input: &I) -> S;
    async fn iterate(&self, state: &mut S, input: &I) -> Result<IterationResult<O>>;
    fn converged(&self, state: &S, threshold: f64) -> bool;
}

Usage:

let kernel = PageRank::new();

// Create initial state
let mut state = kernel.initial_state(&input);

// Iterate until convergence
while !kernel.converged(&state, tolerance) {
    let result = kernel.iterate(&mut state, &input).await?;
    println!("Iteration {}: delta={:.6}", result.iteration, result.delta);
}

Next Steps

• Architecture Overview - System design and components
• Kernel Catalogue - Available kernels by domain
• K2K Messaging - Cross-kernel coordination

Security

RustKernels 0.2.0 includes comprehensive enterprise security features for production deployments.

Overview

Authentication

Configure authentication using AuthConfig:

use rustkernel_core::security::{AuthConfig, AuthMethod};

let auth = AuthConfig {
    method: AuthMethod::Jwt {
        secret: "your-jwt-secret".to_string(),
        issuer: Some("rustkernels".to_string()),
        audience: None,
    },
    token_expiry: Duration::from_secs(3600),
    refresh_enabled: true,
};

Supported Methods

• JWT: JSON Web Token validation with configurable issuer/audience
• API Key: Simple API key authentication for service-to-service calls
• None: Disabled authentication (development only)

Role-Based Access Control

Define permissions for kernel operations:

use rustkernel_core::security::{Role, KernelPermission, PermissionSet};

// Built-in roles
let executor = Role::KernelExecutor;  // Can execute kernels
let admin = Role::Admin;              // Full access

// Custom permissions
let permissions = PermissionSet::new()
    .with_permission(KernelPermission::Execute)
    .with_permission(KernelPermission::Monitor)
    .for_domains(vec![Domain::GraphAnalytics, Domain::Compliance]);

Permission Types

Security Context

Pass security context through kernel execution:

use rustkernel_core::security::SecurityContext;

let ctx = SecurityContext::new(user_id, tenant_id)
    .with_roles(vec![Role::KernelExecutor])
    .with_permissions(vec![KernelPermission::Execute]);

// Execute with context
kernel.execute_with_context(&ctx, input).await?;

Multi-Tenancy

Isolate kernels and resources by tenant:

use rustkernel_core::security::{TenantId, TenantConfig};

let tenant = TenantConfig {
    id: TenantId::new("tenant-123"),
    name: "Acme Corp".to_string(),
    max_kernel_instances: 100,
    max_memory_bytes: 8 * 1024 * 1024 * 1024, // 8GB
    allowed_domains: vec![Domain::GraphAnalytics, Domain::Compliance],
};

Secrets Management

Integrate with external secret stores:

use rustkernel_core::security::{SecretStore, SecretRef};

// Reference a secret
let api_key = SecretRef::new("external-api-key");

// Retrieve at runtime
let value = secret_store.get(&api_key).await?;

Production Configuration

Enable security in production:

use rustkernel_core::config::ProductionConfig;

let config = ProductionConfig::production();
// Security is enabled by default in production preset:
// - RBAC enabled
// - Audit logging enabled
// - Multi-tenancy infrastructure ready

config.validate()?; // Warns if security is weak

Environment Variables

Best Practices

1. Always enable auth in production: Use ProductionConfig::production()
2. Principle of least privilege: Grant minimum required permissions
3. Rotate secrets regularly: Use external secret management
4. Enable audit logging: Track all security events
5. Validate tenant boundaries: Test multi-tenant isolation

Next Steps

• Observability - Monitor security events
• Runtime - Configure production runtime

Observability

RustKernels 0.2.0 provides comprehensive observability for production monitoring.

Overview

Metrics

Configuration

use rustkernel_core::observability::{MetricsConfig, ObservabilityConfig};

let config = ObservabilityConfig::production()
    .with_metrics(MetricsConfig {
        enabled: true,
        endpoint: "/metrics".to_string(),
        include_runtime: true,
        include_kernel_stats: true,
        histogram_buckets: vec![0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1.0],
    });

Available Metrics

Custom Metrics

use rustkernel_core::observability::KernelMetrics;

let metrics = KernelMetrics::new("my-kernel");
metrics.record_execution(Duration::from_micros(150));
metrics.record_memory_allocated(1024 * 1024);

Distributed Tracing

OTLP Export

use rustkernel_core::observability::{TracingConfig, OtlpConfig};

let config = TracingConfig {
    enabled: true,
    sampling_rate: 0.1, // Sample 10% of requests
    otlp: Some(OtlpConfig {
        endpoint: "http://localhost:4317".to_string(),
        ..Default::default()
    }),
};

Kernel Spans

Traces are automatically created for kernel executions:

[kernel:graph/pagerank] 15.2ms
├── [validate] 0.1ms
├── [prepare_input] 2.1ms
├── [gpu_execute] 12.5ms
└── [collect_output] 0.5ms

Context Propagation

Trace context propagates through K2K messages:

use rustkernel_core::observability::TraceContext;

// Context automatically propagated
let result = kernel_a.execute_with_context(&ctx, input).await?;
// Child kernel inherits trace context

Structured Logging

Configuration

use rustkernel_core::observability::{LoggingConfig, LogLevel};

let config = LoggingConfig {
    level: LogLevel::Info,
    format: LogFormat::Json,
    include_kernel_context: true,
    per_domain_levels: vec![
        (Domain::Compliance, LogLevel::Debug), // More verbose for compliance
    ],
};

Log Output

{
  "timestamp": "2026-01-19T10:30:00Z",
  "level": "INFO",
  "message": "Kernel execution complete",
  "kernel_id": "graph/pagerank",
  "domain": "GraphAnalytics",
  "duration_ms": 15.2,
  "trace_id": "abc123",
  "tenant_id": "tenant-456"
}

Alerting

Alert Rules

use rustkernel_core::observability::{AlertRule, AlertSeverity, AlertCondition};

let rule = AlertRule {
    name: "high_latency".to_string(),
    condition: AlertCondition::LatencyExceeds {
        threshold: Duration::from_millis(100),
        percentile: 95,
    },
    severity: AlertSeverity::Warning,
    for_duration: Duration::from_secs(60),
};

Notification Channels

use rustkernel_core::observability::{AlertChannel, SlackConfig};

let channels = vec![
    AlertChannel::Slack(SlackConfig {
        webhook_url: "https://hooks.slack.com/...".to_string(),
        channel: Some("#alerts".to_string()),
    }),
    AlertChannel::PagerDuty(PagerDutyConfig {
        service_key: "...".to_string(),
    }),
];

SLO Monitoring

use rustkernel_core::slo::{SLOValidator, SLOTarget};

let slo = SLOTarget {
    latency_p99: Duration::from_millis(50),
    availability: 0.999,
    error_rate: 0.001,
};

let validator = SLOValidator::new(slo);
let result = validator.check(&metrics)?;
if !result.compliant {
    alert_slo_breach(&result);
}

Production Setup

Prometheus Integration

# prometheus.yml
scrape_configs:
  - job_name: 'rustkernels'
    static_configs:
      - targets: ['localhost:8080']
    metrics_path: '/metrics'

Grafana Dashboard

Import the provided dashboard for:

• Kernel execution rates
• Latency percentiles
• Memory usage
• Circuit breaker states
• Error rates by domain

Environment Variables

Next Steps

• Resilience - Monitor circuit breaker health
• Runtime - Configure health endpoints

Resilience

RustKernels 0.2.0 includes production-grade resilience patterns for fault-tolerant deployments.

Overview

Circuit Breaker

Protect kernels from repeated failures:

use rustkernel_core::resilience::{CircuitBreaker, CircuitBreakerConfig};

let config = CircuitBreakerConfig {
    failure_threshold: 5,      // Open after 5 failures
    success_threshold: 2,      // Close after 2 successes
    timeout: Duration::from_secs(30), // Half-open after 30s
    ..Default::default()
};

let cb = CircuitBreaker::new(config);

// Execute with protection
match cb.call(|| kernel.execute(input)).await {
    Ok(result) => handle_result(result),
    Err(ResilienceError::CircuitOpen) => use_fallback(),
    Err(e) => handle_error(e),
}

Circuit States

Monitoring

let state = cb.state();
let stats = cb.stats();

println!("State: {:?}", state);
println!("Failures: {}", stats.failure_count);
println!("Success rate: {:.1}%", stats.success_rate * 100.0);

Retry with Backoff

Automatically retry transient failures:

use rustkernel_core::resilience::{RetryConfig, BackoffStrategy};

let config = RetryConfig {
    max_attempts: 3,
    backoff: BackoffStrategy::ExponentialWithJitter {
        initial: Duration::from_millis(100),
        max: Duration::from_secs(10),
        multiplier: 2.0,
    },
    retryable_errors: vec![ErrorKind::Transient, ErrorKind::Timeout],
};

let result = config.execute(|| kernel.execute(input)).await?;

Backoff Strategies

Timeout and Deadlines

Per-Kernel Timeouts

use rustkernel_core::resilience::TimeoutConfig;

let config = TimeoutConfig {
    default_timeout: Duration::from_secs(30),
    max_timeout: Duration::from_secs(300),
    propagate_deadline: true,
    include_queue_time: true,
};

Deadline Context

Propagate deadlines through K2K chains:

use rustkernel_core::resilience::DeadlineContext;

let deadline = DeadlineContext::new(Duration::from_secs(10));

// Check remaining time
if deadline.remaining() < Duration::from_secs(1) {
    return Err(DeadlineExceeded);
}

// Execute with deadline
let result = deadline.execute(|| kernel.execute(input)).await?;

// Create child deadline for downstream calls
let child = deadline.child_with_timeout(Duration::from_secs(5));

Health Checks

Health Probe Configuration

use rustkernel_core::resilience::{HealthProbe, HealthProbeConfig};

let probe = HealthProbe::new(HealthProbeConfig {
    interval: Duration::from_secs(10),
    timeout: Duration::from_secs(5),
    failure_threshold: 3,
    success_threshold: 1,
});

// Register kernel for monitoring
probe.register("graph/pagerank", kernel.clone());

// Get health status
let status = probe.check("graph/pagerank").await;

Health Status

use rustkernel_core::resilience::{HealthCheckResult, HealthStatus};

let result = HealthCheckResult::healthy();
let result = HealthCheckResult::degraded("High latency");
let result = HealthCheckResult::unhealthy("GPU unavailable");

// Check status
if result.status == HealthStatus::Unhealthy {
    take_kernel_offline();
}

Kubernetes Probes

// Liveness: Is the service alive?
app.route("/health/live", get(|| async { "OK" }));

// Readiness: Can the service handle traffic?
app.route("/health/ready", get(|| async {
    if all_kernels_ready() { "OK" } else { StatusCode::SERVICE_UNAVAILABLE }
}));

// Startup: Has the service finished initializing?
app.route("/health/startup", get(|| async {
    if initialization_complete() { "OK" } else { StatusCode::SERVICE_UNAVAILABLE }
}));

Recovery Policies

Recovery Strategies

use rustkernel_core::resilience::{RecoveryPolicy, RecoveryStrategy};

let policy = RecoveryPolicy {
    strategy: RecoveryStrategy::RestartKernel,
    max_restarts: 3,
    restart_delay: Duration::from_secs(5),
    escalation: Some(RecoveryStrategy::NotifyOperator),
};

Checkpointing

For long-running kernels, implement checkpointing:

use rustkernel_core::traits::CheckpointableKernel;

impl CheckpointableKernel for MyKernel {
    type Checkpoint = MyCheckpoint;

    async fn checkpoint(&self) -> Result<Self::Checkpoint> {
        Ok(MyCheckpoint { state: self.state.clone() })
    }

    async fn restore(&mut self, checkpoint: Self::Checkpoint) -> Result<()> {
        self.state = checkpoint.state;
        Ok(())
    }
}

Production Configuration

use rustkernel_core::resilience::ResilienceConfig;

// Production preset with sensible defaults
let config = ResilienceConfig::production();

// Customize
let config = ResilienceConfig {
    circuit_breaker: CircuitBreakerConfig::production(),
    retry: RetryConfig::production(),
    timeout: TimeoutConfig::production(),
    health_check: HealthCheckConfig::production(),
    ..Default::default()
};

CLI Commands

# Check health status
rustkernel health

# JSON output for monitoring
rustkernel health --format json

# Check specific component
rustkernel health --component runtime

Next Steps

• Runtime - Lifecycle management
• Observability - Monitor resilience metrics

Runtime

RustKernels 0.2.0 provides comprehensive runtime lifecycle management for production deployments.

Overview

Lifecycle States

┌──────────┐    start()    ┌─────────┐
│ Starting │ ────────────▶ │ Running │
└──────────┘               └────┬────┘
                                │ shutdown()
                                ▼
                          ┌──────────┐    drain complete    ┌─────────┐
                          │ Draining │ ──────────────────▶  │ Stopped │
                          └──────────┘                      └─────────┘

State Descriptions

Runtime Configuration

Presets

use rustkernel_core::runtime::{RuntimeConfig, RuntimePreset};

// Development: relaxed timeouts, verbose logging
let config = RuntimeConfig::development();

// Production: optimized for reliability
let config = RuntimeConfig::production();

// High-performance: maximum throughput
let config = RuntimeConfig::high_performance();

Custom Configuration

let config = RuntimeConfig {
    gpu_enabled: true,
    max_kernel_instances: 100,
    worker_threads: 8,
    blocking_threads: 32,
    shutdown_timeout: Duration::from_secs(30),
    health_check_interval: Duration::from_secs(10),
    ..Default::default()
};

Configuration Fields

Runtime Builder

use rustkernel_core::runtime::RuntimeBuilder;

let runtime = RuntimeBuilder::new()
    .preset(RuntimePreset::Production)
    .with_max_instances(500)
    .with_shutdown_timeout(Duration::from_secs(60))
    .with_health_check_interval(Duration::from_secs(5))
    .build()?;

// Start the runtime
runtime.start().await?;

// Graceful shutdown
runtime.shutdown().await?;

Graceful Shutdown

Handle shutdown signals properly:

use tokio::signal;

// Wait for shutdown signal
let ctrl_c = async {
    signal::ctrl_c().await.expect("failed to listen for ctrl+c");
};

tokio::select! {
    _ = ctrl_c => {
        println!("Shutdown signal received");
        runtime.shutdown().await?;
    }
    _ = server.run() => {}
}

Drain Period

During draining:

1. New requests are rejected with 503 Service Unavailable
2. In-flight requests are allowed to complete
3. Health probes return “not ready”
4. After timeout, remaining requests are cancelled

Memory Management

Memory Configuration

use rustkernel_core::memory::MemoryConfig;

let config = MemoryConfig {
    max_gpu_memory: 8 * 1024 * 1024 * 1024, // 8GB
    max_staging_memory: 2 * 1024 * 1024 * 1024, // 2GB
    pooling_enabled: true,
    pressure_threshold: 0.8, // Warn at 80% usage
    auto_defrag: true,
    ..Default::default()
};

Memory Pressure Levels

Size-Stratified Pooling

use rustkernel_core::memory::KernelMemoryManager;

let manager = KernelMemoryManager::new(config);

// Allocate from pool
let buffer = manager.allocate(1024 * 1024)?; // 1MB

// Return to pool
manager.deallocate(buffer);

// Check stats
let stats = manager.stats();
println!("Allocated: {} bytes", stats.allocated_bytes);
println!("Pool utilization: {:.1}%", stats.pool_utilization * 100.0);

Production Configuration

Unified Config

use rustkernel_core::config::{ProductionConfig, ProductionConfigBuilder};

// Load from environment
let config = ProductionConfig::from_env()?;

// Load from file
let config = ProductionConfig::from_file("config/production.toml")?;

// Use builder
let config = ProductionConfigBuilder::production()
    .service_name("my-kernel-service")
    .environment("production")
    .runtime(|r| r
        .max_kernel_instances(500)
        .shutdown_timeout(Duration::from_secs(60)))
    .memory(|m| m
        .max_gpu_memory(16 * 1024 * 1024 * 1024))
    .build()?;

// Validate
config.validate()?;

TOML Configuration

# production.toml
environment = "production"
service_name = "rustkernels"
service_version = "0.2.0"

[runtime]
gpu_enabled = true
max_kernel_instances = 500
worker_threads = 16
shutdown_timeout_secs = 60

[memory]
max_gpu_memory = 17179869184  # 16GB
max_staging_memory = 4294967296  # 4GB
pooling_enabled = true
pressure_threshold = 0.8

[security]
rbac_enabled = true
audit_logging = true

[observability]
metrics_enabled = true
tracing_enabled = true

CLI Commands

# Show runtime status
rustkernel runtime status

# Show current configuration
rustkernel runtime show

# Initialize with preset
rustkernel runtime init --preset production

# Generate config template
rustkernel config generate --preset production --output config.toml

# Validate config file
rustkernel config validate config.toml

# Show environment variables
rustkernel config env

Environment Variables

Next Steps

• Service Deployment - Deploy as a service
• Observability - Monitor runtime metrics

Service Deployment

RustKernels 0.4.0 includes the rustkernel-ecosystem crate for deploying kernels as production services. All service integrations perform real kernel execution — requests are routed through the KernelRegistry, dispatched to type-erased BatchKernelDyn implementations, and return actual computation results.

Overview

Ring kernels are discoverable through metadata endpoints but require the RingKernel persistent actor runtime for execution. REST/gRPC endpoints return an informative error (HTTP 422 / gRPC UNIMPLEMENTED) with guidance to use the Ring protocol.

Installation

[dependencies]
rustkernel-ecosystem = { version = "0.4.0", features = ["axum", "grpc"] }

Feature Flags

How Execution Works

All four integrations follow the same execution path:

1. Registry lookup — Find the kernel by ID in the KernelRegistry
2. Mode check — Verify the kernel is a Batch kernel (Ring kernels return an error)
3. Factory create — Instantiate the kernel via its registered factory closure
4. JSON serialize — Serialize the request input to JSON bytes
5. Type-erased dispatch — Call execute_dyn(&input_bytes) on the BatchKernelDyn trait object
6. Deserialize response — Convert the output bytes back to a JSON response

The TypeErasedBatchKernel<K, I, O> wrapper bridges the typed BatchKernel<I, O> interface to the type-erased BatchKernelDyn trait using serde JSON serialization.

Axum REST API

Quick Start

use rustkernel_ecosystem::axum::{KernelRouter, RouterConfig};
use rustkernel_core::registry::KernelRegistry;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    // Create and populate registry
    let registry = Arc::new(KernelRegistry::new());
    rustkernels::register_all(&registry).unwrap();

    // Build router — all endpoints perform real kernel execution
    let router = KernelRouter::new(registry, RouterConfig::default());
    let app = router.into_router();

    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}

Endpoints

Execute Request

curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{
    "kernel_id": "graph/betweenness-centrality",
    "input": {
      "num_nodes": 4,
      "edges": [[0, 1], [1, 2], [2, 3], [0, 3]],
      "normalized": true
    }
  }'

Response

{
  "request_id": "req-abc123",
  "kernel_id": "graph/betweenness-centrality",
  "output": {
    "scores": [0.3333, 0.6667, 0.6667, 0.3333]
  },
  "metadata": {
    "duration_us": 850,
    "backend": "CPU"
  }
}

Health Check

The health endpoint aggregates component status:

{
  "status": "healthy",
  "components": {
    "registry": { "status": "healthy", "kernel_count": 106 },
    "execution": { "status": "healthy", "error_rate": 0.0 }
  }
}

Custom Configuration

let config = RouterConfig {
    prefix: "/api/v1".to_string(),
    enable_metrics: true,
    enable_health: true,
    cors_enabled: true,
    max_request_size: 10 * 1024 * 1024, // 10 MB
};

Tower Middleware

Kernel Service

use rustkernel_ecosystem::tower::KernelService;
use tower::ServiceExt;

let service = KernelService::new(registry);

// Execute via Tower Service trait — dispatches to real kernels
let response = service
    .ready()
    .await?
    .call(request)
    .await?;

Timeout Layer

use rustkernel_ecosystem::tower::TimeoutLayer;

let layer = TimeoutLayer::new(Duration::from_secs(30));
let service = ServiceBuilder::new()
    .layer(layer)
    .service(kernel_service);

Rate Limiting

use rustkernel_ecosystem::tower::RateLimiterLayer;

let layer = RateLimiterLayer::new(
    100,  // requests per second
    Duration::from_secs(1),
);

Middleware Stack

use tower::ServiceBuilder;

let service = ServiceBuilder::new()
    .layer(TimeoutLayer::new(Duration::from_secs(30)))
    .layer(RateLimiterLayer::new(100, Duration::from_secs(1)))
    .layer(TracingLayer::new())
    .service(KernelService::new(registry));

gRPC Server

Server Setup

use rustkernel_ecosystem::grpc::KernelGrpcServer;
use tonic::transport::Server;

let server = KernelGrpcServer::new(registry);

Server::builder()
    .add_service(server.into_service())
    .serve("[::1]:50051".parse().unwrap())
    .await?;

gRPC execution includes deadline support — if the client sets a gRPC deadline, the server applies it as a timeout around kernel execution. Exceeded deadlines return DEADLINE_EXCEEDED.

Client Usage

let mut client = KernelClient::connect("http://[::1]:50051").await?;

let request = tonic::Request::new(ExecuteRequest {
    kernel_id: "graph/betweenness-centrality".to_string(),
    input: serde_json::to_string(&input)?,
});

let response = client.execute(request).await?;

Health Service

use rustkernel_ecosystem::grpc::HealthService;

Server::builder()
    .add_service(HealthService::new())
    .add_service(kernel_server.into_service())
    .serve(addr)
    .await?;

Actix Actors

Kernel Actor

use rustkernel_ecosystem::actix::{KernelActor, KernelActorConfig, ExecuteKernel};
use actix::prelude::*;

let config = KernelActorConfig {
    name: "kernel-worker".to_string(),
    mailbox_capacity: 1000,
    default_timeout: Duration::from_secs(30),
    ..Default::default()
};

let actor = KernelActor::new(registry, config);
let addr = actor.start();

// Execute — dispatches to real batch kernel
let result = addr.send(ExecuteKernel {
    kernel_id: "graph/betweenness-centrality".to_string(),
    input: serde_json::json!({
        "num_nodes": 4,
        "edges": [[0, 1], [1, 2], [2, 3]],
        "normalized": true
    }),
    metadata: Default::default(),
}).await??;

Actor Supervisor

use rustkernel_ecosystem::actix::KernelActorSupervisor;

let mut supervisor = KernelActorSupervisor::new(registry);

for i in 0..num_workers {
    supervisor.spawn(KernelActorConfig {
        name: format!("worker-{}", i),
        ..Default::default()
    });
}

let workers = supervisor.actors();

Messages

Docker Deployment

Dockerfile

FROM rust:1.85 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --package rustkernel-ecosystem --features full

FROM debian:bookworm-slim
COPY --from=builder /app/target/release/rustkernel-server /usr/local/bin/
EXPOSE 8080 50051
CMD ["rustkernel-server"]

docker-compose.yml

version: '3.8'
services:
  rustkernels:
    build: .
    ports:
      - "8080:8080"   # REST API
      - "50051:50051" # gRPC
    environment:
      - RUSTKERNEL_ENV=production
      - RUSTKERNEL_GPU_ENABLED=true
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rustkernels
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: rustkernels
        image: rustkernels:0.4.0
        ports:
        - containerPort: 8080
        - containerPort: 50051
        env:
        - name: RUSTKERNEL_ENV
          value: "production"
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8080
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8080
        resources:
          limits:
            nvidia.com/gpu: 1

Next Steps

• Security — Secure your deployment
• Observability — Monitor service health
• Runtime — Configure for production

Kernel Catalogue

RustKernels provides 106 GPU-accelerated kernels across 14 domain-specific crates. This catalogue organizes kernels by business domain.

Quick Reference

Execution Support

Kernels fall into three registration categories based on their trait implementations:

Fully Executable (via REST/gRPC)

Kernels implementing BatchKernel<I, O> are registered with register_batch_typed() and can be executed through the type-erased BatchKernelDyn interface used by REST and gRPC endpoints.

Examples: BetweennessCentrality, KMeans, DBSCAN, KYCScoring, ARIMAForecast, StressTesting

Metadata-Only (Batch)

Kernels implementing GpuKernel only are registered with register_batch_metadata_from(). They are discoverable through metadata endpoints but require direct Rust API calls for execution.

Examples: GraphDensity, LouvainCommunity, IsolationForest, AMLPatternDetection

Ring Kernels

Ring kernels are registered with register_ring_metadata_from(). They require the RingKernel persistent actor runtime for execution and communicate via lock-free ring buffers.

Examples: PageRankRing, DegreeCentralityRing, OrderMatchingRing, NetworkGenerationRing

Using the Catalogue

Each domain page includes:

1. Domain Overview — Purpose and key use cases
2. Kernel List — All kernels with brief descriptions
3. Kernel Details — For each kernel:
   • Kernel ID and execution mode
   • Input/output types
   • Usage examples
   • Performance characteristics

Feature Flags

Enable specific domains via Cargo features:

# Default domains (graph, ml, compliance, temporal, risk)
rustkernels = "0.4.0"

# Selective
rustkernels = { version = "0.4.0", features = ["accounting", "treasury"] }

# All domains
rustkernels = { version = "0.4.0", features = ["full"] }

Kernel ID Convention

Kernel IDs follow the pattern {domain}/{kernel-name}:

graph/pagerank
ml/kmeans
compliance/aml-pattern-detection
risk/monte-carlo-var
accounting/network-generation

This enables hierarchical organization and clear domain ownership.

Graph Analytics

Crate: rustkernel-graph Kernels: 28 Feature: graph (included in default features)

Graph analytics kernels for network analysis, social network analysis, knowledge graph operations, and AML/fraud detection.

Kernel Overview

Centrality Measures (6)

Community Detection (3)

Similarity Measures (5)

Graph Metrics (5)

Motif Detection (3)

Topology Analysis (2)

Cycle Detection (1)

Path Analysis (1)

Graph Neural Networks (2)

Kernel Details

PageRank

The PageRank algorithm computes the importance of nodes based on link structure.

ID: graph/pagerank Modes: Batch, Ring Throughput: ~100,000 nodes/sec Latency: 50μs (Batch), 500ns (Ring)

Input

pub struct PageRankInput {
    /// Number of nodes in the graph
    pub num_nodes: u32,
    /// Edges as (from, to) pairs
    pub edges: Vec<(u32, u32)>,
    /// Damping factor (typically 0.85)
    pub damping_factor: f64,
    /// Maximum iterations
    pub max_iterations: u32,
    /// Convergence tolerance
    pub tolerance: f64,
}

Output

pub struct PageRankOutput {
    /// PageRank scores indexed by node ID
    pub scores: Vec<f64>,
    /// Number of iterations performed
    pub iterations: u32,
    /// Final delta (convergence measure)
    pub delta: f64,
}

Example

use rustkernel::graph::centrality::{PageRank, PageRankInput};

let kernel = PageRank::new();

let input = PageRankInput {
    num_nodes: 4,
    edges: vec![(0, 1), (0, 2), (1, 2), (2, 0), (2, 3), (3, 0)],
    damping_factor: 0.85,
    max_iterations: 100,
    tolerance: 1e-6,
};

let result = kernel.execute(input).await?;
println!("Top node: {}", result.top_node());

LouvainCommunity

Detects communities using the Louvain method for modularity optimization.

ID: graph/louvain-community Modes: Batch, Ring Throughput: ~50,000 nodes/sec

Input

pub struct LouvainInput {
    pub num_nodes: u32,
    pub edges: Vec<(u32, u32)>,
    /// Resolution parameter (1.0 = standard modularity)
    pub resolution: f64,
}

Output

pub struct LouvainOutput {
    /// Community assignment per node
    pub communities: Vec<u32>,
    /// Number of communities found
    pub num_communities: u32,
    /// Final modularity score
    pub modularity: f64,
}

TriangleCounting

Counts triangles in the graph, useful for clustering coefficient and network density analysis.

ID: graph/triangle-counting Modes: Batch, Ring

Example

use rustkernel::graph::motif::{TriangleCounting, TriangleInput};

let kernel = TriangleCounting::new();
let result = kernel.execute(TriangleInput {
    num_nodes: 100,
    edges: edges,
}).await?;

println!("Triangles: {}", result.triangle_count);
println!("Clustering coefficient: {:.4}", result.global_clustering);

ShortCycleParticipation

Detects participation in short cycles (2-4 hops) which are key indicators for AML.

ID: graph/cycle-participation Modes: Batch Throughput: ~25,000 nodes/sec

Short cycles are critical AML indicators:

• 2-cycles (reciprocal): Immediate return transactions
• 3-cycles (triangles): Layering patterns - HIGH AML risk
• 4-cycles (squares): Organized laundering - CRITICAL AML risk

Example

use rustkernel::graph::cycles::{ShortCycleParticipation, CycleRiskLevel};

let kernel = ShortCycleParticipation::new();
let results = kernel.compute_all(&graph);

// Find high-risk nodes
for result in &results {
    if matches!(result.risk_level, CycleRiskLevel::High | CycleRiskLevel::Critical) {
        println!("HIGH RISK: Node {} participates in {} 4-cycles",
                 result.node_index, result.cycle_count_4hop);
    }
}

// Count triangles in the graph
let triangles = ShortCycleParticipation::count_triangles(&graph);

DegreeRatio

Calculates in-degree/out-degree ratio for node classification.

ID: graph/degree-ratio Modes: Ring Latency: ~300ns per query

Classifies nodes as:

• Source: Mostly outgoing edges (payment originators)
• Sink: Mostly incoming edges (collection accounts)
• Balanced: Equal in/out (intermediary accounts)

Example

use rustkernel::graph::topology::{DegreeRatio, NodeClassification};

let results = DegreeRatio::compute_batch(&graph);
let roles = DegreeRatio::classify_nodes(&graph);

println!("Sources: {:?}", roles.sources);
println!("Sinks: {:?}", roles.sinks);

StarTopologyScore

Detects hub-and-spoke patterns for smurfing and money mule detection.

ID: graph/star-topology Modes: Batch Throughput: ~20,000 nodes/sec

Star types:

• In-Star: Collection pattern (many payers to one receiver)
• Out-Star: Distribution pattern (smurfing indicator)
• Mixed: Money mule hub

Example

use rustkernel::graph::topology::{StarTopologyScore, StarType};

let kernel = StarTopologyScore::with_min_degree(10);
let hubs = kernel.top_k_hubs(&graph, 10);

// Find potential smurfing accounts (out-stars)
let out_stars = kernel.find_out_stars(&graph, 0.8);
for hub in out_stars {
    println!("POTENTIAL SMURFING: Node {} with score {:.2}",
             hub.node_index, hub.star_score);
}

ShortestPath

Computes shortest paths using BFS or Delta-Stepping algorithm.

ID: graph/shortest-path Modes: Batch Throughput: ~50,000 nodes/sec

Supports:

• Single-source shortest path (SSSP)
• All-pairs shortest path (APSP)
• K-shortest paths (Yen’s algorithm)

Example

use rustkernel::graph::paths::ShortestPath;

// Single-source shortest path
let sssp = ShortestPath::compute_sssp_bfs(&graph, source);
println!("Distance to target: {}", sssp[target].distance);

// Reconstruct path
if let Some(path) = ShortestPath::compute_path(&graph, source, target) {
    println!("Path: {:?}", path.node_path);
}

// Graph diameter
let diameter = ShortestPath::compute_diameter(&graph);

ValueSimilarity

Compares node value distributions using statistical distance metrics.

ID: graph/value-similarity Modes: Batch Throughput: ~25,000 pairs/sec

Metrics:

• Jensen-Shannon Divergence (JSD): Symmetric KL divergence
• Wasserstein Distance: Earth Mover’s Distance

Example

use rustkernel::graph::similarity::{ValueSimilarity, ValueDistribution};

// Create distributions from transaction amounts
let dist = ValueDistribution::from_values(&node_amounts, 50);

// Find similar nodes using JSD
let pairs = ValueSimilarity::compute_all_pairs_jsd(&dist, 0.9, 100);
for pair in &pairs {
    println!("Similar: {} and {} (similarity: {:.3})",
             pair.node_a, pair.node_b, pair.similarity);
}

GNNInference

Graph Neural Network inference using message passing.

ID: graph/gnn-inference Modes: Batch Throughput: ~10,000 nodes/sec

Supports configurable aggregation functions (mean, sum, max) and multiple message passing iterations.

Example

use rustkernel::graph::gnn::{GNNInference, GNNConfig, AggregationType};

let kernel = GNNInference::new();

// Configure the GNN
let config = GNNConfig {
    hidden_dim: 64,
    output_dim: 32,
    num_layers: 2,
    aggregation: AggregationType::Mean,
    activation: ActivationType::ReLU,
};

// Run inference
let node_embeddings = kernel.infer(&graph, &node_features, &config)?;
println!("Node 0 embedding: {:?}", node_embeddings[0]);

GraphAttention

Multi-head graph attention network for node classification and link prediction.

ID: graph/graph-attention Modes: Batch Throughput: ~8,000 nodes/sec

Uses self-attention to learn importance weights for neighboring nodes.

Example

use rustkernel::graph::gnn::{GraphAttention, AttentionConfig};

let kernel = GraphAttention::new();

let config = AttentionConfig {
    num_heads: 4,
    hidden_dim: 64,
    output_dim: 32,
    dropout: 0.1,
    concat_heads: true,
};

let output = kernel.forward(&graph, &node_features, &config)?;
println!("Attention weights: {:?}", output.attention_weights);

Ring Mode Usage

For high-frequency graph updates, use Ring mode:

use rustkernel::graph::centrality::PageRankRing;

let ring = PageRankRing::new();

// Add edges with low latency
ring.add_edge(0, 1).await?;
ring.add_edge(1, 2).await?;

// Query current scores
let score = ring.query_score(0).await?;

// Trigger recalculation
ring.recalculate().await?;

Performance Tips

1. Use CSR format: For large static graphs, convert to CSR before processing
2. Batch edge updates: When using Ring mode, batch multiple edges when possible
3. Choose appropriate algorithms: BetweennessCentrality is O(V*E), consider sampling for large graphs
4. Leverage GPU: Ensure CUDA is available for maximum throughput

Statistical ML

Crate: rustkernel-ml Kernels: 17 Feature: ml (included in default features)

Machine learning kernels for clustering, anomaly detection, NLP, federated learning, and healthcare analytics.

Kernel Overview

Clustering (3)

Anomaly Detection (3)

Regression (2)

NLP / Embeddings (2)

Federated Learning (1)

Healthcare Analytics (2)

Streaming ML (2)

Explainability (2)

Kernel Details

KMeans

Partitions data into K clusters using the K-means++ initialization.

ID: ml/kmeans Modes: Batch, Ring Throughput: ~500,000 points/sec

Input

pub struct KMeansInput {
    /// Data points as flattened array
    pub points: Vec<f64>,
    /// Number of dimensions per point
    pub dimensions: u32,
    /// Number of clusters
    pub k: u32,
    /// Maximum iterations
    pub max_iterations: u32,
    /// Convergence tolerance
    pub tolerance: f64,
}

Output

pub struct KMeansOutput {
    /// Cluster assignment per point
    pub assignments: Vec<u32>,
    /// Centroids (k * dimensions)
    pub centroids: Vec<f64>,
    /// Iterations performed
    pub iterations: u32,
    /// Inertia (sum of squared distances)
    pub inertia: f64,
}

Example

use rustkernel::ml::clustering::{KMeans, KMeansInput};

let kernel = KMeans::new();

let input = KMeansInput {
    points: vec![
        1.0, 2.0,  // Point 0
        1.5, 1.8,  // Point 1
        5.0, 8.0,  // Point 2
        6.0, 9.0,  // Point 3
    ],
    dimensions: 2,
    k: 2,
    max_iterations: 100,
    tolerance: 1e-4,
};

let result = kernel.execute(input).await?;
println!("Clusters: {:?}", result.assignments);

IsolationForest

Detects anomalies by isolating observations using random forests.

ID: ml/isolation-forest Modes: Batch

Input

pub struct IsolationForestInput {
    pub points: Vec<f64>,
    pub dimensions: u32,
    /// Number of trees
    pub n_estimators: u32,
    /// Subsample size
    pub max_samples: u32,
    /// Contamination ratio (expected anomaly rate)
    pub contamination: f64,
}

Output

pub struct IsolationForestOutput {
    /// Anomaly scores (higher = more anomalous)
    pub scores: Vec<f64>,
    /// Binary labels (-1 = anomaly, 1 = normal)
    pub labels: Vec<i32>,
}

LocalOutlierFactor

Measures local density deviation to identify outliers.

ID: ml/local-outlier-factor Modes: Batch, Ring

Example

use rustkernel::ml::anomaly::{LocalOutlierFactor, LOFInput};

let kernel = LocalOutlierFactor::new();

let result = kernel.execute(LOFInput {
    points: data_points,
    dimensions: 3,
    k_neighbors: 20,
}).await?;

// Scores > 1.0 indicate outliers
let outliers: Vec<usize> = result.scores
    .iter()
    .enumerate()
    .filter(|(_, &s)| s > 1.5)
    .map(|(i, _)| i)
    .collect();

LinearRegression

Fits a linear model using ordinary least squares.

ID: ml/linear-regression Modes: Batch, Ring

Input

pub struct LinearRegressionInput {
    /// Feature matrix (n_samples * n_features)
    pub features: Vec<f64>,
    /// Target values (n_samples)
    pub targets: Vec<f64>,
    /// Number of features
    pub n_features: u32,
    /// Whether to fit intercept
    pub fit_intercept: bool,
}

Output

pub struct LinearRegressionOutput {
    /// Coefficients (n_features, or n_features + 1 with intercept)
    pub coefficients: Vec<f64>,
    /// Intercept (if fit_intercept = true)
    pub intercept: f64,
    /// R-squared score
    pub r_squared: f64,
}

EmbeddingGeneration

Generates text embeddings from documents using TF-IDF and n-gram features.

ID: ml/embedding-generation Modes: Batch

Example

use rustkernel::ml::nlp::{EmbeddingGeneration, EmbeddingConfig};

let kernel = EmbeddingGeneration::new();

let config = EmbeddingConfig {
    embedding_dim: 128,
    ngram_range: (1, 2),
    max_features: 10000,
    use_idf: true,
};

let documents = vec!["financial transaction", "bank transfer"];
let embeddings = kernel.generate(&documents, &config)?;

SemanticSimilarity

Computes cosine similarity between document embeddings.

ID: ml/semantic-similarity Modes: Batch

Example

use rustkernel::ml::nlp::{SemanticSimilarity, SimilarityConfig};

let kernel = SemanticSimilarity::new();

let similar = kernel.find_similar(
    &embeddings,
    query_index,
    &SimilarityConfig { top_k: 10, threshold: 0.5, include_self: false }
)?;

SecureAggregation

Privacy-preserving federated learning with differential privacy.

ID: ml/secure-aggregation Modes: Batch

Aggregates model updates from multiple clients while preserving privacy through noise injection and gradient clipping.

Example

use rustkernel::ml::federated::{SecureAggregation, AggregationConfig};

let kernel = SecureAggregation::new();

let config = AggregationConfig {
    num_clients: 10,
    clip_threshold: 1.0,
    noise_multiplier: 0.1,
    secure_mode: true,
};

let global_update = kernel.aggregate(&client_updates, &config)?;

DrugInteractionPrediction

Predicts multi-drug interaction risks using hypergraph neural networks.

ID: ml/drug-interaction Modes: Batch

Example

use rustkernel::ml::healthcare::{DrugInteractionPrediction, DrugProfile};

let kernel = DrugInteractionPrediction::new();

let drugs = vec![
    DrugProfile { id: "D001", features: moa_features.clone() },
    DrugProfile { id: "D002", features: target_features.clone() },
];

let result = kernel.predict(&drugs)?;
println!("Interaction risk: {:.2}", result.risk_score);

ClinicalPathwayConformance

Checks treatment event sequences against clinical guidelines.

ID: ml/clinical-pathway Modes: Batch

Example

use rustkernel::ml::healthcare::{ClinicalPathwayConformance, ClinicalPathway};

let kernel = ClinicalPathwayConformance::new();

let pathway = ClinicalPathway {
    name: "Sepsis Protocol".to_string(),
    required_steps: vec!["blood_culture", "antibiotics", "fluids"],
    max_time_hours: 3.0,
};

let result = kernel.check_conformance(&events, &pathway)?;
println!("Conformance: {:.1}%", result.conformance_score * 100.0);

Ring Mode for Streaming ML

Ring mode enables online learning scenarios:

use rustkernel::ml::clustering::KMeansRing;

let ring = KMeansRing::new(k: 5, dimensions: 3);

// Stream data points
for point in incoming_stream {
    // Assign to nearest cluster (sub-millisecond)
    let cluster = ring.assign_point(point).await?;

    // Periodically update centroids
    if should_update_centroids() {
        ring.update_centroids().await?;
    }
}

Performance Considerations

1. Dimensionality: High dimensions slow down distance calculations
2. Memory: KMeans stores all points; for very large datasets, consider mini-batch
3. Initialization: K-means++ is more expensive but gives better results
4. GPU utilization: Ensure batch sizes are large enough to saturate GPU

Compliance

Crate: rustkernel-compliance Kernels: 11 Feature: compliance (included in default features)

Anti-money laundering (AML), Know Your Customer (KYC), and regulatory compliance kernels.

Kernel Overview

AML Pattern Detection (6)

KYC/Screening (4)

Monitoring (1)

Kernel Details

AMLPatternDetection

Comprehensive AML scoring combining multiple detection methods.

ID: compliance/aml-pattern-detection Modes: Batch, Ring

Input

pub struct AMLPatternInput {
    /// Transaction graph edges (from_account, to_account, amount)
    pub transactions: Vec<(String, String, f64)>,
    /// Time window in seconds
    pub time_window: u64,
    /// Minimum amount threshold
    pub min_amount: f64,
    /// Detection thresholds
    pub thresholds: AMLThresholds,
}

pub struct AMLThresholds {
    pub circular_flow_threshold: f64,
    pub reciprocity_threshold: f64,
    pub rapid_movement_threshold: f64,
    pub structuring_threshold: f64,
}

Output

pub struct AMLPatternOutput {
    /// Overall risk scores per account
    pub risk_scores: HashMap<String, f64>,
    /// Detected patterns
    pub patterns: Vec<DetectedPattern>,
    /// High-risk accounts
    pub flagged_accounts: Vec<String>,
}

pub struct DetectedPattern {
    pub pattern_type: PatternType,
    pub accounts: Vec<String>,
    pub confidence: f64,
    pub description: String,
}

Example

use rustkernel::compliance::aml::{AMLPatternDetection, AMLPatternInput};

let kernel = AMLPatternDetection::new();

let input = AMLPatternInput {
    transactions: vec![
        ("A".into(), "B".into(), 9500.0),
        ("B".into(), "C".into(), 9400.0),
        ("C".into(), "A".into(), 9300.0),  // Circular flow
    ],
    time_window: 86400,  // 24 hours
    min_amount: 1000.0,
    thresholds: AMLThresholds::default(),
};

let result = kernel.execute(input).await?;

for pattern in result.patterns {
    println!("Detected: {:?} with confidence {:.2}",
        pattern.pattern_type,
        pattern.confidence
    );
}

SanctionsScreening

Screens entities against sanctions and watchlists.

ID: compliance/sanctions-screening Modes: Batch, Ring

Input

pub struct SanctionsScreeningInput {
    /// Entities to screen
    pub entities: Vec<EntityInfo>,
    /// Sanctions list identifier
    pub list_ids: Vec<String>,
    /// Fuzzy matching threshold (0.0-1.0)
    pub match_threshold: f64,
}

pub struct EntityInfo {
    pub name: String,
    pub aliases: Vec<String>,
    pub country: Option<String>,
    pub date_of_birth: Option<String>,
}

Output

pub struct SanctionsScreeningOutput {
    /// Matches found
    pub matches: Vec<SanctionsMatch>,
    /// Number of entities screened
    pub entities_screened: u32,
    /// Processing time
    pub processing_time_ms: u64,
}

pub struct SanctionsMatch {
    pub entity_index: u32,
    pub list_id: String,
    pub matched_entry: String,
    pub match_score: f64,
    pub match_type: MatchType,
}

KYCScoring

Computes customer risk scores for KYC compliance.

ID: compliance/kyc-scoring Modes: Batch, Ring

Example

use rustkernel::compliance::kyc::{KYCScoring, KYCInput};

let kernel = KYCScoring::new();

let result = kernel.execute(KYCInput {
    customer_id: "CUST001".into(),
    transaction_volume: 150000.0,
    transaction_count: 45,
    countries: vec!["US".into(), "UK".into()],
    account_age_days: 365,
    verification_level: VerificationLevel::Enhanced,
}).await?;

println!("Risk score: {:.2}", result.risk_score);
println!("Risk level: {:?}", result.risk_level);

CircularFlowRatio

Detects circular transaction patterns indicative of money laundering.

ID: compliance/circular-flow-ratio Modes: Batch, Ring

The kernel analyzes transaction graphs to find cycles where money flows back to its origin:

A → B → C → A  (circular flow detected)

Output

pub struct CircularFlowOutput {
    /// Detected circular flows
    pub circular_flows: Vec<CircularFlow>,
    /// Overall circular flow ratio
    pub overall_ratio: f64,
}

pub struct CircularFlow {
    /// Accounts in the circular path
    pub path: Vec<String>,
    /// Total amount circulated
    pub amount: f64,
    /// Time span of the cycle
    pub time_span_seconds: u64,
}

FlowReversalPattern

Detects transaction reversals (A→B followed by B→A) that may indicate wash trading, round-tripping, or layering.

ID: compliance/flow-reversal Modes: Batch Throughput: ~80,000 transactions/sec

Configuration

pub struct FlowReversalConfig {
    /// Maximum time window to consider reversals (seconds)
    pub max_window_seconds: u64,        // default: 86400 (24 hours)
    /// Time threshold for suspicious reversals (seconds)
    pub suspicious_window_seconds: u64,  // default: 3600 (1 hour)
    /// Time threshold for critical reversals (seconds)
    pub critical_window_seconds: u64,    // default: 300 (5 minutes)
    /// Minimum amount match ratio (0-1)
    pub min_amount_match_ratio: f64,     // default: 0.9
}

Output

pub struct FlowReversalResult {
    /// Detected reversal pairs
    pub reversals: Vec<FlowReversalPair>,
    /// Total reversal volume
    pub reversal_volume: f64,
    /// Reversal ratio (reversal volume / total volume)
    pub reversal_ratio: f64,
    /// Entities with multiple reversals
    pub repeat_offenders: Vec<(u64, u32)>,
    /// Overall risk score (0-100)
    pub risk_score: f64,
}

pub struct FlowReversalPair {
    pub original_tx_id: u64,
    pub reversal_tx_id: u64,
    pub entity_a: u64,
    pub entity_b: u64,
    pub original_amount: f64,
    pub reversal_amount: f64,
    pub time_delta: u64,
    pub amount_match_ratio: f64,
    pub risk_level: ReversalRiskLevel,  // Normal, Suspicious, High, Critical
}

Example

use rustkernel::compliance::aml::{FlowReversalPattern, FlowReversalConfig};

let result = FlowReversalPattern::compute(&transactions, &FlowReversalConfig {
    max_window_seconds: 86400,
    suspicious_window_seconds: 3600,
    critical_window_seconds: 300,
    min_amount_match_ratio: 0.9,
});

// Find critical reversals
for reversal in &result.reversals {
    if matches!(reversal.risk_level, ReversalRiskLevel::Critical) {
        println!("CRITICAL: {} -> {} reversed in {}s",
            reversal.entity_a, reversal.entity_b, reversal.time_delta);
    }
}

FlowSplitRatio

Detects structuring (smurfing) patterns where transactions are split to avoid reporting thresholds.

ID: compliance/flow-split Modes: Batch Throughput: ~60,000 transactions/sec

Configuration

pub struct FlowSplitConfig {
    /// Reporting threshold to detect structuring around (e.g., $10,000)
    pub reporting_threshold: f64,   // default: 10_000.0 (BSA threshold)
    /// Time window to look for split transactions (seconds)
    pub window_seconds: u64,        // default: 86400 (24 hours)
    /// Minimum number of transactions to constitute a split
    pub min_split_count: usize,     // default: 3
}

Output

pub struct FlowSplitResult {
    /// Detected split patterns
    pub splits: Vec<FlowSplitPattern>,
    /// Entities with structuring patterns
    pub structuring_entities: Vec<u64>,
    /// Total amount in split patterns
    pub split_volume: f64,
    /// Split ratio (split volume / total volume)
    pub split_ratio: f64,
    /// Overall risk score (0-100)
    pub risk_score: f64,
}

pub struct FlowSplitPattern {
    pub source_entity: u64,
    pub dest_entities: Vec<u64>,
    pub transaction_ids: Vec<u64>,
    pub amounts: Vec<f64>,
    pub total_amount: f64,
    pub time_span: u64,
    pub estimated_threshold: f64,
    pub risk_level: SplitRiskLevel,  // Normal, Elevated, High, Critical
}

Example

use rustkernel::compliance::aml::{FlowSplitRatio, FlowSplitConfig};

let result = FlowSplitRatio::compute(&transactions, &FlowSplitConfig {
    reporting_threshold: 10_000.0,  // BSA threshold
    window_seconds: 86400,
    min_split_count: 3,
});

// Find structuring entities
for entity in &result.structuring_entities {
    println!("STRUCTURING ALERT: Entity {} flagged", entity);
}

// Analyze high-risk splits
for split in result.splits.iter().filter(|s|
    matches!(s.risk_level, SplitRiskLevel::High | SplitRiskLevel::Critical)
) {
    println!("Split detected: {} transactions totaling ${:.2}",
        split.transaction_ids.len(), split.total_amount);
}

Ring Mode for Real-Time Compliance

Ring mode enables real-time transaction screening:

use rustkernel::compliance::aml::AMLPatternRing;

let ring = AMLPatternRing::new();

// Process streaming transactions
for tx in transaction_stream {
    // Sub-millisecond screening
    let alert = ring.screen_transaction(tx).await?;

    if alert.risk_score > threshold {
        notify_compliance_team(alert);
    }
}

Integration Patterns

Batch Processing (Daily/Weekly)

// Load all transactions for period
let transactions = load_transactions(start_date, end_date)?;

// Run comprehensive AML analysis
let aml_result = aml_kernel.execute(AMLPatternInput {
    transactions,
    ..Default::default()
}).await?;

// Generate compliance report
generate_sar_report(aml_result)?;

Real-Time Screening

// Screen each transaction before processing
async fn process_transaction(tx: Transaction) -> Result<()> {
    let screening = sanctions_ring.screen(&tx.counterparty).await?;

    if screening.is_match() {
        return Err(TransactionBlocked::Sanctions);
    }

    // Continue with transaction processing
    process_payment(tx).await
}

Regulatory Alignment

These kernels support requirements from:

• FATF: Financial Action Task Force recommendations
• BSA/AML: Bank Secrecy Act
• EU AMLD: EU Anti-Money Laundering Directives
• OFAC: Office of Foreign Assets Control sanctions

Temporal Analysis

Crate: rustkernel-temporal Kernels: 7 Feature: temporal (included in default features)

Time series analysis kernels for forecasting, anomaly detection, and pattern recognition.

Kernel Overview

Kernel Details

ARIMAForecast

Auto-Regressive Integrated Moving Average forecasting.

ID: temporal/arima-forecast Modes: Batch, Ring

Input

pub struct ARIMAInput {
    /// Time series values
    pub values: Vec<f64>,
    /// AR order (p)
    pub p: u32,
    /// Differencing order (d)
    pub d: u32,
    /// MA order (q)
    pub q: u32,
    /// Forecast horizon
    pub forecast_periods: u32,
}

Output

pub struct ARIMAOutput {
    /// Forecasted values
    pub forecast: Vec<f64>,
    /// Confidence intervals (lower, upper)
    pub confidence_intervals: Vec<(f64, f64)>,
    /// Fitted values
    pub fitted: Vec<f64>,
    /// Model coefficients
    pub coefficients: ARIMACoefficients,
}

Example

use rustkernel::temporal::forecasting::{ARIMAForecast, ARIMAInput};

let kernel = ARIMAForecast::new();

let input = ARIMAInput {
    values: historical_prices,
    p: 2,  // AR(2)
    d: 1,  // First differencing
    q: 1,  // MA(1)
    forecast_periods: 30,
};

let result = kernel.execute(input).await?;

println!("30-day forecast: {:?}", result.forecast);

ChangePointDetection

Detects structural breaks in time series data.

ID: temporal/change-point-detection Modes: Batch, Ring

Input

pub struct ChangePointInput {
    pub values: Vec<f64>,
    /// Detection method
    pub method: ChangePointMethod,
    /// Minimum segment length
    pub min_segment_length: u32,
    /// Penalty factor for number of change points
    pub penalty: f64,
}

pub enum ChangePointMethod {
    PELT,      // Pruned Exact Linear Time
    BinSeg,    // Binary Segmentation
    Window,    // Sliding window
}

Output

pub struct ChangePointOutput {
    /// Indices of detected change points
    pub change_points: Vec<u32>,
    /// Segment statistics
    pub segments: Vec<SegmentStats>,
    /// Overall detection confidence
    pub confidence: f64,
}

VolatilityAnalysis

Estimates and forecasts volatility using GARCH/EWMA models.

ID: temporal/volatility-analysis Modes: Batch, Ring

Example

use rustkernel::temporal::volatility::{VolatilityAnalysis, VolatilityInput};

let kernel = VolatilityAnalysis::new();

let result = kernel.execute(VolatilityInput {
    returns: daily_returns,
    model: VolatilityModel::GARCH { p: 1, q: 1 },
    forecast_periods: 10,
}).await?;

println!("Current volatility: {:.4}", result.current_volatility);
println!("VaR (95%): {:.4}", result.var_95);

SeasonalDecomposition

Decomposes time series into trend, seasonal, and residual components.

ID: temporal/seasonal-decomposition Modes: Batch

Input

pub struct SeasonalDecompInput {
    pub values: Vec<f64>,
    /// Seasonal period (e.g., 12 for monthly, 7 for daily)
    pub period: u32,
    /// Decomposition model
    pub model: DecompModel,
}

pub enum DecompModel {
    Additive,       // y = trend + seasonal + residual
    Multiplicative, // y = trend * seasonal * residual
}

Output

pub struct SeasonalDecompOutput {
    pub trend: Vec<f64>,
    pub seasonal: Vec<f64>,
    pub residual: Vec<f64>,
    /// Seasonal strength measure
    pub seasonal_strength: f64,
}

TimeSeriesAnomalyDetection

Identifies anomalies in time series using multiple detection methods.

ID: temporal/anomaly-detection Modes: Batch, Ring

Example

use rustkernel::temporal::detection::{TimeSeriesAnomalyDetection, AnomalyInput};

let kernel = TimeSeriesAnomalyDetection::new();

let result = kernel.execute(AnomalyInput {
    values: sensor_readings,
    method: AnomalyMethod::Twitter,  // Twitter's anomaly detection
    sensitivity: 0.05,
}).await?;

for anomaly in result.anomalies {
    println!("Anomaly at index {}: value={:.2}, score={:.2}",
        anomaly.index,
        anomaly.value,
        anomaly.score
    );
}

Ring Mode for Streaming

Ring mode enables real-time time series processing:

use rustkernel::temporal::detection::AnomalyDetectionRing;

let ring = AnomalyDetectionRing::new();

// Process streaming data points
for (timestamp, value) in data_stream {
    let result = ring.process_point(timestamp, value).await?;

    if result.is_anomaly {
        alert_system.notify(timestamp, result.anomaly_score);
    }
}

Use Cases

Financial Time Series

• Stock price forecasting
• Volatility estimation for options pricing
• Regime change detection in markets

Operational Monitoring

• Server metric anomaly detection
• IoT sensor analysis
• Capacity planning forecasts

Business Analytics

• Sales seasonality analysis
• Demand forecasting
• Trend identification for KPIs

Risk Analytics

Crate: rustkernel-risk Kernels: 4 Feature: risk (included in default features)

Financial risk calculation kernels for credit risk, market risk, and portfolio analysis.

Kernel Overview

Kernel Details

CreditRiskScoring

Calculates Probability of Default (PD), Loss Given Default (LGD), and Exposure at Default (EAD).

ID: risk/credit-risk-scoring Modes: Batch, Ring

Input

pub struct CreditRiskInput {
    /// Borrower information
    pub borrowers: Vec<BorrowerInfo>,
    /// Scoring model to use
    pub model: CreditModel,
    /// Time horizon in months
    pub horizon_months: u32,
}

pub struct BorrowerInfo {
    pub id: String,
    pub credit_score: u32,
    pub debt_to_income: f64,
    pub loan_amount: f64,
    pub collateral_value: Option<f64>,
    pub industry_code: String,
    pub years_in_business: u32,
}

pub enum CreditModel {
    Scorecard,  // Traditional scorecard
    IRB,        // Basel IRB approach
    Merton,     // Structural model
}

Output

pub struct CreditRiskOutput {
    /// Risk metrics per borrower
    pub risk_metrics: Vec<BorrowerRisk>,
    /// Portfolio-level metrics
    pub portfolio_metrics: PortfolioCreditMetrics,
}

pub struct BorrowerRisk {
    pub borrower_id: String,
    pub pd: f64,         // Probability of Default
    pub lgd: f64,        // Loss Given Default
    pub ead: f64,        // Exposure at Default
    pub expected_loss: f64,
    pub risk_weight: f64,  // For RWA calculation
}

Example

use rustkernel::risk::credit::{CreditRiskScoring, CreditRiskInput};

let kernel = CreditRiskScoring::new();

let result = kernel.execute(CreditRiskInput {
    borrowers: vec![
        BorrowerInfo {
            id: "B001".into(),
            credit_score: 720,
            debt_to_income: 0.35,
            loan_amount: 250_000.0,
            collateral_value: Some(300_000.0),
            industry_code: "REAL_ESTATE".into(),
            years_in_business: 5,
        },
    ],
    model: CreditModel::IRB,
    horizon_months: 12,
}).await?;

let risk = &result.risk_metrics[0];
println!("PD: {:.2}%, LGD: {:.2}%, EL: ${:.2}",
    risk.pd * 100.0,
    risk.lgd * 100.0,
    risk.expected_loss
);

MonteCarloVaR

Calculates Value-at-Risk using Monte Carlo simulation.

ID: risk/monte-carlo-var Modes: Batch, Ring Throughput: ~1M simulations/sec

Input

pub struct VaRInput {
    /// Portfolio positions
    pub positions: Vec<Position>,
    /// Number of simulations
    pub n_simulations: u32,
    /// Time horizon in days
    pub horizon_days: u32,
    /// Confidence levels
    pub confidence_levels: Vec<f64>,
    /// Correlation matrix (flattened)
    pub correlations: Vec<f64>,
    /// Volatilities per asset
    pub volatilities: Vec<f64>,
}

pub struct Position {
    pub asset_id: String,
    pub quantity: f64,
    pub current_price: f64,
}

Output

pub struct VaROutput {
    /// VaR at each confidence level
    pub var_values: HashMap<String, f64>,
    /// Expected Shortfall (CVaR)
    pub expected_shortfall: HashMap<String, f64>,
    /// Simulated P&L distribution
    pub pnl_distribution: Vec<f64>,
    /// Component VaR by position
    pub component_var: Vec<(String, f64)>,
}

Example

use rustkernel::risk::market::{MonteCarloVaR, VaRInput};

let kernel = MonteCarloVaR::new();

let result = kernel.execute(VaRInput {
    positions: portfolio_positions,
    n_simulations: 100_000,
    horizon_days: 10,
    confidence_levels: vec![0.95, 0.99],
    correlations: correlation_matrix,
    volatilities: asset_volatilities,
}).await?;

println!("10-day VaR (99%): ${:.2}", result.var_values["0.99"]);
println!("Expected Shortfall (99%): ${:.2}", result.expected_shortfall["0.99"]);

PortfolioRiskAggregation

Aggregates risk across multiple portfolios with diversification effects.

ID: risk/portfolio-risk-aggregation Modes: Batch, Ring

Example

use rustkernel::risk::portfolio::{PortfolioRiskAggregation, AggregationInput};

let kernel = PortfolioRiskAggregation::new();

let result = kernel.execute(AggregationInput {
    portfolio_vars: vec![
        ("Equities".into(), 1_000_000.0),
        ("Fixed Income".into(), 500_000.0),
        ("Commodities".into(), 250_000.0),
    ],
    correlations: correlation_matrix,
    method: AggregationMethod::VarianceCovariance,
}).await?;

println!("Undiversified VaR: ${:.2}", result.undiversified_var);
println!("Diversified VaR: ${:.2}", result.diversified_var);
println!("Diversification benefit: ${:.2}", result.diversification_benefit);

StressTesting

Evaluates portfolio impact under stress scenarios.

ID: risk/stress-testing Modes: Batch

Input

pub struct StressTestInput {
    pub portfolio: Portfolio,
    pub scenarios: Vec<StressScenario>,
}

pub struct StressScenario {
    pub name: String,
    /// Shocks to risk factors
    pub shocks: HashMap<String, f64>,
    pub description: String,
}

Output

pub struct StressTestOutput {
    pub results: Vec<ScenarioResult>,
    pub worst_case: ScenarioResult,
}

pub struct ScenarioResult {
    pub scenario_name: String,
    pub pnl_impact: f64,
    pub pnl_impact_pct: f64,
    pub positions_affected: Vec<PositionImpact>,
}

Ring Mode for Real-Time Risk

Ring mode enables streaming risk calculations:

use rustkernel::risk::market::MonteCarloVaRRing;

let ring = MonteCarloVaRRing::new();

// Real-time position updates
ring.update_position("AAPL", 100, 185.50).await?;
ring.update_position("GOOG", 50, 142.30).await?;

// Query current VaR (sub-millisecond)
let current_var = ring.query_var(0.99).await?;
println!("Current VaR: ${:.2}", current_var);

// Recalculate on market data updates
ring.recalculate().await?;

Regulatory Applications

These kernels support:

• Basel III/IV: RWA calculation, capital adequacy
• FRTB: Fundamental Review of the Trading Book
• CCAR/DFAST: Fed stress testing requirements
• Solvency II: Insurance capital requirements

Banking

Crate: rustkernel-banking Kernels: 1 Feature: banking

Specialized banking operations kernel for fraud detection.

Kernel Overview

Kernel Details

FraudPatternMatch

GPU-accelerated fraud pattern detection using behavioral analysis and rule matching.

ID: banking/fraud-pattern-match Modes: Batch, Ring Throughput: ~500,000 transactions/sec

Input

pub struct FraudPatternInput {
    /// Transactions to analyze
    pub transactions: Vec<Transaction>,
    /// Pattern rules to apply
    pub rules: Vec<FraudRule>,
    /// Historical behavior profiles
    pub profiles: HashMap<String, BehaviorProfile>,
    /// Detection threshold
    pub threshold: f64,
}

pub struct Transaction {
    pub id: String,
    pub account_id: String,
    pub amount: f64,
    pub currency: String,
    pub merchant_category: String,
    pub location: Option<GeoLocation>,
    pub timestamp: u64,
    pub channel: TransactionChannel,
}

pub struct BehaviorProfile {
    pub avg_transaction_amount: f64,
    pub typical_merchants: Vec<String>,
    pub typical_locations: Vec<GeoLocation>,
    pub typical_hours: Vec<u8>,
}

pub enum TransactionChannel {
    CardPresent,
    CardNotPresent,
    ATM,
    Wire,
    ACH,
}

Output

pub struct FraudPatternOutput {
    /// Fraud scores per transaction
    pub scores: Vec<TransactionScore>,
    /// Triggered rules
    pub triggered_rules: Vec<TriggeredRule>,
    /// Recommended actions
    pub actions: Vec<RecommendedAction>,
}

pub struct TransactionScore {
    pub transaction_id: String,
    pub fraud_score: f64,
    pub risk_factors: Vec<RiskFactor>,
    pub recommendation: Recommendation,
}

pub enum Recommendation {
    Approve,
    Review,
    Decline,
    Challenge,  // 3D Secure, OTP, etc.
}

Example

use rustkernel::banking::fraud::{FraudPatternMatch, FraudPatternInput};

let kernel = FraudPatternMatch::new();

let result = kernel.execute(FraudPatternInput {
    transactions: vec![
        Transaction {
            id: "TX001".into(),
            account_id: "ACC123".into(),
            amount: 5000.0,
            currency: "USD".into(),
            merchant_category: "ELECTRONICS".into(),
            location: Some(GeoLocation { lat: 40.7128, lon: -74.0060 }),
            timestamp: 1699000000,
            channel: TransactionChannel::CardNotPresent,
        },
    ],
    rules: default_rules(),
    profiles: customer_profiles,
    threshold: 0.7,
}).await?;

for score in result.scores {
    if score.fraud_score > 0.7 {
        println!("High risk: {} - score {:.2}",
            score.transaction_id,
            score.fraud_score
        );
        for factor in score.risk_factors {
            println!("  - {:?}", factor);
        }
    }
}

Detection Methods

Behavioral Analysis

Compares transactions against established customer behavior:

• Amount deviation: Transaction size vs historical average
• Location deviation: Geographic distance from typical locations
• Time deviation: Transaction time vs typical activity hours
• Merchant deviation: New merchant category or type

Rule-Based Detection

Configurable rules for known fraud patterns:

pub struct FraudRule {
    pub id: String,
    pub name: String,
    pub conditions: Vec<RuleCondition>,
    pub score_impact: f64,
    pub enabled: bool,
}

pub enum RuleCondition {
    AmountGreaterThan(f64),
    VelocityExceeds { count: u32, window_seconds: u64 },
    LocationMismatch { max_distance_km: f64 },
    NewMerchant,
    HighRiskCountry(Vec<String>),
    CardNotPresentHighValue,
}

Velocity Checks

Detects rapid transaction patterns:

• Multiple transactions in short time
• Multiple cards on same device
• Multiple devices for same card

Ring Mode for Real-Time Scoring

Ring mode enables sub-millisecond fraud scoring:

use rustkernel::banking::fraud::FraudPatternRing;

let ring = FraudPatternRing::new();

// Pre-load customer profiles
ring.load_profiles(profiles).await?;

// Score transactions in real-time
async fn score_transaction(tx: Transaction) -> FraudDecision {
    let score = ring.score(tx).await?;

    match score.fraud_score {
        s if s < 0.3 => FraudDecision::Approve,
        s if s < 0.7 => FraudDecision::Review,
        _ => FraudDecision::Decline,
    }
}

Integration Patterns

Authorization Flow

// In payment authorization path
async fn authorize(tx: Transaction) -> AuthResult {
    // 1. Real-time fraud scoring (< 100ms)
    let fraud_result = fraud_ring.score(tx.clone()).await?;

    if fraud_result.recommendation == Recommendation::Decline {
        return AuthResult::Declined("Fraud risk");
    }

    if fraud_result.recommendation == Recommendation::Challenge {
        return AuthResult::Challenge3DS;
    }

    // 2. Continue with authorization
    process_authorization(tx).await
}

Batch Analysis

// Daily fraud pattern review
async fn daily_fraud_review() {
    let transactions = load_day_transactions().await?;

    let result = fraud_kernel.execute(FraudPatternInput {
        transactions,
        rules: all_rules(),
        profiles: all_profiles(),
        threshold: 0.5,  // Lower threshold for review
    }).await?;

    // Generate suspicious activity report
    generate_sar_report(result.scores.filter(|s| s.fraud_score > 0.5));
}

Performance Considerations

1. Profile caching: Keep frequently accessed profiles in GPU memory
2. Rule optimization: Order rules by selectivity (most filtering first)
3. Batch when possible: Process multiple transactions per GPU call
4. Async patterns: Don’t block authorization on slow operations

Behavioral Analytics

Crate: rustkernel-behavioral Kernels: 6 Feature: behavioral

Behavioral profiling, forensic analysis, and event correlation kernels.

Kernel Overview

Kernel Details

BehavioralProfiling

Constructs behavioral profiles from historical activity data.

ID: behavioral/profiling Modes: Batch, Ring

Input

pub struct ProfilingInput {
    pub entity_id: String,
    pub events: Vec<BehaviorEvent>,
    pub profile_type: ProfileType,
    pub time_window_days: u32,
}

pub struct BehaviorEvent {
    pub timestamp: u64,
    pub event_type: String,
    pub attributes: HashMap<String, String>,
    pub numeric_values: HashMap<String, f64>,
}

pub enum ProfileType {
    User,
    Account,
    Device,
    Session,
}

Output

pub struct ProfilingOutput {
    pub profile: BehaviorProfile,
    pub confidence: f64,
    pub data_quality: DataQuality,
}

pub struct BehaviorProfile {
    pub entity_id: String,
    pub typical_patterns: Vec<Pattern>,
    pub statistics: ProfileStatistics,
    pub risk_indicators: Vec<RiskIndicator>,
}

EventCorrelationKernel

Correlates events across multiple data sources to identify related activities.

ID: behavioral/event-correlation Modes: Batch, Ring

Example

use rustkernel::behavioral::correlation::{EventCorrelationKernel, CorrelationInput};

let kernel = EventCorrelationKernel::new();

let result = kernel.execute(CorrelationInput {
    events: vec![
        Event { source: "auth", type_: "login_failure", entity: "user123", ts: 1000 },
        Event { source: "auth", type_: "login_success", entity: "user123", ts: 1005 },
        Event { source: "api", type_: "data_export", entity: "user123", ts: 1010 },
    ],
    correlation_window_seconds: 60,
    correlation_rules: default_rules(),
}).await?;

for chain in result.correlated_chains {
    println!("Attack chain detected:");
    for event in chain.events {
        println!("  {} -> {}", event.source, event.type_);
    }
}

CausalGraphConstruction

Builds causal relationship graphs from event sequences.

ID: behavioral/causal-graph Modes: Batch

Output

pub struct CausalGraphOutput {
    pub nodes: Vec<CausalNode>,
    pub edges: Vec<CausalEdge>,
    pub root_causes: Vec<String>,
    pub impact_paths: Vec<ImpactPath>,
}

pub struct CausalEdge {
    pub from: String,
    pub to: String,
    pub strength: f64,
    pub lag_seconds: u64,
}

Use Cases

Security Operations

• Detect account takeover attempts
• Identify insider threats
• Correlate security events across systems

Fraud Investigation

• Build fraud case timelines
• Identify related accounts
• Trace fund flows across entities

User Analytics

• Understand user journeys
• Predict churn risk
• Personalize experiences

Order Matching

Crate: rustkernel-orderbook Kernels: 1 Feature: orderbook

High-performance order book matching engine for trading systems.

Kernel Overview

Kernel Details

OrderMatchingEngine

Ultra-low latency order matching with price-time priority.

ID: orderbook/matching-engine Modes: Batch, Ring Latency: <1μs per order (Ring mode)

Input

pub struct OrderInput {
    pub orders: Vec<Order>,
    pub symbol: String,
}

pub struct Order {
    pub id: String,
    pub side: Side,
    pub price: f64,
    pub quantity: u64,
    pub order_type: OrderType,
    pub time_in_force: TimeInForce,
    pub timestamp: u64,
}

pub enum Side {
    Buy,
    Sell,
}

pub enum OrderType {
    Limit,
    Market,
    StopLimit { trigger_price: f64 },
    IcebergLimit { display_qty: u64 },
}

pub enum TimeInForce {
    GTC,  // Good Till Cancelled
    IOC,  // Immediate Or Cancel
    FOK,  // Fill Or Kill
    GTD { expiry: u64 },  // Good Till Date
}

Output

pub struct OrderOutput {
    pub executions: Vec<Execution>,
    pub book_state: BookState,
    pub statistics: MatchingStatistics,
}

pub struct Execution {
    pub execution_id: String,
    pub buy_order_id: String,
    pub sell_order_id: String,
    pub price: f64,
    pub quantity: u64,
    pub timestamp: u64,
}

pub struct BookState {
    pub bids: Vec<PriceLevel>,
    pub asks: Vec<PriceLevel>,
    pub last_trade_price: f64,
    pub last_trade_quantity: u64,
}

Example

use rustkernel::orderbook::{OrderMatchingEngine, OrderInput, Order, Side, OrderType};

let kernel = OrderMatchingEngine::new();

let result = kernel.execute(OrderInput {
    orders: vec![
        Order {
            id: "O1".into(),
            side: Side::Buy,
            price: 100.50,
            quantity: 1000,
            order_type: OrderType::Limit,
            time_in_force: TimeInForce::GTC,
            timestamp: 1699000000,
        },
        Order {
            id: "O2".into(),
            side: Side::Sell,
            price: 100.50,
            quantity: 500,
            order_type: OrderType::Limit,
            time_in_force: TimeInForce::GTC,
            timestamp: 1699000001,
        },
    ],
    symbol: "AAPL".into(),
}).await?;

for exec in result.executions {
    println!("Execution: {} shares @ ${:.2}",
        exec.quantity,
        exec.price
    );
}

Ring Mode for Live Trading

Ring mode maintains order book state on GPU for sub-microsecond matching:

use rustkernel::orderbook::OrderMatchingRing;

let ring = OrderMatchingRing::new("AAPL");

// Process incoming orders
async fn process_order(order: Order) -> Vec<Execution> {
    match order.order_type {
        OrderType::Limit => ring.add_limit_order(order).await?,
        OrderType::Market => ring.add_market_order(order).await?,
        _ => unimplemented!(),
    }
}

// Cancel order
ring.cancel_order("O123").await?;

// Query book state
let book = ring.get_book_snapshot().await?;
println!("Best bid: ${:.2}", book.bids[0].price);
println!("Best ask: ${:.2}", book.asks[0].price);

Matching Rules

Price-Time Priority

Orders are matched following price-time priority:

1. Best price first (highest bid, lowest ask)
2. Earlier orders at same price matched first

Order Types

Time in Force

Performance Characteristics

• Throughput: >1M orders/sec (batch)
• Latency: <1μs per order (ring)
• Book depth: Unlimited price levels
• Symbols: One ring per symbol

Integration Notes

For production trading systems:

1. Sequencer: Orders must be sequenced before matching
2. Persistence: Log all orders and executions
3. Risk checks: Pre-trade risk should precede matching
4. Market data: Publish book updates after each match

Process Intelligence

Crate: rustkernel-procint Kernels: 7 Feature: procint

Process mining and analysis kernels for business process optimization.

Kernel Overview

Kernel Details

DFGConstruction

Constructs Directly-Follows Graphs from event logs.

ID: procint/dfg-construction Modes: Batch, Ring

Input

pub struct DFGInput {
    /// Event log entries
    pub events: Vec<ProcessEvent>,
    /// Minimum edge frequency threshold
    pub min_frequency: u32,
}

pub struct ProcessEvent {
    pub case_id: String,
    pub activity: String,
    pub timestamp: u64,
    pub resource: Option<String>,
    pub attributes: HashMap<String, String>,
}

Output

pub struct DFGOutput {
    /// Activities (nodes)
    pub activities: Vec<Activity>,
    /// Edges with frequencies
    pub edges: Vec<DFGEdge>,
    /// Start activities
    pub start_activities: Vec<String>,
    /// End activities
    pub end_activities: Vec<String>,
}

pub struct DFGEdge {
    pub from: String,
    pub to: String,
    pub frequency: u32,
    pub avg_duration_seconds: f64,
}

Example

use rustkernel::procint::dfg::{DFGConstruction, DFGInput};

let kernel = DFGConstruction::new();

let result = kernel.execute(DFGInput {
    events: vec![
        ProcessEvent { case_id: "C1".into(), activity: "Submit".into(), timestamp: 1000, .. },
        ProcessEvent { case_id: "C1".into(), activity: "Review".into(), timestamp: 2000, .. },
        ProcessEvent { case_id: "C1".into(), activity: "Approve".into(), timestamp: 3000, .. },
    ],
    min_frequency: 1,
}).await?;

for edge in result.edges {
    println!("{} -> {} (freq: {}, avg: {:.1}s)",
        edge.from,
        edge.to,
        edge.frequency,
        edge.avg_duration_seconds
    );
}

ConformanceChecking

Checks if process executions conform to a reference model.

ID: procint/conformance-checking Modes: Batch, Ring

Input

pub struct ConformanceInput {
    pub events: Vec<ProcessEvent>,
    pub reference_model: ProcessModel,
    pub tolerance: ConformanceTolerance,
}

pub struct ProcessModel {
    pub activities: Vec<String>,
    pub transitions: Vec<(String, String)>,
    pub start: String,
    pub end: String,
}

Output

pub struct ConformanceOutput {
    /// Fitness score (0.0 - 1.0)
    pub fitness: f64,
    /// Precision score
    pub precision: f64,
    /// Deviations found
    pub deviations: Vec<Deviation>,
    /// Per-case conformance
    pub case_conformance: HashMap<String, f64>,
}

pub struct Deviation {
    pub case_id: String,
    pub deviation_type: DeviationType,
    pub activity: String,
    pub description: String,
}

OCPMPatternMatching

Object-Centric Process Mining for complex, multi-object processes.

ID: procint/ocpm-pattern-matching Modes: Batch

Example

use rustkernel::procint::ocpm::{OCPMPatternMatching, OCPMInput};

let kernel = OCPMPatternMatching::new();

let result = kernel.execute(OCPMInput {
    events: order_events,
    object_types: vec!["Order".into(), "Item".into(), "Delivery".into()],
    patterns: vec![
        Pattern::BottleneckDetection,
        Pattern::ObjectLifecycle,
        Pattern::InteractionAnalysis,
    ],
}).await?;

for bottleneck in result.bottlenecks {
    println!("Bottleneck: {} (avg wait: {:.1}h)",
        bottleneck.activity,
        bottleneck.avg_wait_hours
    );
}

NextActivityPrediction

Predicts the next activity in a process using sequence models.

ID: procint/next-activity-prediction Modes: Batch

Example

use rustkernel::procint::prediction::{NextActivityPrediction, PredictionConfig};

let kernel = NextActivityPrediction::new();

let config = PredictionConfig {
    sequence_length: 10,
    top_k: 3,
};

let predictions = kernel.predict(&event_sequence, &config)?;
for (activity, prob) in predictions {
    println!("{}: {:.1}%", activity, prob * 100.0);
}

EventLogImputation

Handles missing events, incorrect timestamps, and duplicates in event logs.

ID: procint/event-log-imputation Modes: Batch

Example

use rustkernel::procint::imputation::{EventLogImputation, ImputationConfig};

let kernel = EventLogImputation::new();

let config = ImputationConfig {
    detect_missing: true,
    fix_timestamps: true,
    remove_duplicates: true,
};

let cleaned_log = kernel.impute(&raw_events, &config)?;
println!("Fixed {} issues", cleaned_log.issues_fixed);

DigitalTwin

Process simulation for what-if analysis and optimization using Monte Carlo methods.

ID: procint/digital-twin Modes: Batch

Example

use rustkernel::procint::simulation::{DigitalTwin, ProcessModel, SimulationConfig};

let kernel = DigitalTwin::new();

let config = SimulationConfig {
    num_simulations: 1000,
    time_horizon_hours: 24.0,
    seed: Some(42),
};

let result = kernel.simulate(&process_model, &config)?;
println!("Avg completion time: {:.2}h", result.avg_completion_time_hours);
println!("Bottleneck: {}", result.bottlenecks[0].activity);

Use Cases

Process Discovery

• Automatically discover process models from logs
• Identify common paths and variants
• Measure process performance

Compliance Monitoring

• Ensure processes follow defined procedures
• Detect deviations in real-time
• Generate audit trails

Process Optimization

• Identify bottlenecks using DigitalTwin simulation
• Analyze resource utilization
• Run what-if scenarios for capacity planning

Predictive Analytics

• Predict next activities for proactive intervention
• Clean and impute event logs for better analysis
• Estimate remaining process time

Clearing

Crate: rustkernel-clearing Kernels: 5 Feature: clearing

Post-trade clearing, settlement, and netting kernels for financial market infrastructure.

Kernel Overview

Kernel Details

NettingCalculation

Calculates multilateral netting positions to minimize settlement volume.

ID: clearing/netting-calculation Modes: Batch, Ring

Input

pub struct NettingInput {
    /// Trades to net
    pub trades: Vec<Trade>,
    /// Netting set definition
    pub netting_set: NettingSet,
    /// Currency for settlement
    pub settlement_currency: String,
}

pub struct Trade {
    pub id: String,
    pub buyer: String,
    pub seller: String,
    pub instrument: String,
    pub quantity: i64,
    pub price: f64,
    pub trade_date: u64,
    pub settlement_date: u64,
}

pub struct NettingSet {
    pub participants: Vec<String>,
    pub netting_type: NettingType,
}

pub enum NettingType {
    Bilateral,
    Multilateral,
    CCP,  // Central Counterparty
}

Output

pub struct NettingOutput {
    /// Net positions per participant
    pub positions: Vec<NetPosition>,
    /// Settlement instructions
    pub instructions: Vec<SettlementInstruction>,
    /// Netting statistics
    pub statistics: NettingStatistics,
}

pub struct NetPosition {
    pub participant: String,
    pub instrument: String,
    pub net_quantity: i64,
    pub net_value: f64,
}

pub struct NettingStatistics {
    pub gross_value: f64,
    pub net_value: f64,
    pub netting_efficiency: f64,  // (1 - net/gross) * 100
    pub trades_netted: u32,
}

Example

use rustkernel::clearing::netting::{NettingCalculation, NettingInput};

let kernel = NettingCalculation::new();

let result = kernel.execute(NettingInput {
    trades: vec![
        Trade { buyer: "A".into(), seller: "B".into(), quantity: 100, price: 50.0, .. },
        Trade { buyer: "B".into(), seller: "A".into(), quantity: 80, price: 51.0, .. },
        Trade { buyer: "A".into(), seller: "C".into(), quantity: 50, price: 49.0, .. },
    ],
    netting_set: NettingSet {
        participants: vec!["A".into(), "B".into(), "C".into()],
        netting_type: NettingType::Multilateral,
    },
    settlement_currency: "USD".into(),
}).await?;

println!("Netting efficiency: {:.1}%", result.statistics.netting_efficiency);
for pos in result.positions {
    println!("{}: {} units, ${:.2}", pos.participant, pos.net_quantity, pos.net_value);
}

DVPMatching

Matches Delivery versus Payment instructions to ensure atomic settlement.

ID: clearing/dvp-matching Modes: Batch, Ring

Output

pub struct DVPMatchOutput {
    pub matched_pairs: Vec<MatchedPair>,
    pub unmatched_deliveries: Vec<String>,
    pub unmatched_payments: Vec<String>,
    pub match_rate: f64,
}

SettlementExecution

Executes settlement instructions with fail handling.

ID: clearing/settlement-execution Modes: Batch

Example

use rustkernel::clearing::settlement::{SettlementExecution, SettlementInput};

let kernel = SettlementExecution::new();

let result = kernel.execute(SettlementInput {
    instructions: settlement_instructions,
    available_securities: securities_inventory,
    available_cash: cash_positions,
    fail_tolerance: FailTolerance::PartialAllowed,
}).await?;

println!("Settled: {}/{}", result.settled_count, result.total_count);
for fail in result.fails {
    println!("Failed: {} - {}", fail.instruction_id, fail.reason);
}

Use Cases

• CCP clearing: Central counterparty netting and novation
• Securities settlement: DVP settlement for equities, bonds
• FX settlement: CLS-style payment-versus-payment
• Derivatives clearing: Margin calculation and variation margin

Treasury

Crate: rustkernel-treasury Kernels: 5 Feature: treasury

Treasury management kernels for cash flow, FX hedging, and liquidity optimization.

Kernel Overview

Kernel Details

CashFlowForecasting

Forecasts cash positions across accounts and time horizons.

ID: treasury/cash-flow-forecasting Modes: Batch, Ring

Input

pub struct CashFlowInput {
    /// Current positions
    pub positions: Vec<CashPosition>,
    /// Expected inflows
    pub inflows: Vec<CashFlow>,
    /// Expected outflows
    pub outflows: Vec<CashFlow>,
    /// Forecast horizon in days
    pub horizon_days: u32,
}

pub struct CashPosition {
    pub account_id: String,
    pub currency: String,
    pub balance: f64,
}

pub struct CashFlow {
    pub account_id: String,
    pub amount: f64,
    pub currency: String,
    pub expected_date: u64,
    pub probability: f64,
    pub category: FlowCategory,
}

Output

pub struct CashFlowOutput {
    /// Daily forecast per account/currency
    pub daily_forecast: Vec<DailyPosition>,
    /// Minimum/maximum projections
    pub min_projection: Vec<f64>,
    pub max_projection: Vec<f64>,
    /// Shortfall alerts
    pub shortfall_alerts: Vec<ShortfallAlert>,
}

FXHedging

Analyzes FX exposures and recommends hedging strategies.

ID: treasury/fx-hedging Modes: Batch, Ring

Example

use rustkernel::treasury::fx::{FXHedging, FXHedgingInput};

let kernel = FXHedging::new();

let result = kernel.execute(FXHedgingInput {
    exposures: vec![
        FXExposure {
            currency_pair: "EUR/USD".into(),
            amount: 1_000_000.0,
            direction: ExposureDirection::Long,
            maturity_days: 90,
        },
    ],
    hedging_instruments: available_instruments,
    risk_tolerance: RiskTolerance::Moderate,
    hedge_ratio_target: 0.80,
}).await?;

for recommendation in result.recommendations {
    println!("Hedge {} with {} {} forward",
        recommendation.exposure,
        recommendation.amount,
        recommendation.instrument
    );
}

InterestRateRisk

Calculates interest rate risk metrics for fixed income portfolios.

ID: treasury/interest-rate-risk Modes: Batch, Ring

Output

pub struct InterestRateRiskOutput {
    /// Modified duration
    pub duration: f64,
    /// Convexity
    pub convexity: f64,
    /// Dollar value of a basis point
    pub dv01: f64,
    /// Key rate durations
    pub key_rate_durations: HashMap<String, f64>,
    /// Scenario analysis
    pub scenario_pnl: HashMap<String, f64>,
}

LiquidityOptimization

Optimizes liquidity positions for regulatory compliance (LCR, NSFR).

ID: treasury/liquidity-optimization Modes: Batch

Example

use rustkernel::treasury::liquidity::{LiquidityOptimization, LiquidityInput};

let kernel = LiquidityOptimization::new();

let result = kernel.execute(LiquidityInput {
    assets: liquid_assets,
    liabilities: funding_sources,
    target_lcr: 1.10,  // 110% target
    target_nsfr: 1.05, // 105% target
    constraints: optimization_constraints,
}).await?;

println!("Current LCR: {:.1}%", result.current_lcr * 100.0);
println!("Optimized LCR: {:.1}%", result.optimized_lcr * 100.0);
for action in result.recommended_actions {
    println!("Action: {}", action.description);
}

Use Cases

• Cash management: Forecast positions, optimize sweeps
• FX treasury: Manage currency exposures, hedge programs
• ALM: Asset-liability management, gap analysis
• Regulatory: LCR/NSFR compliance, stress testing

Accounting

Crate: rustkernel-accounting Kernels: 9 Feature: accounting

Accounting network generation, reconciliation, and analysis kernels for financial close and audit.

Kernel Overview

Core Kernels (7)

Detection Kernels (2)

Kernel Details

NetworkGeneration

Transforms double-entry journal entries into directed accounting flow networks.

ID: accounting/network-generation Modes: Batch Feature Article: Accounting Network Generation

Input

pub struct NetworkGenerationInput {
    /// Journal entries to process
    pub entries: Vec<JournalEntry>,
    /// Configuration options
    pub config: Option<NetworkGenerationConfig>,
}

pub struct JournalEntry {
    pub id: u64,
    pub date: u64,
    pub posting_date: u64,
    pub document_number: String,
    pub lines: Vec<JournalLine>,
    pub status: JournalStatus,
    pub source_system: String,
    pub description: String,
}

pub struct JournalLine {
    pub line_number: u32,
    pub account_code: String,
    pub debit: f64,
    pub credit: f64,
    pub currency: String,
    pub entity_id: String,
    pub cost_center: Option<String>,
    pub description: String,
}

Output

pub struct NetworkGenerationOutput {
    /// Generated accounting flows
    pub flows: Vec<AccountingFlow>,
    /// Network statistics
    pub stats: NetworkGenerationStats,
}

pub struct AccountingFlow {
    pub flow_id: String,
    pub entry_id: u64,
    pub from_account: String,
    pub to_account: String,
    pub amount: f64,
    pub method: SolvingMethod,
    pub confidence: f64,
    pub from_entity: String,
    pub to_entity: String,
    /// Account classification
    pub from_account_class: Option<AccountClass>,
    pub to_account_class: Option<AccountClass>,
    /// Detected transaction pattern
    pub pattern: Option<TransactionPattern>,
    /// VAT/tax indicators
    pub is_tax_flow: bool,
    pub vat_rate: Option<f64>,
}

Solving Methods

The kernel uses five methods with decreasing confidence:

Example

use rustkernel::accounting::network_generation::{NetworkGeneration, NetworkGenerationInput};

let kernel = NetworkGeneration::new();

let result = kernel.execute(NetworkGenerationInput {
    entries: journal_entries,
    config: Some(NetworkGenerationConfig {
        enable_pattern_matching: true,
        enable_vat_detection: true,
        ..Default::default()
    }),
}).await?;

println!("Generated {} flows", result.flows.len());
println!("Weighted confidence: {:.2}", result.stats.weighted_confidence);

// Analyze flows by pattern
let sales = result.flows.iter()
    .filter(|f| matches!(f.pattern, Some(TransactionPattern::SaleWithVat)))
    .count();
println!("Sales transactions: {}", sales);

GLReconciliation

Reconciles general ledger balances across systems.

ID: accounting/gl-reconciliation Modes: Batch, Ring

Output

pub struct ReconciliationOutput {
    pub matched_pairs: Vec<MatchedPair>,
    pub unmatched: Vec<String>,
    pub exceptions: Vec<ReconciliationException>,
    pub stats: ReconciliationStats,
}

pub struct ReconciliationStats {
    pub total_items: usize,
    pub matched_count: usize,
    pub match_rate: f64,
    pub total_variance: f64,
}

NetworkAnalysis

Analyzes intercompany transaction networks for consolidation.

ID: accounting/network-analysis Modes: Batch, Ring

Example

use rustkernel::accounting::network::{NetworkAnalysis, NetworkAnalysisInput};

let kernel = NetworkAnalysis::new();

let result = kernel.execute(NetworkAnalysisInput {
    transactions: intercompany_transactions,
    entities: group_entities,
    analysis_type: AnalysisType::Elimination,
}).await?;

println!("Elimination entries needed: {}", result.elimination_entries.len());
for entry in result.elimination_entries {
    println!("Eliminate: {} -> {} (${:.2})",
        entry.from_entity,
        entry.to_entity,
        entry.amount
    );
}

TemporalCorrelation

Analyzes correlations between accounts over time to detect anomalies.

ID: accounting/temporal-correlation Modes: Batch

Output

pub struct CorrelationOutput {
    pub correlations: Vec<AccountCorrelation>,
    pub anomalies: Vec<CorrelationAnomaly>,
    pub stats: CorrelationStats,
}

pub struct AccountCorrelation {
    pub account_a: String,
    pub account_b: String,
    pub coefficient: f64,
    pub p_value: f64,
}

SuspenseAccountDetection

Identifies suspense accounts using centrality-based analysis on the account transaction graph.

ID: accounting/suspense-detection Modes: Batch Throughput: ~20,000 accounts/sec

Suspense accounts are detected based on:

• High centrality: Accounts that connect many other accounts
• High turnover: Large volume relative to balance
• Short holding period: Funds don’t stay long
• Balanced flows: Equal in/out suggests clearing function
• Zero end balance: Period-end balance near zero
• Naming patterns: Contains “suspense”, “clearing”, “holding”

Configuration

pub struct SuspenseDetectionConfig {
    /// Minimum betweenness centrality to flag
    pub centrality_threshold: f64,        // default: 0.1
    /// Minimum turnover ratio (turnover/balance)
    pub turnover_ratio_threshold: f64,    // default: 10.0
    /// Maximum average holding period (days)
    pub holding_period_threshold: f64,    // default: 7.0
    /// Minimum balance ratio to consider balanced (0-1)
    pub balance_ratio_threshold: f64,     // default: 0.9
    /// Minimum counterparty count to flag
    pub counterparty_threshold: usize,    // default: 5
    /// Maximum balance to consider "zero"
    pub zero_balance_threshold: f64,      // default: 100.0
}

Output

pub struct SuspenseAccountResult {
    /// Detected suspense account candidates
    pub candidates: Vec<SuspenseAccountCandidate>,
    /// High-risk accounts
    pub high_risk_accounts: Vec<String>,
    /// Total accounts analyzed
    pub accounts_analyzed: usize,
    /// Overall risk score
    pub risk_score: f64,
}

pub struct SuspenseAccountCandidate {
    pub account_code: String,
    pub account_name: String,
    pub suspense_score: f64,           // 0-100
    pub centrality_score: f64,
    pub turnover_volume: f64,
    pub avg_holding_period: f64,
    pub counterparty_count: usize,
    pub balance_ratio: f64,
    pub risk_level: SuspenseRiskLevel, // Low, Medium, High, Critical
    pub indicators: Vec<SuspenseIndicator>,
}

Example

use rustkernel::accounting::detection::{SuspenseAccountDetection, SuspenseDetectionConfig};

let result = SuspenseAccountDetection::detect(&journal_entries, &SuspenseDetectionConfig {
    centrality_threshold: 0.1,
    holding_period_threshold: 7.0,
    ..Default::default()
});

// Review high-risk suspense accounts
for account in &result.high_risk_accounts {
    println!("HIGH RISK: Account {} flagged as suspense", account);
}

// Analyze candidates
for candidate in &result.candidates {
    println!("{}: score={:.1}, centrality={:.3}, indicators={:?}",
        candidate.account_code,
        candidate.suspense_score,
        candidate.centrality_score,
        candidate.indicators);
}

GaapViolationDetection

Detects prohibited transaction patterns that violate GAAP principles.

ID: accounting/gaap-violation Modes: Batch Throughput: ~15,000 entries/sec

Detected violation types:

• DirectRevenueExpense: Direct transfer from revenue to expense without capital account
• RevenueInflation: Circular flows that may inflate revenue
• ImproperAssetExpense: Asset expensed without proper depreciation
• SuspenseAccountMisuse: Large amounts in suspense accounts
• ImproperElimination: Incorrect intercompany eliminations
• ProhibitedRelatedParty: Prohibited related-party transactions

Configuration

pub struct GaapDetectionConfig {
    /// Threshold for suspense account amounts
    pub suspense_amount_threshold: f64,   // default: 10_000.0
    /// Minimum amount for asset-to-expense flag
    pub asset_expense_threshold: f64,     // default: 5_000.0
    /// Minimum circular flow amount
    pub circular_flow_threshold: f64,     // default: 1_000.0
}

Output

pub struct GaapViolationResult {
    /// Detected violations
    pub violations: Vec<GaapViolation>,
    /// Total entries analyzed
    pub entries_analyzed: usize,
    /// Total amount at risk
    pub amount_at_risk: f64,
    /// Overall compliance score (0-100, higher is better)
    pub compliance_score: f64,
    /// Violation counts by type
    pub violation_counts: HashMap<String, usize>,
}

pub struct GaapViolation {
    pub id: String,
    pub violation_type: GaapViolationType,
    pub accounts: Vec<String>,
    pub entry_ids: Vec<u64>,
    pub amount: f64,
    pub description: String,
    pub severity: GaapViolationSeverity,  // Minor, Moderate, Major, Critical
    pub remediation: String,
}

Example

use rustkernel::accounting::detection::{GaapViolationDetection, GaapDetectionConfig};
use std::collections::HashMap;

// Map account codes to types
let mut account_types = HashMap::new();
account_types.insert("SALES_REVENUE".to_string(), AccountType::Revenue);
account_types.insert("SALARIES_EXPENSE".to_string(), AccountType::Expense);
account_types.insert("EQUIPMENT_ASSET".to_string(), AccountType::Asset);

let result = GaapViolationDetection::detect(
    &journal_entries,
    &account_types,
    &GaapDetectionConfig::default()
);

println!("Compliance score: {:.1}%", result.compliance_score);
println!("Amount at risk: ${:.2}", result.amount_at_risk);

// Review violations by severity
for violation in result.violations.iter()
    .filter(|v| matches!(v.severity, GaapViolationSeverity::Major | GaapViolationSeverity::Critical))
{
    println!("{}: {} - {}",
        violation.id,
        violation.description,
        violation.remediation);
}

Enhanced Features

Account Classification

Automatic classification of accounts:

• Asset (1xxx): Cash, receivables, inventory
• Liability (2xxx): Payables, debt, accruals
• Equity (3xxx): Capital, retained earnings
• Revenue (4xxx): Sales, service income
• COGS (5xxx): Cost of goods sold
• Expense (6xxx-7xxx): Operating expenses
• Tax: VAT, GST, withholding tax

VAT Detection

Automatic detection of VAT patterns:

• EU standard rates (19-25%)
• Reduced rates (5-10%)
• GST/HST (Canada, Australia)

Transaction Patterns

Recognition of common patterns:

• SimpleSale, SaleWithVat
• SimplePurchase, PurchaseWithVat
• Payment, Receipt
• Payroll, Depreciation
• Intercompany, CostAllocation

Use Cases

• Financial close: Automate journal analysis
• Audit: Trace value flows, detect anomalies
• Consolidation: Identify elimination entries
• Compliance: VAT reporting, intercompany analysis

Payments

Crate: rustkernel-payments Kernels: 2 Feature: payments

Payment processing and flow analysis kernels for payment systems.

Kernel Overview

Kernel Details

PaymentProcessing

Processes and validates payment instructions.

ID: payments/processing Modes: Batch, Ring

Input

pub struct PaymentProcessingInput {
    pub payments: Vec<Payment>,
    pub validation_rules: Vec<ValidationRule>,
    pub processing_window: ProcessingWindow,
}

pub struct Payment {
    pub id: String,
    pub sender: PartyInfo,
    pub receiver: PartyInfo,
    pub amount: f64,
    pub currency: String,
    pub payment_type: PaymentType,
    pub value_date: u64,
    pub reference: String,
    pub remittance_info: Option<String>,
}

pub enum PaymentType {
    Wire,
    ACH,
    SEPA,
    SWIFT,
    RTP,  // Real-Time Payments
    FedNow,
}

Output

pub struct PaymentProcessingOutput {
    pub processed: Vec<ProcessedPayment>,
    pub rejected: Vec<RejectedPayment>,
    pub pending: Vec<String>,
    pub statistics: ProcessingStatistics,
}

pub struct ProcessedPayment {
    pub id: String,
    pub status: PaymentStatus,
    pub processing_time_us: u64,
    pub fees: f64,
}

pub struct RejectedPayment {
    pub id: String,
    pub reason: RejectionReason,
    pub failed_rules: Vec<String>,
}

Example

use rustkernel::payments::processing::{PaymentProcessing, PaymentProcessingInput};

let kernel = PaymentProcessing::new();

let result = kernel.execute(PaymentProcessingInput {
    payments: incoming_payments,
    validation_rules: default_rules(),
    processing_window: ProcessingWindow::Same_Day,
}).await?;

println!("Processed: {}", result.processed.len());
println!("Rejected: {}", result.rejected.len());

for rejection in result.rejected {
    println!("Rejected {}: {:?}", rejection.id, rejection.reason);
}

FlowAnalysis

Analyzes payment flows for patterns, anomalies, and liquidity insights.

ID: payments/flow-analysis Modes: Batch, Ring

Input

pub struct FlowAnalysisInput {
    pub payments: Vec<Payment>,
    pub analysis_type: FlowAnalysisType,
    pub time_window: TimeWindow,
}

pub enum FlowAnalysisType {
    VolumeAnalysis,
    NetworkAnalysis,
    AnomalyDetection,
    LiquidityForecasting,
}

Output

pub struct FlowAnalysisOutput {
    /// Flow statistics by counterparty
    pub counterparty_flows: Vec<CounterpartyFlow>,
    /// Detected anomalies
    pub anomalies: Vec<FlowAnomaly>,
    /// Network metrics
    pub network_metrics: NetworkMetrics,
    /// Liquidity forecast
    pub liquidity_forecast: Option<LiquidityForecast>,
}

pub struct CounterpartyFlow {
    pub counterparty: String,
    pub inflow_volume: f64,
    pub outflow_volume: f64,
    pub net_flow: f64,
    pub transaction_count: u32,
}

Example

use rustkernel::payments::flow::{FlowAnalysis, FlowAnalysisInput};

let kernel = FlowAnalysis::new();

let result = kernel.execute(FlowAnalysisInput {
    payments: daily_payments,
    analysis_type: FlowAnalysisType::NetworkAnalysis,
    time_window: TimeWindow::Days(30),
}).await?;

// Top counterparties by volume
for flow in result.counterparty_flows.iter().take(10) {
    println!("{}: in=${:.0}, out=${:.0}, net=${:.0}",
        flow.counterparty,
        flow.inflow_volume,
        flow.outflow_volume,
        flow.net_flow
    );
}

Ring Mode for Real-Time Processing

use rustkernel::payments::processing::PaymentProcessingRing;

let ring = PaymentProcessingRing::new();

// Process payments as they arrive
for payment in payment_stream {
    let result = ring.process(payment).await?;

    match result.status {
        PaymentStatus::Processed => send_confirmation(result),
        PaymentStatus::Rejected(reason) => notify_sender(reason),
        PaymentStatus::Pending => queue_for_review(result),
    }
}

Use Cases

• Payment hubs: Central payment processing
• Real-time payments: Instant payment validation
• Correspondent banking: SWIFT message processing
• Treasury: Cash position forecasting

Audit

Crate: rustkernel-audit Kernels: 2 Feature: audit

Financial audit and forensic analysis kernels.

Kernel Overview

Kernel Details

FeatureExtraction

Extracts features from financial data for audit analysis and anomaly detection.

ID: audit/feature-extraction Modes: Batch, Ring

Input

pub struct FeatureExtractionInput {
    pub transactions: Vec<AuditTransaction>,
    pub feature_config: FeatureConfig,
    pub entity_context: Option<EntityContext>,
}

pub struct AuditTransaction {
    pub id: String,
    pub timestamp: u64,
    pub amount: f64,
    pub account_from: String,
    pub account_to: String,
    pub entity_id: String,
    pub user_id: String,
    pub transaction_type: String,
    pub attributes: HashMap<String, String>,
}

pub struct FeatureConfig {
    pub temporal_features: bool,
    pub behavioral_features: bool,
    pub network_features: bool,
    pub benford_analysis: bool,
}

Output

pub struct FeatureExtractionOutput {
    /// Extracted features per transaction
    pub features: Vec<TransactionFeatures>,
    /// Aggregate features
    pub aggregate_features: AggregateFeatures,
    /// Benford's Law analysis
    pub benford_results: Option<BenfordResults>,
}

pub struct TransactionFeatures {
    pub transaction_id: String,
    /// Temporal features
    pub hour_of_day: u8,
    pub day_of_week: u8,
    pub is_weekend: bool,
    pub is_month_end: bool,
    /// Amount features
    pub amount_log: f64,
    pub round_amount_flag: bool,
    pub just_below_threshold: bool,
    /// Behavioral features
    pub velocity_1h: u32,
    pub velocity_24h: u32,
    pub deviation_from_mean: f64,
}

pub struct BenfordResults {
    pub first_digit_distribution: Vec<f64>,
    pub expected_distribution: Vec<f64>,
    pub chi_square_statistic: f64,
    pub p_value: f64,
    pub conformity_score: f64,
}

Example

use rustkernel::audit::feature_extraction::{FeatureExtraction, FeatureExtractionInput};

let kernel = FeatureExtraction::new();

let result = kernel.execute(FeatureExtractionInput {
    transactions: journal_entries,
    feature_config: FeatureConfig {
        temporal_features: true,
        behavioral_features: true,
        network_features: true,
        benford_analysis: true,
    },
    entity_context: None,
}).await?;

// Check Benford's Law conformity
if let Some(benford) = result.benford_results {
    if benford.conformity_score < 0.8 {
        println!("Warning: Data may not conform to Benford's Law");
        println!("Conformity: {:.1}%", benford.conformity_score * 100.0);
    }
}

// Find suspicious transactions
for feat in result.features {
    if feat.just_below_threshold && feat.is_weekend {
        println!("Suspicious: {} - just below threshold on weekend",
            feat.transaction_id
        );
    }
}

HypergraphConstruction

Builds hypergraphs representing complex multi-entity relationships.

ID: audit/hypergraph-construction Modes: Batch

A hypergraph allows edges to connect more than two nodes, capturing complex relationships like:

• A transaction involving multiple parties
• A document signed by multiple entities
• An event affecting multiple accounts

Input

pub struct HypergraphInput {
    pub events: Vec<AuditEvent>,
    pub entity_types: Vec<EntityType>,
    pub relationship_rules: Vec<RelationshipRule>,
}

pub struct AuditEvent {
    pub id: String,
    pub event_type: String,
    pub entities: Vec<EntityReference>,
    pub timestamp: u64,
    pub attributes: HashMap<String, String>,
}

pub struct EntityReference {
    pub entity_id: String,
    pub entity_type: EntityType,
    pub role: String,  // e.g., "sender", "approver", "beneficiary"
}

Output

pub struct HypergraphOutput {
    pub nodes: Vec<HypergraphNode>,
    pub hyperedges: Vec<Hyperedge>,
    pub metrics: HypergraphMetrics,
}

pub struct Hyperedge {
    pub id: String,
    pub nodes: Vec<String>,
    pub edge_type: String,
    pub weight: f64,
    pub attributes: HashMap<String, String>,
}

pub struct HypergraphMetrics {
    pub node_count: usize,
    pub hyperedge_count: usize,
    pub avg_hyperedge_size: f64,
    pub max_hyperedge_size: usize,
    pub connected_components: usize,
}

Example

use rustkernel::audit::hypergraph::{HypergraphConstruction, HypergraphInput};

let kernel = HypergraphConstruction::new();

let result = kernel.execute(HypergraphInput {
    events: audit_events,
    entity_types: vec![
        EntityType::User,
        EntityType::Account,
        EntityType::Document,
    ],
    relationship_rules: default_rules(),
}).await?;

// Find densely connected entity clusters
for component in result.connected_components() {
    if component.density > 0.8 {
        println!("Highly connected cluster: {:?}", component.entities);
    }
}

Use Cases

Internal Audit

• Journal entry testing
• Segregation of duties analysis
• Unusual transaction detection

External Audit

• Substantive testing sample selection
• Benford’s Law analysis
• Related party transaction identification

Fraud Investigation

• Network analysis of parties
• Pattern detection across time
• Relationship mapping

Regulatory Compliance

• SOX testing automation
• Audit trail analysis
• Control effectiveness testing

Articles

Technical deep-dives into RustKernels algorithms, implementation details, and use cases.

Featured Articles

Accounting Network Generation: Transforming Journal Entries to Directed Graphs

A comprehensive look at the GPU-accelerated transformation of double-entry bookkeeping journal entries into directed accounting networks. Covers the five solving methods, confidence calculation, VAT detection, and pattern recognition.

Topics covered:

• The accounting network problem
• Five solving methods (A-E) with confidence hierarchy
• Fixed-point arithmetic for financial precision
• Account classification and VAT detection
• Transaction pattern recognition
• Performance characteristics

Upcoming Articles

• Graph Analytics at Scale: PageRank and community detection on billion-edge graphs
• Real-Time Risk: Streaming VaR calculation with Ring kernels
• Process Mining with DFG: Automatically discovering business processes
• Compliance Patterns: Detecting AML patterns in transaction networks

Contributing Articles

Want to contribute an article? Articles should:

1. Focus on a specific kernel or algorithm
2. Explain the underlying theory
3. Show practical implementation details
4. Include code examples
5. Discuss performance characteristics

Submit proposals via GitHub issues.

Accounting Network Generation: Transforming Journal Entries to Directed Graphs

Published: January 2026 Domain: Accounting Kernels: NetworkGeneration, NetworkGenerationRing

Abstract

This article describes the GPU-accelerated transformation of double-entry bookkeeping journal entries into directed accounting networks. We implement five solving methods with decreasing confidence levels, enabling sophisticated analysis of value flows between accounts. The implementation includes automatic account classification, VAT/tax detection, transaction pattern recognition, and confidence boosting based on domain knowledge.

Introduction

Traditional accounting views journal entries as balanced debit/credit pairs following the fundamental equation:

Assets = Liabilities + Equity

Every transaction creates at least one debit and one credit, always balancing. However, understanding the flow of value between accounts requires transforming these entries into a directed graph representation where:

• Nodes represent accounts
• Edges represent flows (directed from debit accounts to credit accounts)
• Edge weights represent amounts transferred

This transformation enables powerful analytics:

• Flow tracing: Follow value through the organization
• Anomaly detection: Identify unusual patterns
• Intercompany analysis: Detect circular flows requiring elimination
• Audit trails: Trace specific amounts to source transactions

The challenge lies in determining which debit amount flows to which credit account when an entry has multiple lines.

The Solving Problem

Consider a simple journal entry:

Dr. Cash           $1,000
    Cr. Revenue              $1,000

The flow is trivial: Cash receives $1,000 from Revenue.

But what about:

Dr. Cash           $1,000
Dr. Receivables      $500
    Cr. Revenue              $1,200
    Cr. Deferred Revenue       $300

Which debit flows to which credit? There are multiple valid interpretations. Our algorithm provides a principled approach to solve this ambiguity while quantifying confidence.

The Five Solving Methods

We implement five methods in order of decreasing confidence. The algorithm tries each method in sequence until one succeeds.

Method A: Trivial 1-to-1 (Confidence: 1.0)

When applied: Exactly 1 debit line and 1 credit line.

This is deterministic. The single debit flows entirely to the single credit.

Entry:
  Dr. Cash $1,000
  Cr. Revenue $1,000

Result:
  Flow: Cash -> Revenue ($1,000) [confidence: 1.0]

Approximately 60% of entries in typical general ledgers are 2-line entries solved by Method A.

Method B: n-to-n Bijective Matching (Confidence: 0.95)

When applied: Equal count of debits and credits (n debits, n credits), where n <= 10.

Uses a two-phase greedy matching algorithm:

1. Phase 1: Match exact amounts (within tolerance)
2. Phase 2: Match remaining by order

Entry:
  Dr. Cash         $500
  Dr. Receivables  $300
  Cr. Sales        $500
  Cr. Service      $300

Phase 1 matches:
  Cash ($500) -> Sales ($500)      [exact match]
  Receivables ($300) -> Service ($300)  [exact match]

Result: Two flows with confidence 0.95

Method C: n-to-m Partition Matching (Confidence: 0.85)

When applied: Unequal counts of debits and credits, total lines <= 20.

Uses subset-sum matching to find which credits combine to match each debit amount.

For small n (<=12): Exhaustive search using bit manipulation (2^n combinations) For larger n: Greedy approximation (sorted descending)

Entry:
  Dr. Cash $800
  Cr. Revenue    $500
  Cr. Service    $300

Algorithm finds: {Revenue, Service} sums to $800

Result:
  Flow: Cash -> Revenue ($500) [confidence: 0.85]
  Flow: Cash -> Service ($300) [confidence: 0.85]

If no exact partition exists, falls back to proportional allocation with reduced confidence (0.765).

Method D: Aggregation (Confidence: 0.70)

When applied: Many lines (>20 total), aggregation enabled.

Aggregates to account level and allocates proportionally:

1. Sum all debits by account code
2. Sum all credits by account code
3. For each (debit_account, credit_account) pair:

   allocation = debit_amount * (credit_amount / total_credits)
   

Use case: Large allocation entries with many cost centers.

Method E: Entity Decomposition (Confidence: 0.50)

When applied: Multi-entity entries, decomposition enabled.

Decomposes by entity_id and attempts within-entity matching first:

1. Group debits by entity
2. Group credits by entity
3. Try matching within each entity
4. Cross-entity flows get additional 0.8x confidence multiplier

Use case: Intercompany transactions, consolidation entries.

Unsolvable Entries

If all methods fail or entry is unbalanced:

• Route all flows through suspense account
• Confidence: 0.0
• Provides audit trail for investigation

Fixed-Point Arithmetic

Financial calculations require exact precision. Floating-point arithmetic introduces rounding errors that compound over millions of transactions. We use 128-bit fixed-point arithmetic with 18 decimal places:

pub struct FixedPoint128 {
    pub value: i128,  // Scaled by 10^18
}

const SCALE: i128 = 1_000_000_000_000_000_000; // 10^18

impl FixedPoint128 {
    pub fn from_f64(v: f64) -> Self {
        Self {
            value: (v * SCALE as f64) as i128
        }
    }

    pub fn to_f64(&self) -> f64 {
        self.value as f64 / SCALE as f64
    }
}

This provides:

• Range: Up to ~170 trillion (sufficient for any practical amount)
• Precision: Exactly 18 decimal places
• Determinism: Same result across platforms

All amount comparisons use tolerance-aware equality:

impl FixedPoint128 {
    pub fn approx_eq(&self, other: &Self, tolerance: i128) -> bool {
        (self.value - other.value).abs() <= tolerance
    }
}

Enhanced Features

Account Classification

Accounts are automatically classified into standard categories:

pub enum AccountClass {
    Asset,              // 1xxx accounts
    Liability,          // 2xxx accounts
    Equity,             // 3xxx accounts
    Revenue,            // 4xxx accounts
    COGS,               // 5xxx accounts
    Expense,            // 6xxx-7xxx accounts
    OtherIncomeExpense, // 8xxx accounts
    Tax,                // VAT, GST, etc.
    Intercompany,       // Related party accounts
    Suspense,           // Clearing/suspense
    Unknown,            // Unclassified
}

Classification uses two strategies:

1. Numeric prefix: 1xxx = Asset, 2xxx = Liability, etc.
2. Keyword matching: “CASH”, “RECEIVABLE” -> Asset; “PAYABLE” -> Liability

impl AccountClass {
    pub fn from_account_code(code: &str) -> Self {
        // Try numeric classification first
        if let Some(first_digit) = code.chars().find(|c| c.is_ascii_digit()) {
            match first_digit {
                '1' => return AccountClass::Asset,
                '2' => return AccountClass::Liability,
                '3' => return AccountClass::Equity,
                '4' => return AccountClass::Revenue,
                '5' => return AccountClass::COGS,
                '6' | '7' => return AccountClass::Expense,
                '8' => return AccountClass::OtherIncomeExpense,
                _ => {}
            }
        }

        // Fall back to keyword matching
        let upper = code.to_uppercase();
        if upper.contains("VAT") || upper.contains("TAX") {
            AccountClass::Tax
        } else if upper.contains("CASH") || upper.contains("BANK") {
            AccountClass::Asset
        }
        // ... additional patterns
    }
}

VAT/Tax Detection

The system automatically detects VAT patterns by analyzing amount relationships:

pub struct VatDetector {
    known_rates: Vec<VatRate>,
    tolerance: f64,
}

pub struct VatRate {
    pub name: String,
    pub rate: f64,        // e.g., 0.20 for 20%
    pub jurisdiction: String,
}

Built-in rates include:

• EU: 19% (Germany), 20% (UK, France), 21% (Netherlands), 23% (Ireland), 25% (Sweden)
• Reduced: 5%, 7%, 10%
• GST/HST: 5% (Canada GST), 13%/15% (HST)

Detection algorithm:

pub fn detect_vat_split(&self, amounts: &[i128]) -> Option<VatPattern> {
    // Sort amounts descending
    let mut sorted = amounts.to_vec();
    sorted.sort_by(|a, b| b.cmp(a));

    // Try each pair: largest could be gross, second could be net
    for (gross, net) in pairs(&sorted) {
        let tax = gross - net;
        let implied_rate = tax as f64 / net as f64;

        // Check against known rates
        for rate in &self.known_rates {
            if (implied_rate - rate.rate).abs() < self.tolerance {
                return Some(VatPattern {
                    gross_amount: gross,
                    net_amount: net,
                    tax_amount: tax,
                    rate: rate.clone(),
                    // ... additional fields
                });
            }
        }
    }
    None
}

Transaction Pattern Recognition

14 common transaction patterns are automatically detected:

pub enum TransactionPattern {
    SimpleSale,        // Dr. Asset, Cr. Revenue
    SaleWithVat,       // Dr. Asset, Cr. Revenue + Tax
    SimplePurchase,    // Dr. Expense/Asset, Cr. Asset/Liability
    PurchaseWithVat,   // Dr. Expense + Tax, Cr. Liability
    Payment,           // Dr. Liability, Cr. Asset
    Receipt,           // Dr. Asset, Cr. Asset
    Payroll,           // Dr. Expense, Cr. Multiple Liabilities
    Depreciation,      // Dr. Expense, Cr. Contra-Asset
    Accrual,           // Dr. Expense, Cr. Liability
    AccrualReversal,   // Reverse of accrual
    Transfer,          // Dr. Asset, Cr. Asset (multiple)
    Intercompany,      // Cross-entity debits/credits
    CostAllocation,    // Multiple cost centers
    Adjustment,        // Miscellaneous adjustments
    Unknown,
}

Pattern detection examines:

1. Account classes on debit side
2. Account classes on credit side
3. Presence of tax accounts
4. Entity relationships

Confidence Boosting

Recognized patterns boost confidence scores:

Final confidence is capped at 1.0:

let base_confidence = method.confidence();
let pattern_boost = pattern.confidence_boost();
let final_confidence = (base_confidence + pattern_boost).min(1.0);

Data Structures

AccountingFlow

The primary output structure:

pub struct AccountingFlow {
    pub flow_id: String,
    pub entry_id: u64,
    pub from_account: String,
    pub to_account: String,
    pub amount: FixedPoint128,
    pub timestamp: u64,
    pub method: SolvingMethod,
    pub confidence: f64,
    pub from_entity: String,
    pub to_entity: String,
    pub currency: String,
    pub source_lines: Vec<u32>,

    // Enhanced fields
    pub from_account_class: Option<AccountClass>,
    pub to_account_class: Option<AccountClass>,
    pub pattern: Option<TransactionPattern>,
    pub is_tax_flow: bool,
    pub vat_rate: Option<f64>,
    pub is_intercompany: bool,
    pub confidence_factors: Vec<String>,
}

AccountingNetwork

The complete network representation:

pub struct AccountingNetwork {
    pub flows: Vec<AccountingFlow>,
    pub accounts: HashSet<String>,
    pub account_index: HashMap<String, usize>,
    pub adjacency: HashMap<String, Vec<(String, usize)>>,
    pub stats: NetworkGenerationStats,
}

impl AccountingNetwork {
    pub fn outgoing_flows(&self, account: &str) -> Vec<&AccountingFlow> {
        // Returns all flows from this account
    }

    pub fn incoming_flows(&self, account: &str) -> Vec<&AccountingFlow> {
        // Returns all flows to this account
    }

    pub fn total_volume(&self) -> f64 {
        self.flows.iter().map(|f| f.amount.to_f64()).sum()
    }

    pub fn weighted_confidence(&self) -> f64 {
        let total_amount: f64 = self.flows.iter()
            .map(|f| f.amount.to_f64())
            .sum();

        if total_amount == 0.0 {
            return self.flows.iter()
                .map(|f| f.confidence)
                .sum::<f64>() / self.flows.len() as f64;
        }

        self.flows.iter()
            .map(|f| f.confidence * f.amount.to_f64())
            .sum::<f64>() / total_amount
    }
}

Usage Example

use rustkernel::accounting::network_generation::{
    NetworkGeneration,
    NetworkGenerationInput,
    NetworkGenerationConfig,
};

// Configure the kernel
let config = NetworkGenerationConfig {
    amount_tolerance: 0.01,
    max_lines_method_b: 10,
    max_lines_method_c: 20,
    enable_aggregation: true,
    enable_decomposition: true,
    suspense_account: "SUSPENSE".to_string(),
    strict_balance: false,

    // Enhanced features
    enable_pattern_matching: true,
    enable_vat_detection: true,
    apply_confidence_boost: true,
    annotate_account_classes: true,
    custom_vat_rates: vec![],
};

let kernel = NetworkGeneration::with_config(config);

// Process journal entries
let result = kernel.execute(NetworkGenerationInput {
    entries: journal_entries,
    config: None,  // Use kernel's config
}).await?;

// Analyze results
println!("Generated {} flows", result.flows.len());
println!("Total volume: ${:.2}", result.stats.total_volume);
println!("Weighted confidence: {:.2}%", result.stats.weighted_confidence * 100.0);

// Method distribution
println!("\nMethod distribution:");
println!("  Method A (1:1): {}", result.stats.method_a_count);
println!("  Method B (n:n): {}", result.stats.method_b_count);
println!("  Method C (n:m): {}", result.stats.method_c_count);
println!("  Method D (agg): {}", result.stats.method_d_count);
println!("  Method E (dec): {}", result.stats.method_e_count);

// Pattern analysis
println!("\nTransaction patterns:");
println!("  Sales: {}", result.stats.sales_pattern_count);
println!("  Purchases: {}", result.stats.purchase_pattern_count);
println!("  Payments: {}", result.stats.payment_pattern_count);
println!("  Payroll: {}", result.stats.payroll_pattern_count);
println!("  Intercompany: {}", result.stats.intercompany_count);

// VAT analysis
println!("\nVAT detection:");
println!("  VAT entries: {}", result.stats.vat_entries_count);
println!("  Total VAT: ${:.2}", result.stats.total_vat_amount);

Performance Characteristics

Typical Distribution

For a standard GL with 100,000 entries:

Overall weighted confidence: ~0.94

Ring Mode for Streaming

For real-time processing, use Ring mode:

use rustkernel::accounting::network_generation::NetworkGenerationRing;

let ring = NetworkGenerationRing::new();

// Add entries as they arrive
ring.add_entry(entry).await?;

// Query flows within time window
let flows = ring.query_flows(start_time, end_time).await?;

// Get current statistics
let stats = ring.get_statistics().await?;

Conclusion

The Accounting Network Generation kernel provides a robust, GPU-accelerated method for transforming traditional journal entries into graph structures. The five-method hierarchy balances precision with practicality, while enhanced features like VAT detection and pattern recognition add domain intelligence to the analysis.

This enables sophisticated applications:

• Audit analytics: Trace flows, detect anomalies
• Consolidation: Identify intercompany eliminations
• Compliance: Analyze tax flows, verify postings
• Forensics: Follow money through the organization

The implementation demonstrates how GPU acceleration can be applied to accounting workloads, achieving throughputs suitable for even the largest enterprise general ledgers.

References

1. Hardware Accelerated Method for Accounting Network Generation (Internal paper)
2. Double-Entry Bookkeeping and the Fundamental Accounting Equation
3. Graph-Based Financial Analysis Techniques
4. Fixed-Point Arithmetic for Financial Applications

Changelog

All notable changes to RustKernels are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

[0.4.0] - 2026-02-07

Added

Production-Ready Kernel Execution

• TypeErasedBatchKernel: Bridges typed BatchKernel<I, O> to BatchKernelDyn via JSON serialization, enabling REST/gRPC dispatch without compile-time type knowledge
• TypeErasedRingKernel: Equivalent wrapper for ring kernels
• Factory Registration: register_batch_typed(factory) with automatic type inference from BatchKernel<I, O> implementations
• Metadata Registration: register_batch_metadata_from(factory) and register_ring_metadata_from(factory) for discovery-only registration
• Registry Execution: execute_batch(kernel_id, input_json) convenience method for type-erased execution

Real Ecosystem Execution (Replacing All Stubs)

• Axum: execute_kernel() now performs real batch kernel dispatch with configurable timeout; ring kernels return HTTP 422 with guidance
• Tower: KernelService::execute() performs real batch kernel dispatch
• Tonic gRPC: execute_kernel() performs real execution with gRPC deadline support; exceeded deadlines return DEADLINE_EXCEEDED
• Actix: Actor handler performs real execution via tokio::task::block_in_place bridge
• Health endpoint: Aggregated component health with registry status and error rate
• Metrics endpoint: Per-domain kernel counts, batch/ring breakdown, error rate

Deep RingKernel 0.4.2 Integration

• Bidirectional domain conversion (Domain::to_ring_domain(), Domain::from_ring_domain())
• New re-exports: ControlBlock, Backend, KernelStatus, RuntimeMetrics, K2KConfig, Priority
• Submodule re-exports: checkpoint, dispatcher, health, pubsub
• Ring message type ID ranges aligned with ringkernel_core::domain::Domain base offsets

Changed

• Upgraded to RingKernel 0.4.2 from 0.3.1
• All 14 domain crates now use factory-based registration (register_batch_typed, register_batch_metadata_from, register_ring_metadata_from)
• Ecosystem integrations execute real kernels instead of returning mock responses
• Updated prelude with BatchKernelDyn, RingKernelDyn, TypeErasedBatchKernel, TypeErasedRingKernel

[0.3.0] - 2026-01-28

Added

New Kernels (24 kernels added, bringing total to 106)

• Graph: GNNInference, GraphAttention, TopologicalSort, CycleDetection, ShortestPath, BipartiteMatching, GraphColoring
• ML: EmbeddingGeneration, SemanticSimilarity, SecureAggregation, DrugInteractionPrediction, ClinicalPathwayConformance, StreamingIsolationForest, AdaptiveThreshold, SHAPValues, FeatureImportance
• Compliance: FlowReversalPattern, FlowSplitRatio
• Process Intelligence: DigitalTwin, NextActivityPrediction, EventLogImputation
• Risk: CorrelationStress
• Accounting: DuplicateDetection, CurrencyConversion

Enterprise Enhancements

• Ring message definitions for all 14 domains with #[derive(RingMessage)]
• K2K coordination patterns: IterativeState, ScatterGatherState, FanOutTracker, PipelineTracker
• Domain-specific Ring message type ID ranges (100–799)

Changed

• Upgraded to RingKernel 0.3.1
• Graph analytics expanded from 21 to 28 kernels
• ML expanded from 8 to 17 kernels
• Risk analytics expanded from 4 to 5 kernels
• Process intelligence expanded from 4 to 7 kernels
• Accounting expanded from 7 to 9 kernels
• Compliance expanded from 9 to 11 kernels

[0.2.0] - 2026-01-19

Added

Enterprise Security (rustkernel-core/src/security/)

• Authentication: JWT and API key validation via AuthConfig
• RBAC: Role-based access control with KernelPermission (Execute, Configure, Monitor, Admin)
• Multi-tenancy: Tenant isolation with TenantId and resource quotas
• Secrets Management: SecretStore abstraction for credential management
• Security Context: Unified context for auth/tenant/permission propagation

Observability (rustkernel-core/src/observability/)

• Metrics: Prometheus-compatible metrics via KernelMetrics
• Distributed Tracing: OTLP export support via KernelTracing
• Structured Logging: Kernel context propagation with configurable levels
• Alerting: SLO-based alerts with AlertRule and multiple notification channels

Resilience Patterns (rustkernel-core/src/resilience/)

• Circuit Breaker: Failure isolation with configurable thresholds
• Retry: Exponential backoff with jitter via RetryConfig
• Timeouts: Deadline propagation in K2K chains via DeadlineContext
• Health Checks: Liveness, readiness, and startup probes via HealthProbe
• Recovery Policies: Configurable recovery strategies for kernel failures

Runtime Lifecycle (rustkernel-core/src/runtime/)

• Lifecycle State Machine: Starting -> Running -> Draining -> Stopped
• Runtime Presets: Development, production, and high-performance configurations
• Graceful Shutdown: Drain period with active connection tracking
• Configuration Validation: Runtime parameter validation with hot reload support

Memory Management (rustkernel-core/src/memory/)

• Size-Stratified Pooling: KernelMemoryManager with bucket-based allocation
• Pressure Handling: Configurable thresholds with PressureLevel enum
• Multi-Phase Reductions: InterPhaseReduction<T> for iterative algorithms
• Analytics Contexts: Workload-specific buffer management via AnalyticsContextManager
• Sync Modes: Cooperative, SoftwareBarrier, and MultiLaunch synchronization

Production Configuration (rustkernel-core/src/config/)

• Unified Config: ProductionConfig combining all enterprise settings
• Builder Pattern: ProductionConfigBuilder with fluent API
• Environment Loading: from_env() with RUSTKERNEL_* variable overrides
• File Loading: TOML configuration file support via from_file()

Ecosystem Integrations (rustkernel-ecosystem/)

• New Crate: rustkernel-ecosystem for service deployments
• Axum REST API: KernelRouter with endpoints for kernels, execute, health, metrics
• Tower Middleware: TimeoutLayer, RateLimiterLayer, KernelService
• gRPC Server: KernelGrpcServer via Tonic
• Actix Actors: KernelActor with message handlers

Enhanced Core Traits

• GpuKernel: Added health_check(), shutdown(), refresh_config() methods
• BatchKernel: Added execute_with_context() for auth/tenant propagation
• RingKernelHandler: Added handle_secure() for security context
• New Trait: CheckpointableKernel for recovery/restart support
• New Trait: DegradableKernel for graceful degradation
• New Trait: IterativeKernel for multi-pass algorithms

CLI Enhancements

• rustkernel runtime status|show|init — Runtime lifecycle management
• rustkernel health [--format json] — Component health checks
• rustkernel config show|validate|generate|env — Configuration management

Changed

• Upgraded to RingKernel 0.3.1 from 0.2.0
• Workspace now includes 19 crates (added rustkernel-ecosystem)
• Updated Tokio to 1.48
• Enhanced prelude with all enterprise module exports

[0.1.1] - 2026-01-15

Changed

• Renamed crate from rustkernel to rustkernels (crate name taken on crates.io)
• Added consistent README files for all 18 crates
• Resolved all compiler warnings for clean build
• Fixed User-Agent header in crates.io API requests

[0.1.0] - 2026-01-12

Added

Infrastructure

• rustkernel facade crate with domain re-exports
• rustkernel-core with core traits, registry, K2K messaging
• rustkernel-derive with #[gpu_kernel] and #[derive(KernelMessage)] macros
• rustkernel-cli command-line interface

82 Kernels across 14 Domains

• Graph Analytics (21): PageRank, DegreeCentrality, BetweennessCentrality, ClosenessCentrality, EigenvectorCentrality, KatzCentrality, ModularityScore, LouvainCommunity, LabelPropagation, JaccardSimilarity, CosineSimilarity, AdamicAdarIndex, CommonNeighbors, GraphDensity, AveragePathLength, ClusteringCoefficient, ConnectedComponents, FullGraphMetrics, TriangleCounting, MotifDetection, KCliqueDetection
• Statistical ML (8): KMeans, DBSCAN, HierarchicalClustering, IsolationForest, LocalOutlierFactor, EnsembleVoting, LinearRegression, RidgeRegression
• Compliance (9): CircularFlowRatio, ReciprocityFlowRatio, RapidMovement, AMLPatternDetection, KYCScoring, EntityResolution, SanctionsScreening, PEPScreening, TransactionMonitoring
• Temporal Analysis (7): ARIMAForecast, ProphetDecomposition, ChangePointDetection, TimeSeriesAnomalyDetection, SeasonalDecomposition, TrendExtraction, VolatilityAnalysis
• Risk Analytics (4): CreditRiskScoring, MonteCarloVaR, PortfolioRiskAggregation, StressTesting
• Banking (1): FraudPatternMatch
• Behavioral Analytics (6): BehavioralProfiling, AnomalyProfiling, FraudSignatureDetection, CausalGraphConstruction, ForensicQueryExecution, EventCorrelationKernel
• Order Matching (1): OrderMatchingEngine
• Process Intelligence (4): DFGConstruction, PartialOrderAnalysis, ConformanceChecking, OCPMPatternMatching
• Clearing (5): ClearingValidation, DVPMatching, NettingCalculation, SettlementExecution, ZeroBalanceFrequency
• Treasury (5): CashFlowForecasting, CollateralOptimization, FXHedging, InterestRateRisk, LiquidityOptimization
• Accounting (7): ChartOfAccountsMapping, JournalTransformation, GLReconciliation, NetworkAnalysis, TemporalCorrelation, NetworkGeneration, NetworkGenerationRing
• Payments (2): PaymentProcessing, FlowAnalysis
• Audit (2): FeatureExtraction, HypergraphConstruction

Infrastructure Features

• Batch and Ring execution modes
• K2K (kernel-to-kernel) messaging patterns
• Fixed-point arithmetic for financial precision
• Enterprise licensing system
• Feature flags for selective compilation

Version History

Migration Guides

From 0.3.x to 0.4.0

1. Registration: Replace register_metadata(kernel.metadata().clone()) with factory-based methods:
   • register_batch_typed(MyKernel::new) for kernels implementing BatchKernel<I, O>
   • register_batch_metadata_from(MyKernel::new) for metadata-only batch kernels
   • register_ring_metadata_from(MyKernel::new) for ring kernels
2. Execution: Use registry.execute_batch(id, json_bytes) for type-erased execution
3. Ecosystem: All service endpoints now execute real kernels — remove any mock/fallback code

From DotCompute (C#)

RustKernels is a Rust port of DotCompute. Key differences:

1. Async execution: All kernel execution is async
2. Ownership: Rust ownership model affects API design
3. Error handling: Uses Result<T, E> instead of exceptions
4. Ring messages: Use rkyv serialization instead of protobuf

Contributing

Thank you for your interest in contributing to RustKernels!

Code of Conduct

This project follows the Rust Code of Conduct. Please be respectful and constructive in all interactions.

Getting Started

Development Setup

1. Clone the repository:

   git clone https://github.com/mivertowski/RustKernels.git
   cd RustKernels
   

2. Ensure RustCompute is available:

   # Clone alongside RustKernels
   cd ..
   git clone https://github.com/mivertowski/RustCompute.git
   

3. Build and test:

   cd RustKernels
   cargo build --workspace
   cargo test --workspace
   

Development Commands

# Format code
cargo fmt --all

# Lint
cargo clippy --all-targets --all-features -- -D warnings

# Run specific domain tests
cargo test --package rustkernel-graph

# Build documentation
cargo doc --workspace --no-deps --open

# Check all features compile
cargo check --all-features

Contributing Code

Types of Contributions

• Bug fixes: Fix issues in existing kernels
• New kernels: Add kernels to existing domains
• Documentation: Improve docs, add examples
• Performance: Optimize existing implementations
• Tests: Increase test coverage

Pull Request Process

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: cargo test --workspace
5. Run lints: cargo clippy --all-targets -- -D warnings
6. Format code: cargo fmt --all
7. Commit with clear messages
8. Open a Pull Request

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat(graph): add triangle counting kernel
fix(accounting): correct VAT detection for reduced rates
docs(readme): update kernel count
test(ml): add edge cases for kmeans

Adding a New Kernel

1. Define the Kernel Struct

use rustkernel_core::{GpuKernel, KernelMetadata, Domain, KernelMode};

#[derive(Debug, Clone)]
pub struct MyNewKernel {
    metadata: KernelMetadata,
}

impl MyNewKernel {
    pub fn new() -> Self {
        Self {
            metadata: KernelMetadata {
                id: "domain/my-new-kernel".to_string(),
                mode: KernelMode::Batch,
                domain: Domain::MyDomain,
                description: "Description of what this kernel does".to_string(),
                expected_throughput: 100_000,
                target_latency_us: 50.0,
                requires_gpu_native: false,
                version: 1,
            },
        }
    }
}

impl GpuKernel for MyNewKernel {
    fn metadata(&self) -> &KernelMetadata {
        &self.metadata
    }
}

2. Implement BatchKernel

use rustkernel_core::BatchKernel;

impl BatchKernel<MyInput, MyOutput> for MyNewKernel {
    async fn execute(&self, input: MyInput) -> Result<MyOutput> {
        // Implementation
    }
}

3. Add Input/Output Types

In messages.rs:

#[derive(Debug, Clone)]
pub struct MyInput {
    pub data: Vec<f64>,
    pub config: MyConfig,
}

#[derive(Debug, Clone)]
pub struct MyOutput {
    pub result: Vec<f64>,
    pub statistics: Stats,
}

4. Add Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_my_new_kernel_basic() {
        let kernel = MyNewKernel::new();
        let input = MyInput { /* ... */ };
        let result = kernel.execute(input).await.unwrap();
        assert!(/* expected conditions */);
    }

    #[test]
    fn test_my_new_kernel_metadata() {
        let kernel = MyNewKernel::new();
        assert_eq!(kernel.metadata().id, "domain/my-new-kernel");
    }
}

5. Register the Kernel

In the domain’s lib.rs:

pub fn register_all(registry: &mut KernelRegistry) -> Result<()> {
    registry.register_batch(MyNewKernel::new())?;
    // ... other registrations
    Ok(())
}

6. Update Documentation

• Add kernel to domain’s documentation page
• Update kernel count if needed
• Add to changelog

Code Style

Rust Style

• Follow standard Rust idioms
• Use rustfmt formatting
• Address all clippy warnings
• Document public APIs with /// comments

Naming Conventions

• Kernels: PascalCase (e.g., PageRank, MonteCarloVaR)
• Kernel IDs: kebab-case (e.g., graph/page-rank)
• Functions/methods: snake_case
• Constants: SCREAMING_SNAKE_CASE

Error Handling

• Use Result<T, KernelError> for fallible operations
• Provide meaningful error messages
• Don’t panic in library code

Testing Guidelines

Test Categories

1. Unit tests: Test individual functions
2. Integration tests: Test kernel execution
3. Property tests: For numerical algorithms (when applicable)

Test Naming

#[test]
fn test_{function}_{scenario}_{expected_result}() {
    // e.g., test_pagerank_empty_graph_returns_empty()
}

Coverage Goals

• New code should have >80% test coverage
• Critical paths should have 100% coverage

Questions?

• Open a GitHub issue for bugs or feature requests
• Use discussions for questions
• Email maintainers for sensitive issues

Thank you for contributing!