A Rust simulation engine for reproducible discrete-event and agent-based models.
KairoECS combines event scheduling, entity/component state, resource queues, agent behaviours and deterministic random streams. Optional Rust crates add columnar data exchange, parallel execution, distributed synchronization and GPU kernels. Applications such as CareOps own their domain models and consume Kairos through a versioned dependency boundary.
Kairos owns simulation mechanisms. UOGTO supplies game semantics; Paignia is the separate Rust game library for representations and solvers; CareOps, Innovate and reimbursement applications own their models. Economic valuation belongs above neutral resource-use records. See scope and ecosystem for the accepted boundaries and the distinction between implemented packages and planned extraction.
Documentation · Install from source · Current capabilities and evidence · Development programme
Alpha. v0.4.0-alpha.1 was published on 18 October 2026. The default branch contains later experimental work; it is not a stable API or production-release promise. Beta and 1.0 have explicit acceptance gates.
Rust is the only supported simulation core. Python, R, Julia, TypeScript, C# and Go are integration surfaces. They may execute a compiled Rust native library or Rust-compiled WebAssembly; they must never substitute a scheduler, random generator or simulation model written in the host language. Missing native capabilities return an explicit error. The former host-language preview cores are unsupported immediately; see the breaking-change notice. A successful package import or metadata check is not native-engine qualification.
| Area | Implemented scope | Qualification boundary |
|---|---|---|
| Core simulation | Ordered event scheduling, cancellation, generational entities, component storage and versioned random streams | Replay depends on the recorded engine, model, RNG and numerical contract. |
| DES and ABM | Resource queues, priority/preemption primitives, staged allocation, behaviours, spatial operations and hazard clocks | Applications must validate their own models and supported compositions. |
| Data exchange | Optional Arrow/Polars tables, IPC/Parquet paths and C Data ownership interfaces | Features and installed consumers need separate qualification; zero-copy applies only to proven boundaries. |
| Parallel and distributed execution | Conservative PDES, optimistic rollback, native MPI and typed gRPC synchronization | Bounded native acceptance exists; general HPC scaling and performance superiority are unproven. |
| GPU execution | Native backends and persistent buffers for specific particle/event kernels | Kernel evidence does not establish arbitrary model offload, universal bitwise parity or end-to-end speedup. |
| Scientific extensions | Game-theory, calibration, inference and FMI surfaces with differing maturity | Known algorithm gaps and demonstration backends are tracked; feature names do not certify scientific correctness. |
The capability register separates implementation,
execution, validation and release acceptance. A Conductor track marked Done
means its recorded scope was completed; it does not certify every feature in
that topic.
At the reviewed baseline
d568635,
hosted Rust verification
reported 994 passing tests, 93.70% core line coverage and native MPI smoke runs
with two and four ranks. Those results belong to that revision and execution
matrix; each change requires its own relevant checks.
Read the measured PDES benchmark before choosing parallel execution. Its small ring workloads were slower than the sequential baseline. The scaling-report correction explains why generated placeholder figures are not performance evidence. General comparative performance and real-system model validity remain evaluation work, with a dataset and oracle plan.
Clone the repository and use the toolchain pinned in rust-toolchain.toml:
git clone https://github.com/edithatogo/kairos.git
cd kairos
cargo test --locked -p kairo-ecs-core -p kairo-ecs-state
cargo test --locked -p kairo-ecs-des -p kairo-ecs-abmThe Rust quickstart introduces the scheduler. The installation guide explains the native-library requirement for language wrappers. The binding inventory records which operations each adapter can actually perform.
- Documentation overview, tutorials and model building.
- Rust crates, conformance and benchmark policy.
- Scenario replay, model zoo and verification, validation and uncertainty.
- Contributing, security, citation and release checklist.
- Conductor index, track registry, workflow and phase evidence.
- Consumer inventory, movement/resource contract and bounded maturity tasks.
For a coherent Rust change, use just ci. Documentation changes use:
npm --prefix website ci
npm --prefix website run check:allPrefer qualified maintained dependencies; see the dependency policy. Python 3.15.2 remains the selected tooling default. Necessary compatible profiles need a recorded consumer and qualification; follow AGENTS.md.
Apache-2.0 OR MIT. See LICENSE, LICENSE-APACHE and LICENSE-MIT.