urbanopt-scenario 0.1.1

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

@@ -0,0 +1,34 @@
+# 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  |
+| Electricity:Grid:ToLoad                  | kWh.    |

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,830 @@
+{
+	"$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"
+				},
+				"distributed_generation": {
+					"$ref": "#/definitions/DistributedGeneration"
+				}
+				
+			},
+			"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
+		},
+		"DistributedGeneration": {
+			"type": "object",
+			"properties": {
+				"lcc_us_dollars": {
+					"type": "number", 
+					"description": "Optimal lifecycle cost"
+				},
+				"npv_us_dollars": {
+					"type": "number", 
+					"description": "Net present value of savings realized by the project"
+				},
+				"year_one_energy_cost_us_dollars": {
+					"type": "number", 
+					"description": "Optimal year one utility energy cost"
+				},
+				"year_one_demand_cost_us_dollars": {
+					"type": "number", 
+					"description": "Optimal year one utility demand cost"
+				},
+				"year_one_bill_us_dollars": {
+					"type": "number", 
+					"description": "Optimal year one utility bill"
+				},
+				"total_energy_cost_us_dollars": {
+					"type": "number", 
+					"description": "Total utility energy cost over the lifecycle, after-tax"
+				},
+				"SolarPV" : {
+					"$ref": "#/definitions/SolarPV"
+				},
+				"Wind" : {
+					"$ref": "#/definitions/Wind"
+				},
+				"Generator" : {
+					"$ref": "#/definitions/Generator"
+				},
+				"Storage" : {
+					"$ref": "#/definitions/Storage"
+				}
+			 }
+		},
+		"SolarPV": {
+			"type": "object",
+			"properties": {
+				"size_kw": {
+					"description": "rated power in kW",
+					"type": "string"
+				}
+			}
+		},
+		"Wind": {
+			"type": "object",
+			"properties": {
+				"size_kw": {
+					"description": "rated power in kW",
+					"type": "string"
+				}
+			}
+		},
+		"Generator": {
+			"type": "object",
+			"properties": {
+				"size_kw": {
+					"description": "rated power in kW",
+					"type": "string"
+				}
+			}
+		},
+		"Storage": {
+			"type": "object",
+			"properties": {
+				"size_kw": {
+					"description": "rated power in kW",
+					"type": "string"
+				},
+				"size_kw": {
+					"description": "rated capacity in kWh",
+					"type": "string"
+				}
+			}
+		},
+		"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"
+				},
+				"distributed_generation": {
+					"$ref": "#/definitions/DistributedGeneration"
+				}
+			},
+			"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
+		}
+	}
+}