Skip to content

Tools: Peak Loads

Peak load QA/QC analysis tool.

ZoneAreaInfo dataclass

Per-zone geometry metadata from the EnergyPlus Zone Summary table.

area_m2 is the zone's own floor area (single instance). EnergyPlus's zone-level peak results are reported without the multiplier applied, so area_m2 is the correct denominator for per-zone W/m² density.

Facility roll-ups must use effective_area_m2 (area * multiplier), gated by part_of_total_area -- matching how EnergyPlus computes "Total Facility" peaks.

Source code in src/idfkit_mcp/tools/peak_loads.py 
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
@dataclass(frozen=True)
class ZoneAreaInfo:
    """Per-zone geometry metadata from the EnergyPlus Zone Summary table.

    `area_m2` is the zone's own floor area (single instance). EnergyPlus's zone-level
    peak results are reported without the multiplier applied, so `area_m2` is the
    correct denominator for per-zone W/m² density.

    Facility roll-ups must use `effective_area_m2` (area * multiplier), gated by
    `part_of_total_area` -- matching how EnergyPlus computes "Total Facility" peaks.
    """

    area_m2: float
    multiplier: int
    part_of_total_area: bool

    @property
    def effective_area_m2(self) -> float:
        """Area contribution to the building total, or 0 if excluded from facility rollup."""
        return self.area_m2 * self.multiplier if self.part_of_total_area else 0.0

effective_area_m2 property

Area contribution to the building total, or 0 if excluded from facility rollup.

analyze_peak_loads()

Analyze peak heating and cooling loads for QA/QC.

Decomposes facility and zone-level peaks into components (solar, people, lighting, equipment, infiltration, envelope) and flags potential issues such as unusual peak timing, excessive loads, or component dominance.

Requires a completed simulation with SQL output and the SensibleHeatGainSummary and HVACSizingSummary reports.

Source code in src/idfkit_mcp/tools/peak_loads.py 
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
@tool(
    annotations=_READ_ONLY,
    meta={
        "ui": app_config_to_meta_dict(
            AppConfig(
                resourceUri="ui://idfkit/peak-loads-viewer.html",
                prefersBorder=False,
            )
        )
    },
)
def analyze_peak_loads() -> PeakLoadAnalysisResult:
    """Analyze peak heating and cooling loads for QA/QC.

    Decomposes facility and zone-level peaks into components (solar, people,
    lighting, equipment, infiltration, envelope) and flags potential issues
    such as unusual peak timing, excessive loads, or component dominance.

    Requires a completed simulation with SQL output and the
    SensibleHeatGainSummary and HVACSizingSummary reports.
    """
    return build_peak_load_analysis()

build_peak_load_analysis()

Run the full peak load QA/QC analysis on the current simulation.

Source code in src/idfkit_mcp/tools/peak_loads.py 
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
def build_peak_load_analysis() -> PeakLoadAnalysisResult:
    """Run the full peak load QA/QC analysis on the current simulation."""
    state = get_state()
    result = state.require_simulation_result()

    with _open_sql(result) as sql:
        zone_areas = _get_zone_areas(sql)
        total_area = _facility_total_area_m2(zone_areas)

        cooling = _parse_peak_components(sql, "Peak Cooling Sensible Heat Gain Components", zone_areas)
        heating = _parse_peak_components(sql, "Peak Heating Sensible Heat Gain Components", zone_areas)

        sizing_cooling = _parse_sizing(sql, "Zone Sensible Cooling", zone_areas)
        sizing_heating = _parse_sizing(sql, "Zone Sensible Heating", zone_areas)

    flags = _generate_flags(cooling, heating, sizing_cooling, sizing_heating, total_area)

    return PeakLoadAnalysisResult(
        cooling=cooling,
        heating=heating,
        sizing_cooling=sizing_cooling,
        sizing_heating=sizing_heating,
        total_floor_area_m2=round(total_area, 2),
        flags=flags,
    )

peak_loads_viewer_html()

Return the self-contained peak load viewer HTML.

Source code in src/idfkit_mcp/tools/peak_loads.py 
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
@resource(
    "ui://idfkit/peak-loads-viewer.html",
    name="peak_loads_viewer",
    title="Peak Load Viewer",
    description="Interactive peak load QA/QC viewer for heating and cooling load breakdowns.",
    meta={
        "ui": app_config_to_meta_dict(
            AppConfig(
                csp=ResourceCSP(resourceDomains=["https://unpkg.com"]),
                domain="peak-loads-viewer.idfkit.com",
                prefersBorder=False,
            )
        )
    },
)
def peak_loads_viewer_html() -> str:
    """Return the self-contained peak load viewer HTML."""
    return PEAK_LOADS_VIEWER_HTML