---
name: wufi-xml
description: "Navigate, verify, and extract data from WUFI-Passive XML model files (.xml exported from WUFI-Passive or generated by PHX/Honeybee-PH). Use this skill whenever working with WUFI-Passive XML files for QA/QC, certification review, value verification, data extraction, or comparison tasks. Trigger on: WUFI XML, WUFI-Passive model, .xml energy model, Phius certification verification, WUFI QA, checking values in WUFI, verifying feedback items against XML, or any task involving reading or auditing a Passive House energy model file."
---

# WUFI-Passive XML Navigation and Verification

WUFI-Passive XML files are the primary data exchange format for Passive House energy models. They can be 30,000-100,000+ lines and contain the complete building model: geometry, constructions, windows, HVAC, DHW, renewables, and certification parameters. This skill helps you navigate these files efficiently and verify values accurately.

## Load the Reference Doc

At the start of a WUFI XML task, fetch the canonical schema reference. This contains the full XML structure map, field dictionary (UI label → XML element), and unit conversion tables:

```
WebFetch https://docs.passivehousetools.com/llm/phx/reference/wufi-xml-schema.md
```

This is the single source of truth — it consolidates the structure map, field dictionary, and unit conversions into one document.

**Related docs** (fetch if the task involves these areas):
- PHX model classes: `https://docs.passivehousetools.com/llm/phx/reference/phx-model-reference.md`
- Exporter/importer code: `https://docs.passivehousetools.com/llm/phx/dev/exporter-patterns.md`

**If the fetch fails** (offline, URL unreachable), the quick-start tables and gotchas below are sufficient for most tasks. For discovery, try `https://docs.passivehousetools.com/llm-instructions.md`.

## Quick Start: Navigating a WUFI XML

WUFI XML files follow a consistent top-level structure. The key sections and what lives in them:

| You want to find... | Look in... |
|---|---|
| Ventilation units (ERV/HRV/NERV) | `HVAC > Systems > System > Devices` (TypeDevice=1) |
| Heat pumps, heaters | `HVAC > Systems > System > Devices` (TypeDevice=2 or 5) |
| DHW water heaters | `HVAC > Systems > System > Devices` (UsedFor_DHW=true) |
| PV / renewables | `HVAC > Systems > System > Devices` (SystemType=10) |
| Ducts | `HVAC > Systems > System > PHDistribution > DistributionVentilation > Ducts` |
| DHW piping | `HVAC > Systems > System > PHDistribution > DistributionDHW > Truncs` |
| Thermal bridges | `Zones > Zone > ThermalBridges` |
| Window types (thermal properties) | `WindowTypes > WindowType` (near end of file) |
| Window components (shading, reveals) | `Zones > Zone > Components > Component` (Type=2) |
| Opaque assemblies | `Assemblies > Assembly` (near end of file) |
| Certification targets | `PassivehouseData > AnnualHeatingDemand`, etc. |
| Space ventilation airflows | `Zones > Zone > Rooms > Room` |
| Climate / location | `ClimateLocation` or `ProjectData` section |

### Finding a Specific Device or Component

The fastest approach for a known name:

```
# Find all lines mentioning a device name
grep -n "ERV-2\|NERV-N4A" model.xml
```

This gives you multiple hit locations (device definition, duct assignment, room assignment). The device definition section has the performance parameters you usually need.

## QA/QC Verification Workflow

When verifying feedback items or certification review comments against a WUFI XML:

### 1. Map the item to an XML section
Use the table above to identify which section of the XML contains the value. For ventilation performance, that's the Devices section. For duct insulation, it's the Ducts section. For window shading, it's the aperture Component entries (not the WindowType entries).

### 2. Read the relevant section
WUFI XMLs are large. Don't try to read the whole file. Use grep to find the device/component name, then read ~50 lines of context around the hit to get all the fields for that element.

### 3. Convert units before comparing
Almost every value in the XML is in SI units, while Phius feedback forms and US specifications use IP units. Always convert before declaring a match or mismatch. See the reference doc for the exact factors.

### 4. Watch for combined vs. separate values
Some XML fields contain combined/composite values. For example, `DefaultCorrectionShadingMonth` on window components is a general-purpose solar correction factor — what it represents depends on the project methodology (it could be a glass fraction, a combined shading estimate, or something else). Always cross-reference with the project's source calculations (e.g., a window U-value workbook or methodology doc) rather than assuming what a value represents.

### 5. Log results methodically
For each verification item, record: the expected value (with units), the XML value (with units), the conversion math, and pass/fail. A spreadsheet log works well for certification submittals.

## Key Gotchas

**FrameFactor on WindowType is NOT the same as DefaultCorrectionShadingMonth on the Component.** `FrameFactor` on the WindowType describes the glass-to-total area ratio for thermal calculation purposes. The `DefaultCorrectionShadingMonth` on the aperture Component (Type=2) is a separate solar correction factor. These serve different purposes — don't confuse them. On some projects, the WindowType may have FrameFactor ≈ 1.0 with near-zero frame widths because the U-value was pre-calculated externally; check for project-specific methodology docs if you see this pattern.

**ElectricEfficiency is in Wh/m3, not W/cfm.** Divide by 1.69901 to get back to W/cfm, or multiply W/cfm by 0.58856 to predict the XML value.

**Order_Layers on assemblies matters.** `Order_Layers=2` means layers are listed outside-to-inside. For floor assemblies over ground, "outside" = ground side, so insulation should appear as Layer 0.

**Airflows are in m3/h, not CFM.** Divide by 1.69901 to convert to CFM (same factor as electric efficiency, since both involve volume flow).

**Thermal conductivity for ducts is composite.** If duct insulation has multiple layers (e.g., fiberglass liner + reflective wrap), the XML stores a single equivalent conductivity. The value may look unfamiliar if you're expecting the conductivity of a single material.

**PsiValue on thermal bridges is in W/mK.** Divide by 1.7307 to convert to Btu/hr-ft-F.