Open Control Sim

open-control-sim (crates ocs-*) is a fast, bit-deterministic, lumped-parameter building-physics and plant simulator: RC-network thermal core, quasi-static equipment, native fault injection, seeded scenario generation, and protocol-realistic point publication (BACnet, with a generated Brick + ASHRAE 223P semantic model). It closes the loop control outputs → building response → sensor values → agent observations around the Open Control Engine (oce-*) for reinforcement-learning training.

In research publications this system is called verdant-sim; see NAMING.md for the mapping. Citations to verdant-sim resolve here.

The one invariant everything serves

On the simulation side, identical binary + scenario seed yields a bit-identical trajectory, cross-run and cross-architecture (x86_64/arm64). In the composed loop, signals traversing one of the engine's designated aligned-tolerance classes use the engine's documented cross-architecture band. The repo's structure makes that boundary structural rather than disciplinary:

• Two modes, one binary. Deterministic mode composes everything in-process against a virtual clock — the only mode the reward loop ever sees. Fleet mode runs the same components over a live network for integration, stress, and demos — never in the reward path.
• The default build is async-free and C-free. Group H (ocs-fleet, ocs-py) is excluded from default-members; a CI gate walks the default dependency closure and fails on any async runtime, -sys crate, or C build script.
• One pinned libm. All transcendentals route through ocs_core::math over the pinned pure-Rust libm — the same version the engine pins (compared mechanically in CI). std float transcendentals and mul_add are denied by clippy.toml.
• Fixed-iteration solvers only. No convergence-dependent exits anywhere on the deterministic path.
• Independent numerical fixtures. The matrix-exponential oracle is off-workspace, firewalled from simulator code, and generates Arb-certified fixtures corroborated by independent mpmath methods. Light CI consumes the fixture bytes; the release/daily gate reproduces them from hash-pinned wheels inside a runtime audit boundary. Neither path generates expected values from the implementation under test.

Workspace

Crate	Group	Owns
ocs-core	S	RC thermal core, exact discretization, determinism substrate (libm boundary, denormal probe)
ocs-equipment	S	Performance maps, fixed-iteration pressure network, actuators
ocs-weather	S	EPW ingest, solar transposition, ground model, seeded stress
ocs-faults	S	Fault taxonomy, typed seeded injectors, FDD rule engine
ocs-buildgen	S	Procedural buildings from prototype priors, archetypes
ocs-scenario	S	Deterministic ChaCha stream splitting; scenario artifact and extension contexts remain planned
ocs-points	P	Point schema, sync BACnet mapping + encode/decode, Brick/223P semantic-graph generation, sensor model
ocs-bridge	—	Co-simulation master over oce-api (the only crate that names it)
ocs-api	—	The single public surface (frozen by an armed public-api baseline)
ocs-fleet	H	Fleet-mode host (async; excluded from the default build)
ocs-py	H	Python bindings — the reward-path transport (excluded from the default build)

Working on this repo

bash scripts/install-hooks.sh   # once per clone
bash .agents/gate.sh            # the per-PR gate, in CI's exact command form
bash .agents/gate.sh full       # adds the full workspace suite + doctests

.agents/gate.sh is the runnable local gate and lists CI-only coverage it cannot reproduce, including cross-architecture execution and pinned oracle regeneration. CONTRIBUTING.md covers how changes land; TESTING.md is the testing standard (four pillars; goldens are bit-exact, never epsilon).

Documentation

Document	Covers
docs/thermal-core.md	The RC network, exact discretization via the Van Loan augmented form, fixed Padé-13 scaling-and-squaring and where its scaling exponent comes from, the planned derived air-node capacitance multiplier, the three-case explicit-flow classification, and what refusing to sub-step measurably costs
docs/determinism.md	What the bit-determinism contract covers and why each constraint exists — the pinned libm, the no-C rule, bit-exact goldens
TESTING.md	The four-pillar standard: edge, golden, oracle, determinism
NAMING.md	Crate and identifier conventions; the verdant-sim ↔ Open Control Sim mapping
CONTRIBUTING.md	Gate, review and merge process

Diagrams live in docs/img/ as hand-authored SVG, each carrying a <title> and <desc> for screen readers and a prefers-color-scheme block so one file reads correctly on both light and dark backgrounds. Equations use GitHub's LaTeX rendering rather than ASCII approximations, so Γ = q(N)⁻¹(p̂(N) − q̂(N))K appears as the expression it actually is.

Design rationale that is settled and shipped belongs in docs/. Working material — the in-progress specification, research briefs, review logs — lives in local _*/ directories, which are untracked by design: this repo mirrors open-control's arrangement, where the durable record of decisions lives in project memory rather than the public tree.

Offline reference tools live under tools/reference-rig/. The landed expm tenant certifies 17 adversarial matrix classes plus 150-state and 278-state physical-shape RC networks. EnergyPlus/BOPTEST correspondence remains a separate M1/M3 deliverable.

Third-party material

third_party/ holds input files copied verbatim from upstream projects. Nothing there is Open Control Sim code and nothing there is compiled — the directories sit outside every crate root, so cargo package does not see them.

Directory	Contents	Licence
third_party/doe-prototype-models/	DOE/PNNL Commercial Prototype Building Models (ASHRAE 90.1-2022, climate zone 5A) — the evidence base for the thermal-core rules and the offline reference rig's inputs	US Government public domain, with a requested acknowledgement

Each directory carries a README.md recording provenance and licence, plus a MANIFEST.sha256 that the gate verifies bidirectionally: every listed file still hashes to its recorded digest, and no unlisted file has appeared. The second direction is the one that matters in practice — a check that only re-hashes what it already knows about cannot notice content being added to a vendored tree. The manifest covers each directory's README too, so provenance and attribution text cannot be edited without the gate noticing.

Status

Milestone M0 (workspace, gates, determinism substrate) and the M1 opening slice are landed. ocs-core currently carries the determinism substrate — the pinned-libm transcendental boundary and the behavioural subnormal probe — plus the RC-network model layer with typed validation and the Van Loan Padé-13 discretization producing (Φ, Γ). The discretizer chooses a power-of-two scale per Van Loan input column and accepts it only when normalization plus state-driven initial scaling preserve every nonzero input bit-exactly and the initially scaled column stays in Padé's finite coefficient range; the state block and normalized output receive the same no-silent-loss preflight. Independent oracle fixtures cover singular/defective, threshold, stiffness, cancellation, overflow, underflow, and 192/354-augmented physical-shape cases. The 354-augmented release run is inside the 0.5 s local build budget; CI performance regression gating is not yet landed.

The remaining crates compile as scaffolds. Next in ocs-core: the algebraic layer (flows, moisture, CO₂), the trapezoidal + Sherman–Morrison–Woodbury path for envelope-fault segments, and thresholded-CSR Φ storage.

License

Dual-licensed under Apache 2.0 or MIT, at your option.