How to discover output variables¶

The OutputVariableIndex helps you discover available output variables and meters from EnergyPlus, then add them to your model for future simulations.

Not in JavaScript yet

Reading the output variable dictionary and selecting variables is available in Python and is not in JavaScript today. A temporary gap, not a boundary. The port is tracked in idfkit-js#19.

The full entry, including the vocabulary this capability owns, is on the capability parity page.

Basic Usage¶

from idfkit.simulation import simulate

result = simulate(model, weather)

variables = result.variables
if variables is not None:
    # Search for temperature-related outputs
    matches = variables.search("Temperature")
    for var in matches[:10]:
        print(f"{var.name} [{var.units}]")

Understanding RDD and MDD Files¶

EnergyPlus generates these files to describe available outputs:

File	Contents
`.rdd`	Output variables (zone temps, surface temps, etc.)
`.mdd`	Output meters (energy consumption, etc.)

These files are only generated after a simulation runs — they describe what outputs could be requested, not what was actually recorded.

OutputVariableIndex¶

Creating an Index¶

From simulation results:

variables = result.variables

From files directly:

from idfkit.simulation import OutputVariableIndex

index = OutputVariableIndex.from_files(
    rdd_path="/path/to/eplusout.rdd",
    mdd_path="/path/to/eplusout.mdd",
)

Search Variables¶

# Search by name pattern
matches = variables.search("Zone Mean Air Temperature")

# Search with regex
matches = variables.search(r"Zone.*Temperature")

# Case-insensitive
matches = variables.search("temperature")  # Finds all temperature vars

Filter by Units¶

# Get all temperature variables (°C)
temp_vars = variables.filter_by_units("C")

# Get all energy variables
energy_vars = variables.filter_by_units("J")

List All Variables¶

# All output variables
for var in variables.variables:
    print(f"Variable: {var.name} [{var.units}]")

# All meters
for meter in variables.meters:
    print(f"Meter: {meter.name} [{meter.units}]")

OutputVariable and OutputMeter¶

OutputVariable Attributes¶

Every field of OutputVariable, with its type and its default, is in the API reference. It is generated from the source, so it cannot fall behind the way the table that used to sit here did.

OutputMeter Attributes¶

Every field of OutputMeter, with its type and its default, is in the API reference. It is generated from the source, so it cannot fall behind the way the table that used to sit here did.

Adding Outputs to Model¶

Add All Matching¶

# Add all temperature outputs
count = variables.add_all_to_model(
    model,
    filter_pattern="Zone.*Temperature",
)
print(f"Added {count} output requests")

Selective Addition¶

# Search first, review, then add selectively
matches = variables.search("Heating")

# Filter to specific ones
selected = [v for v in matches if "Coil" in v.name]

# Add to model (name is optional for Output:Variable)
for var in selected:
    model.add(
        "Output:Variable",
        key_value="*",
        variable_name=var.name,
        reporting_frequency="Timestep",
    )

Reporting Frequencies¶

Frequency	Description
`"Detailed"`	Every zone timestep
`"Timestep"`	Every zone timestep
`"Hourly"`	Once per hour
`"Daily"`	Once per day
`"Monthly"`	Once per month
`"RunPeriod"`	Once per run period
`"Environment"`	Once per environment

variables.add_all_to_model(
    model,
    filter_pattern="Temperature",
    frequency="Hourly",
)

Workflow: Discover Then Request¶

A common pattern is to run a "discovery" simulation to find available outputs, then run a second simulation with those outputs requested:

from idfkit.simulation import simulate

# Step 1: Discovery run
result = simulate(model, weather, design_day=True)

# Step 2: Find interesting outputs
matches = result.variables.search("Zone Mean Air Temperature")
print(f"Found {len(matches)} matching variables")

# Step 3: Add outputs to model
result.variables.add_all_to_model(
    model,
    filter_pattern="Zone Mean Air Temperature",
    frequency="Hourly",
)

# Step 4: Full run with outputs
result = simulate(model, weather, annual=True)

# Step 5: Query the data
for zone in ["ZONE 1", "ZONE 2"]:
    ts = result.sql.get_timeseries(
        "Zone Mean Air Temperature",
        zone,
    )
    print(f"{zone}: avg {sum(ts.values) / len(ts.values):.1f}°C")

Common Output Variables¶

Zone-Level¶

Variable	Description
`Zone Mean Air Temperature`	Average zone air temperature
`Zone Air Relative Humidity`	Zone relative humidity
`Zone Air System Sensible Cooling Energy`	Cooling energy delivered
`Zone Air System Sensible Heating Energy`	Heating energy delivered
`Zone People Total Heating Energy`	Heat from occupants
`Zone Lights Total Heating Energy`	Heat from lights
`Zone Electric Equipment Total Heating Energy`	Heat from equipment

Surface-Level¶

Variable	Description
`Surface Inside Face Temperature`	Interior surface temperature
`Surface Outside Face Temperature`	Exterior surface temperature
`Surface Inside Face Convection Heat Transfer Coefficient`	Interior convection
`Surface Outside Face Convection Heat Transfer Coefficient`	Exterior convection

HVAC¶

Variable	Description
`Zone Ideal Loads Supply Air Total Cooling Energy`	Ideal loads cooling
`Zone Ideal Loads Supply Air Total Heating Energy`	Ideal loads heating
`Facility Total Electric Demand Power`	Total electric load

Common Meters¶

Meter	Description
`Electricity:Facility`	Total facility electricity
`Gas:Facility`	Total facility gas
`Heating:Electricity`	Heating electricity
`Cooling:Electricity`	Cooling electricity
`InteriorLights:Electricity`	Interior lighting electricity
`InteriorEquipment:Electricity`	Interior equipment electricity