core/docs/benchmarks/apple-uma-rust-baseline.md

Apple UMA Rust Baseline Report

Engineering guide for generating a Rust-enabled Apple Silicon UMA mechanical sympathy benchmark report. Python remains the semantic source of truth; Rust is the incumbent native algebra backend activated only when explicitly requested.

See also:

• benchmarks/apple_uma_mechanical_sympathy.py — benchmark harness
• docs/outreach/apple-silicon-support-brief.md — claim-safe outreach framing
• docs/adr/ADR-0235-apple-silicon-uma-acceleration-lanes.md — staged acceleration roadmap

Prerequisites

• macOS arm64 (Apple Silicon) recommended; benchmark runs on any platform
• Python environment with repo dependencies (uv sync)
• Rust toolchain (cargo, rustc) for building core_rs
• maturin (installed automatically by core rust build)

Install / build core_rs

From the repository root:

# Verify Rust toolchain
cargo --version

# Build and install core_rs into the active Python environment
core rust build

# Confirm activation (optional; exits nonzero if inactive)
core rust status
core rust status --require-active

Manual equivalent:

uv pip install maturin
python -m maturin develop --release --manifest-path core-rs/Cargo.toml

The crate lives at core-rs/ (module-name = "core_rs" in core-rs/pyproject.toml).

Activate the Rust backend

Rust is opt-in. Importing core_rs alone does not activate native dispatch. Set:

export CORE_BACKEND=rust

Accepted aliases: rust, core_rs, rs (case-insensitive).

Verify in Python:

from algebra.backend import using_rust
assert using_rust() is True

Or:

CORE_BACKEND=rust core rust status --require-active

Run the benchmark

CORE_BACKEND=rust uv run python -m benchmarks.apple_uma_mechanical_sympathy --json
CORE_BACKEND=rust uv run python -m benchmarks.apple_uma_mechanical_sympathy --write-report

CORE_BACKEND=rust uv run python -m core.cli bench --suite apple-uma --json
CORE_BACKEND=rust uv run python -m core.cli bench --suite apple-uma --write-report

Reports are written to:

• evals/reports/apple_uma_mechanical_sympathy_latest.json
• evals/reports/apple_uma_mechanical_sympathy_latest.md

What changes when Rust is active

When CORE_BACKEND=rust, core_rs is installed, and using_rust() is true, the report should show:

Field	Rust-active expectation
machine.using_rust	true
machine.core_rs.import_succeeded	true
backend_status.native_status	rust_active
backend_status.diffusion_step_eligible	true
backend_status.vault_recall_rust_zero_copy_eligible	true
tracks.diffusion_step.skipped	false
tracks.exact_cga_recall.cases[].rust_zero_copy_input_eligible	true (contiguous f32)
claim_safety_audit.rust_backend_notes	Notes native active + scalar copy paths remain
copy_zero_copy_truth_table	Includes Rust vault_recall and diffusion_step zero-copy input rows

Scalar Cl(4,1) ops (geometric_product, cga_inner, versor_condition, versor_apply) still report copy paths via extract_f32_slice until PR C (scalar zero-copy boundary cleanup). This is intentional and honest.

Python fallback (Rust unavailable)

When core_rs is not installed or CORE_BACKEND is unset:

Field	Python-fallback expectation
machine.using_rust	false
backend_status.native_status	python_fallback or rust_requested_unavailable
tracks.diffusion_step.skipped	true with explicit reason
claim_safety_audit.rust_backend_notes	Documents Python fallback / activation hint
copy_zero_copy_truth_table	diffusion_step row shows skipped — Rust unavailable

Do not publish a Rust-active report without actually running the commands above on hardware where using_rust() is true.

Explicit non-claims

This benchmark and report do not claim:

• MLX as semantic backend or acceleration (future ADR lane)
• CoreML or Neural Engine acceleration
• "Zero-copy everywhere"
• Token-generation throughput
• ANN / approximate recall
• A fixed hardware speedup multiplier
• Apple endorsement, partnership, or product integration

Validation

After generating a report:

uv run python -m pytest -q tests/test_apple_uma_mechanical_sympathy_benchmark.py

When Rust is available:

CORE_BACKEND=rust cargo test --manifest-path core-rs/Cargo.toml
CORE_BACKEND=rust uv run python -m pytest -q tests/test_cga_inner_rust_parity.py

Troubleshooting

Symptom	Likely cause	Fix
using_rust(): false with CORE_BACKEND=rust	core_rs not built	core rust build
using_rust(): false, core_rs importable	CORE_BACKEND unset	export CORE_BACKEND=rust
diffusion_step.skipped: true	Rust not active	Follow activation steps above
native_status: rust_requested_unavailable	Import failed	Rebuild core_rs; check cargo toolchain

Next lane (PR C)

Scalar Rust zero-copy boundary cleanup (feat/rust-scalar-cl41-zero-copy-boundary) targets extract_f32_slice copy tax on scalar hot paths. That work is separate from this baseline report lane and requires parity gates before any copy-boundary claims change.