urbanopt-scenario 0.1.0

data/lib/urbanopt/scenario/default_reports/scenario_report.rb

@@ -0,0 +1,276 @@
+# *********************************************************************************
+# URBANopt, Copyright (c) 2019, Alliance for Sustainable Energy, LLC, and other
+# contributors. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+#
+# Redistributions of source code must retain the above copyright notice, this list
+# of conditions and the following disclaimer.
+#
+# Redistributions in binary form must reproduce the above copyright notice, this
+# list of conditions and the following disclaimer in the documentation and/or other
+# materials provided with the distribution.
+#
+# Neither the name of the copyright holder nor the names of its contributors may be
+# used to endorse or promote products derived from this software without specific
+# prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+# ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+# IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+# INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+# OF THE POSSIBILITY OF SUCH DAMAGE.
+# *********************************************************************************
+
+require 'urbanopt/scenario/default_reports/construction_cost'
+require 'urbanopt/scenario/default_reports/feature_report'
+require 'urbanopt/scenario/default_reports/logger'
+require 'urbanopt/scenario/default_reports/program'
+require 'urbanopt/scenario/default_reports/reporting_period'
+require 'urbanopt/scenario/default_reports/timeseries_csv'
+require 'urbanopt/scenario/default_reports/validator'
+require 'json-schema'
+
+require 'json'
+require 'pathname'
+
+module URBANopt
+  module Scenario
+    module DefaultReports
+      ##
+      # ScenarioReport can generate two types of reports from a scenario.
+      # The first is a JSON format saved to 'default_scenario_report.json'.
+      # The second is a CSV format saved to 'default_scenario_report.csv'.
+      ##
+      class ScenarioReport
+        attr_accessor :id, :name, :directory_name, :timesteps_per_hour, :number_of_not_started_simulations,
+                      :number_of_started_simulations, :number_of_complete_simulations, :number_of_failed_simulations,
+                      :timeseries_csv, :location, :program, :construction_costs, :reporting_periods, :feature_reports # :nodoc:
+        # ScenarioReport class intializes the scenario report attributes:
+        # +:id+ , +:name+ , +:directory_name+, +:timesteps_per_hour+ , +:number_of_not_started_simulations+ ,
+        # +:number_of_started_simulations+ , +:number_of_complete_simulations+ , +:number_of_failed_simulations+ ,
+        # +:timeseries_csv+ , +:location+ , +:program+ , +:construction_costs+ , +:reporting_periods+ , +:feature_reports+
+        ##
+        # Each ScenarioReport object corresponds to a single Scenario.
+        ##
+        # [parameters:]
+        # +hash+ - _Hash_ - A hash of a previously serialized ScenarioReport.
+        ##
+        def initialize(hash = {})
+          hash.delete_if { |k, v| v.nil? }
+          hash = defaults.merge(hash)
+
+          @id = hash[:id]
+          @name = hash[:name]
+          @directory_name = hash[:directory_name]
+          @timesteps_per_hour = hash[:timesteps_per_hour]
+          @number_of_not_started_simulations = hash[:number_of_not_started_simulations]
+          @number_of_started_simulations = hash[:number_of_started_simulations]
+          @number_of_complete_simulations = hash[:number_of_complete_simulations]
+          @number_of_failed_simulations = hash[:number_of_failed_simulations]
+          @timeseries_csv = TimeseriesCSV.new(hash[:timeseries_csv])
+          @location = Location.new(hash[:location])
+          @program = Program.new(hash[:program])
+
+          @construction_costs = []
+          hash[:construction_costs].each do |cc|
+            @constructiion_costs << ConstructionCost.new(cc)
+          end
+
+          @reporting_periods = []
+          hash[:reporting_periods].each do |rp|
+            @reporting_periods << ReportingPeriod.new(rp)
+          end
+
+          # intialized here to be used in the add_feature_report method
+          @feature_reports = []
+          hash[:feature_reports].each do |fr|
+            @feature_reports << FeatureReport.new(fr)
+          end
+
+          # initialize class variables @@validator and @@schema
+          @@validator ||= Validator.new
+          @@schema ||= @@validator.schema
+
+          # initialize @@logger
+          @@logger ||= URBANopt::Scenario::DefaultReports.logger
+        end
+
+        ##
+        # Assigns default values if values do not exist.
+        ##
+        def defaults
+          hash = {}
+          hash[:id] = nil.to_s
+          hash[:name] = nil.to_s
+          hash[:directory_name] = nil.to_s
+          hash[:timesteps_per_hour] = nil # unknown
+          hash[:number_of_not_started_simulations] = 0
+          hash[:number_of_started_simulations] = 0
+          hash[:number_of_complete_simulations] = 0
+          hash[:number_of_failed_simulations] = 0
+          hash[:timeseries_csv] = TimeseriesCSV.new.to_hash
+          hash[:location] = Location.new.defaults
+          hash[:program] = Program.new.to_hash
+          hash[:construction_costs] = []
+          hash[:reporting_periods] = []
+          hash[:feature_reports] = []
+          return hash
+        end
+
+        ##
+        # Gets the saved JSON file path.
+        ##
+        def json_path
+          File.join(@directory_name, 'default_scenario_report.json')
+        end
+
+        ##
+        # Gets the saved CSV file path.
+        ##
+        def csv_path
+          File.join(@directory_name, 'default_scenario_report.csv')
+        end
+
+        ##
+        # Saves the 'default_feature_report.json' and 'default_scenario_report.csv' files
+        ##
+        def save
+          hash = {}
+          hash[:scenario_report] = to_hash
+          hash[:feature_reports] = []
+          @feature_reports.each do |feature_report|
+            hash[:feature_reports] << feature_report.to_hash
+          end
+
+          File.open(json_path, 'w') do |f|
+            f.puts JSON.pretty_generate(hash)
+            # make sure data is written to the disk one way or the other #:nodoc:
+            begin
+              f.fsync
+            rescue StandardError
+              f.flush
+            end
+          end
+
+          # save the csv data #:nodoc:
+          timeseries_csv.save_data(csv_path)
+
+          return true
+        end
+
+        ##
+        # Converts to a Hash equivalent for JSON serialization.
+        ##
+        # - Exclude attributes with nil values.
+        # - Validate reporting_period hash properties against schema.
+        ##
+        def to_hash
+          result = {}
+          result[:id] = @id if @id
+          result[:name] = @name if @name
+          result[:directory_name] = @directory_name if @directory_name
+          result[:timesteps_per_hour] = @timesteps_per_hour if @timesteps_per_hour
+          result[:number_of_not_started_simulations] = @number_of_not_started_simulations if @number_of_not_started_simulations
+          result[:number_of_started_simulations] = @number_of_started_simulations if @number_of_started_simulations
+          result[:number_of_complete_simulations] = @number_of_complete_simulations if @number_of_complete_simulations
+          result[:number_of_failed_simulations] = @number_of_failed_simulations if @number_of_failed_simulations
+          result[:timeseries_csv] = @timeseries_csv.to_hash if @timeseries_csv
+          result[:location] = @location.to_hash if @location
+          result[:program] = @program.to_hash if @program
+
+          result[:construction_costs] = []
+          @construction_costs.each { |cc| result[:construction_costs] << cc.to_hash } if @construction_costs
+
+          result[:reporting_periods] = []
+          @reporting_periods.each { |rp| result[:reporting_periods] << rp.to_hash } if @reporting_periods
+
+          # result[:feature_reports] = []
+          # @feature_reports.each { |fr| result[:feature_reports] << fr.to_hash } if @feature_reports
+
+          # validate scenario_report properties against schema
+          if @@validator.validate(@@schema[:definitions][:ScenarioReport][:properties], result).any?
+            raise "scenario_report properties does not match schema: #{@@validator.validate(@@schema[:definitions][:ScenarioReport][:properties], result)}"
+          end
+
+          # have to use the module method because we have not yet initialized the class one
+          @@logger.info("Scenario name: #{@name}")
+
+          return result
+        end
+
+        ##
+        # Add feature reports to each other.
+        ##
+        # - check if a feature report have been already added.
+        # - check feature simulation status
+        # - merge timeseries_csv information
+        # - merge program information
+        # - merge construction_cost information
+        # - merge reporting_periods information
+        # - add the array of feature_reports
+        # - scenario report location takes the location of the first feature in the list
+        ##
+        # [parmeters:]
+        # +feature_report+ - _FeatureReport_ - An object of FeatureReport class.
+        ##
+        def add_feature_report(feature_report)
+          if @timesteps_per_hour.nil?
+            @timesteps_per_hour = feature_report.timesteps_per_hour
+          else
+            if feature_report.timesteps_per_hour != @timesteps_per_hour
+              raise "FeatureReport timesteps_per_hour = '#{feature_report.timesteps_per_hour}' does not match scenario timesteps_per_hour '#{@timesteps_per_hour}'"
+            end
+          end
+
+          # check that we have not already added this feature
+          id = feature_report.id
+          @feature_reports.each do |existing_feature_report|
+            if existing_feature_report.id == id
+              raise "FeatureReport with id = '#{id}' has already been added"
+            end
+          end
+
+          # check feature simulation status
+          if feature_report.simulation_status == 'Not Started'
+            @number_of_not_started_simulations += 1
+          elsif feature_report.simulation_status == 'Started'
+            @number_of_started_simulations += 1
+          elsif feature_report.simulation_status == 'Complete'
+            @number_of_complete_simulations += 1
+          elsif feature_report.simulation_status == 'Failed'
+            @number_of_failed_simulations += 1
+          else
+            raise "Unknown feature_report simulation_status = '#{feature_report.simulation_status}'"
+          end
+
+          # merge timeseries_csv information
+          @timeseries_csv.add_timeseries_csv(feature_report.timeseries_csv)
+
+          @timeseries_csv.run_dir_name(@directory_name)
+
+          # merge program information
+          @program.add_program(feature_report.program)
+
+          # merge construction_cost information
+          @construction_costs = ConstructionCost.merge_construction_costs(@construction_costs, feature_report.construction_costs)
+
+          # merge reporting_periods information
+          @reporting_periods = ReportingPeriod.merge_reporting_periods(@reporting_periods, feature_report.reporting_periods)
+
+          # add the array of feature_reports
+          @feature_reports << feature_report
+
+          # scenario report location takes the location of the first feature in the list
+          @location = feature_reports[0].location
+        end
+      end
+    end
+  end
+end

data/lib/urbanopt/scenario/default_reports/schema/README.md

@@ -0,0 +1,33 @@
+# URBANopt Scenario Schema
+
+The URBANopt Scenario Gem includes functionality for defining scenarios, running simulations, and post-processing results.  An URBANopt Scenario describes a specific set of options to apply to each Feature in a FeatureFile (e.g. each GeoJSON Feature in an URBANopt GeoJSON File).  User defined SimulationMapper classes translate each Feature to a SimulationDir which is a directory containing simulation input files.  A ScenarioRunner is used to perform simulations for each SimulationDir.  Finally, a ScenarioPostProcessor can run on a Scenario to generate scenario level results.  The [URBANopt Scenario Gem Design Document](https://docs.google.com/document/d/1ExcGuHliaSvPlrYevAJTSV8XAtTQXz_KQqH3p4iQDwg/edit) describes the gem in more detail.  The [URBANopt Example Project](https://github.com/urbanopt/urbanopt-example-project) demonstrates how to use the URBANopt Scenario Gem to perform a scenario analysis.
+
+## Reporting output units
+
+**JSON Output Units**
+
+- energy outputs: kbtu
+- water rate outputs : GPM (gallon per minute)
+- mass flow rate outputs : lbs/min
+- Temperature outputs : °F
+- area output: sf
+- measured distance output: ft
+- cost outputs: $
+
+**CSV Output Units**
+
+|            output                   |  unit   |
+| ----------------------------------- | ------- |
+| Electricity:Facility                | kbtu    |
+| ElectricityProduced:Facility        | kbtu    |
+| Gas:Facility                        | kbtu    |
+| DistrictCooling:Facility            | kbtu    |
+| DistrictHeating:Facility            | kbtu    |
+| District Cooling Chilled Water Rate | GPM     |
+| District Cooling Mass Flow Rate     | lbs/min |
+| District Cooling Inlet Temperature  | °F  |
+| District Cooling Outlet Temperature | °F  |
+| District Heating Hot Water Rate     | GPM     |
+| District Heating Mass Flow Rate     | lbs/min |
+| District Heating Inlet Temperature  | °F  |
+| District Heating Outlet Temperature | °F  |

data/lib/urbanopt/scenario/default_reports/schema/scenario_csv_columns.txt

@@ -0,0 +1,13 @@
+Electricity:Facility	
+ElectricityProduced:Facility	
+Gas:Facility	
+DistrictCooling:Facility	
+DistrictHeating:Facility	
+District Cooling Chilled Water Rate	
+District Cooling Mass Flow Rate	
+District Cooling Inlet Temperature	
+District Cooling Outlet Temperature	
+District Heating Hot Water Rate	
+District Heating Mass Flow Rate	
+District Heating Inlet Temperature	
+District Heating Outlet Temperature

data/lib/urbanopt/scenario/default_reports/schema/scenario_schema.json

@@ -0,0 +1,742 @@
+{
+	"$schema": "http://json-schema.org/draft-04/schema#",
+	"description": "Comment describing your JSON Schema",
+	"type": "object",
+	"properties": {
+		"scenario_report": {
+			"$ref": "#/definitions/ScenarioReport"
+		},
+		"feature_reports": {
+			"description": "features of each data point in the scenario",
+			"type": "array",
+			"items": {
+				"$ref": "#/definitions/FeatureReport"
+			}
+		}
+	},
+	"required": [
+		"scenario_report"
+	],
+	"additionalProperties": false,
+	"definitions": {
+		"ScenarioReport": {
+			"type": "object",
+			"properties": {
+				"id": {
+					"type": "string"
+				},
+				"name": {
+					"type": "string"
+				},
+				"directory_name": {
+					"type": "string"
+				},
+				"timesteps_per_hour": {
+					"$ref": "#/definitions/TimestepsPerHour"
+				},
+				"number_of_not_started_simulations": {
+					"type": "number"
+				},
+				"number_of_started_simulations": {
+					"type": "number"
+				},
+				"number_of_complete_simulations": {
+					"type": "number"
+				},
+				"number_of_failed_simulations": {
+					"type": "number"
+				},
+				"location": {
+					"$ref": "#/definitions/Location"
+				},
+				"timeseries_csv": {
+					"$ref": "#/definitions/TimeseriesCSV"
+				},
+				"program": {
+					"$ref": "#/definitions/Program"
+				},
+				"construction_costs": {
+					"$ref": "#/definitions/ConstructionCosts"
+				},
+				"reporting_periods": {
+					"$ref": "#/definitions/ReportingPeriods"
+				}
+			},
+			"required": [
+				"id",
+				"name",
+				"directory_name",
+				"timesteps_per_hour",
+				"number_of_not_started_simulations",
+				"number_of_started_simulations",
+				"number_of_complete_simulations",
+				"number_of_failed_simulations",
+				"program"
+			],
+			"additionalProperties": false
+		},
+		"FeatureReport": {
+			"type": "object",
+			"properties": {
+				"id": {
+					"description": "Id refers to the id of a building/feature",
+					"type": "string"
+				},
+				"name": {
+					"description": "name refers to the name of the feature (eg. Building 1, tranformer 5)",
+					"type": "string"
+				},
+				"directory_name": {
+					"type": "string"
+				},
+				"feature_type": {
+					"type": "string",
+					"enum": [
+						"Building",
+						"District System",
+						"Transformer"
+					]
+				},
+				"timesteps_per_hour": {
+					"$ref": "#/definitions/TimestepsPerHour"
+				},
+				"simulation_status": {
+					"type": "string",
+					"enum": [
+						"Not Started",
+						"Started",
+						"Complete",
+						"Failed"
+					]
+				},
+				"timeseries_csv": {
+					"$ref": "#/definitions/TimeseriesCSV"
+				},
+				"location": {
+					"$ref": "#/definitions/Location"
+				},
+				"program": {
+					"$ref": "#/definitions/Program"
+				},
+				"design_parameters": {
+					"$ref": "#/definitions/DesignParameters"
+				},
+				"construction_costs": {
+					"$ref": "#/definitions/ConstructionCosts"
+				},
+				"reporting_periods": {
+					"$ref": "#/definitions/ReportingPeriods"
+				}
+			},
+			"required": [
+				"id",
+				"name",
+				"directory_name",
+				"feature_type",
+				"timesteps_per_hour",
+				"simulation_status"
+			],
+			"additionalProperties": false
+		},
+		"ReportingPeriods": {
+			"type": "array",
+			"items": {
+				"$ref": "#/definitions/ReportingPeriod"
+			}
+		},
+		"ReportingPeriod": {
+			"description": "Non-overlapping reporting periods",
+			"type": "object",
+			"properties": {
+				"id": {
+					"description": "Id refers to the id of the reporting period. Ids of reporting periods are matched across simulations, so the same period of time gets the same id for all simulations.",
+					"type": "number"
+				},
+				"name": {
+					"description": "name refers to the name of the reporting period(eg. Annual, January)",
+					"type": "string"
+				},
+				"multiplier": {
+					"description": "Multiplier used if this reporting period is representative of mulitple periods.  For example one week simulation that represents entire month.",
+					"type": "number",
+					"default": 1
+				},
+				"start_date": {
+					"$ref": "#/definitions/Date"
+				},
+				"end_date": {
+					"$ref": "#/definitions/Date"
+				},
+				"total_site_energy": {
+					"description": "Total energy used on site, does not include generation (kBtu)",
+					"type": "number"
+				},
+				"total_source_energy": {
+					"description": "Total source energy used, does not include generation (kBtu)",
+					"type": "number"
+				},
+				"net_site_energy": {
+					"description": "Net site energy (kBtu)",
+					"type": "number"
+				},
+				"net_source_energy": {
+					"description": "Net source energy (kBtu)",
+					"type": "number"
+				},
+				"net_utility_cost": {
+					"description": "Total utility cost for reporting period includes generation",
+					"type": "number"
+				},
+				"electricity": {
+					"description": "Sum of all electricity used, does not include electricity produced (kWh)",
+					"type": "number"
+				},
+				"natural_gas": {
+					"description": "Sum of all natural gas end uses consumption (kBtu)",
+					"type": "number"
+				},
+				"additional_fuel": {
+					"description": "Sum of all additional fuel end uses consumption (kBtu)",
+					"type": "number"
+				},
+				"district_cooling": {
+					"description": "Sum of all distric cooling end uses consumption (kBtu)",
+					"type": "number"
+				},
+				"district_heating": {
+					"description": "Sum of all distric heating end uses consumption (kBtu)",
+					"type": "number"
+				},
+				"water": {
+					"description": "Sum of all water end uses consumption (ft^3)",
+					"type": "number"
+				},
+				"electricity_produced": {
+					"description": "Sum of all electricity produced (kWh)",
+					"type": "number"
+				},
+				"end_uses": {
+					"$ref": "#/definitions/EndUses"
+				},
+				"energy_production": {
+					"description": "Energy produced for reporting period.  Electricity reported in kWh, water in m^3, all others in kBtu.",
+					"type": "object",
+					"properties": {
+						"electricity_produced": {
+							"type": "object",
+							"properties": {
+								"photovoltaic": {
+									"type": "number"
+								}
+							},
+							"additionalProperties": false
+						}
+					},
+					"additionalProperties": false
+				},
+				"utility_costs": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/UtilityCost"
+					}
+				},
+				"comfort_result": {
+					"$ref": "#/definitions/ComfortResult"
+				}
+			},
+			"additionalProperties": false
+		},
+		"Date": {
+			"type": "object",
+			"properties": {
+				"month": {
+					"type": "integer"
+				},
+				"day_of_month": {
+					"type": "integer"
+				},
+				"year": {
+					"type": "integer"
+				}
+			},
+			"additionalProperties": false
+		},
+		"EndUses": {
+			"description": "End uses for reporting period.  Does not include energy produced. Electricity reported in kWh, water in m^3, all others in kBtu.",
+			"type": "object",
+			"properties": {
+				"electricity": {
+					"$ref": "#/definitions/EndUse"
+				},
+				"natural_gas": {
+					"$ref": "#/definitions/EndUse"
+				},
+				"additional_fuel": {
+					"$ref": "#/definitions/EndUse"
+				},
+				"district_cooling": {
+					"$ref": "#/definitions/EndUse"
+				},
+				"district_heating": {
+					"$ref": "#/definitions/EndUse"
+				},
+				"water": {
+					"$ref": "#/definitions/EndUse"
+				}
+			},
+			"additionalProperties": false
+		},
+		"EndUse": {
+			"type": "object",
+			"properties": {
+				"heating": {
+					"type": "number"
+				},
+				"cooling": {
+					"type": "number"
+				},
+				"interior_lighting": {
+					"type": "number"
+				},
+				"exterior_lighting": {
+					"type": "number"
+				},
+				"interior_equipment": {
+					"type": "number"
+				},
+				"exterior_equipment": {
+					"type": "number"
+				},
+				"fans": {
+					"type": "number"
+				},
+				"pumps": {
+					"type": "number"
+				},
+				"heat_rejection": {
+					"type": "number"
+				},
+				"humidification": {
+					"type": "number"
+				},
+				"heat_recovery": {
+					"type": "number"
+				},
+				"water_systems": {
+					"type": "number"
+				},
+				"refrigeration": {
+					"type": "number"
+				},
+				"generators": {
+					"type": "number"
+				}
+			},
+			"additionalProperties": false
+		},
+		"ComfortResult": {
+			"type": "object",
+			"properties": {
+				"time_setpoint_not_met_during_occupied_cooling": {
+					"description": "(hrs)",
+					"type": "number"
+				},
+				"time_setpoint_not_met_during_occupied_heating": {
+					"description": "(hrs)",
+					"type": "number"
+				},
+				"time_setpoint_not_met_during_occupied_hours": {
+					"description": "(hrs)",
+					"type": "number"
+				}
+			},
+			"additionalProperties": false
+		},
+		"ConstructionCosts": {
+			"type": "array",
+			"items": {
+				"$ref": "#/definitions/ConstructionCost"
+			}
+		},
+		"ConstructionCost": {
+			"description": "Program related information, does not change in time",
+			"type": "object",
+			"properties": {
+				"category": {
+					"type": "string",
+					"enum": [
+						"Construction",
+						"Building",
+						"Space",
+						"ThermalZone",
+						"AirLoop",
+						"PlantLoop",
+						"ZoneHVAC",
+						"Lights",
+						"Luminaire",
+						"Equipment",
+						"HVACComponent",
+						"ZoneHVACComponent"
+					]
+				},
+				"item_name": {
+					"description": "Name of the item being costed, e.g. the name of the exterior wall construction",
+					"type": "string"
+				},
+				"unit_cost": {
+					"description": "Cost per unit of item, e.g. cost per area of construction.  This can be adjusted in post processing.",
+					"type": "number"
+				},
+				"cost_units": {
+					"description": "Unit of cost for this item",
+					"type": "string",
+					"enum": [
+						"CostPerEach",
+						"CostPerFt2",
+						"CostPerKW",
+						"CostPerCFM"
+					]
+				},
+				"item_quantity": {
+					"description": "Amount of the item in units corresponding to cost_units",
+					"type": "number"
+				},
+				"total_cost": {
+					"description": "Total cost is unit_cost multiplied by item_quantity. Can be updated if unit_cost is changed.",
+					"type": "number"
+				}
+			},
+			"additionalProperties": false
+		},
+		"UtilityCost": {
+			"type": "object",
+			"properties": {
+				"fuel_type": {
+					"type": "string",
+					"enum": [
+						"Electricity",
+						"Natural Gas",
+						"District Cooling",
+						"District Heating",
+						"Additional Fuel",
+						"Water"
+					]
+				},
+				"total_cost": {
+					"description": "($)",
+					"type": "number"
+				},
+				"usage_cost": {
+					"description": "($)",
+					"type": "number"
+				},
+				"demand_cost": {
+					"description": "($)",
+					"type": "number"
+				}
+			},
+			"additionalProperties": false
+		},
+		"Location": {
+			"type": "object",
+			"properties": {
+				"latitude": {
+					"description": "(deg)",
+					"type": "number"
+				},
+				"longitude": {
+					"description": "(deg)",
+					"type": "number"
+				},
+				"surface_elevation": {
+					"description": "The surface elevation (above NAVD88 datum) (ft).",
+					"type": "number"
+				},
+				"weather_filename": {
+					"description": "Name of EPW weather file.",
+					"type": "string"
+				}
+			},
+			"additionalProperties": false
+		},
+		"TimestepsPerHour": {
+			"type": "integer",
+			"minimum": 1,
+			"maximum": 60
+		},
+		"Program": {
+			"type": "object",
+			"properties": {
+				"site_area": {
+					"description": "Area of the entire site or lot (ft^2)",
+					"type": "number"
+				},
+				"floor_area": {
+					"description": "Building gross floor area (ft^2)",
+					"type": "number"
+				},
+				"conditioned_area": {
+					"description": "Building conditioned floor area (ft^2)",
+					"type": "number"
+				},
+				"unconditioned_area": {
+					"description": "Building unconditioned floor area (ft^2)",
+					"type": "number"
+				},
+				"footprint_area": {
+					"description": "Building floorprint area (ft^2)",
+					"type": "number"
+				},
+				"maximum_roof_height": {
+					"description": "Maximum height of the roof relative to surface elevation (ft)",
+					"type": "number"
+				},
+				"maximum_number_of_stories": {
+					"description": "The maximum number of building stories, sum of number of above and below ground stories.",
+					"type": "number"
+				},
+				"maximum_number_of_stories_above_ground": {
+					"description": "The maximum number of building stories above ground",
+					"type": "number"
+				},
+				"parking_area": {
+					"description": "Parking gross area (ft^2)",
+					"type": "number"
+				},
+				"number_of_parking_spaces": {
+					"description": "Number of parking spaces",
+					"type": "number"
+				},
+				"number_of_parking_spaces_charging": {
+					"description": "Number of parking spaces with electric vehicle charging",
+					"type": "number"
+				},
+				"parking_footprint_area": {
+					"description": "Parking floorprint area (ft^2)",
+					"type": "number"
+				},
+				"maximum_parking_height": {
+					"description": "Maximum height of the parking structure relative to surface elevation (ft)",
+					"type": "number"
+				},
+				"maximum_number_of_parking_stories": {
+					"description": "The maximum number of parking stories, sum of number of above and below ground stories.",
+					"type": "number"
+				},
+				"maximum_number_of_parking_stories_above_ground": {
+					"description": "The maximum number of parking stories above ground",
+					"type": "number"
+				},
+				"number_of_residential_units": {
+					"description": "Total number of residential units.",
+					"type": "integer"
+				},
+				"building_types": {
+					"type": "array",
+					"items": {
+						"$ref": "#/definitions/BuildingType"
+					}
+				},
+				"window_area": {
+					"description": "Exterior windows gross area (ft^2)",
+					"type": "object",
+					"properties": {
+						"north_window_area": {
+							"type": "number"
+						},
+						"south_window_area": {
+							"type": "number"
+						},
+						"east_window_area": {
+							"type": "number"
+						},
+						"west_window_area": {
+							"type": "number"
+						},
+						"total_window_area": {
+							"type": "number"
+						}
+					},
+					"required": [
+						"total_window_area"
+					],
+					"additionalProperties": false
+				},
+				"wall_area": {
+					"description": "exterior walls gross area (ft^2)",
+					"type": "object",
+					"properties": {
+						"north_wall_area": {
+							"type": "number"
+						},
+						"south_wall_area": {
+							"type": "number"
+						},
+						"east_wall_area": {
+							"type": "number"
+						},
+						"west_wall_area": {
+							"type": "number"
+						},
+						"total_wall_area": {
+							"type": "number"
+						}
+					},
+					"required": [
+						"north_wall_area",
+						"south_wall_area",
+						"east_wall_area",
+						"west_wall_area",
+						"total_wall_area"
+					],
+					"additionalProperties": false
+				},
+				"roof_area": {
+					"type": "object",
+					"properties": {
+						"equipment_roof_area": {
+							"type": "number"
+						},
+						"photovoltaic_roof_area": {
+							"type": "number"
+						},
+						"available_roof_area": {
+							"description": "gross roof area (ft^2)",
+							"type": "number"
+						},
+						"total_roof_area": {
+							"description": "Exterior roofs gross area (ft^2)",
+							"type": "number"
+						}
+					},
+					"required": [
+						"total_roof_area"
+					],
+					"additionalProperties": false
+				},
+				"orientation": {
+					"description": "Rotation of longest axis from East-West,about up axis (deg)",
+					"type": "number"
+				},
+				"aspect_ratio": {
+					"description": "Ratio of longest to shortest axis",
+					"type": "number"
+				}
+			},
+			"required": [
+				"floor_area",
+				"conditioned_area",
+				"unconditioned_area",
+				"footprint_area",
+				"maximum_roof_height",
+				"number_of_residential_units",
+				"building_types",
+				"window_area",
+				"wall_area",
+				"roof_area"
+			],
+			"additionalProperties": false
+		},
+		"BuildingType": {
+			"type": "object",
+			"properties": {
+				"building_type": {
+					"description": "Primary building space type",
+					"type": "string",
+					"enum": [
+						"Single-Family",
+						"Multifamily (2 to 4 units)",
+						"Multifamily (5 or more units)",
+						"Mobile Home",
+						"Vacant",
+						"Office",
+						"Laboratory",
+						"Nonrefrigerated warehouse",
+						"Food sales",
+						"Public order and safety",
+						"Outpatient health care",
+						"Refrigerated warehouse",
+						"Religious worship",
+						"Public assembly",
+						"Education",
+						"Food service",
+						"Inpatient health care",
+						"Nursing",
+						"Lodging",
+						"Strip shopping mall",
+						"Enclosed mall",
+						"Retail other than mall",
+						"Service"
+					]
+				},
+				"maximum_occupancy": {
+					"description": "Maximum number of occupants ",
+					"type": "number"
+				},
+				"floor_area": {
+					"description": "Building gross floor area of this type (ft^2)",
+					"type": "number"
+				}
+			},
+			"required": [
+				"building_type",
+				"maximum_occupancy",
+				"floor_area"
+			],
+			"additionalProperties": false
+		},
+		"DesignParameters": {
+			"type": "object",
+			"properties": {
+				"district_cooling_chilled_water_rate": {
+					"type": "number"
+				},
+				"district_cooling_mass_flow_rate": {
+					"type": "number"
+				},
+				"district_cooling_inlet_temperature": {
+					"type": "number"
+				},
+				"district_cooling_outlet_temperature": {
+					"type": "number"
+				},
+				"district_heating_hot_water_rate": {
+					"type": "number"
+				},
+				"district_heating_mass_flow_rate": {
+					"type": "number"
+				},
+				"district_heating_inlet_temperature": {
+					"type": "number"
+				},
+				"district_heating_outlet_temperature": {
+					"type": "number"
+				}
+			},
+			"additionalProperties": false
+		},
+		"TimeseriesCSV": {
+			"type": "object",
+			"properties": {
+				"path": {
+					"type": "string"
+				},
+				"first_report_datetime": {
+					"type": "string"
+				},
+				"column_names": {
+					"type": "array",
+					"items": {
+						"type": "string"
+					}
+				}
+			},
+			"required": [
+				"path",
+				"first_report_datetime",
+				"column_names"
+			],
+			"additionalProperties": false
+		}
+	}
+}