diff --git a/docs/source/api.rst b/docs/source/deprecated/api.rst similarity index 93% rename from docs/source/api.rst rename to docs/source/deprecated/api.rst index 2ef2cc4..be560f8 100644 --- a/docs/source/api.rst +++ b/docs/source/deprecated/api.rst @@ -149,9 +149,12 @@ Property Type Units Constraints Required Default ``storiesCount`` integer count >0 no PSC, BSA ``windowToWallFraction`` float fraction >0 no 0.14 ``yearBuilt`` integer year >1600 no PSC If missing from PSC, model will fail +``propertyUse`` string see [#]_ no PSC Advanced option. See [#]_ ======================== ======= ======== =========== ======== ================== ============================================== .. [#] ``bedroomsCount``/2 + 0.5 +.. [#] ``propertyUse`` options are “single-family detached”, “single-family attached”, or “manufactured home” +.. [#] ``propertyUse`` is an advanced field. Overriding the existing property use may produce in abnormal model results. If you set this, we recommend setting square footage as well. .. _cost: @@ -217,18 +220,19 @@ Property Type Units Constraints Required Defa Attics ~~~~~~ -The attic is entered in ``...building.enclosure.attics``. Currently, this array must contain exactly 1 attic object. If there is no attic present in house, set ``area`` to 0. -See note about `objects and arrays`_ for more information. +The attic is entered in ``...building.enclosure.attics``. Currently, this array must contain exactly 1 attic object. See note about `objects and arrays`_ for more information. ================================= ======= ================ ============== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== -``id`` id Must be unique yes Attic1 -``area`` float ft2 >0 no PSC -``isVented`` boolean no yes -``floorAssemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no BSA +``id`` id Must be unique yes Attic1 +``type`` string see [#]_ no BSA +``area`` float ft2 >0 no PSC Not applicable when ``type`` is "cathedral ceiling" or "flat roof" +``floorAssemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no BSA Not applicable when ``type`` is "cathedral ceiling" or "flat roof" ================================= ======= ================ ============== ======== ================== ============================================== +.. [#] ``type`` options are "attic vented", "attic unvented", "cathedral ceiling", or "flat roof". + Roofs ~~~~~ @@ -259,7 +263,7 @@ Property Type Units Constraints Re ``wallHeight`` float ft >=0 no PSC ================================= ======= ================ ============== ======== ================== ============================================== -.. [#] ``type`` choices are "basement conditioned", "basement unconditioned", "crawl vented", "crawl unvented", "slab", and "pier and beam". +.. [#] ``type`` choices are "basement conditioned", "basement unconditioned", "crawl vented", "crawl unvented", "slab", and "belly and wing". Walls ~~~~~ @@ -365,7 +369,7 @@ Property Type Units Constra .. [#] If ``systemType`` is "central air conditioner" .. [#] ``systemType`` choices are "central air conditioner", "room air conditioner", "evaporative cooler", "packaged terminal air conditioner", and "mini-split". .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed". -.. [#] ``coolEfficiencyUnits`` choices are "percent", "EER", "CEER", and "SEER". The option to use "SEER2" is planned for a future release. +.. [#] ``coolEfficiencyUnits`` choices are "fraction", "EER", "CEER", "SEER", and "SEER2". HVAC Heating Systems ~~~~~~~~~~~~~~~~~~~~ @@ -388,7 +392,7 @@ Property Type Units Constra .. [#] Required when ``systemType`` is "furnace" or "boiler". .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". -.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent". +.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction". HVAC Heat Pumps ~~~~~~~~~~~~~~~ @@ -406,9 +410,9 @@ Property Type Units Constrai ``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined ``coolCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined ``heatEfficiency`` float Btu/Wh >0 no PSC -``heatEfficiencyUnits`` string HSPF [#]_ no HSPF +``heatEfficiencyUnits`` string see [#]_ no HSPF ``coolEfficiency`` float Btu/Wh >0 no PSC -``coolEfficiencyUnits`` string SEER [#]_ no SEER +``coolEfficiencyUnits`` string see [#]_ no SEER ``heatLoadFraction`` float fraction 0-1 yes 1 ``coolLoadFraction`` float fraction 0-1 yes 1 ``backupSystem`` object yes @@ -418,8 +422,8 @@ Property Type Units Constrai .. [#] Required when ``systemType`` is "air-to-air" or "ground-to-air". .. [#] ``systemType`` choices are "mini-split", "air-to-air", and "ground-to-air". .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed". -.. [#] The option to use "HSPF2" is planned for a future release. -.. [#] The option to use "SEER2" is planned for a future release. +.. [#] ``heatEfficiencyUnits`` choices are "HSPF" and "HSPF2". +.. [#] ``coolEfficiencyUnits`` choices are "SEER" and "SEER2". ``backupSystem`` schema for HVAC Heat Pumps: @@ -430,15 +434,15 @@ Property Type Units Constrai ``heatingSwitchoverTemp`` float F no determined by modeling engine if undefined ``fuel`` string see [#]_ no electricity only applicable if backupSystem.systemType = "integrated" ``heatEfficiency`` float see ``heatEfficiencyUnit`` 0-1 no 1 only applicable if backupSystem.systemType = "integrated" -``heatEfficiencyUnits`` string see [#]_ no percent only applicable if backupSystem.systemType = "integrated" +``heatEfficiencyUnits`` string see [#]_ no fraction only applicable if backupSystem.systemType = "integrated" ``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined, only applicable if backupSystem.systemType = "integrated" ``backupHvacId`` idref see [#]_ see [#]_ PSC ================================= ======= ========================== ============== ======== ================== ============================================== .. [#] ``systemType`` choices are "integrated" and "separate". .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". -.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent". -.. [#] Must reference an defined ``hvacHeatingSystem.id`` +.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction". +.. [#] Must reference a defined ``hvacHeatingSystem.id`` .. [#] Required when ``backupSystem.systemType`` is "separate". HVAC Air Distribution Systems @@ -468,14 +472,14 @@ Property Type Units Constrai ``systemType`` string see [#]_ yes "supply" and "return" both supply and return must be defined ``insulationRValue`` float F-ft2-hr/Btu >=0 no 0 ``leakageValue`` float see ``leakageUnits`` >=0 no BSA -``leakageUnits`` string see [#]_ no Percent +``leakageUnits`` string see [#]_ no fraction ``location`` string see [#]_ no see notes [#]_ ================================= ======= ========================== ============== ======== ====================== ============================================== .. [#] ``systemType`` choices are "supply" and "return". -.. [#] ``leakageUnits`` choices are"CFM25", "CFM50", and "percent". -.. [#] ``location`` choices are "living space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", "outside", "exterior wall", "under slab", "roof deck", "other heated space", and "other non-freezing space". -.. [#] If ``location`` not provided, defaults to the first present space type: "basement conditioned", "basement unconditioned", "crawlspace vented", "crawlspace unvented", "attic vented", "attic unvented", "garage", or "living space". +.. [#] ``leakageUnits`` choices are "CFM25", "CFM50", and "fraction". +.. [#] ``location`` choices are "conditioned space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", "outside", "exterior wall", "under slab", "roof deck", "other heated space", "other non-freezing space", and "manufactured home belly". +.. [#] If ``location`` not provided, defaults to the first present space type: "basement conditioned", "basement unconditioned", "crawlspace conditioned", "crawlspace vented", "crawlspace unvented", "attic vented", "attic unvented", "garage", or "conditioned space". HVAC Hydronic Distribution Systems ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -725,7 +729,8 @@ Property Type Units ``tankVolume`` float gal no ``dhwLoadFraction`` float fraction 0-1 yes sum of dhwLoadFraction must equal 1 ``heatCapacityBtuPerHour`` float Btu/hr >0 no autosized by modeling engine if undefined -``energyFactor`` or ``uniformEnergyFactor`` float fraction <1 no BSA +``efficiency`` float fraction >0 no BSA +``efficiencyUnits`` string see [#]_ no BSA ``hotWaterTemperature`` float F >0 no 125 =========================================== ======= ========================== ============== ======== ==================== ============================================== @@ -733,12 +738,13 @@ Property Type Units .. [#] Must reference a defined ``hvacHeatingSystem.id``. .. [#] Only required when ``systemType`` is "space-heating boiler with ..." .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". -.. [#] ``location`` choices are "living space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", “other exterior”, “other heated space”, and “other non-freezing space”. +.. [#] ``location`` choices are "conditioned space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", “other exterior”, “other heated space”, and “other non-freezing space”. .. [#] If ``location`` not provided, defaults to the first present space type: - IECC zones 1-3, excluding 3A: "garage", "living space" + IECC zones 1-3, excluding 3A: "garage", "conditioned space" - IECC zones 3A, 4-8, unknown: "basement conditioned", "basement unconditioned", "living space" + IECC zones 3A, 4-8, unknown: "basement conditioned", "basement unconditioned", "conditioned space" +.. [#] ``efficiencyUnits`` choices are "EF" and "UEF". .. _weather: diff --git a/docs/source/automated_measures.rst b/docs/source/deprecated/automated_measures.rst similarity index 93% rename from docs/source/automated_measures.rst rename to docs/source/deprecated/automated_measures.rst index bbb0e20..d329a81 100644 --- a/docs/source/automated_measures.rst +++ b/docs/source/deprecated/automated_measures.rst @@ -123,17 +123,17 @@ connected to the base building's heating and cooling systems. ``adjust`` schema for existing HVAC distribution system: - ==================== ======= =========== ============================================== + ==================== ======= =========== ======================================================== Property Type Constraints Description - ==================== ======= =========== ============================================== - ``leakageUnits`` String See [#]_ Duct leakage units + ==================== ======= =========== ======================================================== + ``leakageUnits`` String See [#]_ Duct leakage units must be the same as ``baseBuilding`` ``leakageValue`` Double >= 0.0 Duct leakage value ``insulationRValue`` Double >= 0.0 - ==================== ======= =========== ============================================== + ==================== ======= =========== ======================================================== Values can be defined and will only be applied if applicable. For example, if there isn't ``airDistribution``, then ``leakageValue`` won't be applied. - .. [#] Units choices are CFM25, CFM50, or Percent. + .. [#] Units choices are "CFM25", "CFM50", or "fraction". .. _existing_water_heating_system: @@ -218,7 +218,7 @@ Characteristics of a new water heating system can be entered in ``automatedMeasu ===================== ==================== =========== ======== ======= =================================== Property Type Constraints Required Default Description ===================== ==================== =========== ======== ======= =================================== - ``systemType`` String See [#]_ Yes Type of water heating system. fuelType assumed as base heating fuel for "storage water heater" and "instantaneous water heater". + ``systemType`` String See [#]_ Yes Type of water heating system. ``fuelType`` assumed as base heating fuel for "storage water heater" and "instantaneous water heater". ``efficiencyClass`` String See [#]_ Yes ``dhwLoadFraction`` Double 0 - 1 [#]_ No 1.0 DHW load for the new water heating system ``costs`` Array of :ref:`cost` No ``[]`` Implied costs of measure @@ -246,6 +246,16 @@ Assumptions for ``efficiencyClass``: instantaneous water heater other N/A N/A ========================== =========== ======== ======= +Assumptions for ``tankVolume`` when ``systemType`` is "heat pump water heater": + =============== ============= + Resident Count Volume (gal) + =============== ============= + 2 or less 50 + 3 65 + 4 or more 80 + =============== ============= + + Adjust global aspects of the building ------------------------------------- @@ -280,6 +290,8 @@ Adjustments to the building air leakage rates can be entered in ``automatedMeasu .. [#] rateUnit choices are ACH or CFM. +The air sealing measure is only applicable when the improved air sealing rate is less than the base rate. + .. _adjust_attic_insulation: Attic Insulation @@ -304,6 +316,19 @@ Adjustments to existing attic insulation can be entered in ``automatedMeasures.a ``floorAssemblyEffectiveRValue`` Double F-ft2-hr/Btu > 0.0 50.6 Effective R-value of attic floor assembly ================================ ====== ============ =========== ======= ======================================= +Attic insulation measure applicability is determined based on the difference between the base and improved assembly effective R-value using the following table. + + ===================== ========================= =========== + Base Assembly R-Value Improved Assembly R-Value Applicable? + ===================== ========================= =========== + < 8.7 < 8.7 false + < 8.7 >= 8.7 true + 8.7 - 20.6 < 26.6 false + 8.7 - 20.6 >= 26.6 true + > 20.6 < 31.6 false + > 20.6 >= 31.6 true + ===================== ========================= =========== + .. _adjust_thermostat: Thermostat diff --git a/docs/source/extensive_inputs_and_outputs.rst b/docs/source/deprecated/extensive_inputs_and_outputs.rst similarity index 100% rename from docs/source/extensive_inputs_and_outputs.rst rename to docs/source/deprecated/extensive_inputs_and_outputs.rst diff --git a/docs/source/modeling_results_resolution.rst b/docs/source/deprecated/modeling_results_resolution.rst similarity index 100% rename from docs/source/modeling_results_resolution.rst rename to docs/source/deprecated/modeling_results_resolution.rst diff --git a/docs/source/examples/request/timelines/post/extensive_inputs.json b/docs/source/examples/request/timelines/post/extensive_inputs.json index 8be9cfa..50485bd 100644 --- a/docs/source/examples/request/timelines/post/extensive_inputs.json +++ b/docs/source/examples/request/timelines/post/extensive_inputs.json @@ -15,7 +15,8 @@ "residentCount": 5, "storiesCount": 1, "windowToWallFraction": 0.14, - "yearBuilt": 1945 + "yearBuilt": 1945, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -81,7 +82,7 @@ "systemType": "electric resistance", "fuel": "electricity", "heatEfficiency": 1, - "heatEfficiencyUnits": "percent", + "heatEfficiencyUnits": "fraction", "heatLoadFraction": 1 } ], @@ -101,13 +102,14 @@ "waterHeating": { "waterHeatingSystems": [ { - "energyFactor": 0.92, + "efficiency": 0.92, + "efficiencyUnits": "EF", "dhwLoadFraction": 1, "systemType": "storage water heater", "fuel": "electricity", "id": "WaterHeater1", "hotWaterTemperature": 125, - "location": "living space", + "location": "conditioned space", "lifetime": { "replacementCost": 1000, "installedDate": "2015-11-12" diff --git a/docs/source/examples/response/timelines/post/automated_measures_new_heat_pump.json b/docs/source/examples/response/timelines/post/automated_measures_new_heat_pump.json index 9c4448c..79bcff3 100644 --- a/docs/source/examples/response/timelines/post/automated_measures_new_heat_pump.json +++ b/docs/source/examples/response/timelines/post/automated_measures_new_heat_pump.json @@ -26,7 +26,8 @@ "residentCount": 5, "storiesCount": 1, "windowToWallFraction": 0.14, - "yearBuilt": 1945 + "yearBuilt": 1945, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -91,7 +92,7 @@ "systemType": "electric resistance", "fuel": "electricity", "heatEfficiency": 1.0, - "heatEfficiencyUnits": "percent", + "heatEfficiencyUnits": "fraction", "heatLoadFraction": 1.0 } ], @@ -113,10 +114,11 @@ "id": "WaterHeater1", "systemType": "storage water heater", "fuel": "electricity", - "location": "living space", + "location": "conditioned space", "tankVolume": 40, "dhwLoadFraction": 1.0, - "energyFactor": 0.92, + "efficiency": 0.92, + "efficiencyUnits": "EF", "hotWaterTemperature": 125.0, "lifetime": { "replacementCost": 1000, @@ -235,7 +237,8 @@ "residentCount": 5, "storiesCount": 1, "windowToWallFraction": 0.14, - "yearBuilt": 1945 + "yearBuilt": 1945, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -333,12 +336,12 @@ "systemType": "storage water heater", "connectedHeatingId": "Boiler1", "fuel": "natural gas", - "location": "living space", + "location": "conditioned space", "tankVolume": 40, "dhwLoadFraction": 1.0, "heatCapacityBtuPerHour": null, - "energyFactor": 0.92, - "uniformEnergyFactor": null, + "efficiency": 0.92, + "efficiencyUnits": "EF", "hotWaterTemperature": 125.0 } ] diff --git a/docs/source/examples/response/timelines/post/extensive_inputs.json b/docs/source/examples/response/timelines/post/extensive_inputs.json index 2fc2b3e..eb64c93 100644 --- a/docs/source/examples/response/timelines/post/extensive_inputs.json +++ b/docs/source/examples/response/timelines/post/extensive_inputs.json @@ -163,7 +163,8 @@ "residentCount": 3.2366863905325443, "storiesCount": 2, "windowToWallFraction": 0.14, - "yearBuilt": 2007 + "yearBuilt": 2007, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -282,9 +283,9 @@ "fuel": "natural gas", "heatCapacityBtuPerHour": null, "systemType": "storage water heater", - "energyFactor": 0.59, + "efficiency": 0.59, + "efficiencyUnits": "EF", "id": "WaterHeater1", - "uniformEnergyFactor": null, "location": null } ] diff --git a/docs/source/examples/response/timelines/post/simple_bare_bones.json b/docs/source/examples/response/timelines/post/simple_bare_bones.json index 5e4050e..34e4d5c 100644 --- a/docs/source/examples/response/timelines/post/simple_bare_bones.json +++ b/docs/source/examples/response/timelines/post/simple_bare_bones.json @@ -26,7 +26,8 @@ "residentCount": 5, "storiesCount": 2, "windowToWallFraction": 0.14, - "yearBuilt": 2007 + "yearBuilt": 2007, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -119,7 +120,7 @@ "systemType": "supply", "insulationRValue": 0.0, "leakageValue": 0.2, - "leakageUnits": "percent", + "leakageUnits": "fraction", "location": "attic vented" }, { @@ -127,7 +128,7 @@ "systemType": "return", "insulationRValue": 0.0, "leakageValue": 0.2, - "leakageUnits": "percent", + "leakageUnits": "fraction", "location": "attic vented" } ] @@ -141,10 +142,11 @@ "id": "WaterHeater1", "systemType": "storage water heater", "fuel": "natural gas", - "location": "living space", + "location": "conditioned space", "tankVolume": 40, "dhwLoadFraction": 1.0, - "energyFactor": 0.59, + "efficiency": 0.59, + "efficiencyUnits": "EF", "hotWaterTemperature": 125.0, "lifetime": { "replacementCost": 1000, diff --git a/docs/source/examples/response/timelines/post/simple_with_monthly.json b/docs/source/examples/response/timelines/post/simple_with_monthly.json index 6a54bfe..06768b4 100644 --- a/docs/source/examples/response/timelines/post/simple_with_monthly.json +++ b/docs/source/examples/response/timelines/post/simple_with_monthly.json @@ -26,7 +26,8 @@ "residentCount": 5, "storiesCount": 2, "windowToWallFraction": 0.14, - "yearBuilt": 2007 + "yearBuilt": 2007, + "propertyUse": "single-family detached" }, "enclosure": { "airInfiltration": { @@ -119,7 +120,7 @@ "systemType": "supply", "insulationRValue": 0.0, "leakageValue": 0.2, - "leakageUnits": "percent", + "leakageUnits": "fraction", "location": "attic vented" }, { @@ -127,7 +128,7 @@ "systemType": "return", "insulationRValue": 0.0, "leakageValue": 0.2, - "leakageUnits": "percent", + "leakageUnits": "fraction", "location": "attic vented" } ] @@ -141,10 +142,11 @@ "id": "WaterHeater1", "systemType": "storage water heater", "fuel": "natural gas", - "location": "living space", + "location": "conditioned space", "tankVolume": 40, "dhwLoadFraction": 1.0, - "energyFactor": 0.59, + "efficiency": 0.59, + "efficiencyUnits": "EF", "hotWaterTemperature": 125.0, "lifetime": { "replacementCost": 1000, diff --git a/docs/source/examples/response/timelines/post/simple_with_monthly_and_hourly.json.gz b/docs/source/examples/response/timelines/post/simple_with_monthly_and_hourly.json.gz index db0b143..303a70a 100644 Binary files a/docs/source/examples/response/timelines/post/simple_with_monthly_and_hourly.json.gz and b/docs/source/examples/response/timelines/post/simple_with_monthly_and_hourly.json.gz differ diff --git a/docs/source/introduction.rst b/docs/source/introduction.rst index ae6eb48..4eca6b7 100644 --- a/docs/source/introduction.rst +++ b/docs/source/introduction.rst @@ -14,11 +14,15 @@ The Modeling API also supports :ref:`automated_measures`, a streamlined approach This API and documentation site is under active development. +.. _data_sources: + Data Sources ------------ Radiant Labs collects data from a wide range of public and private data sources to develop our “Common Schema”, which is a cleaned, merged data structure providing a host of property characteristics, including building features, owner details, demographics, and regional factors. The following tables provide details on each data source included in our pipeline and information on the recency of the data. +.. _public_sources: + Public Sources ************** @@ -33,6 +37,8 @@ EIA Electric prices Identifies average residential electric r EIA Fuel rates Identifies average residential fuel costs by state 2022 ============= ======================== ========================================================= =================== +.. _private_sources: + Private Sources *************** @@ -43,6 +49,8 @@ Proprietary Tax assessor Building characteristics documented by re Proprietary Building permits Building permit data categorized by work type. Fill rate and data quality varies by region Live data stream ============= ======================== ========================================================================================== =================== +.. _modeling_methodology: + Modeling Methodology -------------------- diff --git a/docs/source/request_structure.rst b/docs/source/request_structure.rst index 6f64cfb..89cd56f 100644 --- a/docs/source/request_structure.rst +++ b/docs/source/request_structure.rst @@ -7,11 +7,18 @@ The following sections provide the specifications and syntax for each API reques :language: javascript :caption: Top-level request payload schema +As discussed in :ref:`Usage Instructions `, the Defaulting Engine will populate any missing or null building characteristics. In each schema definition table below, information about each key's default is provided. + + .. _PSC-: + - **PSC**: Property-specific characteristic. This type of default indicates that specific information about the address is collected and applied to that attribute. Thus, each address may have a different default value. For example, ``buildingSummary.conditionedFloorArea`` is collected from various :ref:`Data Sources ` to be populated when missing or null. + .. _BSA-: + - **BSA** : Building stock assumption. This type of default indicates that location- and vintage-based building stock assumptions are used by the defaulting engine to populate missing and null keys. + .. note:: _`Objects and arrays` are used as values throughout the API. The difference is: - - Object: This represents a single item that is not inherently a collection. An example of this is `Air Infiltration`_, which is characteristic of the entire building and thus can only be defined once. - - Array: This represents an item that is inherently a collection, even if we don’t yet support more than one item. Often it will be an array of objects, where each object defines an item in the collection. `HVAC`_ and `Walls`_ are examples of this. + - Object: This represents a single item that is not inherently a collection. An example of this is :ref:`Air Infiltration `, which is characteristic of the entire building and thus can only be defined once. + - Array: This represents an item that is inherently a collection, even if we don’t yet support more than one item. Often it will be an array of objects, where each object defines an item in the collection. :ref:`HVAC` and :ref:`Walls` are examples of this. .. _address: @@ -49,20 +56,23 @@ Base Building Building Summary **************** -======================== ======= ======== =========== ======== ================== ============================================== -Property Type Units Constraints Required Default Notes -======================== ======= ======== =========== ======== ================== ============================================== -``conditionedFloorArea`` integer ft2 >0 no PSC If missing from PSC, model will fail +======================== ======= ======== =========== ======== ==================================== ============================================== +Property Type Units Constraints Required Default Notes +======================== ======= ======== =========== ======== ==================================== ============================================== +``conditionedFloorArea`` integer ft2 >0 no :ref:`PSC ` If missing from :ref:`PSC `, model will fail ``averageCeilingHeight`` integer ft >0 no 8 ``bathCount`` integer count >0 no see [#]_ -``bedroomsCount`` integer count >0 no PSC, BSA -``residentCount`` integer count >=0 no BSA -``storiesCount`` integer count >0 no PSC, BSA +``bedroomsCount`` integer count >0 no :ref:`PSC `, :ref:`BSA ` +``residentCount`` integer count >=0 no :ref:`BSA ` +``storiesCount`` integer count >0 no :ref:`PSC `, :ref:`BSA ` ``windowToWallFraction`` float fraction >0 no 0.14 -``yearBuilt`` integer year >1600 no PSC If missing from PSC, model will fail -======================== ======= ======== =========== ======== ================== ============================================== +``yearBuilt`` integer year >1600 no :ref:`PSC ` If missing from :ref:`PSC `, model will fail +``propertyUse`` string see [#]_ no :ref:`PSC ` Advanced option. See [#]_ +======================== ======= ======== =========== ======== ==================================== ============================================== .. [#] ``bedroomsCount``/2 + 0.5 +.. [#] ``propertyUse`` options are "single-family detached", "single-family attached", or "manufactured home". +.. [#] ``propertyUse`` is an advanced field. Overriding the existing property use may produce in abnormal model results. If you set this, we recommend setting ``conditionedFloorArea`` as well. .. _enclosure: @@ -80,7 +90,7 @@ Air Infiltration ======================== ======= ================ =========== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ======================== ======= ================ =========== ======== ================== ============================================== -``rate`` float see ``rateUnit`` >0 no BSA +``rate`` float see ``rateUnit`` >0 no :ref:`BSA ` ``rateUnit`` string see [#]_ no ACH ``housePressurePa`` float Pascals >0 no 50 ======================== ======= ================ =========== ======== ================== ============================================== @@ -99,9 +109,9 @@ See note about `objects and arrays`_ for more information. Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== ``id`` id Must be unique yes Attic1 -``area`` float ft2 >0 no PSC +``area`` float ft2 >0 no :ref:`PSC ` ``isVented`` boolean no yes -``floorAssemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no BSA +``floorAssemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no :ref:`BSA ` ================================= ======= ================ ============== ======== ================== ============================================== .. _roofs: @@ -116,7 +126,7 @@ for more information. Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== ``id`` id Must be unique yes Roof1 -``area`` float ft2 >0 no PSC +``area`` float ft2 >0 no :ref:`PSC ` ``pitch`` float ?:12 >=0 no 6 ``assemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no 2.3 ================================= ======= ================ ============== ======== ================== ============================================== @@ -132,10 +142,10 @@ for more information. ================================= ======= ================ ============== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== -``id`` id must be unique yes PSC -``type`` string see [#]_ no BSA -``area`` float ft2 >0 no PSC -``wallHeight`` float ft >=0 no PSC +``id`` id must be unique yes :ref:`PSC ` +``type`` string see [#]_ no :ref:`BSA ` +``area`` float ft2 >0 no :ref:`PSC ` +``wallHeight`` float ft >=0 no :ref:`PSC ` ================================= ======= ================ ============== ======== ================== ============================================== .. [#] ``type`` choices are "basement conditioned", "basement unconditioned", "crawl vented", "crawl unvented", "slab", and "pier and beam". @@ -152,10 +162,10 @@ See note about `objects and arrays`_ for more information. Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== ``id`` id Must be unique yes Wall1 -``type`` string see [#]_ no BSA -``assemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no BSA -``fractionAreaShared`` float fraction 0-1 no PSC -``area`` float ft2 >0 no PSC +``type`` string see [#]_ no :ref:`BSA ` +``assemblyEffectiveRValue`` float F-ft2-hr/Btu >0 no :ref:`BSA ` +``fractionAreaShared`` float fraction 0-1 no :ref:`PSC ` +``area`` float ft2 >0 no :ref:`PSC ` ================================= ======= ================ ============== ======== ================== ============================================== .. [#] ``type`` choices are "wood stud", "concrete masonry unit", "structural brick", "steel frame", "stone", "adobe", "log wall", and "solid concrete". @@ -181,23 +191,23 @@ See note about `objects and arrays`_ for more information. .. literalinclude:: schemas/request/HVACCoolingSystem.json5 :language: javascript -================================= ======= =========================== ============== ======== ================== ============================================== -Property Type Units Constraints Required Default Notes -================================= ======= =========================== ============== ======== ================== ============================================== -``id`` id Must be unique yes PSC -``connectedDistributionId`` idref yes [#]_ PSC -``systemType`` string see [#]_ yes PSC, BSA -``coolCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined -``compressorType`` string see [#]_ no single stage only applicable if systemType = "central air conditioner" -``coolEfficiency`` float see ``coolEfficiencyUnits`` >0 no PSC -``coolEfficiencyUnits`` string see [#]_ no PSC +================================= ======= =========================== ============== ======== ==================================== ============================================== +Property Type Units Constraints Required Default Notes +================================= ======= =========================== ============== ======== ==================================== ============================================== +``id`` id Must be unique yes :ref:`PSC ` +``connectedDistributionId`` idref yes [#]_ :ref:`PSC ` +``systemType`` string see [#]_ yes :ref:`PSC `, :ref:`BSA ` +``coolCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined +``compressorType`` string see [#]_ no single stage only applicable if systemType = "central air conditioner" +``coolEfficiency`` float see ``coolEfficiencyUnits`` >0 no :ref:`PSC ` +``coolEfficiencyUnits`` string see [#]_ no :ref:`PSC ` ``coolLoadFraction`` float fraction <=1 yes 1 -================================= ======= =========================== ============== ======== ================== ============================================== +================================= ======= =========================== ============== ======== ==================================== ============================================== .. [#] If ``systemType`` is "central air conditioner" .. [#] ``systemType`` choices are "central air conditioner", "room air conditioner", "evaporative cooler", "packaged terminal air conditioner", and "mini-split". .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed". -.. [#] ``coolEfficiencyUnits`` choices are "percent", "EER", "CEER", and "SEER". The option to use "SEER2" is planned for a future release. +.. [#] ``coolEfficiencyUnits`` choices "EER" and "CEER" for room air conditioners and packaged terminal air conditioners. "SEER" and "SEER2" are the choices for central air conditioners and mini-splits. Evaporative coolers do not require `coolEfficiency`. .. _hvac_heating_systems: @@ -210,22 +220,22 @@ See note about `objects and arrays`_ for more information. .. literalinclude:: schemas/request/HVACHeatingSystem.json5 :language: javascript -================================= ======= =========================== ============== ======== ================== ============================================== -Property Type Units Constraints Required Default Notes -================================= ======= =========================== ============== ======== ================== ============================================== -``id`` id Must be unique yes PSC -``connectedDistributionId`` idref see [#]_ PSC -``systemType`` string yes PSC, BSA -``fuel`` string see [#]_ no PSC -``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined -``heatEfficiency`` float see ``heatEfficiencyUnits`` 0-1 no PSC -``heatEfficiencyUnits`` string see [#]_ no PSC +================================= ======= =========================== ============== ======== ==================================== ============================================== +Property Type Units Constraints Required Default Notes +================================= ======= =========================== ============== ======== ==================================== ============================================== +``id`` id Must be unique yes :ref:`PSC ` +``connectedDistributionId`` idref see [#]_ :ref:`PSC ` +``systemType`` string yes :ref:`PSC `, :ref:`BSA ` +``fuel`` string see [#]_ no :ref:`PSC ` +``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined +``heatEfficiency`` float see ``heatEfficiencyUnits`` 0-1 no :ref:`PSC ` +``heatEfficiencyUnits`` string see [#]_ no :ref:`PSC ` ``heatLoadFraction`` float fraction 0-1 yes 1 -================================= ======= =========================== ============== ======== ================== ============================================== +================================= ======= =========================== ============== ======== ==================================== ============================================== .. [#] Required when ``systemType`` is "furnace" or "boiler". .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". -.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent". +.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction". .. _hvac_heat_pumps: @@ -241,16 +251,16 @@ See note about `objects and arrays`_ for more information. ================================= ======= ========================== ============== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ========================== ============== ======== ================== ============================================== -``id`` id Must be unique yes PSC -``connectedDistributionId`` idref see [#]_ see [#]_ PSC -``systemType`` string see [#]_ yes PSC +``id`` id Must be unique yes :ref:`PSC ` +``connectedDistributionId`` idref see [#]_ see [#]_ :ref:`PSC ` +``systemType`` string see [#]_ yes :ref:`PSC ` ``compressorType`` string see [#]_ no single stage ``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined ``coolCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined -``heatEfficiency`` float Btu/Wh >0 no PSC -``heatEfficiencyUnits`` string HSPF [#]_ no HSPF -``coolEfficiency`` float Btu/Wh >0 no PSC -``coolEfficiencyUnits`` string SEER [#]_ no SEER +``heatEfficiency`` float Btu/Wh >0 no :ref:`PSC ` +``heatEfficiencyUnits`` string see [#]_ no HSPF +``coolEfficiency`` float Btu/Wh >0 no :ref:`PSC ` +``coolEfficiencyUnits`` string see [#]_ no SEER ``heatLoadFraction`` float fraction 0-1 yes 1 ``coolLoadFraction`` float fraction 0-1 yes 1 ``backupSystem`` object yes @@ -260,8 +270,8 @@ Property Type Units Constrai .. [#] Required when ``systemType`` is "air-to-air" or "ground-to-air". .. [#] ``systemType`` choices are "mini-split", "air-to-air", and "ground-to-air". .. [#] ``compressorType`` choices are "single stage", "two stage", and "variable speed". -.. [#] The option to use "HSPF2" is planned for a future release. -.. [#] The option to use "SEER2" is planned for a future release. +.. [#] ``heatEfficiencyUnits`` choices are "HSPF" or "HSPF2". +.. [#] ``coolEfficiencyUnits`` choices are "SEER" or "SEER2". ``backupSystem`` schema for HVAC Heat Pumps: @@ -272,14 +282,14 @@ Property Type Units Constrai ``heatingSwitchoverTemp`` float F no determined by modeling engine if undefined ``fuel`` string see [#]_ no electricity only applicable if backupSystem.systemType = "integrated" ``heatEfficiency`` float see ``heatEfficiencyUnit`` 0-1 no 1 only applicable if backupSystem.systemType = "integrated" -``heatEfficiencyUnits`` string see [#]_ no percent only applicable if backupSystem.systemType = "integrated" +``heatEfficiencyUnits`` string see [#]_ no fraction only applicable if backupSystem.systemType = "integrated" ``heatCapacityBtuPerHour`` float Btu/hr >=0 no autosized by modeling engine if undefined, only applicable if backupSystem.systemType = "integrated" -``backupHvacId`` idref see [#]_ see [#]_ PSC +``backupHvacId`` idref see [#]_ see [#]_ :ref:`PSC ` ================================= ======= ========================== ============== ======== ================== ============================================== .. [#] ``systemType`` choices are "integrated" and "separate". .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". -.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "percent". +.. [#] ``heatEfficiencyUnits`` choices are "AFUE" and "fraction". .. [#] Must reference an defined ``hvacHeatingSystem.id`` .. [#] Required when ``backupSystem.systemType`` is "separate". @@ -297,30 +307,28 @@ See note about `objects and arrays`_ for more information. ================================= ======= ========================== ============== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ========================== ============== ======== ================== ============================================== -``id`` id Must be unique yes PSC -``systemType`` string see [#]_ yes PSC -``numberOfReturnRegisters`` integer count >=0 no PSC -``conditionedFloorAreaServed`` float ft2 >0 no PSC +``id`` id Must be unique yes :ref:`PSC ` +``systemType`` string see [#]_ yes :ref:`PSC ` +``numberOfReturnRegisters`` integer count >=0 no :ref:`PSC ` +``conditionedFloorAreaServed`` float ft2 >0 no :ref:`PSC ` ``ducts`` object yes ================================= ======= ========================== ============== ======== ================== ============================================== .. [#] ``systemType`` choices are "regular velocity" and "gravity". -``ducts`` object uses the following schema: +``ducts`` contains two keys, ``supply`` and ``return``. Each of these keys are object arrays using the following schema: ================================= ======= ========================== ============== ======== ====================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ========================== ============== ======== ====================== ============================================== -``id`` id Must be unique yes PSC -``systemType`` string see [#]_ yes "supply" and "return" both supply and return must be defined +``id`` id Must be unique yes :ref:`PSC ` ``insulationRValue`` float F-ft2-hr/Btu >=0 no 0 -``leakageValue`` float see ``leakageUnits`` >=0 no BSA -``leakageUnits`` string see [#]_ no Percent +``leakageValue`` float see ``leakageUnits`` >=0 no :ref:`BSA ` +``leakageUnits`` string see [#]_ no fraction ``location`` string see [#]_ no see notes [#]_ ================================= ======= ========================== ============== ======== ====================== ============================================== -.. [#] ``systemType`` choices are "supply" and "return". -.. [#] ``leakageUnits`` choices are"CFM25", "CFM50", and "percent". +.. [#] ``leakageUnits`` choices are "CFM25", "CFM50", and "fraction". .. [#] ``location`` choices are "living space", "basement conditioned", "basement unconditioned", "crawlspace unvented", "crawlspace vented", "attic unvented", "attic vented", "garage", "outside", "exterior wall", "under slab", "roof deck", "other heated space", and "other non-freezing space". .. [#] If ``location`` not provided, defaults to the first present space type: "basement conditioned", "basement unconditioned", "crawlspace vented", "crawlspace unvented", "attic vented", "attic unvented", "garage", or "living space". @@ -338,9 +346,9 @@ See note about `objects and arrays`_ for more information. ================================= ======= ========================== ============== ======== ================== ============================================== Property Type Units Constraints Required Default Notes ================================= ======= ========================== ============== ======== ================== ============================================== -``id`` id Must be unique yes PSC +``id`` id Must be unique yes :ref:`PSC ` ``systemType`` string yes -``conditionedFloorAreaServed`` float ft2 >0 no PSC +``conditionedFloorAreaServed`` float ft2 >0 no :ref:`PSC ` ================================= ======= ========================== ============== ======== ================== ============================================== .. _hvac_control_systems: @@ -394,7 +402,8 @@ Property Type Units ``tankVolume`` float gal no ``dhwLoadFraction`` float fraction 0-1 yes sum of dhwLoadFraction must equal 1 ``heatCapacityBtuPerHour`` float Btu/hr >0 no autosized by modeling engine if undefined -``energyFactor`` or ``uniformEnergyFactor`` float fraction <1 no BSA +``efficency`` float fraction >0 no :ref:`BSA ` +``efficiencyUnits`` string see [#]_ no :ref:`BSA ` ``hotWaterTemperature`` float F >0 no 125 =========================================== ======= ========================== ============== ======== ==================== ============================================== @@ -408,6 +417,7 @@ Property Type Units IECC zones 1-3, excluding 3A: "garage", "living space" IECC zones 3A, 4-8, unknown: "basement conditioned", "basement unconditioned", "living space" +.. [#] ``efficiencyUnits`` choices are "EF" and "UEF". .. _electrical_panels: @@ -475,7 +485,7 @@ for more information. Property Type Units Constraints Required Default Notes ================================= ======= ================ ============== ======== ================== ============================================== ``id`` id Must be unique yes ClothesDryer1 -``fuel`` string see [#]_ no BSA +``fuel`` string see [#]_ no :ref:`BSA ` ``combinedEnergyFactor`` float lb/kWh >0 no 3.73 ``isVented`` boolean no true ``ventedFlowRate`` float ft3/min no 150 @@ -494,13 +504,13 @@ for more information. .. literalinclude:: schemas/request/CookingRange.json5 :language: javascript -================================= ======= ================ ============== ======== ================== ============================================== -Property Type Units Constraints Required Default Notes -================================= ======= ================ ============== ======== ================== ============================================== +================================= ======= ================ ============== ======== ==================================== ============================================== +Property Type Units Constraints Required Default Notes +================================= ======= ================ ============== ======== ==================================== ============================================== ``id`` id Must be unique yes CookingRange1 -``fuel`` string see [#]_ no PSC, BSA +``fuel`` string see [#]_ no :ref:`PSC `, :ref:`BSA ` ``isInduction`` boolean no false -================================= ======= ================ ============== ======== ================== ============================================== +================================= ======= ================ ============== ======== ==================================== ============================================== .. [#] ``fuel`` choices are "electricity", "natural gas", "fuel oil", "propane", "coal", "wood", and "wood pellets". @@ -512,14 +522,14 @@ Lifetime .. literalinclude:: schemas/request/Lifetime.json5 :language: javascript -================================= ======= ================== ============== ========== ================== ============================================== -Property Type Units Constraints Required Default Notes -================================= ======= ================== ============== ========== ================== ============================================== -``replacementCost`` float ``units.monetary`` >=0 see [#]_ Default values not supported currently +================================= ======= ================== ============== ========== ==================================== ============================================== +Property Type Units Constraints Required Default Notes +================================= ======= ================== ============== ========== ==================================== ============================================== +``replacementCost`` float ``units.monetary`` >=0 see [#]_ Default values not supported currently ``endOfLifeDate`` date in the future see [#LT]_ -``effectiveUsefulLifeDays`` integer days >0 see [#LT]_ BSA -``installedDate`` date in the past see [#LT]_ PSC, BSA -================================= ======= ================== ============== ========== ================== ============================================== +``effectiveUsefulLifeDays`` integer days >0 see [#LT]_ :ref:`BSA ` +``installedDate`` date in the past see [#LT]_ :ref:`PSC `, :ref:`BSA ` +================================= ======= ================== ============== ========== ==================================== ============================================== .. [#] Required to run status quo timeline. .. [#LT] Two of these three properties (``endOfLifeDate``, ``effectiveUsefulLifeDays``, ``installedDate``) are required to be included in the status quo timeline. @@ -717,17 +727,17 @@ connected to the base building's heating and cooling systems. ``adjust`` schema for existing HVAC distribution system: - ==================== ======= =========== ============================================== + ==================== ======= =========== ======================================================== Property Type Constraints Description - ==================== ======= =========== ============================================== - ``leakageUnits`` String See [#]_ Duct leakage units + ==================== ======= =========== ======================================================== + ``leakageUnits`` String See [#]_ Duct leakage units must be the same as ``baseBuilding``. ``leakageValue`` Double >= 0.0 Duct leakage value ``insulationRValue`` Double >= 0.0 - ==================== ======= =========== ============================================== + ==================== ======= =========== ======================================================== Values can be defined and will only be applied if applicable. For example, if there isn't ``airDistribution``, then ``leakageValue`` won't be applied. - .. [#] Units choices are CFM25, CFM50, or Percent. + .. [#] Units choices are "CFM25", "CFM50", or "fraction". .. _existing_water_heating_system: @@ -991,9 +1001,25 @@ Global controls is an optional schema and contains a variety of customization se Units ***** +Units is an optional schema that allows the user to specify what unit(s) are included in the response. + .. literalinclude:: schemas/request/Units.json5 :language: javascript +The following list contains the conversion factors used within the modeling engine. + +* 1 MBTU= 1,000,000 BTU +* 1 BTU = 0.000293071 kWh +* 1 BTU = 1.055056 × :math:`10^{-5}` therms +* 1 kWh = 3412.142 BTU +* 1 kWh = 0.003412142 MBTU +* 1 metric ton of coal = 20.9 MBTU +* 1 short ton of coal = 19.6 MBTU +* 1 gallon fueloil = 0.139 MBTU +* 1 gallon propane = 0.09154 MBTU +* 1 ccf natural gas = 1.034129 MBTU +* 1 therm natural gas = 0.000010015 MBTU + .. _escalation_rates: Escalation Rates diff --git a/docs/source/response_structure.rst b/docs/source/response_structure.rst index dafa7de..cf75815 100644 --- a/docs/source/response_structure.rst +++ b/docs/source/response_structure.rst @@ -70,6 +70,30 @@ Energy Totals per Fuel Time Series .. literalinclude:: schemas/response/EnergyTotalsPerFuelTimeSeries.json5 :language: javascript +Energy End Uses +~~~~~~~~~~~~~~~ + +.. literalinclude:: schemas/response/EnergyEndUses.json5 + :language: javascript + +Energy End Uses per Fuel Time Series +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. literalinclude:: schemas/response/EnergyEndUsesPerFuelTimeSeries.json5 + :language: javascript + +================================== ========================================================================================================== +Property Notes +================================== ========================================================================================================== +``heating`` Excludes heat pump backup and fans/pumps +``heatingFansPumps`` Includes supply fan (air distribution) or circulating pump (hydronic distribution or geothermal loop) +``heatingHeatPumpBackup`` Excludes heat pump backup fans/pumps +``heatingHeatPumpBackupFansPumps`` Includes supply fan (air distribution) or circulating pump (hydronic distribution) during heat pump backup +``cooling`` Excludes fans/pumps +``coolingFansPumps`` Includes supply fan (air distribution) and circulating pump (geothermal loop) +``pv`` Negative value for any power produced +================================== ========================================================================================================== + Energy Costs ~~~~~~~~~~~~ diff --git a/docs/source/schemas/request/AirDistributionSystem.json5 b/docs/source/schemas/request/AirDistributionSystem.json5 index f95dca8..3a55500 100644 --- a/docs/source/schemas/request/AirDistributionSystem.json5 +++ b/docs/source/schemas/request/AirDistributionSystem.json5 @@ -3,22 +3,24 @@ "systemType": "regular velocity", "numberOfReturnRegisters": 2, "conditionedFloorAreaServed": 3456, - "ducts": [ - { - "id": "HVACDistributionFurnaceAndCentral1Supply", - "systemType": "supply", - "insulationRValue": 0.0, - "leakageValue": 0.2, - "leakageUnits": "percent", - "location": "attic vented" - }, - { - "id": "HVACDistributionFurnaceAndCentral1Return", - "systemType": "return", - "insulationRValue": 0.0, - "leakageValue": 0.2, - "leakageUnits": "percent", - "location": "attic vented" - }, - ] -} + "ducts": { + "supply": [ + { + "id": "HVACDistributionFurnaceAndCentral1Supply", + "insulationRValue": 0.0, + "leakageValue": 0.2, + "leakageUnits": "fraction", + "location": "attic vented" + } + ], + "return": [ + { + "id": "HVACDistributionFurnaceAndCentral1Return", + "insulationRValue": 0.0, + "leakageValue": 0.2, + "leakageUnits": "fraction", + "location": "attic vented" + } + ] + } +} \ No newline at end of file diff --git a/docs/source/schemas/request/BaseBuilding.json5 b/docs/source/schemas/request/BaseBuilding.json5 index cfb6a01..e17b1f4 100644 --- a/docs/source/schemas/request/BaseBuilding.json5 +++ b/docs/source/schemas/request/BaseBuilding.json5 @@ -7,7 +7,8 @@ "residentCount": 2, "storiesCount": 2, "windowToWallFraction": 0.14, - "yearBuilt": 1999 + "yearBuilt": 1999, + "propertyUse": "single-family detached" }, "enclosure": ENCLOSURE, "systems": { diff --git a/docs/source/schemas/request/Enclosure.json5 b/docs/source/schemas/request/Enclosure.json5 index 61a9e83..3e1a938 100644 --- a/docs/source/schemas/request/Enclosure.json5 +++ b/docs/source/schemas/request/Enclosure.json5 @@ -6,11 +6,11 @@ "housePressurePa": 50.0, // if null, default is 50 Pa }, - "attics": [ // required to be 1, if no attic in house, area must be set to 0 + "attics": [ // required to be 1 { "id": "Attic1", + "type": "attic vented", // ("attic vented" | "attic unvented" | "cathedral ceiling" | "flat roof") "area": 1225, - "isVented": true, "floorAssemblyEffectiveRValue": 20.6 } ], @@ -28,7 +28,7 @@ "foundations": [ // limited to 1 { "id": "BasementUnconditioned1", - "type": "basement unconditioned", // ("basement conditioned" | "basement unconditioned" | "crawl vented" | "crawl unvented" | "slab" | "pier and beam") + "type": "basement unconditioned", // ("basement conditioned" | "basement unconditioned" | "crawl vented" | "crawl unvented" | "slab" | "belly any wing") "area": 1234, // if the area is less than the footprint area, the remainder will be assigned to crawlspace "wallHeight": 8, } diff --git a/docs/source/schemas/request/GlobalControls.json5 b/docs/source/schemas/request/GlobalControls.json5 index e798f68..7a72880 100644 --- a/docs/source/schemas/request/GlobalControls.json5 +++ b/docs/source/schemas/request/GlobalControls.json5 @@ -4,6 +4,8 @@ "includeInputs": true, // defaults to true, mirror user inputs in the response + "includeEnergyEndUses": false, // defaults to false + "includeDefaultAssumptions": false, // defaults to false "includeBaseResults": true, // defaults to true @@ -43,4 +45,4 @@ "units": UNITS, // optional, refer to the Units schema "escalationRates": ESCALATION_RATES, // optional, refer to the Escalation Rates schema -} \ No newline at end of file +} diff --git a/docs/source/schemas/request/ImprovedEnclosure.json5 b/docs/source/schemas/request/ImprovedEnclosure.json5 index a67d629..5fe1d8d 100644 --- a/docs/source/schemas/request/ImprovedEnclosure.json5 +++ b/docs/source/schemas/request/ImprovedEnclosure.json5 @@ -10,8 +10,8 @@ "attics": [ // required to be 1, if no attic in house, area must be set to 0 { "id": "Attic1", + "type": "attic vented", // ("attic vented" | "attic unvented" | "cathedral ceiling" | "flat roof") "floorAssemblyEffectiveRValue": 50.6, - "isVented": true, "costs": [ COST ], // refer to the Cost schema } ], @@ -28,7 +28,7 @@ "foundations": [ // limited to 1 { "id": "BasementUnconditioned1", - "type": "basement unconditioned", // ("basement conditioned" | "basement unconditioned" | "crawl vented" | "crawl unvented" | "slab" | "pier and beam") + "type": "basement unconditioned", // ("basement conditioned" | "basement unconditioned" | "crawl vented" | "crawl unvented" | "slab" | "belly and wing") "area": 1234, // if the area is less than the footprint area, the remainder will be assigned to crawlspace "wallHeight": 8, } diff --git a/docs/source/schemas/request/ImprovedHVAC.json5 b/docs/source/schemas/request/ImprovedHVAC.json5 index da3458b..29c8fbd 100644 --- a/docs/source/schemas/request/ImprovedHVAC.json5 +++ b/docs/source/schemas/request/ImprovedHVAC.json5 @@ -79,7 +79,7 @@ "insulationRValue": 0.0, "leakageValue": 0.2, "leakageUnits": "percent" // ("CFM25" | "CFM50" | "percent") - "location": "attic vented", // (“living space” | “basement conditioned” | “basement unconditioned” | “crawlspace unvented” | “crawlspace vented” | “attic unvented” | “attic vented” | “garage” | “outside” | “exterior wall” | “under slab” | “roof deck” | “other heated space” | “other non-freezing space”) + "location": "attic vented", // (“conditioned space” | “basement conditioned” | “basement unconditioned” | “crawlspace unvented” | “crawlspace vented” | “attic unvented” | “attic vented” | “garage” | “outside” | “exterior wall” | “under slab” | “roof deck” | “other heated space” | “other non-freezing space” | "manufactured home belly") "remove": false, //if true, system is removed and any other properties defined are ignored. "costs": [ COST ], // refer to the Cost schema }, @@ -89,7 +89,7 @@ "insulationRValue": 0.0, "leakageValue": 0.2, "leakageUnits": "percent" // ("CFM25" | "CFM50" | "percent") - "location": "attic vented", // (“living space” | “basement conditioned” | “basement unconditioned” | “crawlspace unvented” | “crawlspace vented” | “attic unvented” | “attic vented” | “garage” | “outside” | “exterior wall” | “under slab” | “roof deck” | “other heated space” | “other non-freezing space”) + "location": "attic vented", // (“conditioned space” | “basement conditioned” | “basement unconditioned” | “crawlspace unvented” | “crawlspace vented” | “attic unvented” | “attic vented” | “garage” | “outside” | “exterior wall” | “under slab” | “roof deck” | “other heated space” | “other non-freezing space” | "manufactured home belly") "remove": false, //if true, system is removed and any other properties defined are ignored. "costs": [ COST ], // refer to the Cost schema }, diff --git a/docs/source/schemas/request/ModelControls.json5 b/docs/source/schemas/request/ModelControls.json5 index 41dd275..83cbad9 100644 --- a/docs/source/schemas/request/ModelControls.json5 +++ b/docs/source/schemas/request/ModelControls.json5 @@ -11,17 +11,11 @@ // Describes how autosized heat pumps are handled. // If "max load", heat pumps are sized based on the maximum of heating and cooling design loads. // If "acca", heat pumps are sized per ACCA Manual J/S based on cooling design loads with some oversizing allowances for heating design loads. - // *coming soon* If "hers", autosized heat pumps have their nominal capacity sized equal to the larger of heating/cooling design loads. + // If "hers", autosized heat pumps have their nominal capacity sized equal to the larger of heating/cooling design loads. // If not provided, the default value of "acca" is used. - "heatPumpSizingMethodology": "acca", // ("acca" | "max load") // "HERS" option to be added in future - - // If "asset", end use energy based on number of bedrooms. - // If "operational", end use energy adjusted based on number of occupants. - // If not provided, the default value is "asset". - // - "occupancyCalculationType": "asset", + "heatPumpSizingMethodology": "acca", // ("acca" | "max load" | "hers") "energyCostRates": ENERGY_COST_RATES, // optional, refer to the Energy Costs Rates schema "weather": WEATHER, // optional, refer to Weather schema -} \ No newline at end of file +} diff --git a/docs/source/schemas/request/WaterHeating.json5 b/docs/source/schemas/request/WaterHeating.json5 index 05652a0..ad03851 100644 --- a/docs/source/schemas/request/WaterHeating.json5 +++ b/docs/source/schemas/request/WaterHeating.json5 @@ -9,8 +9,8 @@ "tankVolume": 40, "dhwLoadFraction": 1.0, "heatCapacityBtuPerHour": null, - "energyFactor": 0.92, - "uniformEnergyFactor": null, + "efficiency": 0.92, + "efficiencyUnits": "EF", "hotWaterTemperature": 125.0, "lifetime": LIFETIME } diff --git a/docs/source/schemas/response/EnergyEndUses.json5 b/docs/source/schemas/response/EnergyEndUses.json5 new file mode 100644 index 0000000..58ba9f4 --- /dev/null +++ b/docs/source/schemas/response/EnergyEndUses.json5 @@ -0,0 +1,14 @@ +// ENERGY_END_USES +{ + // given if resolution included "hourly" + // it is guaranteed the timeseries will contain 8,760 datapoints + "hourly": ENERGY_END_USES_PER_FUEL_TIME_SERIES, + + // given if resolution included "monthly" + // it is guaranteed the timeseries will contain 12 datapoints + "monthly": ENERGY_END_USES_PER_FUEL_TIME_SERIES, + + // given if resolution included "annual" + // it is guaranteed the timeseries will only contain 1 datapoint + "annual": ENERGY_END_USES_PER_FUEL_TIME_SERIES, +} diff --git a/docs/source/schemas/response/EnergyEndUsesPerFuelTimeSeries.json5 b/docs/source/schemas/response/EnergyEndUsesPerFuelTimeSeries.json5 new file mode 100644 index 0000000..5606d80 --- /dev/null +++ b/docs/source/schemas/response/EnergyEndUsesPerFuelTimeSeries.json5 @@ -0,0 +1,282 @@ +{ + "electricity": { + "heating": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "heatingFansPumps": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackupFansPumps": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "cooling": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "coolingFansPumps": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "lightingInterior": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "lightingGarage": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "lightingExterior": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "mechVent": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "refrigerator": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "freezer": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "dehumidifier": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "dishwasher": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "clothesWasher": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "ceilingFan": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "television": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "plugLoads": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "poolHeater": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "poolPump": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "permanentSpaHeater": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "permanentSpaPump": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + }, + "pv": { + "mbtu": [0.0, ..., 0.0], + "kwh": [0.0, ..., 0.0] + } + }, + "naturalGas": { + "heating": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "poolHeater": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "permanentSpaHeater": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + "ccf": [0.0, ..., 0.0] + } + }, + "fuelOil": { + "heating": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + } + }, + "propane": { + "heating": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + "gallons": [0.0, ..., 0.0] + } + }, + "woodCord": { + "heating": { + "mbtu": [0.0, ..., 0.0], + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + } + }, + "woodPellets": { + "heating": { + "mbtu": [0.0, ..., 0.0], + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + } + }, + "coal": { + "heating": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "heatingHeatPumpBackup": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "hotWater": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "clothesDryer": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "rangeOven": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "lighting": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + }, + "fireplace": { + "mbtu": [0.0, ..., 0.0], + "metricTons": [0.0, ..., 0.0] + } + } +} \ No newline at end of file diff --git a/docs/source/schemas/response/ResponseModel.json5 b/docs/source/schemas/response/ResponseModel.json5 index f4abfaf..b75b507 100644 --- a/docs/source/schemas/response/ResponseModel.json5 +++ b/docs/source/schemas/response/ResponseModel.json5 @@ -35,6 +35,7 @@ }, "energyTotals": ENERGY_TOTALS, + "energyEndUses": ENERGY_END_USES, "energyCosts": ENERGY_COSTS, "emissionTotals": EMISSION_TOTALS, @@ -59,4 +60,4 @@ "averageMonthly": 0.0, // annual electricity difference/savings - loan cost / 12 }, } -} \ No newline at end of file +} diff --git a/docs/source/usage.rst b/docs/source/usage.rst index c742e02..828458b 100644 --- a/docs/source/usage.rst +++ b/docs/source/usage.rst @@ -1,6 +1,10 @@ +.. _usage_instructions: + Usage Instructions ================== +.. setup_and_authentication: + Setup & Authentication ---------------------- @@ -27,6 +31,7 @@ Here is an example using cURL: --data-raw '{"addressFull":"501 RANDALL RD, BALLSTON SPA, NY 12020"}' \ --compressed +.. _simple_request: Simple Request -------------- @@ -42,6 +47,8 @@ payload. In this case, all characteristics of the ``baseBuilding`` would be popu See :ref:`address-only-response` for the response for this example. +.. _advanced_request: + Advanced Request ----------------