Building blocks of an energyRt model
The new*() constructors, and the system around them
newSupply() — a domestic resource
newDemand() — what must be served
newImport() — a flow from outside
newTechnology() — the converter
Read the diagram left to right: inp → use → act → out.
Grouped input: co-firing
Two fuels feeding one boiler. The group is the thing with an efficiency; the members compete for share within it.
ECOFIRE <- newTechnology(
name = "ECOFIRE",
input = list(comm = c("COA", "BIO"),
unit = c("PJ", "PJ"),
group = c("FUEL", "FUEL"),
combustion = c(1, 1)),
output = list(comm = "ELC", unit = "PJ"),
group = data.frame(group = "FUEL",
desc = "Boiler fuel", unit = "PJ"),
geff = data.frame(group = "FUEL",
ginp2use = 0.38),
ceff = data.frame(comm = c("COA", "BIO"),
cinp2ginp = c(1, 1),
share.up = c(1, 0.30)),
cap2act = 31.536, olife = 30L
)
Grouped input: what the picture tells you
- The
ginpcolumn appears — it is absent for a single-fuel technology. FUELis a node: both fuels flow into it, and it carries the efficiency (ginp2use: 0.38).[0, 0.30]next to BIO is the share bound: biomass may supply at most 30 % of the boiler’s fuel.[0, 1]next to COA: coal may supply all of it.
. . .
Why group at all? Without a group each fuel would need its own efficiency and could not be constrained relative to the other. Shares are the point.
Multiple outputs: CHP
One activity, two products. cact2cout sets how much of each comes out per unit of activity.
ECHP <- newTechnology(
name = "ECHP",
desc = "Gas CHP: power and heat",
input = list(comm = "GAS", unit = "PJ",
combustion = 1),
output = list(comm = c("ELC", "HEA"),
unit = c("PJ", "PJ")),
ceff = data.frame(
comm = c("ELC", "HEA"),
cact2cout = c(1, 1.2) # heat/power ratio
),
cap2act = 31.536, olife = 25L
)Fixing both makes the ratio rigid; bound them instead for a flexible CHP.
Aux linked to capacity, activity, new capacity
ENUC <- newTechnology(
name = "ENUC",
desc = "Nuclear: land, water, steel",
input = list(comm = "NUC", unit = "PJ"),
output = list(comm = "ELC", unit = "PJ"),
aux = data.frame(
acomm = c("LAND", "WAT", "STEEL"),
unit = c("km2", "Mm3", "kt")),
aeff = data.frame(
acomm = c("LAND", "WAT", "STEEL"),
cap2ainp = c(0.5, NA, NA), # per GW held
act2ainp = c(NA, 0.02, NA), # per PJ made
ncap2ainp = c(NA, NA, 40) # per GW built
),
ceff = data.frame(comm = "NUC", cinp2use = 0.35),
cap2act = 31.536, olife = 50L
)
Why the distinction matters
Three physically different things, and the diagram labels each one:
cap2ainp: 0.50— land is occupied for as long as the plant stands, whether or not it runs.act2ainp: 0.02— cooling water is drawn only when it generates.ncap2ainp: 40.00— steel is consumed once, in the year the plant is built.
. . .
Pick the wrong one and the model is quietly wrong: steel on cap2ainp would re-buy the whole plant every year.
Aux as emissions
Pollutants that depend on the plant, not only the fuel, are auxiliary outputs scaled by fuel input:
ECOA_E <- newTechnology(
name = "ECOA_E",
desc = "Coal plant with NOx and SOx",
input = list(comm = "COA", unit = "PJ",
combustion = 1),
output = list(comm = "ELC", unit = "PJ"),
aux = data.frame(acomm = c("NOX", "SOX"),
unit = c("kt", "kt")),
aeff = data.frame(acomm = c("NOX", "SOX"),
comm = "COA",
cinp2aout = c(0.30, 0.45)),
ceff = data.frame(comm = "COA", cinp2use = 0.40),
cap2act = 31.536, olife = 30L
)Contrast with CO2, which sits on the commodity — every burner inherits it.
newStorage() — moving energy in time
seff— charge / discharge efficiency, andstgefffor standing losses.cap2stg— how many hours of storage one unit of capacity buys.- Only meaningful with sub-annual slices — see the Time and storage chapter.
newTrade() — moving energy in space
TBD_ELC <- newTrade(
name = "TBD_ELC",
desc = "Interregional power line",
commodity = "ELC",
routes = data.frame( # which links exist
src = c("R1", "R2"),
dst = c("R2", "R1")
),
trade = data.frame( # their parameters
src = c("R1", "R2"),
dst = c("R2", "R1"),
teff = 0.95 # line losses
),
invcost = list(invcost = 1500)
)Two slots, two jobs: routes declares the links, trade parameterises them. One is not derived from the other — a route with no parameters is unconstrained, and parameters for an undeclared route are ignored.
Trade is directional, so a bidirectional line is two rows in each. Note it has no region — the regions are src and dst.
Ready-made calendars
Eight ship with the package — the fastest way to change a model’s time resolution is to swap one in.
[1] "season_dn" "d365"
[3] "utopia_annual" "utopia_seasons"
[5] "utopia_s4h24" "utopia_m12h24"
[7] "d365_h24" "d365_h24_subset_1day_per_month"
Each rectangle is one slice, sized by its share of the year. ANNUAL sits on top; finer timeframes stack below.
Sampled vs full calendars
A sampled calendar keeps a representative subset of slices and declares what fraction of the year it covers:
slices year_fraction
sampled 288 0.0329
full 8760 1.0000One day per month at hourly resolution — 288 slices instead of 8760, about 3.3 % of the year.
year_fraction is what keeps annual quantities honest when only part of the year is modelled.
Passing reference = lays out the full structure and fills only the slices the sampled calendar declares.
Horizons: the years
start mid end
<num> <num> <num>
1: 2025 2025 2025
2: 2026 2028 2030
3: 2031 2033 2035
4: 2036 2038 2040
5: 2041 2043 2045
6: 2046 2048 2050period— the full span of years.intervals— either lengths (as here) or adata.framewithstart,mid,end.- The first interval is forced to a single base year (
force_BY_interval_to_1_year = TRUE). - The mid is the milestone year the solver actually optimises.
Where the milestone year sits
The same intervals, three placements of the mid-year — the dashed line:
It matters because costs and demands are evaluated at the mid. mid_is_end puts the decision at the end of each period — the convention used in the models we build here. Choose once, and keep it consistent across scenarios you compare.
Ready-made horizons
[1] "Y2020_2060_by_5" "Y2020_2060_by_10" "Y2020" "Y2030"
[5] "Y2040" "Y2050" "Y2060" "Y2070" 
Single-year horizons (Y2030, Y2050, …) are useful for a fast structural check: build the model, solve one year, confirm it is feasible before paying for the full run.
Carbon and other emissions
Emission factors ride on the fuel, so every technology burning it inherits them:
The factor only fires where the consuming technology declares combustion = 1 on that input.
There is no separate carbon-content slot — @emis is the single mechanism, and it generalises to any emitted species.
Roadmap planned
Physical properties — mass, volume, heating value — are not slots today, and @misc is the documented place to park them meanwhile. Adding them as first-class, unit-aware slots is a candidate for a future release.
draw() reads the whole grid
Ask for one cell and you get it, with the other vintages behind it as ghosts:
The faded stack is the vintage marginal through the selected cell — the cells sharing its cluster. Earlier vintages sit down-left, later ones up-right, so the depth of the stack is the technology’s history.
Clusters: rail, deck, or neither
cluster_style changes how the sibling grades are rendered around the selected cell.
"rail" (default)
"deck"
"none"
Cosmetic, not semantic — pick whichever makes the point on your slide.
Seeing every cell at once
Pass "all" to facet a dimension instead of selecting from it:
max_facets = 24L guards the obvious accident — a 4-vintage × 11-region technology asked to draw everything.
Anchors in, series out
You supply anchor years; the pipeline fills the rest:
getData() returns both views — the given rows, and the interpolated series:
Mixes and comparisons
getMix() is the tidy extractor behind the scenario plot. Given a named list it row-binds with a scenario column, so any ggplot2 comparison is a facet_wrap(~ scenario) away.
autoplot() itself takes a single scenario — build multi-scenario charts from getMix().
