EnergyPlus Validator¶

The EnergyPlus validator runs a full EnergyPlus building-energy simulation on the submission, then exposes the simulation results — site EUI, end-use breakdowns, unmet hours, peak demand, envelope flows — as values you can write CEL rules against.

It's the right tool when you accept building energy models (IDF or epJSON) and need to gate them on simulated behaviour rather than just file shape. Typical uses: confirming a contractor-supplied model meets an ASHRAE 90.1 EUI target, that unmet heating/cooling hours are within spec, or that the simulated floor area matches the metadata sent by the submitter.

What you'll need¶

• A Validibot deployment licensed for an edition that includes EnergyPlus.
• A workflow whose allowed file types include IDF or epJSON.
• A representative IDF or epJSON model to test the step with.

How an EnergyPlus step works¶

When a submission reaches the step, Validibot:

1. Parses the IDF/epJSON to extract building facts (zone count, floor area, version) and exposes them as step inputs (i.zone_count, i.floor_area_m2, i.idf_version, …).
2. Resolves any template parameters if the submission is a parametric template.
3. Dispatches the model to an isolated EnergyPlus container, with the weather file and runtime options configured on the step.
4. Extracts simulation results and exposes them as step outputs (o.site_eui_kwh_m2, o.unmet_heating_hours, …).
5. Runs your assertions — both default ones (sanity bounds) and any step-level CEL rules you've added against i.*, o.*, p.*, or s.*.

Setting up an EnergyPlus step¶

1. Open the workflow editor and click Add step.
2. Pick EnergyPlus from the validator library. If it's greyed out, check that your deployment's license includes it and that the workflow's allowed file types include IDF or epJSON.
3. Give the step a name like "Code-compliance simulation" and a short description.
4. Choose the weather file (EPW). For a self-hosted deployment, the admin curates the available list; on Cloud, common stations are bundled.
5. (Optional) Tighten runtime guards — wall-clock timeout, memory ceiling. The defaults are fine for typical small-to-mid models.
6. Click Save step.
7. Add step assertions against the outputs (o.*) and any inputs (i.*) you want to gate on. Examples below.

Outputs the validator exposes¶

The validator surfaces a fixed vocabulary of metrics. The full list is in the in-app step editor; the most commonly used ones:

Use these in CEL assertions. A few common examples:

# EUI must meet the project's target
o.site_eui_kwh_m2 <= s.target_eui_kwh_m2

# Unmet hours within an acceptable bound
o.total_unmet_hours <= 300

# Simulated floor area must match the metadata within 1%
abs(o.floor_area_m2 - i.expected_floor_area_m2) / i.expected_floor_area_m2 < 0.01

# Peak demand below the utility limit
o.peak_electric_demand_w < 500000.0

When to gate on inputs vs. outputs¶

The validator separates checks into two stages:

• Input-stage assertions run before the simulation — fast, cheap, and can short-circuit a costly run. Good for things like "the IDF version must be 25.x" or "must have at least 4 zones".
• Output-stage assertions run after the simulation against o.*. Use these for performance-style rules — EUI, end-use breakdowns, unmet hours.

If an input-stage assertion fails as an error, the simulation doesn't run at all — Validibot returns the finding immediately. That's a meaningful speed/cost win when something is structurally wrong with the model.

Tips¶

• Always include an unmet-hours check. High unmet hours mean the HVAC system couldn't maintain setpoints — usually an undersized system or a modeling error. Catching this early prevents passing-but-wrong submissions.
• Compare simulated floor area to the metadata. Mismatches are a strong signal that the submitter modified geometry without updating the brief.
• Use derived signals like total_site_energy_kwh for overall compliance checks rather than summing end uses in a CEL expression — it's clearer and matches how the EnergyPlus reports define the number.
• Chain a cheap step before EnergyPlus. A JSON Schema or Basic step on the metadata bundle filters out obviously broken submissions without paying the simulation cost.

Where to next¶

• Data Namespaces — how i.* and o.* fit together for a multi-stage validator.
• CEL Expressions — operators and helpers for writing the assertions above.
• FMU Validator — the sibling advanced validator for FMU co-simulations.