Class commodity | energyRt: Energy Systems Modeling with R

Class `commodity`

Commodity in the model is a broad notion of any a substance, material, energy, goods, or services that can be exchanges, produced, transformed to another commodity(-ies) by a technology or used for a final consumption in the model. Examples: electricity, coal, gas, steel, cement, CO2, CH4 etc.

COMM <- newCommodity("COMM")
class(COMM)

## [1] "commodity"
## attr(,"package")
## [1] "energyRt"

slotNames(COMM)

## [1] "name"        "description" "limtype"     "slice"       "unit"       
## [6] "emis"        "agg"         "misc"        ".S3Class"

The structure of a class can be printed with str() function.

show the structure

str(COMM)

## Formal class 'commodity' [package "energyRt"] with 9 slots
##   ..@ name       : chr "COMM"
##   ..@ description: chr(0) 
##   ..@ limtype    : Factor w/ 3 levels "FX","UP","LO": 3
##   ..@ slice      : chr(0) 
##   ..@ unit       : chr(0) 
##   ..@ emis       :'data.frame':  0 obs. of  3 variables:
##   .. ..$ comm: chr(0) 
##   .. ..$ unit: chr(0) 
##   .. ..$ emis: num(0) 
##   ..@ agg        :'data.frame':  0 obs. of  3 variables:
##   .. ..$ comm: chr(0) 
##   .. ..$ unit: num(0) 
##   .. ..$ agg : num(0) 
##   ..@ misc       : list()
##   ..@ .S3Class   : chr "commodity"

The commodity class has 9 slots. The first two name and description are the same in all energyRt classes, representing the name in the model sets (commodity in this case) and optional description. Names should follow the conversions used in GAMS, Python/Pyomo, Julia/JuMP, or GLPK/MathProg, as well as R. All the languages have a little bit different conventions regarding special characters and case sensitivity. The rule of thumb is a) case sensitivity and (b) avoiding special characters including whitespace (), period (.), hyphen or dash (-).
As an example, GAMS is not case sensitive, lower and upper case letters treated are considered the same characters. However R, and all other mentioned above mathematical languages use distinct (case-sensitive) names for sets, parameters, and variables. To avoid potential inconsistencies and bugs, it is recommended to use all names of the model elements in the same upper or lower case. Here in the manual we use upper case letters for all short names, used in the model sets, and avoid all special characters except underscore (_).
Commodities are not region-specific. They must be declared only once for all regions in the model. Though their appearance in different regions will depend on available processes (see Class supply section).

Limit type

The net quantity (balance) of every commodity in the model is constrained by lower (LO or \(\geq\)), upper (UP \(\leq\)), or equality (FX \(\equiv\)) constraint. Default value is LO meaning that the total net quantity of the commodity in the model must be equal or higher than the total amount of all intermediate and final demands, as indicated by equations ___. Changing the default value can be done using the limtype parameter in the newCommodity or update functions:

COMM@limtype

## [1] LO
## Levels: FX UP LO

COMM <- newCommodity("COMM", description = "Some commodity", limtype = "FX")
COMM@limtype

## [1] FX
## Levels: FX UP LO

COMM <- update(COMM, limtype = "UP")
COMM@limtype

## [1] UP
## Levels: FX UP LO

A direct assignment is also possible but not recommended to avoid potential mismatches between data types or allowed values. This type of direct assignment COMM@limtype <- "LO" will not work because class factor is expected as an input:

class(COMM@limtype)

## [1] "factor"

A proper way would be to create a factor with expected values and assign it:

COMM@limtype <- factor("LO", levels = c("FX", "UP", "LO"))
COMM@limtype

## [1] LO
## Levels: FX UP LO

However this process is more complicated and sensitive to potential changes in the package. Function newCommodity and method update will do the job. It is a generic recommendation to use such helper functions for assigning or updating values in all S4 classes.

Timeslice level

Depending on the model purpose, commodities can have different level of sub-annual granularity. For example, in an hourly model with 8760 sub-annual time slices (24 hours * 365 days) a balance between production and consumption of electricity should hold for every hour. However, it makes less sense to track other commodities, such as coal or natural gas, by hours. It might be enough if their balances can be hold on daily or even annual basis. This will significantly reduce dimensionality of the model without sacrificing any important for the study details.

ELC <- newCommodity("ELC", description = "Electricity", slice = "HOUR")
GAS <- newCommodity("GAS", description = "Natural gas", slice = "YDAY")
COA <- newCommodity("COA", description = "Hard coal", slice = "ANNUAL")

In this example generation and consumption of electricity (ELC) will be modeled for every hour of the model (8760 per year), natural gas (GAS) equations will have daily equations (365 per year), and coal (COA) will have no sub-annual resolution (1 per year). The default value of the slice is the lowest level of time-slices in the model. In this example, the lowest level will be “HOUR”. It will be assigned to all commodities by default if it is not set explicitly.

Unit

All commodities are normally measured and tracked in physical units such as Jules, watt-hours, kg or million tonnes, etc. This slot (@unit) is currently used for information only to document units of the data used in the model. They will play an important role in estimation of the efficiency parameters and costs in other classes of the model.

ELC <- newCommodity("ELC", description = "Electricity", slice = "HOUR", unit = "GWh")
GAS <- newCommodity("GAS", description = "Natural gas", slice = "YDAY", unit = "PJ")
IRON <- newCommodity("IRON", description = "Iron metal", slice = "ANNUAL", unit = "kt")

Aggregating type of commodity

In some cases it is handy from modeling perspectives to aggregate several commodities into one that can be further used for modeling policy or any other purposes. For example, there is a broad range of different type of greenhouse gases (GHG), such us carbon dioxide (CO2), methane (CH4), Nitrous oxide (N2O). From a policy perspective and for modeling purposes it might be helpful to combine all of them together into one GHG ‘commodity’ using global warming potential weights (100 years in this example). ¹

# Create different GHG commodities
CO2 <- newCommodity("CO2", description = "Carbon dioxide", unit = "kt")
CH4 <- newCommodity("CH4", description = "Methane", unit = "kt")
N2O <- newCommodity("CO2", description = "Nitrous oxide", unit = "kt")
# Now aggregate them into one
GHG <- newCommodity("GHG", description = "Greenhouse gases", unit = "kt",
                    agg = data.frame(
                      comm = c("CO2", "CH4", "CO2"),
                      unit = rep("kt", 3),
                      agg = c(1, 30, 273)
                    ))

The data.frame assigns aggregating (agg) values to each of the commodities. In the model such aggregating commodities will co-exist with the aggregated components as an additional measurement indicator. It can be consumed or produced by other processes the same way as other commodities.

GHG@agg

##   comm unit agg
## 1  CO2   kt   1
## 2  CH4   kt  30
## 3  CO2   kt 273

Combustion-related emissions

Emissions from fuels combustion can be modeled in two ways:
* explicitly adding to the technology with a combustion process (for example, a power plant);
* or linking emissions to the consumption of the commodity by technologies with an indicator that their process includes combustion.
For some emissions, like CO2, linking to energy use is straightforward. Therefore the information of related to the combustion process emissions can be stored in the commodities themselves. As usual, this information can be added to the commodity classes using newCommodity() or update functions.

COA <- newCommodity(
  name = "COA", 
  description = "Hard coal", 
  slice = "ANNUAL",
  unit = "PJ",
  emis = list(
    comm = "CO2",
    unit = "kt/PJ",
    emis = 95 # approximate
  ))
COA@emis

##   comm  unit emis
## 1  CO2 kt/PJ   95

GAS <- update(GAS, emis = data.frame(comm = "CO2", unit = "kt/PJ", emis = 60))
GAS@emis

##   comm  unit emis
## 1  CO2 kt/PJ   60

Data in table format, such as data.frame can be supplied to the functions as lists with length of all elements equal to the number of rows in the table, or using data.frame as demonstrated in the example above for GAS commodity.

https://en.wikipedia.org/wiki/Greenhouse_gas#Global_warming_potential ↩︎