eta_fu_template: Final-to-useful efficiency template

In MatthewHeun/IEATools: Tools for Working with International Energy Agency Data

Final-to-useful efficiency template

Description

Using a filled final-to-useful allocation table, this function generates a blank template for final-to-useful machine efficiencies.

Usage

eta_fu_template(
  .fu_allocations,
  tidy_specified_iea_data,
  T_0 = 298.15,
  sort_by = c("useful_energy_type", "importance"),
  md = "MD",
  light = "Light",
  ke = "KE",
  heat = "TH",
  perc = "[%]",
  c_ = "C_",
  c_perc = paste(substr(c_, 1, 1), perc),
  c_ratio = substr(c_, 1, 1),
  year_for_maximum_values = 0,
  .row_order = ".row_order",
  non_energy_eff = 1e-06,
  country = IEATools::iea_cols$country,
  year = IEATools::iea_cols$year,
  ledger_side = IEATools::iea_cols$ledger_side,
  flow_aggregation_point = IEATools::iea_cols$flow_aggregation_point,
  product = IEATools::iea_cols$product,
  flow = IEATools::iea_cols$flow,
  e_dot = IEATools::iea_cols$e_dot,
  unit = IEATools::iea_cols$unit,
  ef_product = IEATools::template_cols$ef_product,
  machine = IEATools::template_cols$machine,
  eu_product = IEATools::template_cols$eu_product,
  eta_fu = IEATools::template_cols$eta_fu,
  phi_u = IEATools::template_cols$phi_u,
  destination = IEATools::template_cols$destination,
  quantity = IEATools::template_cols$quantity,
  maximum_values = IEATools::template_cols$maximum_values,
  e_dot_dest = IEATools::template_cols$e_dot_dest,
  e_dot_machine = IEATools::template_cols$e_dot_machine,
  e_dot_machine_max = IEATools::template_cols$e_dot_max,
  e_dot_machine_tot = IEATools::template_cols$e_dot_machine_tot,
  e_dot_machine_perc = IEATools::template_cols$e_dot_machine_perc,
  e_dot_machine_max_perc = IEATools::template_cols$e_dot_machine_max_perc,
  .value = IEATools::template_cols$.values,
  supply = IEATools::ledger_sides$supply,
  consumption = IEATools::ledger_sides$consumption,
  eiou = IEATools::tfc_compare_flows$energy_industry_own_use,
  non_energy = IEATools::tfc_flows$non_energy_use
)

Arguments

.fu_allocations	A data frame containing a completed final-to-useful allocation template for final demand. This data frame can be obtained from the function load_fu_allocation_data().
tidy_specified_iea_data	A tidy data frame containing specified IEA data for the same country(ies) as .fu_allocations. Strictly speaking, this argument is needed only when .fu_allocations is a tidy data frame.
T_0	The dead state temperature (in kelvin) for calculation of heat exergy. Default is 298.15 kelvin.
sort_by	How to sort rows of eta_fu template. Options are (1) by "useful_energy_type" and (2) by "importance". "useful_energy_type" sorts first by md, light, ke, and heat, then by magnitude of energy flow into the machine. "importance" sorts by magnitude of energy flow into the machine only. Default is "useful_energy_type".
md	The name of the mechanical drive useful energy carrier in the eu_product column. Default is "MD".
light	The name of the light useful energy carrier in the eu_product column. Default is "Light".
ke	The name of the kinetic energy useful energy carrier in the eu_product column. Default is "KE".
heat	The string that identifies heat useful energy carriers in the eu_product column. Default is "TH" for "temperature heat".
perc	A string that gives the units for percent. Default is "⁠[%]⁠".
c_	The string prefix for allocation variables. Default is "C_".
c_perc	The string for generic allocation variables in percentage terms. Default is "⁠C [%]⁠".
c_ratio	The string for generic allocation variables in ratio terms. Default is "C".
year_for_maximum_values	The year assumed for the maximum_values column. Default is 0.
.row_order	the name of a metadata column used internally for determining row order. Default is ".row_order".
non_energy_eff	The efficiency for non-energy use, non-zero so we can swim upstream later. Default is 1e-6, or 0.0001%.
country, year, ledger_side, flow_aggregation_point, flow, product, e_dot, unit	See IEATools::iea_cols.
ef_product, machine, eu_product, eta_fu, phi_u, destination, quantity, maximum_values, e_dot_dest, e_dot_machine, e_dot_machine_max, e_dot_machine_tot, e_dot_machine_perc, e_dot_machine_max_perc	See IEATools::template_cols.
.value	The name of a temporary value column. Default is ".value".
supply, consumption	See IEATools::ledger_sides.
eiou	See IEATools::tfc_compare_flows.
non_energy	See IEATools::tfc_flows.

Details

The template produced by this function includes a column (e_dot_machine_perc_max) that contains the percentage of all energy flowing into each final-to-useful machines, thereby providing guidance to the analyst about the efficiencies that carry the most weight for the entire analysis. The template is sorted by metadata column groups then by the values in the e_dot_machine_perc_max column.

The analyst should complete the eta_fu and phi_u rows in this template. eta_fu is the final-to-useful energy efficiency of the machine. phi_u is the exergy-to-energy ratio for the useful product of machine as specified in the eu_product column.

Some of the eta_fu and phi_u values can be pre-calculated to assist the analyst, and the template produced by this function does just that. Any row specified with md (mechanical drive) as its eu_product will have its values for phi.u automatically filled with 1, because mechanical drive is work, which is pure exergy. Any row specified with eu_product being heat ("⁠*TH.xxx.u⁠") will have its values for phi.u automatically filled with the appropriate Carnot efficiency, 1 - T_0/xxx, where xxx is the temperature of the heat and u are the units for that temperature (one of "C", "K", "F", or "R" for ° Celsius, kelvin, ° Fahrenheit, or rankine, respectively). For heat rows, the value of argument T_0 (assumed to be in kelvin) is used to compute the Carnot efficiency for the phi.u rows. The default value for T_0 is ⁠298.15 K⁠ (⁠25 °C⁠).

Note that the rows labeled "⁠C_x [%]⁠" are formatted by default as percentage in the Excel file. When read, values are ratios, not percentages. I.e., the values read by this function are in the range 0 <= x <= 1, not 0 <= x <= 100. If any read values in the c_perc rows are outside of the range 0 <= x <= 1, an error is thrown.

Note that if .fu_allocations is void of any allocation information, an error is thrown.

Value

A data frame containing row-ordered blank template for final-to-useful machine efficiencies.

Examples

load_fu_allocation_data() %>% 
  eta_fu_template()

MatthewHeun/IEATools documentation built on Feb. 6, 2024, 3:29 p.m.