System and Component Models

mswh.system.components module

class mswh.system.components.Converter(params=None, weather=None, sizes=1.0, log_level=10)[source]

Bases: object

Contains energy converter models, such as solar collectors, electric resistance heaters, gas burners, photovoltaic panels, and heat pumps. Depending on the intended usage, the models can be used to determine either a time period of component operation (for example an entire year), or a single timestep of component performance.

Parameters:

params: pd df

Component performance parameters per project Default: None (default model parameters will get used)

weather: pd df

Weather data timeseries with columns: amb. temp, solar irradiation. Number of rows equals the number of timesteps. Default: None (constant values will be set - use for a single timestep calculation, or if passing arguments directly to static methods)

sizes: pd df

Component sizes per project. Default: 1. (see individual components for specifics)

log_level: None or python logger logging level,

Default: logging.DEBUG This applies for a subset of the class functionality, mostly used to deprecate logger messages for certain calculations. For Example: log_level = logging.ERROR will only throw error messages and ignore INFO, DEBUG and WARNING.

Note:

If more than one of the same component is a part of the system, a separate instance of the converter should be created for each instance of the component.

Each component is also implemented as a static method that can be used outside of this framework.

Examples:

See mswh.system.tests.test_components module and scripts/Project Level MSWH System Tool.ipynb for examples on how to use the methods as stand alone and in a system model simulation.

electric_resistance(Q_dem)[source]

Electric resistance heater model. Can be used both as an instantaneous electric WH and as an auxiliary heater within the thermal tank.

Parameters:

Q_dem: float or array like, [W]

Heat demand

Returns:

res: dict

  • self.r[‘q_del_bckp’] : float, array - delivered heat rate, [W]

  • self.r[‘q_el_use’] : float, array - electricity use, [W]

  • self.r[‘q_unmet’] : float, array - unmet demand heat rate, [W]

gas_burner(Q_dem)[source]

Gas burner model. Used both as an instantaneous gas WH and as a gas backup for solar thermal.

Parameters:

Q_dem: float or array like, W

Heat demand

Returns:

res: dict

  • self.r[‘q_del_bckp’] : float, array - delivered heat rate, [W]

  • self.r[‘q_gas_use’] : float, array - gas use heat rate, [W]

  • self.r[‘q_unmet’] : float, array - unmet demand heat rate, [W]

Any further unit conversion should be performed using unit_converters.Utility class

heat_pump(T_wet_bulb, T_tank)[source]

Returns the current heating performance and electricity usage in the current conditions depending on wet bulb temperature, average tank water temperature, and the rated heating performance.

Rated conditions are: wet bulb = 14 degC, tank = 48.9 degC

Parameters:

T_wet_bulb: real, array

Inlet air wet bulb temperature [K]

T_tank: real, array

Water temperature in the storage tank [K]

C1: real

Coefficient 1, either for normalized COP or heating capacity curve [-]

C2: real

Coefficient 2, either for normalized COP or heating capacity curve [1/degC]

C3: real

Coefficient 3, either for normalized COP or heating capacity curve [1/degC2]

C4: real

Coefficient 4, either for normalized COP or heating capacity curve [1/degC]

C5: real

Coefficient 5, either for normalized COP or heating capacity curve [1/degC2]

C6: real

Coefficient 6, either for normalized COP or heating capacity curve [1/degC2]

Returns:

performance: dict

  • ‘cop’: current Coefficient Of Performance (COP), [-]

  • ‘heat_cap’: current heating capacity of heat pump, [W]

  • ‘el_use’: current electricity use of heat pump [W]

photovoltaic(use_p_peak=True, inc_rad=None)[source]

Photovoltaic model

Parameters:

use_p_peak: boolean

Boolean flag determining if peak power is used for sizing the pv panel (instead of area and efficiency)

Returns:

self.pv_power: dict of floats

Generated power [W]

  • ‘ac’ : AC

  • ‘dc’ : DC

property size
solar_collector(t_in, t_amb=None, inc_rad=None)[source]

Two commonly used empirical instantaneous collector efficiency models based on test data from standard test procedures (SRCC, ISO9806), found in J. A. Duffie and W. A. Beckman, Solar engineering of thermal processes, 3rd ed. Hoboken, N.J: Wiley, 2006., are:

  • Cooper and Dunkle (CD model, eq 6.17.7)

  • Hottel-Whillier-Bliss (HWB model, eq 6.16.1, 6.7.6)

Parameters:

t_in: float, array

Collector inlet temperature (timeseries) [K]

t_amb: float, array

Ambient temperature (timeseries) [K] Default: None (to use data extracted from the weather df)

inc_rad: float, array

Incident radiation (timeseries) [W] Default: None (to use data extracted from the weather df)

Returns:

res: dict or floats or arrays

{‘Q_gain’Solar gains from the gross collector area, [W]

‘eff’ : Efficiency of solar to heat conversion, [-]

property weather
class mswh.system.components.Distribution(params=None, sizes=1.0, fluid_medium='water', timestep=1.0, log_level=10)[source]

Bases: object

Describes performance of distribution system components.

Parameters:
sizes: pd df

Pandas dataframe with component sizes, or 1.

fluid_medium: string

Default: ‘water’. No other options implemented

timestep: float, h

Duration of a single timestep, in hours, defaults to 1.

log_level: None or python logger logging level,

Default: logging.DEBUG This applies for a subset of the class functionality, mostly used to deprecate logger messages for certain calculations. For Example: log_level = logging.ERROR will only throw error messages and ignore INFO, DEBUG and WARNING.

Note:

Each component is also implemented as a static method that can be used outside of this framework.

Examples:

See mswh.system.tests.test_components module and for examples on how to use the methods.

pipe_losses(T_in=333.15, T_amb=293.15, V_tap=0.05, max_V_tap=0.1514)[source]

Thermal losses from distribution pipes.

Parameters:

T_in: float, K

Hot water temperature at distribution pipe inlet

T_amb: float, K

Ambient temperature

V_tap: float, m3/h

Timestep draw volume

max_V_tap: float, m3/h

Maximum draw volume, m3/h (design variable)

Returns:

res: dict

[‘heat_rate’]: Loss heat rate, W

pump(on_array=array([1., 1., 1., ..., 1., 1., 1.]), role='solar')[source]

Solar and distribution pump energy use. Assumes a fixed speed pump.

Parameters:

on_array: array

Pump on/off status for the chosen number of discrete timesteps Default: np.ones(8760) - on for a year in hourly timesteps.

role: string

‘solar’ : primary (solar collector) loop ‘distribution’ : secondary (distribution) loop

Returns:

en_use: float or array like

property size
class mswh.system.components.Storage(params=None, size=1.0, type='sol_tank', timestep=1.0, log_level=10)[source]

Bases: object

Describes performance of storage components, such as solar thermal tank, heat pump thermal tank, conventional gas tank water heater.

Parameters:

params: pd df

Component performance parameters per project Default: None. See tests and examples on how to structure this input.

weather: pd df

Weather data timeseeries (amb. temp, solar irradiation) Default: None. See tests and examples on how to structure this input.

size: pd df or float, m3

Tank size. Default 1. See tests and examples on how to structure this input.

type: string

Type of storage component. Options:

  • ‘sol_tank’ - indirect tank WH with a coil to circulate fluid heated by a solar collector

  • ‘hp_tank’ - tank with an inbuilt heat pump ‘wham_tank’ - conventional gas tank water heater model based on a WH model from the efficiency standards analysis

  • ‘gas_tank’ - conventional gas tank water heater (currently not implemented)

log_level: None or python logger logging level,

Default: logging.DEBUG This applies for a subset of the class functionality, mostly used to deprecate logger messages for certain calculations. For Example: log_level = logging.ERROR will only throw error messages and ignore INFO, DEBUG and WARNING.

timestep: float, h

Duration of a single timestep, in hours, defaults to 1.

Note:

Create a new instance of the class for each storage component.

Examples:

See mswh.system.tests.test_components module and scripts/MSWH System Tool.ipynb for examples on how to use the methods as stand alone and in a system model simulation.

electric_tank_wh()[source]

Currently not implemented.

gas_tank_wh(V_draw, T_feed, T_amb=291.48)[source]

Gas storage water heater model (_gas_tank_wh) wrapper.

Parameters:

V_draw: float or array like, m3/h

Hourly water draw for a single timestep of an entire analysis period

T_feed: float or array like, K

Temperature of water heater inlet water for a single timestep of an entire analysis period

T_amb: float or array like, K

Temperature of space surrounding water heater Default: 65 degF

Returns:

res: dict

  • self.r[‘q_del’] : float, array - delivered heat rate, [W]

  • self.r[‘q_dem’] : float, array - demand heat rate, [W]

  • self.r[‘q_gas_use’] : float, array - gas use heat rate, [W]

  • self.r[‘q_unmet’] : float, array - unmet demand, [w]

  • self.r[‘q_dump’] : float, array - dumped heat, [W]

Note:

Assuming no electricity consumption in this version.

Make sure to size the tank according to the recommended sizing rules, since the WHAM model does not apply to tanks that are not appropriately sized.

setup_electric()[source]

Currently not implemented.

setup_thermal(medium='water', split_tank=True, vol_fra_upper=0.5, h_vs_r=6.0, dT_param=2.0, T_max=344.15, T_draw_set=322.04, insul_thickness=0.085, spec_hea_cond=0.04, coil_eff=0.84, tank_re=0.76, dT_err_max=2.0, gas_heater_autosize=False)[source]

Sets thermal storage variables related to:

  • loss calculation

  • distribution of net gains/losses within two tank volumes (upper and lower)

Parameters:

medimum: string

Storage medium (for thermal defaults to ‘water’)

split_tank: boolean

If true, the tank is observed as two volumes, upper and lower tank volume. If false, the tank is observed as a single tank

vol_fra_upper: float

Fraction of storage volume assigned to the upper tank volume (applies to ‘thermal’ only) If split_tank set to False, the value is ignored

dT_param: float, K

Used as:

  • Maximum temperature difference expected to occur between the upper and the lower tank volume while charging

  • In-tank-coil approach

h_vs_r: float

Regression parameter - tank height/diameter ratio (based on web scraped data), default: 6.

T_max: float, K

Maximum allowed fluid temperature in the thermal storage tank, defaults to 344.15 K = 71 degC.

T_draw_set: float, K

Draw temperature used in the load calculation, defaults to 120 degF = 322.04 K = 48.89 degC

insul_thickness: float, m

Insulation thickness Default: .04 m (1-2 inch gas, 2-3 inch electric, based on DOE residential water heaters energy efficiency standard (ECS) analysis)

spec_hea_cond: float, W/mK

Specific heat conductivity of the insulation Default: .04 W/mK (:from library:ModelicaBuidlings)

coil_eff: float

Simplified efficiency of the coil heat exchanger Used in modeling of indirect coil-in-tank water heaters It excludes the approach temperature and represents the remaining heat transfer inefficiency

tank_re: float

Recovery efficiency of a gas tank water heater. Used for the Storage.gas_tank_wh model

dT_err_max: float

Allowed dT error below the minimum tank temperature due to finite timestep length approximation

gas_heater_autosize: boolean

There is a gas heater in the tank and it will be autosized based on the tank volume

property size
tap(V_draw_load, T_tank, T_feed, dT_loss=0.0, T_draw_min=None)[source]

Calculates the water draw volume and heat content drawn from the top of an infinitely large adiabatic tank given the hot water demand, tank temperature and the water main temperature.

It functions somewhat similarly to a thermostatic valve since it regulates the tap flow from the tank as follows:

  • Limits above if the tank temperature is higher than the nominal draw temperature

  • Tap flow equals V_draw_load for any tank temperature between T_draw_min and T_draw_nom

  • Tap flow is zero if tank temperature is below T_draw_min and T_draw_min is provided

The results represent the theoretical limit for the draw. The tank model will check if the full amount can be delivered or only a part of the demand, due to the limited tank volume and thermal losses from the tank, and adjust the values.

Parameters:

V_draw_load: float, m3/h

Volume of DHW drawn at the nominal end-use load temperature.

T_tank: float, K

Tank node temperature from which the DHW is being tapped (usually the upper volume)

T_feed: float or array, K

Temperature of water heater inlet water

dT_loss: float, K

Distribution loss temperature difference

T_draw_min: float, K

Minimal temperature that needs to be achieved in the tank in order to allow tapping.

Default: None - tapping is always enabled

Recommended usage - in colder climates where an outdoors tank may be cooler than the water main.

Returns:

draw: dict

  • Draw volume: ‘vol’, m3/h

  • Total demand heat rate: ‘tot_dem’, W

  • Infinite volume delivered heat rate: ‘heat_rate’, W

  • Infinite volume unmet heat rate: ‘unmet_heat_rate’, W

thermal_tank(pre_T_amb=293.15, pre_T_feed=291.15, pre_T_upper=328.15, pre_T_lower=323.15, pre_V_tap=0.00757, pre_Q_in=400.0, max_V_tap=0.1514)[source]

Model of a thermal storage tank with:

  • Coil heat exchanger for the solar gains

  • DHW tap at the top of the tank

  • Recharge tap at the bottom of the tank

The model can be instantiated as a:

  • Solar thermal tank

  • Heat pump tank

Parameters:

type: string

  • ‘solar’ - solar tank (assumes that heated fluid from a solar collector is circulated through an in-tank-coil)

  • ‘hp’ - heat pump tank (assumes an inbuilt heat pump as a main heat source)

The type will affect output labeling and heat transfer efficiency.

pre_T_amb: float, K

Ambient temperature

pre_T_feed: float, K

Temperature of the water that replenishes the tapped volume (e.g. water main temperature)

pre_T_upper: float, K

Upper tank volume temperature

pre_T_lower: float, K

Lower tank volume temperature

pre_Q_in: float, W

Heat gain passed to in-tank coil from solar collector or from a heat pump, depending on the type

pre_V_tap: float, m3/h

Volume of water tapped from the top of the tank

max_V_tap: float, m3/h

Annual peak flow

Returns:

res: dict

Single timestep input and output values for temperatures [K] and heat rates [W]:

>>> {net_gain_label : pre_Q_in_net,
self.r['q_loss_low'] : pre_Q_loss_lower,
self.r['q_loss_up'] : pre_Q_loss_upper,
# demand, delivered and unmet heat
# (between tap setpoint and water main)
self.r['q_dem'] : tap['net_dem'],
self.r['q_dem_tot'] : tap['tot_dem'],
self.r['q_del_tank'] : tank[self.r['q_del_tank']],
self.r['q_unmet_tank'] : np.round(
tank[self.r['q_unmet_tank']] + tap['unmet_heat_rate'], 2),
self.r['q_dump'] : tank[self.r['q_dump']],
self.r['q_ovrcool_tank'] : tank[self.r['q_ovrcool_tank']],
self.r['q_dem_balance'] : np.round(Q_dem_balance),
# average temperatures for tank volumes
self.r['t_tank_low'] : tank[self.r['t_tank_low']],
self.r['t_tank_up'] : tank[self.r['t_tank_up']],
self.r['dt_dist'] : dist['dt_dist'],
self.r['t_set'] : self.T_draw_set,
self.r['q_dist_loss'] : dist['heat_loss'],
self.r['flow_on_frac'] : dist['flow_on_frac']}
Temperatures in K, heat rates in W
thermal_tank_dynamics(pre_T_amb, pre_T_upper, pre_T_lower, pre_Q_in, pre_Q_loss_upper, pre_Q_loss_lower, pre_T_feed, pre_Q_tap)[source]

Partial model of a thermal storage tank. Applies first order forward marching Euler method and updates the tank state for the current timestep based on the enthalpy balance and simplified assumptions about stratification. Thus, all input variables pertain to the previous timestep, while the outputs are solutions for the current timestep.

For example partial model application see thermal_tank method.

See inline comments for detailed explanation of the model.

Parameters:

pre_T_amb: float, K

Ambient air temperature

pre_T_upper: float, K

Upper tank volume temperature

pre_T_lower: float, K

Lower tank volume temperature

It is recommended to set equal initial values for pre_T_upper and pre_T_lower

pre_Q_in: float, W

Total heat gain (e.g. from a coil heat exchanger, a heating element, etc.)

pre_Q_loss_upper: float, W

Heat loss from the upper tank volume

pre_T_lower: float, W

Heat loss from the lower tank volume

pre_T_feed: float, K

Temperature of the water that replenishes the tapped volume (e.g. water main temperature)

pre_Q_tap: float, W

Heat loss that would occur if the tank volume at pre_T_upper was infinite

Returns:

res: dict of floats

Represent averages in a single timestep. Average temperatures for tank volumes:

  • self.r[self.r[‘t_tank_low’]] : lower, K

  • self.r[‘t_tank_up’] : upper, K

Heat rates:

  • ‘Q_net’ : expected timestep net gain/loss based on inputs, W self.r[‘q_dump’] : dumped heat, W

  • ‘Q_draw’ : delivered to load W

  • ‘Q_draw_unmet’ : unmet load due to finite tank volume, W self.r[‘q_ovrcool_tank’] : error in balancing due to minimal tank temperature limit assumption in each timestep

Note: ‘Q_draw’ + ‘Q_draw_unmet’ = pre_Q_tap

volume_to_power(tank_volume)[source]

Method to convert a gas water heater’s volume input power based on a linear regression performed on the web scraped data.

Parameters:

tank_volume: float or int

Water heater tank volume [m3]

Returns

tank_input_power: float

Water heater input (rated) power [W]

mswh.system.models module

class mswh.system.models.System(sys_params=None, backup_params=None, weather=None, sys_sizes=1.0, backup_sizes=1.0, loads=None, timestep=1.0, log_level=10)[source]

Bases: object

Project level system models:

  • Assembles system configurations

  • Performs timestep simulation

  • Returns annual and timestep project and household level results, such as gas and electricity use, heat delivered, unmet demand and solar fraction.

Parameters:

sys_params: pd df

Main system component performance parameters per project Default: None (default model parameters will get used)

backup_params: pd df

Backup system performance parameters per project. It should contain a household ID column, otherwise columns identical to params.

sys_sizes: pd df

Main system component sizes Default: 1. (see individual components for specifics)

backup_sizes: pd df

Backup system component sizes, contains household id column Default: 1. (see individual components for specifics)

weather: pd df

Weather data timeseries. Number of rows equals the number of timesteps. Can be generated using the Source.irradiation_and_water_main method

Example:

>>> sourceASource(read_from_input_dataframes = inputs)

Oakland climate zone in CEC weather data is ‘03’:

>>> self.weather = source.irradiation_and_water_main('03', method='isotropic diffuse')
loads: pd df

A dataframe with loads for all individual household served by the project level system. It should contain 3 columns: household id, occupancy and a column with a load array in m3 for each household.

Example:

>>> loads_com = pd.DataFrame(data = [[1, occ_indiv - 1., 0.8 * load_array],[2, occ_indiv, 1. * load_array],[3, occ_indiv, 1.2 * load_array],[4, occ_indiv + 1., 1.4 * load_array]], columns = [self.c['id'], self.c['occ'], self.c['load_m3']])
timestep: float, h

Duration of a single timestep, in hours Default: 1. h

log_level: None or python logger logging level,

Default: logging.DEBUG This applies for a subset of the class functionality, mostly used to deprecate logger messages for certain calculations. For Example: log_level = logging.ERROR will only throw error messages and ignore INFO, DEBUG and WARNING.

Examples:

See mswh.system.tests.test_components module and scripts/MSWH System Tool.ipynb for examples on how to use the methods as stand alone and in a system model simulation.

conventional_gas_tank()[source]

Basecase conventional gas tank water heater. Make sure to size the tank according to the recommended sizing rules, since the WHAM model does not apply to tanks that are not appropriately sized.

Returns:

ts_proj: dict of arrays, W

Heat:

  • self.r[‘q_del’]: delivered

  • self.r[‘gas_use’]: gas consumed

simulate(type='gas_tank_wh')[source]

Runs a 8760. hourly simulation of the provided system type.

Parameters:

type: string

  • ‘gas_tank_wh’

  • ‘solar_thermal_retrofit’ (gas tank backup at each household)

  • ‘solar_thermal_new’ (gas tankless backup at each household)

  • ‘solar_electric’

Returns:

en_use: dict

Total energy use for the analysis period:

  • ‘gas’, Wh

  • ‘electricity’, Wh

sys_res: list

List containing detailed system level output. See dedicated methods for details

solar_electric(backup='electric')[source]

Connects the components of the solar electric system and enables simulation.

Parameters:

backup: string

electric - instantaneous WHs (new installations)

Returns:

sys_en_use: dict

System level energy use for the analysis period: ‘electricity’, Wh

sol_fra: dict

Solar fraction. Keys: ‘annual’, ‘monthly’

ts_res: pd df

Colums populated with state variable timeseries, such as average timstep heat rates and temperatures

res: dict

Summarizes ts_res. Any heat rates are summed, while the temperatures are averaged for the analysis period (usually one year)

el_use: dict

Electricity use broken into end uses ‘dist_pump’ - distribution pump, if present

rel_err: float

Balancing error due to limitations of finite timestep averaging. More precisely, due to selecting minimum tank temperature as the lower between the water main and the ambient.

solar_thermal(backup='gas')[source]

Connects the components of the solar thermal system and simulates it in discrete timesteps.

Parameters:

backup: string

retrofit - pulls from the basecase for each household gas, electric - instantaneous WHs (new installations)

Returns:

self.cons_total: pd df

Consumer level energy use [W], heat rates [W], average temperatures [K], and solar fraction for the analysis period.

proj_total: pd series

Project level energy use [W], heat rates [W], average temperatures [K], and solar fraction for the analysis period.

sol_fra: dict

Solar fraction. Keys: ‘annual’, ‘monthly’

pump_el_use: dict

Electricity use broken into end uses ‘dist_pump’ - distribution pump, if present ‘sol_pump’ - solar pump

ts_res: pd df

Timestep project level results for all energy uses [W], heat rates [W], temperatures [K], and the load.

backup_ts_cons: dict of dicts

Timestep household level results for energy uses [W], and heat rates [W].

rel_err: float

Balancing error due to limitations of finite timestep averaging.

property weather

mswh.system.source_and_sink module

class mswh.system.source_and_sink.SourceAndSink(input_dfs=None, random_state=123, log_level=10)[source]

Bases: object

Generates timeseries that are inputs to the simulation model and are known prior to the simulation, such as outdoor air temperature and end use load profiles.

Parameters:

input_dfs: a dict of pd dfs

Dictionary of input dataframes as read in from the input db by the Sql class (see example in test_source_and_sink.SourceAndSinkTests.setUp)

random_state: numpy random state object or an integer

numpy random state object : if there is a need to maintain the same random seed throughout the analysis.

integer : a new random state object gets instanteated at init

log_level: None or python logger logging level,

Default: logging.DEBUG This applies for a subset of the class functionality, mostly used to deprecate logger messages for certain calculations. For Example: log_level = logging.ERROR will only throw error messages and ignore INFO, DEBUG and WARNING.

static demand_estimate(occ)[source]

Estimates gal/day demand as provided in the CSI-Thermal Program Handbook, April 2016 for installations with a known occupancy

Parameters:

occ: float

Number of individual household occupants

irradiation_and_water_main(climate_zone, collector_tilt='latitude', tilt_standard_deviation=None, collector_azimuth=0.0, azimuth_standard_deviation=None, location_ground_reflectance=0.16, solar_constant_Wm2=1367.0, method='isotropic diffuse', weather_data_source='cec', single_row_with_arrays=False)[source]

Calculates the hourly total incident radiation on a tilted surface for any climate zone in California. If weather data from the provided database are passed as input_dfs, the user can specify a single climate.

Two separate methods are available for use, with all equations (along with the equation numbers provided in comments) as provided in J. A. Duffie and W. A. Beckman, Solar engineering of thermal processes, 3rd ed. Hoboken, N.J: Wiley, 2006.

Parameters:

climate_zone: string

String of two digits to indicate the CEC climate zone being analyzed (‘01’ to ‘16’).

collector_azimuth: float, default: 0.

The deviation of the projection on a horizontal plane of the normal to the collector surface from the local meridian, in degrees. Allowable values are between +/- 180 degrees (inclusive). 0 degrees corresponds to due south, east is negative, and west is positive. Default value is 0 degrees (due south).

azimuth_standard_deviation: float, default: ‘None’

Final collector azimuth is a value drawn using a normal distribution around the collector_azimuth value with a azimuth_standard_deviation standard deviation. If set to ‘None’ the final collector azimuth equals collector_azimuth

collector_tilt: float, default: ‘latitude’

The angle between the plane of the collector and the horizontal, in degrees. Allowable values are between 0 and 180 degrees (inclusive), and values greater than 90 degrees mean that the surface has a downward-facing component. If a default flag is left unchanged, the code will assign latitude value to the tilt as a good approximation of a design collector or PV tilt.

tilt_standard_deviation: float, default: ‘None’

Final collector tilt is a value drawn using a normal distribution around the collector_tilt value with a tilt_standard_deviation standard deviation. If set to ‘None’ the final collector tilt equals collector_tilt

location_ground_reflectance: float, default: 0.16

The degree of ground reflectance. Allowable values are 0-1 (inclusive), with 0 meaning no reflectance and 1 meaning very high reflectance. For reference, fresh snow has a high ground reflectance of ~ 0.7. Default value is 0.16, which is the annual average surface albedo averaged across the 16 CEC climate zones.

method: string, default: ‘HDKR anisotropic sky’

Calculation method to use for estimating the total irradiance on the tilted collector surface. See notes below. Default value is ‘HDKR anisotropic sky.’

solar_constant_Wm2: float, default: 1367.

Energy from the sun per unit time received on a unit area of surface perpendicular to the direction of propagation of the radiation at mean earth-sun distance outside the atmosphere. Default value is 1367 W/m^2.

weather_data_source: string, default: ‘cec’

The type of weather data being used to analyze the climate zone for solar insolation. Allowable values are ‘cec’ and ‘tmy3.’ Default value is ‘cec.’

single_row_with_arraysboolean

A flag to reformat the resulting dataframe in a row of data where each resulting 8760 is stored as an array

Returns:

data: pd df

Weather data frame with appended columns: ‘global_tilt_radiation_Wm2’, ‘water_main_t_F’, ‘water_main_t_C’, ‘dry_bulb_C’, ‘wet_bulb_C’, ‘Tilt’, ‘Azimuth’]

Notes:

The user can select one of two methods to use for this calculation:

  1. ‘isotropic diffuse’:

    This model was derived by Liu and Jordan (1963). All diffuse radiation is assumed to be isotropic. It is the simpler and more conservative model, and it has been widely used.

  2. ‘HDKR anisotropic sky’:

    This model combined methods from Hay and Davies (1980), Klucher (1979), and Reindl, et al. (1990). Diffuse radiation in this model is represented in two parts: isotropic and circumsolar. The model also accounts for horizon brightening. This is also a simple model, but it has been found to be slightly more accurate (and less conservative) than the ‘isotropic diffuse’ model. For collectors tilted toward the equator, this model is suggested.