OpenPH

Core PHPP data models and table view generation

Part of the openph UV workspace - a Python implementation of Passive House Planning Package (PHPP) calculations with exact numerical fidelity to Excel PHPP.

Purpose

OpenPH provides:

• Data Models: Python classes representing PHPP building components (areas, constructions, rooms, climate, HVAC systems)
• Table Rendering: Generate formatted output tables (.txt, .html) matching PHPP worksheet layouts for validation
• Plugin Architecture: Extensible table system with auto-discovery via entry points
• HBJSON Import: Convert Honeybee-PH JSON models to OpenPH data structures

Structure

openph/
├── src/
│   └── openph/         # Main package module
│       ├── model/      # PHPP data classes
│       ├── to_table/   # Table rendering system (plugin-based)
│       ├── from_HBJSON/# Honeybee-PH JSON import
│       └── phpp.py     # Main PHPP container class
├── tests/
└── pyproject.toml

Usage

Converting a PHX Model (canonical entry point)

OpenPH's public conversion boundary accepts a live, in-memory PHX.model.project.PhxVariant — no file I/O, no serialization round trips. OpenPH does not accept native Honeybee objects; Honeybee → PHX is PHX's concern, PHX → OpenPH is OpenPH's:

Honeybee/honeybee-ph model
  → PHX.conversion.from_honeybee
  → PhxProject
  → select exactly one PhxVariant
  → openph.conversion.from_phx_variant
  → OpPhPHPP

from PHX.conversion import from_honeybee
from openph.conversion import from_phx_variant

phx_project = from_honeybee(hb_model, group_components=True)
if len(phx_project.variants) != 1:
    raise ValueError(f"OpenPH requires exactly one PHX variant; got {len(phx_project.variants)}")
phpp = from_phx_variant(phx_project.variants[0])

# Calculate through a registered solver (requires the openph-demand plugin):
heating = phpp.get_solver("energy_demand").heating_demand
annual_kwh = heating.total_yearly_heating_demand              # Heating!AF117
annual_kwh_m2a = heating.total_yearly_specific_heating_demand  # Heating!Q78

Read the annual scalars rather than summing a monthly row: each is a canonical PHPP-addressed result, so every consumer reports the same number.

Getting results out

Three surfaces, each doing one job — pick by what the caller needs:

The compact summary supplements the audit document rather than replacing it; for one model it is roughly 200x smaller. Core openph needs neither pandas nor rich for the first two.

from_phx_variant preflights the variant and validates the finished model with the structured readiness diagnostics (openph.validate): it raises OpPhValidationError carrying a machine-readable OpPhValidationReport when error-severity issues exist, and returns a fully built, validated, solver-ready OpPhPHPP otherwise. Call openph.validate_phx_variant(variant) directly for report-style (non-raising) feedback.

The legacy import path openph.from_HBJSON.create_phpp.from_phx_variant remains functional and is the same single implementation.

Basic Model Creation

from openph.phpp import OpPhPHPP

# Create PHPP model
phpp = OpPhPHPP()

# Access model components
phpp.climate
phpp.areas
phpp.rooms
phpp.hvac

Table Rendering (Single Tables)

from openph.to_table import TableDisplayManager, TableNames

# Initialize table display manager
display = TableDisplayManager(phpp)

# Render individual tables
climate_table = display.get_table(TableNames.CLIMATE_ANNUAL)
climate_table.render(format="console")
climate_table.render(format="html", output_path="climate.html")

Table Grouping (Recommended)

Group related tables and render to a single file:

from openph.to_table import TableDisplayManager, TableNames

display = TableDisplayManager(phpp)

# Create logical groups
climate_group = display.create_group([
    TableNames.CLIMATE_ANNUAL,
    TableNames.CLIMATE_PEAK_LOAD,
    TableNames.CLIMATE_RADIATION_FACTORS,
])

# Render entire group to one file
climate_group.render(format="html", output_path="./climate_report.html")
climate_group.render(format="txt", output_path="./climate_report.txt")

Available Core Tables

Climate: CLIMATE_ANNUAL, CLIMATE_PEAK_LOAD, CLIMATE_RADIATION_FACTORS
Areas: AREAS_SUMMARY, AREAS_OPAQUE_SURFACE_*, AREAS_APERTURE_*, AREAS_SOLAR_REDUCTION_*
Rooms: ROOMS_VENTILATION_PROPERTIES, ROOMS_VENTILATION_SCHEDULE
Ventilation: VENTILATION_DUCT_INPUTS, VENTILATION_DUCT_RESULTS, VENTILATION_DUCT_*

See TableNames class for complete list.

Development

Part of UV workspace - see root context/ENVIRONMENT.md:

uv sync                      # Install all workspace packages
uv run pytest openph/tests/  # Run tests