OpenStudio-HPXML v1.11.1

OpenStudio-HPXML v1.11.1 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.11.1 uses OpenStudio v3.11.0, EnergyPlus v25.2.0, and HPXML v5.0-rc1. Please visit the OpenStudio-HPXML v1.11.1 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

Bugfixes

• Fixes heat pump heating performance sensitivity to indoor temperatures.

OpenStudio-HPXML v1.11.0

OpenStudio-HPXML v1.11.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.11.0 uses OpenStudio v3.11.0, EnergyPlus v25.2.0, and HPXML v5.0-rc1. Please visit the OpenStudio-HPXML v1.11.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.11/EnergyPlus 25.2.
• Updates to HPXML v5.0-rc1.
  • Breaking change: HPXML namespace changed from http://hpxmlonline.com/2023/09 to http://hpxmlonline.com/2025/12.
  • Breaking change: Replaces "none" with "not present" for InteriorFinish/Type, Siding, ExteriorShading/Type, InteriorShading/Type, Pool/Type, PermanentSpa/Type, Pump/Type, and Heater/Type.
  • Allows "stone veneer" for Wall/Siding and RimJoist/Siding.
  • Allows "medium light" for Roof/RoofColor, RimJoist/Color, and Wall/Color.
  • Allows SpecificLeakageArea for air infiltration measurements.
• BuildResidentialHPXML measure:
  • Breaking change: New, simpler, easier to use option-based arguments (rather than detailed property arguments).
  • Automatically adjusts garage dimensions for dwelling units with small footprints to avoid errors.
• Heat pump updates:
  • Updates default heating capacities at 17F per RESNET HERS Addendum 82 and NEEP database.
  • Updates supplemental heating energy use during defrost based on RESNET HERS Addendum 82.
  • Updates shared pump power for ground-source heat pumps on a shared recirculation loop to cycle with heating/cooling load rather than operate continuously per RESNET HERS Addendum 94.
  • Allows desuperheaters to be used with the experimental ground-source heat pump model.
  • Adds PanHeaterControlType="heat pump mode", in which the pan heater will run when the HP is running (and the outdoor temperature is below 32F).
  • Updates PanHeaterControlType="continuous" to avoid pan heater operation when the outdoor temperature is below the minimum compressor temperature.
• Allows optional UsageMultiplier for electric vehicles described using Vehicles.
• Water heater improvements:
  • Allows HPWHs to have exhaust air ducted to the outside using HPWHDucting/ExhaustAirTermination="outside".
  • Allows HPWH performance adjustment when installed in confined space per RESNET HERS Addendum 77. When extension/HPWHInConfinedSpaceWithoutMitigation is "true", extension/HPWHContainmentVolume is used to calculate the adjustment.
  • Improves HPWH tank volume defaulting, particularly when NumberofResidents is provided.
  • Improves electric water heater tank losses when using EnergyFactor as the metric; now consistent with how UniformEnergyFactor is handled.
• Updated site defaults:
  • Address/CityMunicipality, Address/StateCode, GeoLocation/Latitude, GeoLocation/Longitude, and TimeZone/UTCOffset now default based on zip code if available.
  • TimeZone/DSTObserved now defaults to false if Address/StateCode is 'AZ' or 'HI'.
• Minor PV improvements:
  • Allow PVSystem/AttachedToInverter to be omitted (unless there are multiple Inverter elements).
  • Allow multiple inverters with different efficiencies and use a weighted-average efficiency in the model (previously threw an error)
• For storm windows, removes minimum base window U-factor limit and throws a warning instead if the base window U-factor is below 0.3.
• Whole SFA/MF buildings:
  • Allows modeling inter-unit heat transfer using the @sameas attribute.
  • Allows modeling detailed electric vehicles.
  • Documents a workaround for modeling common spaces (conditioned or unconditioned).
  • See the documentation for more information.
• Updated default utility bill rates per EIA energy cost data for 2023.
• Adds "Electric Panel Load: Max Current Rating (A)" output to results_panel.csv.
• Adds error-checking for when the sum of supply/return duct leakage to outside values is too high.
• Adds error-checking for when HeatPump/HeatingCapacity17F is provided but HeatPump/HeatingCapacity is not.

Bugfixes

• Fixes incorrect cooling design conditions when using TMYx weather files (OpenStudio bug).
• Fixes ground-source heat pump plant loop fluid type (OpenStudio bug).
• Fixes HERS sizing methodology when compressor lockout temperature is above the heating design temperature.
• Fixes default hours driven per week for electric vehicles (8.88 -> 9.5).
• Fixes empty TimeDST/TimeUTC columns in JSON timeseries data.
• Fixes an EMS bug in heat pump defrost models that over-estimates defrost fractions.
• Fixes zero mech vent fan energy when CFIS system w/ AdditionalRuntimeOperatingMode="air handler fan" has the airflow rate set to zero.
• Fixes requested EnergyPlus timeseries output variables/meters not displayed in DView if they don't have units.
• Fixes possible errors when small water flow rates for variable-speed experimental ground-source heat pump model.
• Fixes possible ground-source heat pump sizing error if the heating or cooling design temperature differences are zero.
• Fixes EMS discharge power program and assignment of default discharging schedule for detailed electric vehicles.
• Avoids thin interior/exterior roof construction layers to help prevent attic temperature out of bounds errors.

OpenStudio-HPXML v1.10.0

OpenStudio-HPXML v1.10.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.10.0 uses OpenStudio v3.10.0, EnergyPlus v25.1.0, and HPXML v4.2-rc2. Please visit the OpenStudio-HPXML v1.10.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.10/EnergyPlus 25.1/HPXML v4.2-rc2.
• HVAC modeling updates per RESNET HERS Addendum 82:
  • Breaking change: CompressorType required for central and mini-split air conditioners and heat pumps as well as ground-to-air heat pumps.
  • Breaking change: Replaces HeatingCapacityRetention[Fraction | Temperature] with HeatingCapacityFraction17F.
  • Allows optional pan heater inputs (extension/PanHeaterPowerWatts and extension/PanHeaterControlType) for central and mini-split heat pumps; defaults to assuming a pan heater is present.
  • Allows optional EER2/EER inputs (AnnualCoolingEfficiency[Units="EER2" or Units="EER"]/Value) for central and mini-split air conditioners and heat pumps.
  • Deprecates SHR inputs (e.g., CoolingSensibleHeatFraction); they are no longer used.
  • Allows optional extension/FanMotorType input for central equipment; updates FanPowerWattsPerCFM defaults to be based on fan motor type.
  • Allows optional extension/EquipmentType inputs for central air conditioners and heat pumps; only used for SEER/SEER2, EER/EER2, and HSPF/HSPF2 conversions.
  • Allows optional design airflow rate inputs (extension/HeatingDesignAirflowCFM and extension/CoolingDesignAirflowCFM).
  • Updates default compressor lockout temperature for dual-fuel heat pumps from 25F to 40F.
  • Updates default design airflow rates to use cfm/ton assumptions rather than Manual S-based approach.
  • Updates defrost model to better account for load and energy use during defrost:
    • Allows optional defrost supplemental heat input (extension/BackupHeatingActiveDuringDefrost) for air-source heat pumps with integrated backup.
    • Deprecates SimulationControl/AdvancedResearchFeatures/DefrostModelType input.
  • Updates to detailed performance datapoints:
    • Breaking change: Updated requirements for allowed combinations of CapacityDescription and OutdoorTemperature; see the documentation for more details.
    • Detailed performance datapoints can now be specified for single stage and two stage equipment too.
    • Adds more error-checking to ensure appropriate data inputs.
• Optional GSHP input SimulationControl/AdvancedResearchFeatures/GroundToAirHeatPumpModelType to choose "standard" (default) or "experimental"; "experimental" model better accounts for coil staging.
• Updates asset calculations for dishwashers, clothes washers, fixtures, and hot water waste per RESNET HERS Addenda 81 and 90f.
• Allows optional ClothesDryer/DryingMethod input to inform whether the appliance is vented or ventless.
• Infiltration improvements:
  • Improves defaults for InfiltrationVolume, InfiltrationHeight, and AverageCeilingHeight.
  • Allows optional WithinInfiltrationVolume input for conditioned basements; defaults to true.
• Electric vehicle enhancements:
  • Allows detailed modeling of electric vehicles (batteries and charging/discharging) using Vehicles as an alternative to the simple EV charging PlugLoad.
  • Adds EV driving unmet hours output.
  • Updates the default schedule for the EV charging PlugLoad to better reflect real-world hourly/monthly variation.
• Electric panel NEC load calculations (experimental research feature):
  • Allows optional ElectricPanel inputs for describing branch circuits and service feeders
  • Optionally reports breaker spaces and calculated loads for specified NEC calculation types (SoftwareInfo/extension/ElectricPanelCalculations/ServiceFeeders/Type)
• Allows requesting timeseries EnergyPlus output meters (e.g., --hourly "MainsWater:Facility"), similar to requesting EnergyPlus output variables.
• BuildResidentialScheduleFile measure:
  • Adds stochastic schedule generation for electric vehicle charging (using Vehicles).
  • Removes generation of stochastic schedules for building components not present in the HPXML file.
• Output updates:
  • Breaking change: Adds generator electricity produced to total fuel/energy use; previously it was only included in net values.
  • Adds optional new outputs for timeseries zone conditions (humidity ratio and relative humidity and dewpoint, radiant, and operative temperatures).
  • Adds new outputs for net peak electricity (summer/winter/annual); same as total peak electricity outputs but subtracts power produced by PV.
  • Avoids writing the E+ eplustbl.htm by default; use the debug flag to get it.
  • Deletes eplusout*.msgpack files by default (run_simulation.rb only); use the debug flag to preserve them.
• Allows arbitrary columns to be present in a detailed schedule csv file with warning.

Bugfixes

• Fixes EPvalidator schematron file extension (.sch, not .xml).
• Fixes zero occupants specified for one unit in a whole MF building from being treated like zero occupants for every unit.
• Fixes using detailed schedules with higher resolution (e.g., 10-min data) than the simulation timestep (e.g., 60-min).
• Fixes possible heating/cooling spikes when using maximum power ratio detailed schedule for variable-speed HVAC systems.
• Fixes unavailable periods for two consecutive, but partial, days.
• Fixes error when specifying a glass block window without interior shading coefficients.
• Fixes battery charging/discharging not being included in peak electricity outputs.
• Fixes possible error if there's a surface w/ interior unconditioned space and exterior "other housing unit".
• Fixes default shading coefficients for window solar screens and solar film.
• Fixes SolarFraction documentation/error-checking for solar thermal systems; must now be <= 0.99.
• Fixes whole house fans so that they are unavailable during vacancies.
• Fixes error if there's a vented attic with zero roof pitch.
• Fixes tank loss coefficient when TankModelType=stratified for a conventional storage water heater.
• Fixes possibility of incorrect design duct load for really bad ducts (e.g., ducts with high surface area in a cold attic).
• Fixes duplicate emission end use rows for electricity in results_annual.csv.
• Adds error-checking to ensure TankModelType=stratified is not used with a non-electric water heater.
• BuildResidentialHPXML measure: Improves default duct areas/locations for 1-story buildings with a conditioned basement and ducts located in the attic.
• BuildResidentialHPXML measure: Fixes error when specifying a combi boiler as the water heater type and a shared boiler as the heating system type.
• BuildResidentialScheduleFile measure: Fixes out-of-sync shifting of occupancy and end use schedule resulting in activities even when there is no occupancy.
• BuildResidentialScheduleFile measure: Fixes a small bug in sink schedule generation resulting in more concentrated schedule.
• ReportUtilityBills measure: Apply fixed charges for fuels that are referenced by the HPXML file but consume no energy (e.g., gas heating system in Florida).

OpenStudio-HPXML v1.9.1

OpenStudio-HPXML v1.9.1 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.9.1 uses OpenStudio v3.9.0, EnergyPlus v24.2.0, and HPXML v4.1-rc1. Please visit the OpenStudio-HPXML v1.9.1 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Now can be used to obtain ACCA Manual J approval; see the OpenStudio-HPXML documentation.

Bugfixes

• Fixes Manual J design load calculations for radiant floors.

OpenStudio-HPXML v1.9.0

OpenStudio-HPXML version 1.9.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.9.0 uses OpenStudio v3.9.0, EnergyPlus v24.2.0, and HPXML v4.1-rc1. Please visit the OpenStudio-HPXML v1.9.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.9/EnergyPlus 24.2/HPXML v4.1-rc1.
• Allows Site/Address/ZipCode to be provided instead of ClimateandRiskZones/WeatherStation/extension/EPWFilePath, in which case the closest TMY3 weather station will be automatically selected.
• Allows optional inputs for modeling skylight curbs and/or shafts.
• Allows modeling exterior horizontal insulation for a slab-on-grade foundation (or basement/crawlspace floor).
• Allows alternative infiltration input AirInfiltrationMeasurement/LeakinessDescription, in which the infiltration level is estimated using age of home, climate zone, foundation type, etc.
• Window shading enhancements:
  • Allows optional InteriorShading/Type input (blinds, shades, curtains) as a way to default summer/winter shading coefficients.
  • Allows optional ExteriorShading/Type input (trees, solar screens/films, etc.) as a way to default summer/winter shading coefficients.
  • Allows optional InsectScreen input.
• Adds optional BuildingConstruction/UnitHeightAboveGrade input for, e.g., apartment units of upper levels where the wind speed, and thus infiltration rate, is higher.
• Updates operational calculations (i.e., when NumberofResidents provided):
  • Updates hot water usage based on FSEC study.
  • Updates misc/tv plug load usage based on RECS 2020 data.
  • Updates relationship between number of bedrooms and number of occupants to use RECS 2020 instead of RECS 2015.
• Allows optional HeatingCapacity and BackupHeatingCapacity inputs for heat pump water heaters (HPWHs).
• Central Fan Integrated Supply (CFIS) mechanical ventilation enhancements:
  • Allows CFIS systems without automatic flow control of outdoor air (CFISControls/HasOutdoorAirControl=false).
  • Allows CFIS systems with no strategy to meet remainder of ventilation target (CFISControls/AdditionalRuntimeOperatingMode="none").
  • Allows CFIS systems with supplemental fans that run simultaneously with the air handler (CFISControls/extension/SupplementalFanRunsWithAirHandlerFan=true).
  • Allows CFIS systems with timer control, in which ventilation operation occurs at a fixed interval (CFISControls/extension/ControlType="timer").
  • Allows CFIS systems to be attached to ductless HVAC systems like PTHPs (requires using a DSE=1 distribution system, see documentation).
• HVAC Manual J design load and sizing calculations:
  • Adds optional DistributionSystemType/AirDistribution/extension/ManualJInputs/BlowerFanHeatBtuh input for HVAC equipment whose performance data has not been adjusted for blower heat.
  • Adds optional DistributionSystemType/AirDistribution/extension/ManualJInputs/DefaultTableDuctLoad input to use Manual J default duct factor tables instead of ASHRAE 152.
  • Adds optional DistributionSystemType/HydronicDistribution/extension/ManualJInputs/HotWaterPipingBtuh input to include hydronic distribution piping losses through unconditioned spaces.
  • Adds optional HVACSizingControl/ManualJInputs/InfiltrationShieldingClass input to specify wind shielding class for infiltration design load calculations.
  • Adds optional HVACSizingControl/ManualJInputs/InfiltrationMethod input to specify which method to use for infiltration design load calculations.
  • Updates heat pump HERS sizing methodology to better prevent unmet hours in warmer climates.
  • Misc Manual J design load calculation improvements.
  • Breaking change: Disaggregates "Walls" into "Above Grade Walls" and "Below Grade Walls" in results_design_load_details.csv output file.
  • Significant speed improvements when using optional space-level design load calculations.
• Advanced research features:
  • Optional input SimulationControl/AdvancedResearchFeatures/OnOffThermostatDeadbandTemperature to model on/off thermostat deadband with start-up degradation for single and two speed AC/ASHP systems and time-based realistic staging for two speed AC/ASHP systems.
  • Optional input SimulationControl/AdvancedResearchFeatures/HeatPumpBackupCapacityIncrement to model multi-stage electric backup coils with time-based staging.
  • Maximum power ratio detailed schedule for variable-speed HVAC systems can now be used with NumberofUnits dwelling unit multiplier.
• BuildResidentialHPXML measure:
  • Breaking change: Replaced slab_under_width and slab_perimeter_depth arguments with slab_under_insulation_width and slab_perimeter_insulation_depth
  • Breaking change: Replaced schedules_vacancy_periods, schedules_power_outage_periods, and schedules_power_outage_periods_window_natvent_availability arguments with schedules_unavailable_period_types, schedules_unavailable_period_dates, and schedules_unavailable_period_window_natvent_availabilities; this improves flexibility for handling more unavailable period types.
• Utility bill calculations:
  • Allows OpenEI URDB tariffs that have $/day fixed charges.
  • Updates openei_rates.zip with the latest residential utility rates from the OpenEI U.S. Utility Rate database.
• Adds a warning if the sum of supply/return duct leakage to outside values is very high.

Bugfixes

• Prevents possible error if only one of FracSensible/FracLatent are provided for a PlugLoad or FuelLoad; Breaking change: FracSensible and FracLatent must now be both be provided or omitted.
• Prevents possible error when using multiple Attic/Foundation elements for the same attic/foundation type.
• Adds error-checking for NumberofConditionedFloorsAboveGrade=0, which is not allowed per the documentation.
• Fixes utility bill calculations if there is battery storage or a generator.
• BuildResidentialScheduleFile measure: Fixes possible divide by zero error during generation of stochastic clothes washer and dishwasher schedules.
• Allows negative values for Building/Site/Elevation.
• Fixes lower element height for a water heater using the advanced WaterHeatingSystem/extension/TankModelType=stratified.
• Fixes possible error for a combi boiler system.
• Fixes error if modeling a ground-to-air heat pump with a separate backup heating system.
• Fixes default CFIS fan power during ventilation only mode.
• Fixes a bug that potentially oversizes heat pumps when detailed performance capacity fractions are provided.
• For a CFIS system with a supplemental fan, fixes supplemental fan runtime when using sub-hourly timesteps.
• Fixes GSHP rated fan/pump powers in net to gross calculations and improves default modeled pump power (W/ton).

OpenStudio-HPXML v1.8.1

OpenStudio-HPXML version 1.8.1 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.8.1 uses OpenStudio v3.8.0, EnergyPlus v24.1.0, and HPXML v4.0-rc4. Please visit the OpenStudio-HPXML v1.8.1 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

Bugfixes

• Fixes cfm/ton restriction from incorrectly applying to furnace heating airflow rate.

OpenStudio-HPXML v1.8.0

OpenStudio-HPXML version 1.8.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.8.0 uses OpenStudio v3.8.0, EnergyPlus v24.1.0, and HPXML v4.0-rc4. Please visit the OpenStudio-HPXML v1.8.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.8/EnergyPlus 24.1/HPXML v4.0-rc4.
• Adds BPI-2400 HPXML test files and results; see Testing Framework for more information.
• Updates per ANSI/RESNET/ICC 301-2022 w/ Addendum C:
  • Breaking change: For shared water heaters, NumberofUnitsServed is replaced by extension/NumberofBedroomsServed.
  • Breaking change: For shared hot water recirculation systems, NumberofUnitsServed is replaced by NumberofBedroomsServed.
  • Allows shared batteries (batteries serving multiple dwelling units).
  • Updated default CFIS fan power to 0.58 W/cfm.
  • Removed natural ventilation availability RH constraint; HR constraint remains.
  • Refrigerator and freezer schedules may now be based on ambient temperature using new TemperatureScheduleCoefficients and ConstantScheduleCoefficients inputs; the refrigerator default schedule uses these new inputs.
  • Default schedules updated for cooking ranges, lighting, plug loads, televisions, hot water recirculation pumps, and occupant heat gains.
  • Adds schedule inputs for hot water recirculation pumps and general water use internal gains.
  • Updated water heater installation default location.
  • Updated calculation of hot water piping length for buildings with both conditioned and unconditioned basements to avoid double counting.
  • Updated how imbalanced infiltration and mechanical ventilation are combined on an hourly basis.
  • Updated handling of duct leakage imbalance induced infiltration.
  • Small change to default flow rate for imbalanced mechanical ventilation systems.
  • Updated window default interior shade coefficients to be calculated based on SHGC.
  • AverageCeilingHeight now used in natural ACH/CFM infiltration calculations.
• Breaking change: Replaces BuildingSummary/Site/extension/GroundConductivity with BuildingSummary/Site/Soil/Conductivity.
• Breaking change: Modeling whole SFA/MF buildings is now specified using a SoftwareInfo/extension/WholeSFAorMFBuildingSimulation=true element instead of building-id=ALL argument.
• Breaking change: Skylights attached to roofs of attics (e.g., with shafts or sun tunnels) must include the Skylight/AttachedToFloor element.
• Air source heat pump/air conditioner enhancements:
  • Adds heat pump backup autosizing methodology input (HeatPumpBackupSizingMethodology) with choices of "emergency" and "supplemental".
  • Allows autosizing with detailed performance data inputs for variable-speed HVAC systems using CapacityFractionOfNominal.
  • Now defaults to -20F for CompressorLockoutTemperature for variable-speed heat pump systems.
• Ground source heat pump enhancements:
  • Allows optional detailed inputs related to geothermal loop (HVACPlant/GeothermalLoop).
  • Allows optional ground diffusivity input.
  • Updates to using G-Functions from the G-Function Library for Modeling Vertical Bore Ground Heat Exchanger.
  • Updated heating/cooling performance curves to reflect newer equipment.
  • Adds geothermal loop outputs (number/length of boreholes) to annual results output file.
• HVAC Manual J design load and sizing calculations:
  • Breaking change: Outputs for "Infiltration/Ventilation" category disaggregated into "Infiltration" and "Ventilation".
  • Breaking change: Outputs for "Windows" category no longer includes AED excursion; now a separate "AED Excursion" category.
  • Allows optional HeatingAutosizingFactor, CoolingAutosizingFactor, BackupHeatingAutosizingFactor inputs to scale HVAC capacities for autosized equipment.
  • Allows optional HeatingAutosizingLimit, CoolingAutosizingLimit, BackupHeatingAutosizingLimit inputs to set maximum HVAC capacities ceiling for autosized equipment.
  • Allows optional zone-level and space-level design load calculations using HPXML Zones/Zone[ZoneType="conditioned"]/Spaces/Space elements.
  • Allows additional outdoor design condition inputs: DailyTemperatureRange and HumidityDifference.
  • Adds a new detailed output file with block/space load details by surface, AED curves, etc.
  • Miscellaneous improvements.
• Allows optional Ducts/DuctShape and Ducts/DuctFractionRectangular inputs, which affect duct effective R-value used for modeling.
• Adds optional Slab/extension/GapInsulationRValue input for cases where a slab has horizontal (under slab) insulation.
• Allows radiant barriers for additional locations (attic gable walls and floor); reduced emissivity due to dust assumed for radiant barriers on attic floor.
• Adds window and skylight GlassType options of "low-e, high-solar-gain" and "low-e, low-solar-gain"; updates U-factor/SHGC lookup tables.
• Updates default temperature capacitance multiplier from 1 to 7, an average value found in the literature when calibrating timeseries EnergyPlus indoor temperatures to field data.
• Allows optional building site inputs (GeoLocation/Latitude, GeoLocation/Longitude, Elevation); useful when located far from, or at a very different elevation than, the EPW weather station.
• Updates default ShieldingofHome to be "well-shielded" for single-family attached and multifamily dwelling units.
• Improves heating/cooling component loads; for timesteps where there is no heating/cooling load, assigns heat transfer to heating or cooling by comparing indoor temperature to the average of heating/cooling setpoints.
• Adds net energy and net electricity timeseries output columns even when there is no PV or generator.
• Allow alternative label energy use (W) input for ceiling fans.
• Replaced state-average default fuel prices with EIA State Energy Data System (SEDS) prices.
• Adds more error-checking for inappropriate inputs (e.g., HVAC SHR=0 or clothes washer IMEF=0).
• Updates to run_simulation.rb script:
  • Allows requesting timeseries outputs with different frequencies (e.g., --hourly enduses --monthly temperatures).
  • Breaking change: Deprecates --add-timeseries-output-variable; EnergyPlus output variables can now be requested like other timeseries categories (using e.g. --hourly 'Zone People Occupant Count').
  • Adds an optional --skip-simulation argument that allows skipping the EnergyPlus simulation.
• BuildResidentialHPXML measure:
  • Breaking change: Replaces roof_radiant_barrier/roof_radiant_barrier_grade arguments with radiant_barrier_attic_location/radiant_barrier_grade.
  • Allows specifying number of bedrooms served by the water heater which is used for apportioning tank losses; Breaking change: Replaces water_heater_num_units_served with water_heater_num_bedrooms_served.
  • Allows defining multiple unavailable periods; Breaking change: arguments renamed to schedules_vacancy_periods, schedules_power_outage_periods, and schedules_power_outage_periods_window_natvent_availability.
  • Adds detailed performance data inputs for variable-speed air source HVAC systems.
  • Adds heat pump backup sizing methodology input.
  • Add soil and moisture type arguments (for determining ground conductivity and diffusivity) and optional geothermal loop arguments for ground source heat pumps.
  • The "Geometry: Building Number of Units" input is now written to the HPXML NumberofUnitsInBuilding element.
  • Adds a blower fan efficiency input for specifying fan power W/cfm at maximum speed.
• BuildResidentialScheduleFile measure:
  • Allows appending columns to an existing CSV file rather than overwriting.
  • Other plug load schedules now use Other schedule fractions per ANSI/RESNET/ICC 301-2022 Addendum C.
  • TV plug load schedules now use TV schedule fractions from the American Time Use Survey and monthly multipliers from the 2010 Building America Analysis Spreadsheets.
  • Ceiling fan schedules now use ceiling fan schedule fractions and monthly multipliers from ANSI/RESNET/ICC 301-2022 Addendum C.
• ReportUtilityBills measure:
  • Adds new optional arguments for registering (with the OpenStudio runner) annual or monthly utility bills.
• Advanced research features:
  • Breaking change: Replaces SimulationControl/TemperatureCapacitanceMultiplier with SimulationControl/AdvancedResearchFeatures/TemperatureCapacitanceMultiplier.
  • Allows an optional boolean input SimulationControl/AdvancedResearchFeatures/DefrostModelType for heat pump advanced defrost model.
  • Adds maximum power ratio detailed schedule for variable-speed HVAC systems to model shedding controls per AHRI 1380.

Bugfixes

• Fixes error if using AllowIncreasedFixedCapacities=true w/ HP detailed performance data.
• Prevents mains water temperature from going below freezing (0 C).
• Fixes error if HPXML has emissions scenario and abbreviated run period.
• Fixes detailed schedule error-checking where schedules with MAX < 1 were incorrectly allowed.
• Fixes error if using MF space types (e.g., "other heated space") and the building has no HVAC equipment...

OpenStudio-HPXML v1.7.0

OpenStudio-HPXML version 1.7.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.7.0 uses OpenStudio v3.7.0, EnergyPlus v23.2.0, and HPXML v4.0-rc2. Please visit the OpenStudio-HPXML v1.7.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.7.0/EnergyPlus 23.2.
• Breaking change: Updates to HPXML v4.0-rc2:
  • HPXML namespace changed from http://hpxmlonline.com/2019/10 to http://hpxmlonline.com/2023/09.
  • Replaces "living space" with "conditioned space", which better represents what is modeled.
  • Replaces HotTubs/HotTub with Spas/PermanentSpa.
  • Replaces PortableHeater and FixedHeater with SpaceHeater.
• Allows simulating whole multifamily (MF) buildings in a single combined simulation:
  • Breaking change: Multiple elements move from SoftwareInfo/extension to BuildingDetails/BuildingSummary/extension to allow variation across units:
    • HVACSizingControl
    • ShadingControl
    • SchedulesFilePath
    • NaturalVentilationAvailabilityDaysperWeek
  • Allows NumberofUnits to be used as a multiplier on dwelling unit simulation results to reduce simulation runtime.
  • See the OpenStudio-HPXML documentation for more detail.
• HVAC modeling updates:
  • Updated assumptions for variable-speed air conditioners, heat pumps, and mini-splits based on NEEP data. Expect results to change, potentially significantly so depending on the scenario.
  • Allows detailed heating and cooling performance data (min/max COPs and capacities at different outdoor temperatures) for variable-speed systems.
  • Updates deep ground temperatures (used for modeling ground-source heat pumps) using L. Xing's simplified design model (2014).
  • Replaces inverse calculations, used to calculate COPs from rated efficiencies, with regressions for single/two-speed central ACs and ASHPs.
• Output updates:
  • Breaking change: "Hot Tub" outputs renamed to "Permanent Spa".
  • Adds "Peak Electricity: Annual Total (W)" output.
  • Adds battery resilience hours output; allows requesting timeseries output.
  • ReportUtilityBills measure: Allows reporting monthly utility bills in addition to (or instead of) annual bills.
• BuildResidentialHPXML measure:
  • Allow duct area fractions (as an alternative to duct areas in ft^2).
  • Allow duct locations to be provided while defaulting duct areas (i.e., without providing duct area/fraction inputs).
  • Add generic "attic" and "crawlspace" location choices for supply/return ducts, water heater, and battery.
  • Always validate the HPXML file before applying defaults and only optionally validate the final HPXML file.
• Adds manufactured home belly as a foundation type and allows modeling ducts in a manufactured home belly.
• Battery losses now split between charging and discharging.
• Interior/exterior window shading multipliers are now modeled using the EnergyPlus incident solar multiplier.
• Allows WaterFixture/FlowRate as an alternative to LowFlow; hot water credit is now calculated based on fraction of low flow fixtures.
• Allows above-grade basements/crawlspaces defined solely with Wall (not FoundationWall) elements.
• Updates to 2022 EIA energy costs.
• Added README.md documentation for all OpenStudio measures.

Bugfixes

• Fixes battery resilience output to properly incorporate battery losses.
• Fixes lighting multipliers not being applied when kWh/yr inputs are used.
• Fixes running detailed schedules with mixed timesteps (e.g., hourly heating/cooling setpoints and 15-minutely miscellaneous plug load schedules).
• Fixes calculation of utility bill fixed costs for simulations with abbreviated run periods.
• Fixes error if heat pump CompressorLockoutTemperature == BackupHeatingLockoutTemperature.
• Fixes possible "Electricity category end uses do not sum to total" error for a heat pump w/o backup.
• Fixes ground source heat pump fan/pump adjustment to rated efficiency.
• Fixes error if conditioned basement has InsulationSpansEntireSlab=true.
• Fixes ReportSimulationOutput outputs for the Parametric Analysis Tool (PAT).
• Fixes missing radiation exchange between window and sky when an interior/exterior window shading multiplier less than 1 exists.
• Fixes monthly shallow ground temperatures (used primarily in HVAC autosizing) for the southern hemisphere.
• Various HVAC sizing bugfixes and improvements.
• Fixes low-speed heating COPs for some two-speed ASHPs and cooling COPs for some single-speed ACs/HPs.
• BuildResidentialHPXML measure: Fixes air distribution CFA served when there is not a central system that meets 100% of the load.

OpenStudio-HPXML v1.6.0

OpenStudio-HPXML version 1.6.0 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.6.0 uses OpenStudio v3.6.1, EnergyPlus v23.1.0, and a proposed HPXML v4.0. Please visit the OpenStudio-HPXML v1.6.0 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• Updates to OpenStudio 3.6.1/EnergyPlus 23.1.
• Updates to newer proposed HPXML v4.0:
  • Breaking change: Replaces VentilationFan/Quantity and CeilingFan/Quantity with Count.
  • Breaking change: Replaces PVSystem/InverterEfficiency with PVSystem/AttachedToInverter and Inverter/InverterEfficiency.
  • Breaking change: Replaces WaterHeatingSystem/extension/OperatingMode with WaterHeatingSystem/HPWHOperatingMode for heat pump water heaters.
• Output updates:
  • Breaking change: Adds End Use: Heating Heat Pump Backup Fans/Pumps (disaggregated from End Use: Heating Fans/Pumps).
  • Breaking change: Replaces Component Load: Windows with Component Load: Windows Conduction and Component Load: Windows Solar.
  • Breaking change: Replaces Component Load: Skylights with Component Load: Skylights Conduction and Component Load: Skylights Solar.
  • Breaking change: Adds Component Load: Lighting (disaggregated from Component Load: Internal Gains).
  • Breaking change: Adds "net" values for emissions; "total" values now exclude generation (e.g., PV).
  • Adds Load: Heating: Heat Pump Backup (heating load delivered by heat pump backup systems).
  • Adds System Use outputs (end use outputs for each heating, cooling, and water heating system); allows requesting timeseries output.
  • All annual load outputs are now provided as timeseries outputs; previously only "Delivered" loads were available.
  • Peak summer/winter electricity outputs are now based on Jun/July/Aug and Dec/Jan/Feb months, not HVAC heating/cooling operation.
  • Allows specifying the number of decimal places for timeseries output.
  • Msgpack outputs are no longer rounded (since there is no file size penalty to storing full precision).
  • Annual emissions and utility bills now include all fuel/end uses, even if zero.
  • ReportSimulationOutput measure: Allows disabling individual annual output sections.
• Breaking change: Deprecates OccupancyCalculationType ("asset" or "operational").
  • If NumberofResidents not provided, an asset calculation is performed assuming standard occupancy per ANSI/RESNET/ICC 301.
  • If NumberofResidents is provided, an operational calculation is performed using a relationship between #Bedrooms and #Occupants from RECS 2015.
• Heat pump enhancements:
  • Allows HeatingCapacityRetention[Fraction | Temperature] inputs to define cold-climate performance; like HeatingCapacity17F but can apply to autosized systems and can use a user-specified temperature.
  • Default mini-split heating capacity retention updated from 0.4 to 0.5 (at 5 deg-F).
  • Allows CompressorLockoutTemperature as an optional input to control the minimum temperature the compressor can operate at.
  • Defaults for CompressorLockoutTemperature: 25F for dual-fuel, -20F for mini-split, 0F for all other heat pumps.
  • Defaults for BackupHeatingLockoutTemperature: 50F for dual-fuel, 40F for all other heat pumps.
  • Provides a warning if BackupHeatingSwitchoverTemperature or BackupHeatingLockoutTemperature are low and may cause unmet hours.
  • Autosizing is no longer all-or-none; backup heating can be autosized (defaulted) while specifying the heat pump capacities, or vice versa.
  • Allows extension/CrankcaseHeaterPowerWatts as an optional input; defaults to 50 W for central HPs/ACs and mini-splits.
  • Increased consistency between variable-speed central HP and mini-split HP models for degradation coefficients, gross SHR calculations, etc.
• Infiltration changes:
  • Breaking change: Infiltration for SFA/MF dwelling units must include TypeOfInfiltrationLeakage ("unit total" or "unit exterior only").
  • Breaking change: Replaces BuildingConstruction/extension/HasFlueOrChimney with AirInfiltration/extension/HasFlueOrChimneyInConditionedSpace; defaults now incorporate HVAC/water heater location.
  • Allows infiltration to be specified using CFMnatural or EffectiveLeakageArea.
• Lighting changes:
  • LightingGroups can now be specified using kWh/year annual consumption values as an alternative to fractions of different lighting types.
  • LightingGroups for interior, exterior, and garage are no longer required; if not provided, these lighting uses will not be modeled.
• HVAC sizing enhancements:
  • Allows optional inputs under HVACSizingControl/ManualJInputs to override Manual J defaults for HVAC autosizing calculations.
  • Updates to better align various default values and algorithms with Manual J.
  • Updates design load calculations to handle conditioned basements with insulated slabs.
• Duct enhancements:
  • Allows modeling ducts buried in attic loose-fill insulation using Ducts/DuctBuriedInsulationLevel.
  • Allows specifying Ducts/DuctEffectiveRValue, the value that will be used in the model, though its use is not recommended.
• Allows modeling a pilot light for non-electric heating systems (furnaces, stoves, boilers, and fireplaces).
• Allows summer vs winter shading seasons to be specified for windows and skylights.
• Allows defining one or more UnavailablePeriods (e.g., occupant vacancies or power outage periods).
• Stochastic schedules for garage lighting and TV plug loads now use interior lighting and miscellaneous plug load schedules, respectively.
• Performance improvement for HPXML files w/ large numbers of Building elements.
• Weather cache files (*foo-cache.csv) are no longer used/needed.

Bugfixes

• Fixes BackupHeatingSwitchoverTemperature for a heat pump w/ separate backup system; now correctly ceases backup operation above this temperature.
• Fixes error if calculating utility bills for an all-electric home with a detailed JSON utility rate.
• Stochastic schedules now excludes columns for end uses that are not stochastically generated.
• Fixes operational calculation when the number of residents is set to zero.
• Fixes possible utility bill calculation error for a home with PV using a detailed electric utility rate.
• Fixes defaulted mechanical ventilation flow rate for SFA/MF buildings, with respect to infiltration credit.
• HPXML files w/ multiple Building elements now only show warnings for the single Building being simulated.
• Adds a warning for SFA/MF dwelling units without at least one attached wall/ceiling/floor surface.
• Various fixes for window/skylight/duct design loads for Manual J HVAC autosizing calculations.
• Ensure that ductless HVAC systems do not have a non-zero airflow defect ratio specified.
• Fixes possible "A neighbor building has an azimuth (XX) not equal to the azimuth of any wall" for SFA/MF units with neighboring buildings for shade.
• Fixes reported loads when no/partial HVAC system (e.g., room air conditioner that meets 30% of the cooling load).

OpenStudio-HPXML v1.5.1

OpenStudio-HPXML version 1.5.1 has been released. The OpenStudio-HPXML workflow uses HPXML building description files to run residential simulations on the Department of Energy's OpenStudio/EnergyPlus building simulation platform.

OpenStudio-HPXML v1.5.1 uses OpenStudio v3.5.0, EnergyPlus v22.2.0, and a proposed HPXML v4.0. Please visit the OpenStudio-HPXML v1.5.1 documentation for instructions on how to get started, how to generate an appropriate HPXML file, etc. The full set of US TMY3 weather files can be obtained from here.

New Features

• When Battery/Location not provided, now defaults to garage if present, otherwise outside.
• BuildResidentialScheduleFile measure:
  • Allows requesting a subset of end uses (columns) to be generated.

Bugfixes

• Fixes total/net electricity timeseries outputs to include battery charging/discharging energy.
• Fixes error when a non-electric water heater has jacket insulation and the UEF metric is used.