Repository navigation
GALAXY v0.5.0 — Deterministic Host-Aware CPU Execution and Memory-Bounded Runtime Architecture
#Release Notes
GALAXY v0.5.0 advances the native CPU runtime introduced in v0.4.0 into a layered, deterministic optimization architecture.
The central change is not one isolated benchmark improvement. The CPU runtime now has a complete progression from SIMD feasibility testing, through bounded worker-local memory, guarded production integration, persistent worker pools, topology-aware scheduling, and finally calibrated host-aware automatic promotion.
Throughout this work the canonical execution path remains available as the correctness oracle. Optimized paths are required to preserve exact deterministic checksum parity and fail closed when that contract is violated.
This release incorporates the work from PRs #10 through #14.
Highlights
- Deterministic SIMD/autovectorization probe
- AVX2 / AVX-512 code-generation evidence tooling
- Worker-local structure-of-arrays CPU execution
- Bounded per-worker particle tiles instead of full-resident optimized state
- Production
bench-soa/verify-soaexecution paths - Persistent worker pools with reusable local buffers
- Best-effort physical-core topology detection
- Explicit physical-first and logical/SMT scheduling policies
- Host-aware automatic runtime and tile calibration
- Exact streaming canonical BAM-LUT oracle
- 5% promotion margin before leaving the canonical path
- Effective tile-shape-faithful calibration
- Requested frame-depth-faithful calibration
- Full persistent startup + teardown lifecycle accounting
- Explicit topology, oracle, lifecycle and RSS evidence scopes
- Cross-platform native CPU CI on Linux x86-64, Linux ARM64, macOS ARM64 and Windows x86-64
- New memory-wall / heterogeneous execution roadmap
CPU optimization sequence
v0.5.0 freezes the following CPU architecture progression:
PR #10 SIMD / autovectorization feasibility
PR #11 worker-local bounded SoA execution
PR #12 guarded production SoA integration
PR #13 persistent workers + topology-aware scheduling
PR #14 calibrated host-aware promotion with fail-closed parity
Each stage preserved the established deterministic BAM-LUT and wrapping-u64 checksum contract before the next stage was allowed to build on it.
PR #10 — Deterministic CPU SIMD probe
PR #10 introduced an isolated deterministic probe for GALAXY's contribution-hash stage.
The probe:
converts the contribution inputs into a structure-of-arrays batch form;
compares every result against the canonical scalar contribution function;
requires repeated checksum stability;
records compile-time and runtime CPU feature evidence;
compares generic x86-64 and target-cpu=native builds;
extracts the batch symbol for disassembly inspection;
records XMM / YMM / ZMM evidence when available;
rejects missing or malformed disassembly evidence rather than silently passing.
The local Ryzen 9 5950X evidence recorded:
generic median 34,942,130 ns
native median 10,742,437 ns
native speedup 3.252719099x
time reduction 69.256491%
checksum e3f89b31c3f4c4e8
The generic build used legacy SSE2 packed operations while the native Zen 3 build used AVX2/VEX packed operations.
This result was deliberately treated as an isolated kernel result, not an end-to-end GALAXY speedup.
PR #11 — Worker-local bounded SoA execution
PR #11 moved the SIMD-friendly contribution shape into a complete BAM-LUT execution experiment.
The reference path retained a full resident array-of-structures representation.
The optimized path instead uses:
logical particle range
↓
bounded worker-local compact SoA tile
↓
BAM-LUT projection
↓
SIMD-friendly contribution batch
↓
wrapping-u64 local reduction
↓
deterministic worker reduction
Each worker owns compact particle fields:
id_lo
id_hi
radius_q16
initial_bam
delta_bam
plus bounded x/y/contribution scratch storage.
The important memory change is architectural:
reference working state ∝ total resident population
worker-local SoA working state ∝ workers × tile size
The optimized path therefore no longer requires a complete resident particle array merely to execute the deterministic workload.
The experiment also added:
generic/native worker and tile sweeps;
reference-vs-SoA checksum gates;
Linux peak-RSS evidence in isolated benchmark processes;
exact worker-count invariance tests;
actual allocated tile-capacity reporting;
decoded SIMD evidence for the production-shaped hash batch;
clean benchmark-output directory requirements.
A timing result is invalid if checksum parity fails.
PR #12 — Guarded production SoA integration
The successful worker-local SoA path was integrated into the production galaxy-cpu binary without silently replacing the canonical runtime.
New commands:
galaxy-cpu verify-soa [--workers N] [--tile N]
galaxy-cpu bench-soa
[--logical U64] [--resident N] [--frames N]
[--workers N] [--tile N] [--repeats N]
[--seed U32] [--receipt PATH]
The existing canonical commands remain:
galaxy-cpu verify
galaxy-cpu bench
Integrated SoA receipts identify the path explicitly:
schema = galaxy.cpu-runtime-soa-receipt.v1
runtime = galaxy-cpu
execution_mode = worker-local-soa-guarded
guarded_opt_in = true
canonical_fallback = bench
The optimized path remains explicit and auditable rather than becoming an invisible default.
The production dispatcher/build arrangement was also hardened so the canonical runtime and optimized modules are exposed through one controlled galaxy-cpu command surface.
PR #13 — Persistent topology-aware worker execution
PR #13 removed repeated worker creation from steady-state optimized execution.
New commands:
galaxy-cpu verify-soa-pool
[--workers N] [--tile N]
[--schedule physical-first|logical]
galaxy-cpu bench-soa-pool
[--logical U64] [--resident N] [--frames N]
[--workers N] [--tile N]
[--schedule physical-first|logical]
[--repeats N] [--seed U32] [--receipt PATH]
Persistent workers:
are created once;
own deterministic contiguous resident ranges;
keep one reusable local SoA tile;
reuse that storage across warm-up and measured trials;
perform the same deterministic particle generation, BAM-LUT projection and contribution hashing as the spawned SoA path;
may complete in arbitrary order;
are always reduced in deterministic worker-index order.
Two scheduling policies are explicit:
physical-first
logical
physical-first uses detected physical-core availability where reliable.
logical permits SMT workers explicitly.
Topology detection is best-effort:
Linux: allowed CPU set plus sysfs package/core topology;
macOS: hw.physicalcpu;
unsupported/unavailable physical topology: explicit logical fallback.
This release does not equate topology detection with CPU affinity or NUMA pinning.
PR #14 — Calibrated host-aware automatic promotion
PR #14 adds the automatic selection layer above the canonical, spawned-SoA and persistent-SoA paths.
New commands:
galaxy-cpu verify-auto [--workers N]
galaxy-cpu bench-auto
[--logical U64] [--resident N] [--frames N]
[--workers N] [--repeats N]
[--seed U32] [--receipt PATH]
Policy identifier:
calibrated-host-auto-v1
The tuner does not use CPU model-name lookup tables.
It measures the actual host and workload.
Candidate families include:
canonical
spawned SoA
persistent physical-first SoA
persistent logical/SMT SoA
across the evidence-backed tile set:
1024
4096
16384
65536
Tile-faithful calibration
A nominal tile size is not treated as measured unless calibration actually exercises that effective per-worker tile size.
For example, a nominal 65,536-particle tile is not considered a 65,536-particle calibration when worker partitioning only gives the worker 256 particles.
The calibration resident population therefore begins from a bounded base but expands when necessary to preserve the requested workload's effective tile shape.
It never expands beyond the requested resident population.
Policy:
tile_shape_policy = expand-resident-for-effective-tile-v1
Every tiled candidate records:
calibration_effective_tile_particles
requested_effective_tile_particles
tile_shape_match
A mismatch fails tuning closed.
Frame-faithful calibration
Calibration also preserves the requested frame depth.
This matters because particle generation and local-tile fill are primarily per-particle costs, while BAM projection and contribution hashing repeat per frame.
A four-frame calibration cannot safely represent the cost mix of an arbitrary deep-frame workload merely by multiplying the result afterward.
Policy:
frame_calibration_policy = preserve-requested-depth-v1
Therefore:
calibration_frames = requested_frames
Full-requested-workload score projection
Candidate timing evidence is compared on the same requested-workload scale.
calibration_work =
calibration_resident × calibration_frames
requested_work =
requested_resident × requested_frames
projected_median =
ceil(
calibration_median ×
requested_work /
calibration_work
)
Policy:
score_projection = linear-particle-frame-v1
This projection is an explicit tuning heuristic, not a theorem of perfectly linear runtime scaling.
Persistent lifecycle scoring
Persistent candidates now account for the complete pool lifecycle.
Startup includes:
worker creation;
worker-local allocation;
explicit first-touch / page commitment of all local SoA and scratch buffers.
Teardown includes:
shutdown signalling;
worker joins;
worker-local buffer destruction and deallocation.
The scored lifecycle is:
full_pool_lifecycle =
full_pool_startup +
full_pool_teardown
and:
persistent_score =
projected_median +
full_pool_lifecycle / requested_repeats
Receipts preserve startup, teardown and combined lifecycle independently.
This prevents low-repeat jobs from promoting a persistent engine by ignoring costs that other execution paths already pay before returning.
5% promotion margin
Auto does not leave the canonical path for a noisy near-tie.
An optimized candidate must beat canonical by at least:
promotion_margin_basis_points = 500
or 5%.
Otherwise canonical remains selected.
Independent fail-closed oracle
Automatic selection uses an independent streaming canonical BAM-LUT oracle:
streaming-canonical-bam-lut-v1
The oracle preserves the established deterministic:
logical-particle generation;
BAM-LUT interpolation;
scalar contribution function;
wrapping-u64 reduction;
while avoiding dependence on the SIMD batch implementation being tested.
Every calibration candidate must match the oracle exactly.
After selection, the complete requested workload is checked again.
Any checksum mismatch terminates execution.
There is no performance-over-correctness fallback.
Timing evidence was tightened
v0.5.0 explicitly records timing components that previously risked being hidden outside their advertised scope.
calibration_oracle_ns includes LUT construction and calibration-oracle evaluation.
full_oracle_ns includes LUT construction and the full streaming validation pass.
tuning_ns begins before topology detection because topology discovery affects the candidate set and worker counts.
The receipt also records:
topology_detection_ns
calibration_oracle_ns
full_oracle_ns
tuning_ns
Scheduling evidence was tightened
Requested scheduling and actual scheduling are now distinguished.
Receipts record:
requested_schedule
effective_schedule
schedule_fell_back_to_logical
If physical-first cannot obtain reliable physical topology, the runtime does not falsely claim that a physical-core policy was applied.
It reports the logical fallback explicitly.
RSS evidence was tightened
Linux /proc/self/status VmHWM is process-wide and monotonic.
Because bench-auto executes multiple calibration candidates and probes before the selected run, its process high-water mark cannot honestly be attributed only to the selected engine.
Auto receipts therefore use:
rss_metric =
linux-vmhwm-process-high-water-mark-when-available
rss_scope =
whole-auto-invocation
auto_invocation_peak_rss_kib =
selected_run_peak_rss_available = false
selected_run_peak_rss_kib = null
The ambiguous auto-level peak_rss_kib field is intentionally not used.
Isolated engine memory comparisons should use the manual execution surfaces, where each path can be measured independently.
Receipt identity
Host-auto receipts use:
schema = galaxy.cpu-runtime-auto-receipt.v1
runtime = galaxy-cpu
execution_mode = host-auto
selection_policy = calibrated-host-auto-v1
canonical_oracle =
streaming-canonical-bam-lut-v1
parity_fail_closed = true
score_projection =
linear-particle-frame-v1
tile_shape_policy =
expand-resident-for-effective-tile-v1
frame_calibration_policy =
preserve-requested-depth-v1
persistent_startup_score_scope =
full-requested-pool
persistent_teardown_score_scope =
full-requested-pool
persistent_startup_includes_buffer_first_touch =
true
Cross-platform verification
The native CPU architecture is now continuously exercised across:
Linux x86-64
Linux ARM64
macOS ARM64
Windows x86-64
CI covers:
canonical CPU verification;
exact-u64 invariants;
worker-local SoA parity;
persistent SoA parity;
physical-first and logical scheduling;
host-auto help and command boundaries;
effective tile-shape fidelity;
requested frame-depth fidelity;
topology fallback reporting;
persistent first-touch accounting;
startup + teardown lifecycle identity;
automatic promotion policy;
receipt schema fields;
RSS evidence scope;
exact selected/oracle checksum equality.
Benchmark and evidence tooling
v0.5.0 adds dedicated tooling for reproducible CPU optimization experiments.
New benchmark/evidence components include:
cpu-runtime/src/bin/simd_probe.rs
cpu-runtime/src/bin/worker_soa_probe.rs
scripts/bench-cpu-simd.sh
scripts/bench-cpu-worker-soa.sh
The runners preserve:
generic versus host-native builds;
host capability evidence;
raw timing receipts;
deterministic checksum gates;
decoded instruction evidence where applicable;
clean output-directory requirements;
worker/tile matrix evidence.
Documentation
New CPU-runtime documentation includes:
docs/CPU-SIMD.md
docs/CPU-WORKER-SOA.md
docs/CPU-SOA-INTEGRATION.md
docs/CPU-PERSISTENT-SOA.md
docs/CPU-AUTO-PROMOTION.md
The README was also refreshed after v0.4.0 to reflect the evolving project state.
New ROADMAP.md
v0.5.0 adds a dedicated optimization roadmap:
ROADMAP.md
Its governing rule is:
Do not store what can be regenerated exactly.
Do not materialize what can be reduced exactly.
Do not transfer what can be summarized exactly.
The next planned experimental phases include:
simultaneous CPU + GPU execution on disjoint logical shards;
rate-proportional heterogeneous scheduling;
GPU stream → reduce → discard evidence execution;
compact GPU readback instead of full particle materialization;
procedural regeneration of deterministic state;
NUMA-local execution experiments;
multi-GPU deterministic sharding;
reduced or symmetry-derived BAM lookup strategies;
direct GPU histogram/image accumulation;
transfer/compute overlap;
proof-gated state compression;
resource-aware automatic execution selection.
These are roadmap experiments, not claims about the capabilities of v0.5.0.
Scientific and performance boundary
GALAXY remains a deterministic galaxy dynamics and visualization instrument.
The v0.5.0 CPU work does not change the physical model.
The runtime continues to evolve independent particles in prescribed potentials rather than implementing self-consistent pairwise N-body gravity.
This release does not claim:
that one worker count is universally optimal;
that one tile size is universally optimal;
that physical-core scheduling always beats SMT;
that NUMA placement can be inferred from core count alone;
that AVX-512 automatically improves the complete runtime;
that a projected auto score is a mathematical runtime guarantee;
that Linux VmHWM from the auto process is selected-engine RSS;
that a performance result is valid when checksum parity fails;
that future CPU/GPU roadmap experiments are already implemented.
Performance remains host- and workload-specific evidence.
Correctness remains governed by the deterministic reference/oracle contract.
Release progression
v0.4.0
deterministic native CPU baseline
-
Ryzen / EPYC scaling evidence
-
topology / affinity evidence
↓
PR #10
deterministic SIMD feasibility
↓
PR #11
bounded worker-local SoA
↓
PR #12
guarded production SoA
↓
PR #13
persistent topology-aware workers
↓
PR #14
calibrated host-aware promotion
-
lifecycle-complete scoring
-
fail-closed streaming oracle
↓
v0.5.0
Included pull requests
PR #10 — Add deterministic CPU SIMD probe for AVX2/AVX-512 evidence
PR #11 — Prototype worker-local SoA CPU runtime path
PR #12 — Integrate guarded worker-local SoA path into galaxy-cpu
PR #13 — Add persistent topology-aware SoA execution architecture
PR #14 — Add calibrated host-aware CPU promotion policy
Release identity
Previous release:
v0.4.0
6f17a73
v0.5.0 release target:
This release contains 64 commits after the v0.4.0 tag.
The v0.5.0 tag should be created from the exact merged main commit above so subsequent formalization and archival records can bind to one immutable source identity.