# bim-energy

> Run whole-building energy simulations and PHIUS CORE 2024 compliance checks. Accepts gbXML and OpenStudio .osm files. Requires NREL OpenStudio CLI (install with `bim energy install`).

## Verbs

```
bim energy run         --in <file.gbxml|file.osm> [--engine openstudio] [--weather <file.epw>]
bim energy phius.check --in <file.gbxml> [--target phius-core-2024] [--path performance|prescriptive]
bim energy doctor
bim energy install     [--dry_run true] [--interactive true]
```

## run

Runs an energy simulation. Returns `eui_kbtu_sf_yr`, `annual_kwh`, `peak_kw`, and `end_uses[]`.

- `--engine openstudio` (only supported engine)
- `--weather <file.epw>` overrides any weather file embedded in the model

Result: `{"ok":true,"result":{"eui_kbtu_sf_yr":42.3,"annual_kwh":187400,"peak_kw":48.2,"end_uses":[...]}}`

## phius.check

Runs PHIUS CORE 2024 compliance check against a gbXML file. Does not require a full simulation run.

- `--target phius-core-2024` (only supported target)
- `--path performance` (default) or `prescriptive`

Result: `{"ok":true,"result":{"compliant":false,"checks":[{"name":"...","target":4.42,"actual":5.1,"pass":false}]}}`

## doctor

Checks for OpenStudio CLI and EnergyPlus installs. Failed checks include a `hint` field.

## install

Downloads and installs NREL OpenStudio CLI. Use `--dry_run true` to preview. Use `--interactive true` for installer wizard.

## Gotchas

- gbXML from Revit requires Energy Settings configured before export.
- .osm files must include a weather file or `--weather` must be provided.
- Simulation runs take 30-120s depending on model complexity.
- `phius.check` does not require `run` to have been called first.