Crate hems_core 

The domain model of a home energy system.

hems-core is the vocabulary every other crate in the workspace speaks. It holds facts and no rules: what a site is made of, what a quarter hour is, what a measurement and a command are. The regulation lives in hems-grid, the economics in hems-tariff, the decisions in hems-optimizer and hems-realtime.

Guarantees

• No I/O, no clock, no async. Every function is a pure function of its arguments; time enters as a parameter. A whole winter day, DST transition included, is a unit test.
• One sign convention. See units — positive is power flowing into the thing being measured, so grid == Σ assets holds site-wide and can be tested (site::Site::balance_residual).
• Commands explain themselves. setpoint::Setpoint cannot be built without a setpoint::Reason, and reasons carry an setpoint::Authority that makes “the grid limit wins” checkable rather than a convention.

Example

use hems_core::prelude::*;

let wallbox = AssetId::new("wallbox-garage")?;
let limit = Setpoint::new(
    wallbox,
    Command::ConsumptionCeiling(Power::from_kw(4.2)),
    Reason::guard(GuardRule::Lpc),
    time::macros::datetime!(2026-01-15 17:04:00 UTC),
)?;

assert_eq!(limit.authority(), Authority::Guard);

Modules

asset

The things behind the grid connection.

circuit

The electrical tree between the grid connection and each asset.

envelope

The interval of power an asset may currently use.

error

Errors the domain model itself can raise.

ids

Identifiers.

measurement

What a driver reports, and how fresh it is.

plan

What the optimiser decided, in a form the arbiter can follow.

prelude

Everything a consumer normally wants, in one use.

setpoint

Commands, and the reason each one exists.

site

One installation: the grid connection, the circuits, the assets.

slot

The 15-minute planning grid.

thermal

The building as thermal storage: a two-mass RC model, discretised exactly.

units

Physical quantities, with one sign convention for the whole workspace.