2 Installing energyRt

energyRt formulates an optimization model once and hands it to one of several mathematical-programming backends. You only need one of them to get started; you can add more later and cross-check results between them.

Important

Every command below is shown for you to copy into your own R session. This page renders without executing anything — no packages are installed while the book builds.

2.1 Prerequisites

You need R (≥ 4.3) and, recommended, RStudio as the IDE for the training. If you are setting up R for the first time — or want the introductory reading, key packages, and cheatsheets — start with R: setup and resources.

Download and run the installer from CRAN.

Install the .pkg from CRAN, or with Homebrew:

brew install --cask r

Install a current R from the CRAN apt repository (see the CRAN Ubuntu guide):

sudo apt update
sudo apt install --no-install-recommends r-base

2.2 Quick install (recommended)

One line installs everything — pak, the system-library guidance, all dependencies, and energyRt itself. Paste this into R:

source("https://raw.githubusercontent.com/optimal2050/energyRt/master/inst/install.R")
# install_energyRt()                  # released version (default branch)
install_energyRt(branch = "dev")      # development version -- use this for the course

On Linux it prints the exact sudo command for any missing system libraries (it never runs sudo itself) — run that, then re-run install_energyRt().

For the training, install the development version with install_energyRt(branch = "dev"): it carries the features the exercises rely on. The exercises require energyRt ≥ 0.85 — the top of each chapter runs source("R/workshop-model.R"), which checks your installed version and warns, before any exercise runs, if it is too old.

0.85 is not an arbitrary floor. Several chapters use things that arrived in it:

the three-role storage — @input, @storage and @output may each name a different commodity, which is what lets a vehicle be one object in Chapter 7 rather than a storage plus two technologies;
storage_duration(), which splits a storage level into how long the energy actually sits there;
a storage capacity read as a rate (cap2act), so cap.up = 7 means 7 kW on any calendar;
draw() and autoplot() fixes for converted models that span many regions, used throughout Chapter 8 and Chapter 9.

Once it finishes, verify your setup in a fresh session:

library(energyRt)
en_setup()

en_setup() reports your OS, the system libraries to install (Linux), and the full dependency status table.

2.3 Step-by-step install (if the quick install fails)

Prefer to install by hand, or need to debug a failure? Install pak first — the installer used throughout this guide:

install.packages("pak")

2.3.1 System libraries (Linux)

On Linux, energyRt’s dependencies compile from source and need a few system libraries. pak lists exactly which ones — install the reported apt packages first so the R installs don’t fail midway:

pak::pkg_sysreqs("optimal2050/energyRt")   # lists the apt packages

# typical set on Debian/Ubuntu:
sudo apt install libcurl4-openssl-dev libssl-dev libxml2-dev

2.3.2 R package dependencies

Install energyRt’s CRAN imports up front — one by one, so any failure is isolated and reported by name. Doing this first makes the energyRt install itself quick and reliable, and avoids the Linux error dependencies '...' are not available for package 'energyRt'.

# energyRt's direct CRAN imports (base packages are omitted):
deps <- c(
  "generics", "data.table", "DBI", "RSQLite", "tibble", "tidyr", "dplyr",
  "rlang", "stringr", "lubridate", "purrr", "arrow", "progressr", "tictoc",
  "cli", "zoo", "registry", "options", "glue", "plyr",
  # suggested -- plots and reports (optional but recommended):
  "ggplot2", "patchwork", "knitr", "rmarkdown", "tinytex", "sf",
  # optional -- the process-designer GUI (process_designer()):
  "shiny", "DT",
  # optional -- remote solving on NEOS (see the NEOS section below):
  "httr2", "xml2", "base64enc"
)

failed <- character(0)
for (pkg in deps) {
  ok <- tryCatch(
    {
      pak::pkg_install(pkg, ask = FALSE)
      message("  [ok]   ", pkg)
      TRUE
    },
    error = function(e) {
      message("  [FAIL] ", pkg, ": ", conditionMessage(e))
      FALSE
    }
  )
  if (!ok) failed <- c(failed, pkg)
}

if (length(failed) == 0) {
  message("All dependencies installed — you're ready to install energyRt.")
} else {
  message("Failed packages: ", paste(failed, collapse = ", "))
  message("Install their system libraries (above), then re-run.")
}

2.3.3 Install energyRt

With the dependencies in place, installing energyRt is a quick one-liner:

pak::pkg_install("optimal2050/energyRt@dev")

# or, with remotes:
# install.packages("remotes")
# remotes::install_github("optimal2050/energyRt")

geoscales — optional, and not published yet

geoscales is the spatial companion in the same stack: nested sets of regions, conversion between spatial resolutions, and maps of results. energyRt lists it as a suggested package and works fully without it — nothing in this training needs it.

It is not on CRAN and is still pre-release, so leave it out for now. Once it is published you will be able to install it with:

# not yet available -- do not run
# pak::pkg_install("optimal2050/geoscales")

2.4 Check what you already have

library(energyRt)
en_check_dependencies()   # solver backends: GLPK / Julia / Python / GAMS / GDX
en_check_packages()       # R packages, training extras, LaTeX engine

en_check_dependencies() prints a status table — for each backend: installed?, version, path, and a hint for what to do next — and tells you whether at least one solver is ready. Each backend also has its own detector, e.g. en_check_glpk(), en_check_julia(), en_check_python(), en_check_pyomo(), en_check_gams().

en_check_packages() covers the rest of the course toolkit: energyRt’s own R dependencies, the plotting/reporting extras (ggplot2, patchwork, knitr, rmarkdown, tinytex, sf), and the external tools they need, such as a LaTeX engine for PDF reports. (en_setup() runs both checks for you.)

2.5 Choose a backend

Backend	Software to install	License	Notes
GLPK	`glpsol` executable	open-source	Easiest to install; slow on very large models. Used in this training.
NEOS	nothing — just an email address	free for academic use	Solves remotely on CPLEX/CBC. Needs `httr2`, `xml2`; see the terms below.
Julia / JuMP	Julia + `JuMP`, `HiGHS`	open-source	Fast (HiGHS barrier); recommended for large models.
Python / Pyomo	Python + `pyomo` + a solver (CBC)	open-source	Convenient if you already use conda.
GAMS	GAMS distribution	proprietary	Needs a license; also enables GDX I/O.

For the training we use GLPK — it is open-source and the quickest to set up. The rest are optional. NEOS is worth knowing about even if you install nothing else: it needs no solver on your machine at all. The remaining three are covered below when enabled.

2.6 GLPK (recommended for the training)

Install the glpsol executable.

Nothing to install. glpsol.exe already ships with Rtools 4.5 — which you already have, since Rtools is required to build energyRt from source. It lives at C:/rtools45/x86_64-w64-mingw32.static.posix/bin/glpsol.exe.

brew install glpk

sudo apt install glpk-utils

Then confirm energyRt can find it. Set the path only if glpsol is not already detected — on macOS/Ubuntu the package managers put it on your PATH automatically:

# Windows (Rtools 4.5): point at the bundled glpsol if not auto-detected.
# On macOS/Ubuntu this is usually unnecessary.
set_glpk_path("C:/rtools45/x86_64-w64-mingw32.static.posix/bin")
en_check_glpk()

2.7 NEOS (remote solve, nothing to install)

The NEOS Server runs commercial solvers — CPLEX, Gurobi, MOSEK, Xpress — free of charge for academic and non-commercial use. energyRt can hand your model to it, so you can solve on CPLEX without installing a solver at all.

Two routes, differing only in what they need on your machine:

Solver option	Needs locally
`neos_gams_cplex`, `neos_gams_cplex_barrier`, `neos_gams_cbc`	nothing. energyRt writes the GAMS model with the data inlined as text and submits that — no GAMS install.
`neos_pyomo_cplex`, `neos_pyomo_cplex_barrier`, `neos_pyomo_cbc`	Python + Pyomo. The model is built locally; only the solve is dispatched to NEOS, so no commercial solver is needed.

Install the three R packages the client uses, set the email address NEOS requires on every job, and check the server is reachable:

install.packages(c("httr2", "xml2", "base64enc"))

library(energyRt)
set_neos_email("you@example.com")   # stored as an option *and* as NEOS_EMAIL
neos_ping()                         # TRUE if the server answers

Then pick a NEOS solver like any other and solve as usual:

set_default_solver(solver_options$neos_gams_cplex)

Read the NEOS terms before submitting

Academic and non-commercial use only for the commercial solvers.
Jobs are public and stored on the server — never submit confidential data.
Roughly 3 GB and 8 hours per job.
Cite NEOS in publications that use results obtained through it.

2.8 Install the library layer

Once your runtime(s) are present, install the packages each backend needs in one call:

en_install_deps()   # detects runtimes, then installs the safe library layer

en_install_deps() runs a dependency check, installs only the library layer for the runtimes it finds (skipping — with a warning — any that are missing), and re-checks at the end.

Manual alternative (if en_install_deps() fails)

en_install_deps() bundles the R, Julia, and Python layers — run them by hand:

R layer — the GAMS GDX bridge (not on CRAN) plus optional I/O helpers:

pak::pkg_install("lolow/gdxtools")   # or remotes::install_github("lolow/gdxtools")
install.packages(c("jsonlite", "readxl", "openxlsx"))

Julia and Python layers — use the manual blocks in the Julia / JuMP and Python / Pyomo sections above (enable them with the show-julia / show-python header params).

2.9 Verify end-to-end

Re-check (everything you installed should now be green), choose a default solver, and solve a tiny model:

en_check_dependencies(solver_pkgs = TRUE)
set_default_solver(solver_options$glpk)   # or neos_gams_cplex, julia_highs_barrier, ...

# a minimal model solve confirms the full toolchain works
# (see the modeling chapters for assembling a model)

If two or more backends are installed, solving the same scenario with each and comparing objectives is the strongest check that your setup is correct.

2.10 Save your settings

Every set_*() call above — set_glpk_path(), set_python_path(), set_gams_path(), set_default_solver() — lasts only for the current R session. Rather than repeat them, write them to a configuration file once:

en_config_write()    # saves every option that differs from the default
en_config_show()     # what is in effect, and where each value came from

energyRt reads the file when the package loads, so the next session starts with your solver paths already in place. en_config_show() is the first thing to run whenever a solver “cannot be found” — it prints each option with a tag saying whether the value came from the config file, an environment variable, an R option, or the package default.

Settings resolve in this order, first match wins:

Priority	Source	Set it with
1	R option	`options(en.gams_path = "...")`
2	Environment variable	`ENERGYRT_GAMS_PATH`
3	Project config, `./.energyRt.yml`	`en_config_write(global = FALSE)`
4	User config	`en_config_write()`
5	Package default	—

Ask energyRt where the user file lives rather than guessing — the location follows the R standard for user configuration and differs by platform:

en_config_path()          # user-wide
en_config_path(FALSE)     # project-local, ./.energyRt.yml

The project file is worth knowing about for coursework: dropping an .energyRt.yml next to a project pins settings for that project alone (a scenarios directory, say) without touching your global setup.

Upgrading from an older energyRt

Older versions kept settings in ~/.energyRt.R — an R script that was executed at startup — and later in ~/.energyRt/config.yml. Both still work, but a package may not write to your home directory, so en_config_write() now saves to the standard R user-configuration directory instead.

If you have either old file, just run en_config_write() once: your current settings are saved to the new location and the old files are renamed to .bak. That last step matters — ~/.energyRt.R is executed after the config file is applied, so while it exists it silently overrides your new settings.

2.11 Trouble?

If something will not install, post the error in the course Q&A thread — include your OS, the output of sessionInfo(), and the message you got. Install problems are the most common thing we help with, and someone else has usually hit the same one.