ArchX Sovereign v3.0 — Fluent Performance Runtime

Adaptive Intelligence. Sovereign Ergonomics.

ArchX v3.0 is a high-performance, adaptive runtime library designed for systems programming in Rust. It introduces the Sovereign Fluent API, a unified, chainable interface for CPU, GPU, and Hybrid compute.

🚀 Quick Start

Add ArchX to your Cargo.toml:

[dependencies]

archx = "3.0"

Basic Vector Addition

use archx::{ArchX, Policy};

fn main() -> archx::ArchXResult<()> {
    let a = vec![1.0; 1000];
    let b = vec![2.0; 1000];
    let mut out = vec![0.0; 1000];

    ArchX::compute()
        .with_policy(Policy::Balanced)
        .add(&a, &b, &mut out)?;
        
    Ok(())
}

🛠️ Core API & Execution Modes

ArchX supports multiple execution modes through a single entry point:

CPU/SIMD: Parallel execution using host threads and SIMD instructions (AVX2, AVX-512).
GPU (Adaptive): Offloads heavy computation to GPU backends (Vulkan/CUDA).
Hybrid: Cooperative scheduling that splits workloads between CPU and GPU.
Async: Non-blocking background execution.

GPU Configuration

use archx::{archx, GpuPolicy};

archx()
    .with_gpu(GpuPolicy::ForceGpu) // Force GPU execution
    .sum(&data)?;

📊 Hybrid Execution & Profiling

ArchX intelligently splits workloads based on hardware state and workload size.

Collecting Metrics

use archx::{archx, Policy};

let metrics = archx()
    .profile(true)
    .with_policy(Policy::Performance)
    .run(|| {
        // Your complex task
    });

// Use the built-in profiler visualization
archx::get_profiler().print_summary();

🧮 Mathematical Operations

The Fluent API provides high-level math primitives:

Method	Operation	Description
`add`	`out = a + b`	Vectorized element-wise addition
`sub`	`out = a - b`	Vectorized element-wise subtraction
`mul`	`out = a * b`	Vectorized element-wise multiplication
`dot`	`sum(a * b)`	Scalar dot product
`sum`	`sum(a)`	Parallel reduction sum

Safety Modes

use archx::{archx, MathMode};

archx()
    .with_mode(MathMode::Safe) // Enable overflow checking
    .mul(&a, &b, &mut out)?;

⚡ Advanced Usage

Asynchronous Operations

Avoid blocking the main thread for massive datasets:

use archx::{add_async, WorkloadHints};

#[tokio::main]
async fn main() {
    let hints = WorkloadHints { prefer_gpu: true, ..Default::default() };
    let result = add_async(vec![1.0; 10_000], vec![2.0; 10_000], hints).await;
}

⚠️ Error Handling

All ArchX operations return ArchXResult<T>. Handle errors gracefully:

use archx::ArchXError;

match archx().add(&a, &b, &mut out) {
    Ok(_) => println!("Success!"),
    Err(e) => match e {
        ArchXError::InvalidInput(msg) => eprintln!("Input error: {}", msg),
        ArchXError::GpuError(msg) => eprintln!("GPU failure: {}", msg),
        ArchXError::ArithmeticOverflow => eprintln!("Result too large!"),
        _ => eprintln!("ArchX Error: {:?}", e),
    }
}

🧪 Verification

Run flagship demo:

cargo run --example v3_sovereign_gpu_demo

archx 3.0.1