honeybee-energy 1.116.106__py3-none-any.whl

honeybee_energy/result/emissions.py

@@ -0,0 +1,290 @@
+"""Module for converting EnergyPlus results into operational carbon emissions."""
+import os
+from collections import OrderedDict
+
+from ladybug.sql import SQLiteResult
+
+
+def emissions_region(location):
+    """Get the region of carbon emissions associated with a location.
+
+    Args:
+        location: A ladybug Location object, which will be used to determine
+            the subregion.
+
+    Returns:
+        A Tuple of text for the eGrid subregion for the location. The first value
+        is the future emissions region, the second is the historical region,
+        and the last is the historic hourly region. This will be None if
+        the location cannot be mapped to a region.
+    """
+    # create the map from states to electric regions
+    region_map = {
+        'FL': ('FRCCc', 'FRCC', 'Florida'),
+        'MS': ('SRMVc', 'SRMV', 'Midwest'),
+        'NE': ('MROWc', 'MROW', 'Midwest'),
+        'OR': ('NWPPc', 'NWPP', 'Northwest'),
+        'CA': ('CAMXc', 'CAMX', 'California'),
+        'VA': ('SRVCc', 'SRVC', 'Carolinas'),
+        'AR': ('SRMVc', 'SRMV', 'Midwest'),
+        'TX': ('ERCTc', 'ERCT', 'Texas'),
+        'OH': ('RFCWc', 'RFCW', 'Midwest'),
+        'UT': ('NWPPc', 'NWPP', 'Northwest'),
+        'MT': ('NWPPc', 'NWPP', 'Northwest'),
+        'TN': ('SRTVc', 'SRTV', 'Tennessee'),
+        'ID': ('NWPPc', 'NWPP', 'Northwest'),
+        'WI': ('MROEc', 'MROE', 'Midwest'),
+        'WV': ('RFCWc', 'RFCW', 'Midwest'),
+        'NC': ('SRVCc', 'SRVC', 'Carolinas'),
+        'LA': ('SRMVc', 'SRMV', 'Midwest'),
+        'IL': ('SRMWc', 'SRMW', 'Midwest'),
+        'OK': ('SPSOc', 'SPSO', 'Central'),
+        'IA': ('MROWc', 'MROW', 'Midwest'),
+        'WA': ('NWPPc', 'NWPP', 'Northwest'),
+        'SD': ('MROWc', 'MROW', 'Midwest'),
+        'MN': ('MROWc', 'MROW', 'Midwest'),
+        'KY': ('SRTVc', 'SRTV', 'Tennessee'),
+        'MI': ('RFCMc', 'RFCM', 'Midwest'),
+        'KS': ('SPNOc', 'SPNO', 'Central'),
+        'NJ': ('RFCEc', 'RFCE', 'Mid-Atlantic'),
+        'NY': ('NYSTc', 'NYCW', 'New York'),
+        'IN': ('RFCWc', 'RFCW', 'Midwest'),
+        'VT': ('NEWEc', 'NEWE', 'New England'),
+        'NM': ('AZNMc', 'AZNM', 'Southwest'),
+        'WY': ('RMPAc', 'RMPA', 'Rocky Mountains'),
+        'GA': ('SRSOc', 'SRSO', 'SRSO'),
+        'MO': ('SRMWc', 'SRMW', 'Midwest'),
+        'DC': ('RFCEc', 'RFCE', 'Mid-Atlantic'),
+        'SC': ('SRVCc', 'SRVC', 'Carolinas'),
+        'PA': ('RFCEc', 'RFCE', 'Mid-Atlantic'),
+        'CO': ('RMPAc', 'RMPA', 'Rocky Mountains'),
+        'AZ': ('AZNMc', 'AZNM', 'Southwest'),
+        'ME': ('NEWEc', 'NEWE', 'New England'),
+        'AL': ('SRSOc', 'SRSO', 'Southeast'),
+        'MD': ('RFCEc', 'RFCE', 'Mid-Atlantic'),
+        'NH': ('NEWEc', 'NEWE', 'New England'),
+        'MA': ('NEWEc', 'NEWE', 'New England'),
+        'ND': ('MROWc', 'MROW', 'Midwest'),
+        'NV': ('NWPPc', 'NWPP', 'Northwest'),
+        'CT': ('NEWEc', 'NEWE', 'New England'),
+        'DE': ('RFCEc', 'RFCE', 'Mid-Atlantic'),
+        'RI': ('NEWEc', 'NEWE', 'New England')
+    }
+    # return the region
+    try:
+        return region_map[location.state]
+    except KeyError:  # location could not be mapped to a region
+        return None
+
+
+def future_electricity_emissions(location, year=2030):
+    """Get the future carbon emissions of the electric grid associated with a location.
+
+    Args:
+        location: A ladybug Location object, which will be used to determine
+            the subregion.
+        year: An integer for the future year for which carbon emissions will
+            be estimated. Values must be an even number and be between 2020
+            and 2050. (Default: 2030).
+
+    Returns:
+        A number for the electric grid carbon emissions in kg CO2 per MWh.
+    """
+    # create the map between regions, years, and carbon
+    years = (2020, 2022, 2024, 2026, 2028, 2030, 2032, 2034,
+             2036, 2038, 2040, 2042, 2044, 2046, 2048, 2050)
+    region_map = {
+        'AZNMc': (352, 412, 404, 389, 335, 301, 288, 279,
+                  243, 208, 179, 182, 144, 136, 132, 126),
+        'CAMXc': (212, 216, 198, 180, 159, 150, 147, 140,
+                  130, 112, 101, 94, 82, 77, 75, 69),
+        'ERCTc': (344, 342, 302, 302, 271, 208, 169, 158,
+                  156, 141, 147, 128, 120, 105, 103, 88),
+        'FRCCc': (368, 377, 381, 399, 355, 288, 273, 277,
+                  268, 259, 251, 228, 192, 193, 190, 179),
+        'MROEc': (411, 419, 411, 427, 389, 335, 285, 156,
+                  149, 156, 146, 145, 121, 107, 122, 99),
+        'MROWc': (375, 386, 354, 325, 298, 185, 149, 133,
+                  127, 126, 129, 110, 88, 89, 79, 70),
+        'NEWEc': (136, 148, 132, 108, 96, 81, 82, 70,
+                  73, 67, 67, 58, 60, 59, 58, 59),
+        'NWPPc': (177, 225, 185, 170, 148, 137, 138, 136,
+                  135, 124, 111, 108, 103, 91, 87, 66),
+        'NYSTc': (189, 206, 153, 134, 111, 92, 92, 79,
+                  86, 83, 77, 78, 79, 78, 83, 83),
+        'RFCEc': (276, 285, 254, 250, 238, 209, 206, 199,
+                  203, 206, 198, 192, 187, 191, 170, 162),
+        'RFCMc': (613, 634, 523, 527, 480, 393, 374, 357,
+                  338, 319, 291, 287, 290, 227, 203, 156),
+        'RFCWc': (493, 508, 467, 477, 463, 415, 390, 363,
+                  335, 316, 287, 259, 242, 215, 217, 197),
+        'RMPAc': (528, 580, 577, 584, 545, 444, 421, 354,
+                  302, 301, 302, 259, 253, 194, 174, 168),
+        'SPNOc': (461, 447, 249, 235, 228, 182, 162, 162,
+                  156, 157, 155, 152, 117, 122, 130, 132),
+        'SPSOc': (287, 277, 161, 143, 134, 119, 87, 82,
+                  72, 64, 60, 56, 47, 49, 58, 56),
+        'SRMVc': (421, 411, 358, 349, 329, 281, 269, 264,
+                  253, 248, 241, 223, 206, 234, 233, 216),
+        'SRMWc': (610, 637, 551, 542, 476, 366, 382, 366,
+                  348, 335, 284, 246, 211, 187, 186, 175),
+        'SRSOc': (334, 322, 327, 347, 263, 222, 206, 208,
+                  207, 188, 185, 161, 145, 123, 126, 112),
+        'SRTVc': (517, 554, 487, 513, 503, 408, 379, 355,
+                  327, 325, 309, 281, 261, 230, 209, 176),
+        'SRVCc': (293, 303, 301, 282, 259, 212, 203, 191,
+                  188, 185, 179, 156, 149, 128, 121, 98),
+    }
+    # return the carbon intensity of electricity
+    yr_i = years.index(year)
+    region_str = emissions_region(location)
+    if region_str is not None:
+        return region_map[region_str[0]][yr_i]
+
+
+def emissions_from_sql(sql_results, electricity_emissions):
+    """Get a dictionary of Carbon Emissions Intensity results from EnergyPlus SQLs.
+
+    This input emissions of electricity will be used to compute carbon intensity
+    for both electricity and district heating/cooling. Fixed numbers will be used
+    to convert the following on-site fuel sources:
+
+    * Natural Gas -- 277.358 kg/MWh
+    * Propane -- 323.897 kg/MWh
+    * Fuel Oil -- 294.962 kg/MWh
+    * District Heating -- 369.811 kg/MWh
+    * District Cooling -- [electricity_emissions] / 3.5 kg/MWh
+
+    Args:
+        sql_results: The file path of the SQL result file that has been generated
+            from an energy simulation. This can also be a list of SQL result files
+            in which case EUI will be computed across all files. Lastly, it can
+            be a directory or list of directories containing results, in which
+            case, EUI will be calculated form all files ending in .sql.
+        electricity_emissions: A number for the electric grid carbon emissions
+            in kg CO2 per MWh. For locations in the USA, this can be
+            obtained from the future_electricity_emissions method. For locations
+            outside of the USA where specific data is unavailable, the following
+            rules of thumb may be used as a guide:
+
+            * 800 kg/MWh - for an inefficient coal or oil-dominated grid
+            * 400 kg/MWh - for the US (energy mixed) grid around 2020
+            * 100-200 kg/MWh - for grids with majority renewable/nuclear composition
+            * 0-100 kg/MWh - for grids with renewables and storage
+
+    Returns:
+        A dictionary with several keys.
+
+        -   carbon_intensity -- A number for the total annual carbon intensity.
+            This is the sum of all operational carbon emissions divided by the
+            gross floor area (including both conditioned and unconditioned spaces).
+            Units are kg CO2/m2.
+
+        -   total_floor_area -- A number for the gross floor area of the building
+            in m2. This excludes Rooms with True exclude_floor_area property.
+
+        -   conditioned_floor_area -- A number for the conditioned floor area of the
+            building in m2. This excludes Rooms with True exclude_floor_area property.
+
+        -   total_carbon -- A number for the total annual operational carbon
+            in kg of Co2.
+
+        -   end_uses -- A dictionary with the carbon intensity for each of the end
+            uses of the building (eg. heating, cooling, lighting, etc.).
+
+        -   sources -- A dictionary with the carbon intensity for each of the energy
+            sources of the building (eg. electricity, natural_gas, district_heat, etc.).
+    """
+    # create a list of sql file path that were either passed directly or are
+    # contained within passed folders
+    if not isinstance(sql_results, (list, tuple)):
+        sql_results = [sql_results]
+    sql_paths = []
+    for file_or_folder_path in sql_results:
+        if os.path.isdir(file_or_folder_path):
+            for file_path in os.listdir(file_or_folder_path):
+                if file_path.endswith('.sql'):
+                    sql_paths.append(os.path.join(file_or_folder_path, file_path))
+        else:
+            sql_paths.append(file_or_folder_path)
+
+    # set initial values that will be computed based on results
+    total_floor_area, conditioned_floor_area = 0, 0
+    tot_elec, tot_gas, tot_pro, tot_oil, tot_heat, tot_cool = 0, 0, 0, 0, 0, 0
+    end_uses = OrderedDict()
+
+    # loop through the sql files and add the energy use
+    for sql_path in sql_paths:
+        # parse the SQL file
+        sql_obj = SQLiteResult(sql_path)
+        # get the total floor area of the model
+        area_dict = sql_obj.tabular_data_by_name('Building Area')
+        areas = tuple(area_dict.values())
+        total_floor_area += areas[0][0]
+        conditioned_floor_area += areas[1][0]
+        # get the energy use
+        eui_dict = sql_obj.tabular_data_by_name('End Uses By Subcategory')
+        for category, vals in eui_dict.items():
+            total_use = sum([val for val in vals[:12]])
+            if total_use != 0:
+                elec = (vals[0] * electricity_emissions) / 1000
+                gas = (vals[1] * 277.358) / 1000
+                pro = (vals[7] * 323.897) / 1000
+                oil = (vals[6] * 294.962) / 1000
+                heat = (vals[11] * 369.811) / 1000
+                cool = (vals[10] * (electricity_emissions / 3.5)) / 1000
+
+                tot_elec += elec
+                tot_gas += gas
+                tot_pro += pro
+                tot_oil += oil
+                tot_heat += heat
+                tot_cool += cool
+                carb = sum((elec, gas, pro, oil, heat, cool))
+
+                cat, sub_cat = category.split(':')
+                eu_cat = cat if sub_cat == 'General' or sub_cat == 'Other' \
+                    else sub_cat
+                try:
+                    end_uses[eu_cat] += carb
+                except KeyError:
+                    end_uses[eu_cat] = carb
+
+    # compute the total carbon emissions
+    sources = OrderedDict([
+        ('electricity', tot_elec),
+        ('natural_gas', tot_gas),
+        ('propane', tot_pro),
+        ('oil', tot_oil),
+        ('district_heat', tot_heat),
+        ('district_cool', tot_cool)
+    ])
+    total_carbon = sum(sources.values())
+
+    # assemble all of the results into a final dictionary
+    if total_floor_area != 0:
+        result_dict = {
+            'carbon_intensity': round(total_carbon / total_floor_area, 3),
+            'total_floor_area': total_floor_area,
+            'conditioned_floor_area': conditioned_floor_area,
+            'total_carbon': round(total_carbon, 3)
+        }
+        result_dict['end_uses'] = OrderedDict(
+            [(key, round(val / total_floor_area, 3)) for key, val in end_uses.items()]
+        )
+        result_dict['sources'] = OrderedDict(
+            [(key, round(val / total_floor_area, 3)) for key, val in sources.items()
+             if val != 0]
+        )
+    else:
+        result_dict = {
+            'carbon_intensity': 0.0,
+            'total_floor_area': total_floor_area,
+            'conditioned_floor_area': conditioned_floor_area,
+            'total_carbon': round(total_carbon, 3)
+        }
+        result_dict['end_uses'] = OrderedDict([(key, 0.0) for key in end_uses.keys()])
+        result_dict['sources'] = OrderedDict(
+            [(key, 0.0) for key, val in sources.items() if val != 0]
+        )
+    return result_dict

honeybee_energy/result/err.py

@@ -0,0 +1,101 @@
+# coding=utf-8
+"""Module for parsing EnergyPlus Error (.err) files."""
+from __future__ import division
+
+import os
+
+
+class Err(object):
+    """Object for parsing EnergyPlus Error (.err) files.
+
+    Args:
+        file_path: Full path to an Err file that was generated by EnergyPlus.
+
+    Properties:
+        * file_path
+        * file_contents
+        * warnings
+        * severe_errors
+        * fatal_errors
+    """
+
+    def __init__(self, file_path):
+        """Initialize Err"""
+        assert os.path.isfile(file_path), 'No file was found at {}'.format(file_path)
+        assert file_path.endswith('.err'), \
+            '{} is not an error file ending in .err.'.format(file_path)
+        self._file_path = file_path
+        self._file_contents = None
+        self._warnings = None
+        self._severe_errors = None
+        self._fatal_errors = None
+
+    @property
+    def file_path(self):
+        """Get the path to the .err file."""
+        return self._file_path
+
+    @property
+    def file_contents(self):
+        """Get a string of all contents in the file."""
+        if not self._file_contents:
+            self._parse_file_contents()
+        return self._file_contents
+
+    @property
+    def warnings(self):
+        """Get a list of strings for all of the warnings found in the .err file.
+
+        Warnings are usually not important enough to bring to the front-end users'
+        attention but they can be helpful for developers and advanced users.
+        """
+        if not self._warnings:
+            self._sort_warnings_errors()
+        return self._warnings
+
+    @property
+    def severe_errors(self):
+        """Get a list of strings for all of the severe errors found in the .err file.
+
+        Severe errors are important enough that front-end users should be made aware of
+        them even though they do not necessarily mean that the simulation has failed.
+        """
+        if not self._severe_errors:
+            self._sort_warnings_errors()
+        return self._severe_errors
+
+    @property
+    def fatal_errors(self):
+        """Get a list of strings for all of the fatal errors found in the .err file.
+
+        Fatal errors indicate the reason why the simulation has failed.
+        """
+        if not self._fatal_errors:
+            self._sort_warnings_errors()
+        return self._fatal_errors
+
+    def _parse_file_contents(self):
+        """Parse all of the contents of a file path."""
+        with open(self._file_path) as err_file:
+            self._file_contents = err_file.read()
+
+    def _sort_warnings_errors(self):
+        """Sort the contents of the error file into warnings and errors."""
+        self._warnings = []
+        self._severe_errors = []
+        self._fatal_errors = []
+        for line in self.file_contents.split('\n'):
+            if '** Warning **' in line:
+                self._warnings.append(line.split('** Warning **')[-1])
+            elif '**  Fatal  **' in line:
+                self._fatal_errors.append(line)
+            elif '** Severe  **' in line:
+                if 'Degenerate surfaces' not in line:
+                    self._severe_errors.append(line)
+
+    def ToString(self):
+        """Overwrite .NET ToString."""
+        return self.__repr__()
+
+    def __repr__(self):
+        return 'Energy Error Result: {}'.format(self.file_path)

honeybee_energy/result/eui.py

@@ -0,0 +1,100 @@
+"""Module to parse End Use Intensity (EUI) from EnergyPlus results."""
+import os
+from collections import OrderedDict
+
+from ladybug.sql import SQLiteResult
+
+
+def eui_from_sql(sql_results):
+    """Get a dictionary of End Use Intensity (EUI) results from EnergyPlus SQLs.
+
+    Args:
+        sql_results: The file path of the SQL result file that has been generated
+            from an energy simulation. This can also be a list of SQL result files
+            in which case EUI will be computed across all files. Lastly, it can
+            be a directory or list of directories containing results, in which
+            case, EUI will be calculated form all files ending in .sql.
+
+    Returns:
+        A dictionary with several keys.
+
+        -   eui -- A number for the total end use intensity. Specifically,
+            this is the sum of all electricity, fuel, district heating/cooling,
+            etc. divided by the gross floor area (including both conditioned
+            and unconditioned spaces). Units are kWh/m2.
+
+        -   total_floor_area -- A number for the gross floor area of the building
+            in m2. This excludes Rooms with True exclude_floor_area property.
+
+        -   conditioned_floor_area -- A number for the conditioned floor area of the
+            building in m2. This excludes Rooms with True exclude_floor_area property.
+
+        -   total_energy -- A number for the total energy use of the building in kWh.
+
+        -   end_uses -- A dictionary with the end use intensity for each of the end
+            uses of the building (eg. heating, cooling, lighting, etc.).
+    """
+    # set initial values that will be computed based on results
+    total_floor_area, conditioned_floor_area, total_energy = 0, 0, 0
+    end_uses = OrderedDict()
+
+    # create a list of sql file path that were either passed directly or are
+    # contained within passed folders
+    if not isinstance(sql_results, (list, tuple)):
+        sql_results = [sql_results]
+    sql_paths = []
+    for file_or_folder_path in sql_results:
+        if os.path.isdir(file_or_folder_path):
+            for file_path in os.listdir(file_or_folder_path):
+                if file_path.endswith('.sql'):
+                    sql_paths.append(os.path.join(file_or_folder_path, file_path))
+        else:
+            sql_paths.append(file_or_folder_path)
+
+    # loop through the sql files and add the energy use
+    for sql_path in sql_paths:
+        # parse the SQL file
+        sql_obj = SQLiteResult(sql_path)
+        # get the total floor area of the model
+        area_dict = sql_obj.tabular_data_by_name('Building Area')
+        areas = tuple(area_dict.values())
+        try:
+            total_floor_area += areas[0][0]
+            conditioned_floor_area += areas[1][0]
+        except IndexError:
+            msg = 'Failed to find the "Building Area" table in the .sql file.'
+            raise ValueError(msg)
+        # get the energy use
+        eui_dict = sql_obj.tabular_data_by_name('End Uses By Subcategory')
+        for category, vals in eui_dict.items():
+            total_use = sum([val for val in vals[:12]])
+            if total_use != 0:
+                total_energy += total_use
+                cat, sub_cat = category.split(':')
+                eu_cat = cat if sub_cat == 'General' or sub_cat == 'Other' \
+                    else sub_cat
+                try:
+                    end_uses[eu_cat] += total_use
+                except KeyError:
+                    end_uses[eu_cat] = total_use
+
+    # assemble all of the results into a final dictionary
+    if total_floor_area != 0:
+        result_dict = {
+            'eui': round(total_energy / total_floor_area, 3),
+            'total_floor_area': total_floor_area,
+            'conditioned_floor_area': conditioned_floor_area,
+            'total_energy': round(total_energy, 3)
+        }
+        result_dict['end_uses'] = OrderedDict(
+            [(key, round(val / total_floor_area, 3)) for key, val in end_uses.items()]
+        )
+    else:
+        result_dict = {
+            'eui': 0.0,
+            'total_floor_area': total_floor_area,
+            'conditioned_floor_area': conditioned_floor_area,
+            'total_energy': round(total_energy, 3)
+        }
+        result_dict['end_uses'] = OrderedDict([(key, 0.0) for key in end_uses.keys()])
+    return result_dict

honeybee_energy/result/generation.py

@@ -0,0 +1,160 @@
+"""Module to parse on-site electricity generation from EnergyPlus results."""
+import os
+from ladybug.sql import SQLiteResult
+
+
+def generation_summary_from_sql(sql_results):
+    """Get a dictionary of electricity generation results from EnergyPlus SQLs.
+
+    Args:
+        sql_results: The file path of the SQL result file that has been generated
+            from an energy simulation. This can also be a list of SQL result files
+            in which case electricity generation will be computed across all files.
+            Lastly, it can be a directory or list of directories containing results,
+            in which case, electricity generation will be calculated form all files
+            ending in .sql.
+
+    Returns:
+        A dictionary with several keys.
+
+        -   total_production -- A positive number for the total electricity
+            produced on-site by all generators. Units are kWh.
+
+        -   total_consumption -- A negative number for the total electricity
+            consumed on-site by all end uses. Units are kWh.
+
+        -   production_used_on_site -- A positive number for the total electricity
+            produced on-site that was also consumed on-site. Units are kWh.
+
+        -   production_surplus_sold -- A positive number for the total electricity
+            produced on-site that was sold to the electric utility as it could
+            not be used on-site. Units are kWh.
+
+        -   consumption_purchased -- A negative number for the total electricity
+            that was purchased from the electric utility as there was no on-site
+            power at the time to meet the energy consumption demand. Units are kWh.
+    """
+    # set initial values that will be computed based on results
+    total_production, total_consumption = 0, 0
+    production_surplus_sold, consumption_purchased = 0, 0
+
+    # create a list of sql file path that were either passed directly or are
+    # contained within passed folders
+    if not isinstance(sql_results, (list, tuple)):
+        sql_results = [sql_results]
+    sql_paths = []
+    for file_or_folder_path in sql_results:
+        if os.path.isdir(file_or_folder_path):
+            for file_path in os.listdir(file_or_folder_path):
+                if file_path.endswith('.sql'):
+                    sql_paths.append(os.path.join(file_or_folder_path, file_path))
+        else:
+            sql_paths.append(file_or_folder_path)
+
+    # loop through the sql files and add the energy production / consumption
+    for sql_path in sql_paths:
+        # parse the SQL file
+        sql_obj = SQLiteResult(sql_path)
+        # get the energy use
+        gen_dict = sql_obj.tabular_data_by_name('Electric Loads Satisfied')
+        for category, vals in gen_dict.items():
+            if category == 'Total On-Site Electric Sources':
+                total_production += vals[0]
+            elif category == 'Total Electricity End Uses':
+                total_consumption += vals[0]
+            elif category == 'Electricity Coming From Utility':
+                consumption_purchased += vals[0]
+            elif category == 'Surplus Electricity Going To Utility':
+                production_surplus_sold += vals[0]
+
+    # assemble all of the results into a final dictionary
+    result_dict = {
+        'total_production': round(total_production, 3),
+        'total_consumption': round(-total_consumption, 3),
+        'production_used_on_site': round(total_production - production_surplus_sold),
+        'production_surplus_sold': round(production_surplus_sold, 3),
+        'consumption_purchased': round(-consumption_purchased, 3)
+    }
+    return result_dict
+
+
+def generation_data_from_sql(sql_results):
+    """Get a data collections of electricity production and consumption.
+
+    Args:
+        sql_results: The file path of the SQL result file that has been generated
+            from an energy simulation. This can also be a list of SQL result files
+            in which case electricity generation will be computed across all files.
+            Lastly, it can be a directory or list of directories containing results,
+            in which case, electricity generation will be calculated form all files
+            ending in .sql.
+
+    Returns:
+        A tuple with two values.
+
+        -   production -- A data collection of the total electricity produced on-site
+            by all generators. Values are in kWh. Will be None if no outputs
+            related to electricity production were requested from the simulation.
+
+        -   consumption -- A data collection of the total electricity consumed
+            by all end uses. Values are in kWh. Will be None if no outputs related
+            to electricity production were requested from the simulation.
+    """
+    prod_data, net_data = [], []
+
+    # create a list of sql file path that were either passed directly or are
+    # contained within passed folders
+    if not isinstance(sql_results, (list, tuple)):
+        sql_results = [sql_results]
+    sql_paths = []
+    for file_or_folder_path in sql_results:
+        if os.path.isdir(file_or_folder_path):
+            for file_path in os.listdir(file_or_folder_path):
+                if file_path.endswith('.sql'):
+                    sql_paths.append(os.path.join(file_or_folder_path, file_path))
+        else:
+            sql_paths.append(file_or_folder_path)
+
+    # loop through the sql files and add the energy production / consumption
+    for sql_path in sql_paths:
+        # parse the SQL file
+        sql_obj = SQLiteResult(sql_path)
+        sql_prod = sql_obj.data_collections_by_output_name(
+            'Facility Total Produced Electricity Energy')
+        prod_data.extend(sql_prod)
+        sql_net = sql_obj.data_collections_by_output_name(
+            'Facility Net Purchased Electricity Energy')
+        net_data.extend(sql_net)
+
+    # sum the production data together
+    if len(net_data) == 0:
+        return None, None
+    elif isinstance(net_data[0], (float, int)):  # annual total of data
+        production = sum(prod_data)
+    else:
+        if len(prod_data) == 0:
+            production = net_data[0].duplicate()
+            production.values = [0] * len(production)
+        elif len(prod_data) == 1:
+            production = prod_data[0]
+        else:
+            production = prod_data[0]
+            for data_i in prod_data[1:]:
+                production = production + data_i
+        production.header.metadata['System'] = 'Whole Building'
+        production.header.metadata['type'] = 'Electricity Production'
+
+    # compute the electricity consumption from the net data
+    if len(net_data) == 1:
+        consumption = net_data[0] + production
+    else:
+        consumption = net_data[0]
+        for data_i in net_data[1:]:
+            consumption = consumption + data_i
+        consumption = consumption + production
+    try:
+        consumption.header.metadata['type'] = 'Electricity Consumption'
+    except AttributeError:  # annual total of data
+        pass
+
+    return production, consumption