Tools: Peak Loads¶

@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()

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 = sum(zone_areas.values())

        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,
    )

@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"]),
                prefersBorder=False,
            )
        )
    },
)
def peak_loads_viewer_html() -> str:
    """Return the self-contained peak load viewer HTML."""
    return PEAK_LOADS_VIEWER_HTML