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:

1. CPU/SIMD: Parallel execution using host threads and SIMD instructions (AVX2, AVX-512).
2. GPU (Adaptive): Offloads heavy computation to GPU backends (Vulkan/CUDA).
3. Hybrid: Cooperative scheduling that splits workloads between CPU and GPU.
4. 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

Designed with ❤️ by AkramStation. MIT / Apache-2.0 © 2026 AkramStation