Allow more fuel economy units for EVs. Fix documentation for EV plug load default kWh/year. Remove separate charging/discharging schedules. Some misc cleanup.

Author: shorowit

BuildResidentialHPXML/README.md

@@ -4549,14 +4549,14 @@ The usable capacity of the vehicle battery, only applies to electric vehicles. I
 
 **Vehicle: Combined Fuel Economy Units**
 
-The combined fuel economy units of the vehicle. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-vehicles'>HPXML Vehicles</a>) is used.
+The combined fuel economy units of the vehicle. Only 'kWh/mile', 'mile/kWh', or 'mpge' are allow for electric vehicles. If not provided, the OS-HPXML default (see <a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-vehicles'>HPXML Vehicles</a>) is used.
 
 - **Name:** ``vehicle_fuel_economy_units``
 - **Type:** ``Choice``
 
 - **Required:** ``false``
 
-- **Choices:** `kWh/mile`
+- **Choices:** `kWh/mile`, `mile/kWh`, `mpge`, `mpg`
 
 <br/>
 

BuildResidentialHPXML/measure.rb

@@ -2702,10 +2702,13 @@ def arguments(model) # rubocop:disable Lint/UnusedMethodArgument
 
     fuel_economy_units_choices = OpenStudio::StringVector.new
     fuel_economy_units_choices << HPXML::UnitsKwhPerMile
+    fuel_economy_units_choices << HPXML::UnitsMilePerKwh
+    fuel_economy_units_choices << HPXML::UnitsMPGe
+    fuel_economy_units_choices << HPXML::UnitsMPG
 
     arg = OpenStudio::Measure::OSArgument::makeChoiceArgument('vehicle_fuel_economy_units', fuel_economy_units_choices, false)
     arg.setDisplayName('Vehicle: Combined Fuel Economy Units')
-    arg.setDescription("The combined fuel economy units of the vehicle. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-vehicles'>HPXML Vehicles</a>) is used.")
+    arg.setDescription("The combined fuel economy units of the vehicle. Only '#{HPXML::UnitsKwhPerMile}', '#{HPXML::UnitsMilePerKwh}', or '#{HPXML::UnitsMPGe}' are allow for electric vehicles. If not provided, the OS-HPXML default (see <a href='#{docs_base_url}#hpxml-vehicles'>HPXML Vehicles</a>) is used.")
     args << arg
 
     arg = OpenStudio::Measure::OSArgument::makeDoubleArgument('vehicle_fuel_economy_combined', false)
@@ -6977,7 +6980,7 @@ def self.set_vehicle(hpxml_bldg, args)
                               vehicle_type: args[:vehicle_type],
                               nominal_capacity_kwh: args[:vehicle_battery_capacity],
                               usable_capacity_kwh: args[:vehicle_battery_usable_capacity],
-                              fuel_economy: args[:vehicle_fuel_economy_combined],
+                              fuel_economy_combined: args[:vehicle_fuel_economy_combined],
                               fuel_economy_units: args[:vehicle_fuel_economy_units],
                               miles_per_year: args[:vehicle_miles_driven_per_year],
                               hours_per_week: args[:vehicle_hours_driven_per_week],

BuildResidentialHPXML/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>build_residential_hpxml</name>
   <uid>a13a8983-2b01-4930-8af2-42030b6e4233</uid>
-  <version_id>92bf4050-3214-403a-8336-e33ab0b2ca04</version_id>
-  <version_modified>2025-01-25T03:34:35Z</version_modified>
+  <version_id>fc615f45-c9b7-4fa8-9143-e3ef83019ed6</version_id>
+  <version_modified>2025-02-04T22:22:51Z</version_modified>
   <xml_checksum>2C38F48B</xml_checksum>
   <class_name>BuildResidentialHPXML</class_name>
   <display_name>HPXML Builder</display_name>
@@ -5549,7 +5549,7 @@
     <argument>
       <name>vehicle_fuel_economy_units</name>
       <display_name>Vehicle: Combined Fuel Economy Units</display_name>
-      <description>The combined fuel economy units of the vehicle. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-vehicles'&gt;HPXML Vehicles&lt;/a&gt;) is used.</description>
+      <description>The combined fuel economy units of the vehicle. Only 'kWh/mile', 'mile/kWh', or 'mpge' are allow for electric vehicles. If not provided, the OS-HPXML default (see &lt;a href='https://openstudio-hpxml.readthedocs.io/en/v1.10.0/workflow_inputs.html#hpxml-vehicles'&gt;HPXML Vehicles&lt;/a&gt;) is used.</description>
       <type>Choice</type>
       <required>false</required>
       <model_dependent>false</model_dependent>
@@ -5558,6 +5558,18 @@
           <value>kWh/mile</value>
           <display_name>kWh/mile</display_name>
         </choice>
+        <choice>
+          <value>mile/kWh</value>
+          <display_name>mile/kWh</display_name>
+        </choice>
+        <choice>
+          <value>mpge</value>
+          <display_name>mpge</display_name>
+        </choice>
+        <choice>
+          <value>mpg</value>
+          <display_name>mpg</display_name>
+        </choice>
       </choices>
     </argument>
     <argument>
@@ -7648,7 +7660,7 @@
       <filename>README.md</filename>
       <filetype>md</filetype>
       <usage_type>readme</usage_type>
-      <checksum>B3788EAB</checksum>
+      <checksum>68786DA5</checksum>
     </file>
     <file>
       <filename>README.md.erb</filename>
@@ -7665,7 +7677,7 @@
       <filename>measure.rb</filename>
       <filetype>rb</filetype>
       <usage_type>script</usage_type>
-      <checksum>2EAA7A94</checksum>
+      <checksum>A0C9DB49</checksum>
     </file>
     <file>
       <filename>constants.rb</filename>

HPXMLtoOpenStudio/measure.xml

@@ -3,8 +3,8 @@
   <schema_version>3.1</schema_version>
   <name>hpxm_lto_openstudio</name>
   <uid>b1543b30-9465-45ff-ba04-1d1f85e763bc</uid>
-  <version_id>03140da5-ec98-48c7-9f17-ae1f326c3c2b</version_id>
-  <version_modified>2025-02-04T21:19:23Z</version_modified>
+  <version_id>1e6e4ecc-c633-4d53-ba12-23bd26f6e1ac</version_id>
+  <version_modified>2025-02-04T22:22:56Z</version_modified>
   <xml_checksum>D8922A73</xml_checksum>
   <class_name>HPXMLtoOpenStudio</class_name>
   <display_name>HPXML to OpenStudio Translator</display_name>
@@ -327,7 +327,7 @@
       <filename>defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>E6A26236</checksum>
+      <checksum>8FE4492D</checksum>
     </file>
     <file>
       <filename>energyplus.rb</filename>
@@ -357,7 +357,7 @@
       <filename>hpxml.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>173BF9FE</checksum>
+      <checksum>B0060C22</checksum>
     </file>
     <file>
       <filename>hpxml_schema/HPXML.xsd</filename>
@@ -375,7 +375,7 @@
       <filename>hpxml_schematron/EPvalidator.xml</filename>
       <filetype>xml</filetype>
       <usage_type>resource</usage_type>
-      <checksum>8946CDA1</checksum>
+      <checksum>84286045</checksum>
     </file>
     <file>
       <filename>hpxml_schematron/iso-schematron.xsd</filename>
@@ -639,7 +639,7 @@
       <filename>vehicle.rb</filename>
       <filetype>rb</filetype>
       <usage_type>resource</usage_type>
-      <checksum>AE524D89</checksum>
+      <checksum>E5218BFB</checksum>
     </file>
     <file>
       <filename>version.rb</filename>
@@ -687,7 +687,7 @@
       <filename>test_defaults.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>3B90FC06</checksum>
+      <checksum>66403D3F</checksum>
     </file>
     <file>
       <filename>test_enclosure.rb</filename>
@@ -759,7 +759,7 @@
       <filename>test_validation.rb</filename>
       <filetype>rb</filetype>
       <usage_type>test</usage_type>
-      <checksum>393966E0</checksum>
+      <checksum>5068EA86</checksum>
     </file>
     <file>
       <filename>test_vehicle.rb</filename>

HPXMLtoOpenStudio/resources/battery.rb

@@ -12,7 +12,7 @@ module Battery
   # @return [nil]
   def self.apply(runner, model, spaces, hpxml_bldg, schedules_file)
     charging_schedule, discharging_schedule = nil, nil
-    if !schedules_file.nil?
+    if not schedules_file.nil?
       charging_schedule = schedules_file.create_schedule_file(model, col_name: SchedulesFile::Columns[:BatteryCharging].name)
       discharging_schedule = schedules_file.create_schedule_file(model, col_name: SchedulesFile::Columns[:BatteryDischarging].name)
     end

HPXMLtoOpenStudio/resources/defaults.rb

@@ -3190,11 +3190,9 @@ def self.apply_vehicles(hpxml_bldg, schedules_file)
         vehicle.battery_type = default_values[:battery_type]
         vehicle.battery_type_isdefaulted = true
       end
-      if vehicle.fuel_economy.nil?
-        vehicle.fuel_economy = default_values[:fuel_economy]
-        vehicle.fuel_economy_isdefaulted = true
-      end
-      if vehicle.fuel_economy_units.nil?
+      if vehicle.fuel_economy_combined.nil? || vehicle.fuel_economy_units.nil?
+        vehicle.fuel_economy_combined = default_values[:fuel_economy_combined]
+        vehicle.fuel_economy_combined_isdefaulted = true
         vehicle.fuel_economy_units = default_values[:fuel_economy_units]
         vehicle.fuel_economy_units_isdefaulted = true
       end
@@ -5732,7 +5730,7 @@ def self.get_electric_vehicle_values()
              hours_per_week: 8.88,
              nominal_capacity_kwh: 63,
              nominal_voltage: 50.0,
-             fuel_economy: 0.22,
+             fuel_economy_combined: 0.22,
              fuel_economy_units: HPXML::UnitsKwhPerMile,
              fraction_charged_home: 0.8,
              usable_fraction: 0.8 } # Fraction of usable capacity to nominal capacity
@@ -5942,8 +5940,9 @@ def self.get_electric_vehicle_charging_annual_energy()
 
     # Use detailed vehicle model defaults
     vehicle_defaults = get_electric_vehicle_values
+    kwh_per_year = vehicle_defaults[:miles_per_year] * vehicle_defaults[:fuel_economy_combined] * vehicle_defaults[:fraction_charged_home] / (ev_charger_efficiency * ev_battery_efficiency)
 
-    return vehicle_defaults[:miles_per_year] * vehicle_defaults[:fuel_economy] * vehicle_defaults[:fraction_charged_home] / (ev_charger_efficiency * ev_battery_efficiency)
+    return kwh_per_year.round(1)
   end
 
   # Gets the default well pump annual energy use.

HPXMLtoOpenStudio/resources/hpxml.rb

@@ -9376,7 +9376,7 @@ class Vehicle < BaseElement
              :vehicle_type,           # [String] VehicleType (HPXML::VehicleTypeXXX)
              :miles_per_year,         # [Double] MilesDrivenPerYear (miles)
              :hours_per_week,         # [Double] HoursDrivenPerWeek (hours)
-             :fuel_economy,           # [Double] FuelEconomyCombined/Value
+             :fuel_economy_combined,  # [Double] FuelEconomyCombined/Value
              :fuel_economy_units,     # [String] FuelEconomyCombined/Units
              :fraction_charged_home,  # [Double] VehicleType/BatteryElectricVehicle/FractionChargedLocation[Location="Home"]/Percentage (frac)
              :ev_charger_idref,       # [String] VehicleType/BatteryElectricVehicle/ConnectedCharger/@idref
@@ -9424,38 +9424,36 @@ def to_doc(building)
       vehicle_type = XMLHelper.add_element(vehicle_type_element, @vehicle_type)
 
       if [HPXML::VehicleTypeBEV, HPXML::VehicleTypePHEV, HPXML::VehicleTypeHybrid].include? @vehicle_type
-        # Battery
-        unless [@battery_type.nil?, @nominal_capacity_kwh.nil?, @nominal_capacity_ah.nil?, @usable_capacity_kwh.nil?, @usable_capacity_ah.nil?, @nominal_voltage.nil?, @lifetime_model.nil?].all?
+        if (not @battery_type.nil?) || (not @nominal_capacity_kwh.nil?) || (not @nominal_capacity_ah.nil?) || (not @usable_capacity_kwh.nil?) || (not @usable_capacity_ah.nil?) || (not @nominal_voltage.nil?) || (not @lifetime_model.nil?)
           battery = XMLHelper.add_element(vehicle_type, 'Battery')
+          XMLHelper.add_element(battery, 'BatteryType', @battery_type, :string, @battery_type_isdefaulted) unless @battery_type.nil?
+          if not @nominal_capacity_kwh.nil?
+            nominal_capacity = XMLHelper.add_element(battery, 'NominalCapacity')
+            XMLHelper.add_element(nominal_capacity, 'Units', UnitsKwh, :string)
+            XMLHelper.add_element(nominal_capacity, 'Value', @nominal_capacity_kwh, :float, @nominal_capacity_kwh_isdefaulted)
+          end
+          if not @nominal_capacity_ah.nil?
+            nominal_capacity = XMLHelper.add_element(battery, 'NominalCapacity')
+            XMLHelper.add_element(nominal_capacity, 'Units', UnitsAh, :string)
+            XMLHelper.add_element(nominal_capacity, 'Value', @nominal_capacity_ah, :float, @nominal_capacity_ah_isdefaulted)
+          end
+          if not @usable_capacity_kwh.nil?
+            usable_capacity = XMLHelper.add_element(battery, 'UsableCapacity')
+            XMLHelper.add_element(usable_capacity, 'Units', UnitsKwh, :string)
+            XMLHelper.add_element(usable_capacity, 'Value', @usable_capacity_kwh, :float, @usable_capacity_kwh_isdefaulted)
+          end
+          if not @usable_capacity_ah.nil?
+            usable_capacity = XMLHelper.add_element(battery, 'UsableCapacity')
+            XMLHelper.add_element(usable_capacity, 'Units', UnitsAh, :string)
+            XMLHelper.add_element(usable_capacity, 'Value', @usable_capacity_ah, :float, @usable_capacity_ah_isdefaulted)
+          end
+          XMLHelper.add_element(battery, 'NominalVoltage', @nominal_voltage, :float, @nominal_voltage_isdefaulted) unless @nominal_voltage.nil?
+          XMLHelper.add_extension(battery, 'LifetimeModel', @lifetime_model, :string, @lifetime_model_isdefaulted) unless @lifetime_model.nil?
         end
-        XMLHelper.add_element(battery, 'BatteryType', @battery_type, :string, @battery_type_isdefaulted) unless @battery_type.nil?
-        if not @nominal_capacity_kwh.nil?
-          nominal_capacity = XMLHelper.add_element(battery, 'NominalCapacity')
-          XMLHelper.add_element(nominal_capacity, 'Units', UnitsKwh, :string)
-          XMLHelper.add_element(nominal_capacity, 'Value', @nominal_capacity_kwh, :float, @nominal_capacity_kwh_isdefaulted)
-        end
-        if not @nominal_capacity_ah.nil?
-          nominal_capacity = XMLHelper.add_element(battery, 'NominalCapacity')
-          XMLHelper.add_element(nominal_capacity, 'Units', UnitsAh, :string)
-          XMLHelper.add_element(nominal_capacity, 'Value', @nominal_capacity_ah, :float, @nominal_capacity_ah_isdefaulted)
-        end
-        if not @usable_capacity_kwh.nil?
-          usable_capacity = XMLHelper.add_element(battery, 'UsableCapacity')
-          XMLHelper.add_element(usable_capacity, 'Units', UnitsKwh, :string)
-          XMLHelper.add_element(usable_capacity, 'Value', @usable_capacity_kwh, :float, @usable_capacity_kwh_isdefaulted)
-        end
-        if not @usable_capacity_ah.nil?
-          usable_capacity = XMLHelper.add_element(battery, 'UsableCapacity')
-          XMLHelper.add_element(usable_capacity, 'Units', UnitsAh, :string)
-          XMLHelper.add_element(usable_capacity, 'Value', @usable_capacity_ah, :float, @usable_capacity_ah_isdefaulted)
-        end
-        XMLHelper.add_element(battery, 'NominalVoltage', @nominal_voltage, :float, @nominal_voltage_isdefaulted) unless @nominal_voltage.nil?
-        XMLHelper.add_extension(battery, 'LifetimeModel', @lifetime_model, :string, @lifetime_model_isdefaulted) unless @lifetime_model.nil?
       end
 
       case @vehicle_type
       when HPXML::VehicleTypeBEV
-        # Battery-Electric Vehicle
         fraction_charged_location = XMLHelper.add_element(vehicle_type, 'FractionChargedLocation') unless @fraction_charged_home.nil?
         XMLHelper.add_element(fraction_charged_location, 'Location', HPXML::ElectricVehicleChargingLocation, :string) unless @fraction_charged_home.nil?
         XMLHelper.add_element(fraction_charged_location, 'Percentage', @fraction_charged_home, :float, @fraction_charged_home_isdefaulted) unless @fraction_charged_home.nil?
@@ -9468,12 +9466,13 @@ def to_doc(building)
         XMLHelper.add_extension(vehicle_type, 'MonthlyScheduleMultipliers', @ev_monthly_multipliers, :string, @ev_monthly_multipliers_isdefaulted) unless @ev_monthly_multipliers.nil?
       end
 
-      # Vehicle
       XMLHelper.add_element(vehicle, 'MilesDrivenPerYear', @miles_per_year, :float, @miles_per_year_isdefaulted) unless @miles_per_year.nil?
       XMLHelper.add_element(vehicle, 'HoursDrivenPerWeek', @hours_per_week, :float, @hours_per_week_isdefaulted) unless @hours_per_week.nil?
-      fuel_economy = XMLHelper.add_element(vehicle, 'FuelEconomyCombined') unless @fuel_economy_units.nil? && @fuel_economy.nil?
-      XMLHelper.add_element(fuel_economy, 'Units', @fuel_economy_units, :string, @fuel_economy_units_isdefaulted) unless @fuel_economy_units.nil?
-      XMLHelper.add_element(fuel_economy, 'Value', @fuel_economy, :float, @fuel_economy_isdefaulted) unless @fuel_economy.nil?
+      if (not @fuel_economy_units.nil?) && (not @fuel_economy_combined.nil?)
+        fuel_economy = XMLHelper.add_element(vehicle, 'FuelEconomyCombined')
+        XMLHelper.add_element(fuel_economy, 'Units', @fuel_economy_units, :string, @fuel_economy_units_isdefaulted)
+        XMLHelper.add_element(fuel_economy, 'Value', @fuel_economy_combined, :float, @fuel_economy_combined_isdefaulted)
+      end
     end
 
     # Populates the HPXML object(s) from the XML document.
@@ -9486,7 +9485,7 @@ def from_doc(vehicle)
       @id = HPXML::get_id(vehicle)
       @miles_per_year = XMLHelper.get_value(vehicle, 'MilesDrivenPeryear', :float)
       @hours_per_week = XMLHelper.get_value(vehicle, 'HoursDrivenPerWeek', :float)
-      @fuel_economy = XMLHelper.get_value(vehicle, 'FuelEconomyCombined/Value', :float)
+      @fuel_economy_combined = XMLHelper.get_value(vehicle, 'FuelEconomyCombined/Value', :float)
       @fuel_economy_units = XMLHelper.get_value(vehicle, 'FuelEconomyCombined/Units', :string)
       @vehicle_type = XMLHelper.get_child_name(vehicle, 'VehicleType')
       if @vehicle_type == HPXML::VehicleTypeBEV

HPXMLtoOpenStudio/resources/hpxml_schematron/EPvalidator.xml

@@ -2540,8 +2540,8 @@
       <sch:assert role='ERROR' test='count(h:extension/h:MonthlyScheduleMultipliers) &lt;= 1'>Expected 0 or 1 element(s) for xpath: extension/MonthlyScheduleMultipliers</sch:assert>
       <sch:assert role='ERROR' test='count(../../h:MilesDrivenPerYear) &lt;= 1'>Expected 0 or 1 element(s) for xpath: ../../MilesDrivenPerYear</sch:assert>
       <sch:assert role='ERROR' test='count(../../h:HoursDrivenPerWeek) &lt;= 1'>Expected 0 or 1 element(s) for xpath: ../../HoursDrivenPerWeek</sch:assert>
-      <sch:assert role='ERROR' test='count(../../h:FuelEconomyCombined[h:Units="kWh/mile"]/h:Value) &lt;= 1'>Expected 0 or 1 element(s) for xpath: ../../FuelEconomyCombined[Units="kWh/mile"]/Value</sch:assert>
-      <sch:assert role='ERROR' test='../../h:FuelEconomyCombined[h:Units="kWh/mile"] or not(../../h:FuelEconomyCombined/h:Units)'>Expected ../../FuelEconomyCombined/Units to be "kWh/mile"</sch:assert>
+      <sch:assert role='ERROR' test='count(../../h:FuelEconomyCombined/h:Value) &lt;= 1'>Expected 0 or 1 element(s) for xpath: ../../FuelEconomyCombined/Value</sch:assert>
+      <sch:assert role='ERROR' test='../../h:FuelEconomyCombined[h:Units="kWh/mile" or h:Units="mile/kWh" or h:Units="mpge"] or not(../../h:FuelEconomyCombined/h:Units)'>Expected ../../FuelEconomyCombined/Units to be "kWh/mile" or "mile/kWh" or "mpge"</sch:assert>
       <!-- Warnings -->
       <sch:report role='WARN' test='count(../../../../../h:MiscLoads/h:PlugLoad[h:PlugLoadType[text()="electric vehicle charging"]]) &gt;= 1'>Electric vehicle charging was specified as both a PlugLoad and a Vehicle, the latter will be ignored.</sch:report>
       <sch:report role='WARN' test='count(h:ConnectedCharger) = 0'>Electric vehicle specified with no charger provided; detailed EV charging will not be modeled.</sch:report>