Package index • energyRt

Model components

The S4 classes a model is made of. Each is built by its new*() constructor below and carries its data in slots.

class-calendar: An S4 class to represent sub-annual time resolution structure.
class-commodity: An S4 class to represent a commodity
class-config: An S4 class to represent default model configuration.
class-constraint class-summand summand-class experimental: An S4 class to represent a custom constraint.
class-costs experimental: An S4 class to add costs to objective function
class-demand: An S4 class to declare a demand in the model
class-export: An S4 class to represent commodity export to the rest of the world.
class-horizon: An S4 class to represent model/scenario planning horizon with intervals (year-steps)
class-import: An S4 class to represent commodity import from the rest of the world.
class-model model: An S4 class to represent model
class-modInp: An S4 class to represent model input
class-modOut: An S4 class to store results of a solved scenario
class-parameter: An S4 class to specify the model set or parameter
class-repository: An S4 class to store the model objects.
class-scenario scenario: An S4 class to represent scenario, an interpolated and/or solved model.
class-settings: An S4 class to represent scenario settings
class-technology: An S4 class to represent technology
class-trade: An S4 class to represent inter-regional trade
class-variable: An S4 class to specify a model variable
class-weather: S4 class to represent weather factors
storage-class: An S4 class to represent storage type of technological process.
subsidy-class: An S4 class to represent a commodity subsidy
tax-class: An S4 class to represent a commodity tax
supply-class: An S4 class to represent a supply of a commodity

Building a model

Constructors for the objects above, the repository that holds them, and the model that binds them to a calendar, regions and a horizon.

newModel() setHorizon(<model>) getHorizon(<model>): Create new model object
newRepository(): A constructor for the repository class
newCommodity(): Create new commodity object
newTechnology() update(<technology>): Create a new "technology" object.
newStorage(): Create new storage object
newSupply(): Constructor for supply object.
newDemand() update(<demand>): Create new demand object
newTrade(): Create new trade object
newACLine() experimental: Create an AC transmission line
newDCLink() experimental: Create a DC transmission link
newImport(): Create new export object
newExport() update(<export>): Create new export object
newWeather() update(<weather>): Create new weather object
newConstraint() newConstraintS(): Create constraint object to add custom constraints to the model.
newCosts(): Create new costs object
newTax(): Create a new tax object
newSub(): Create a new subsidy object
newScenario(): Generate a new scenario object
newRegistry() load_registry() save_registry() add_to_registry() add(<en_registry>) find_in_registry() refresh_registry(): Project registry of models, scenarios, and runs
add(<repository>) add(<model>): Add an object to the model's repository
update(<supply>) update(<storage>) update(<trade>) update(<import>): Update supply object
asSupplyCurve() asImportCurve() asExportCurve() experimental: Stepped supply, export and import curves
lossTranches() experimental: Loss tranches for a transmission line
combine_vintages(): Combine per-vintage technology objects into one vintaged technology

Time resolution

Calendars and horizons. The shipped calendars catalog is generated with the sibling timescales package; newCalendar() builds your own.

newCalendar(): Generate a new calendar object from
newHorizon() update(<horizon>) setHorizon(<config>) update(<config>): Create a new object of class 'horizon'
calendars: Example calendars
horizons: Example planning horizons
tsl_sets tsl_levels: Sets of the common formats with structure
make_timetable(): Create timetable of time-timeslices from given structure as a list
autoplot(<calendar>): Visualize a Calendar object
autoplot(<horizon>): Visualize a Horizon object
year_label(): Display labels of the model's milestone years

Space resolution

Multi-level regions. A commodity declares the level it balances on, and coarse balances roll up without a trade route for every pair.

setGeoscale(<config>) getGeoscale(<config>) setGeoscale(<model>) getGeoscale(<model>) setGeoscale(<scenario>) getGeoscale(<scenario>) getCalendar(<config>) getCalendar(<model>) getCalendar(<scenario>): Attach or read a model's geoscale
get_process_groups(): Technologies that may be merged into one clustered object
process_cluster_sweep(): Sweep a technology family's clusterings, to choose k by looking
model_clusters(): The clustering behind an aggregated model
check_geoscale_regions(): Check a geoscale against the model's declared regions
plot_geoscale(): Draw a model's geoscale
get_region(): Collect the regions an object operates in
subset_model_regions(): Restrict a model to a region subset
aggregate_model_regions(): Aggregate a model to a coarser set of regions

Process specifications

Portable YAML/JSON process definitions, and the interactive designer.

process_from_spec(): Build a process object from a spec
process_to_spec(): Export a process object as a spec list
process_spec_code(): The constructor call equivalent to a process spec, as text
process_spec_issues(): Validate a process spec and report issues
read_process_spec(): Read and validate a process spec
process_designer(): Launch the process designer
read_technology_xlsx(): Read technology object(s) from an Excel workbook
write_technology_xlsx(): Write technology object(s) to an Excel workbook

Interpolating and solving

The core pipeline. solve_model() does the whole sequence; the separate verbs let a stage be inspected or re-run.

interpolate_model() interpolate(<model>): Interpolate a model into a solver-ready scenario
solve_model() solve_scenario() solve(<model>,<character>): Solve a model or an interpolated scenario
write_script() write_sc(): Write scenario object as a Python, Julia, GAMS, or MathProg script with data files to a directory
read_solution() read(<scenario>): Read a solved run's solution into a scenario
read_sequence(): Rebuild a solve sequence from the variants on disk
with_solver_log(): Send the solver's progress log to a file

multimod

Converting an interpolated scenario into a multimod model, which can then be rendered to any backend multimod supports or assembled straight into a matrix and solved. multimod is a suggested package; these are no-ops without it.

as_multimod(<scenario>): Build a multimod model from an interpolated scenario
multimod_import_data(): Import energyRt scenario data into a multimod model
multimod_import_log(): Get data import log from model
multimod_unmatched(): Show unmatched elements
multimod_from_energyRt(): Build a multimod model from an interpolated energyRt scenario

Solver configuration

Choosing a backend and pointing energyRt at it.

get_default_solver() set_default_solver(): Default solver
set_solver_path() get_solver_path(): Set or get the path to a solver toolchain
set_gams_path() get_gams_path() set_gdxlib_path() get_gdxlib_path() set_glpk_path() get_glpk_path() set_julia_path() get_julia_path() set_python_path() get_python_path(): Set GAMS and GDX library directory
get_exchange_format() set_exchange_format() get_exchange_compression() set_exchange_compression() get_exchange_compression_level() set_exchange_compression_level(): Solver data-exchange options
get_storage_format() set_storage_format() get_storage_compression() set_storage_compression() get_storage_compression_level() set_storage_compression_level(): On-disk table storage options

Remote and cloud solving

Solving where you are not: the NEOS server for GAMS/CPLEX without a local licence, and GPU/cloud execution for models too large for a laptop.

neos_ping() neos_list_solvers(): NEOS Server client (query the remote solver service)
get_neos_email() set_neos_email(): NEOS submission email
get_hf_token() set_hf_token(): Hugging Face access token

Solve drivers

Sequences of solves — myopic foresight, sampled calendars, region-by-region decomposition, and guided target-seeking — with their primitives.

solve_myopic(): Solve a model sequentially (myopic foresight)
solve_by_sample(): Solve a model on samples of its calendar
solve_by_region(): Solve a model region by region
solve_guided(): Solve a model with guided perfect foresight
horizon_windows(): Split a horizon into sequential solve windows
solution_ledger(): Extract the carry-forward ledger from a solved scenario
apply_ledger(): Apply a carry ledger to a model
myopic_objective(): Globally discounted total cost of a myopic sequence
calendar_samples(): Build a calendar-sample specification
sample_summary(): Summarise an ensemble across samples
boundary_window(): A generic boundary trade window
guided_windows(): Two-milestone windows for a guided solve
guided_gap(): Cost of the guidance
solution_targets(): Capacity targets from a solved scenario
apply_targets(): Impose capacity targets on a model

Reading results

Getting tidy data out of a solved scenario.

getData(): Extract data from energyRt objects
get_variable(): Get one solved variable from a scenario
get_weather(): Collect the weather objects an object refers to
getMix(): Extract a tidy mix (generation, capacity, fuel) from a solved scenario
getObject(): Retrieve model objects from a repository, model or scenario
getScenario() getModel() getRepository() getDataset() open_project(): Access registered scenarios, models, repositories, and datasets by name
getVariants(): Process variants of a solved (or interpolated) scenario
variantSummary(): Summarise a result variable across technology variants
findData(): Performs search for available data in scenario object.
find_in_model(): Find where value(s) are stored across a model's objects
findDuplicates(): Function to find duplicated values in interpolated scenario.
size(): Size of an object
model_size(): Size estimate of an interpolated scenario and the result of folding

Levelized cost

Pricing a technology a-priori (screening LCOE) or ex-post from a solved scenario.

levcost(): Levelized cost of commodity production
tech_share_frontier(): Extract feasible share ranges for grouped inputs/outputs
plot_share_frontier(): Plot feasible share-mix diagram for technology inputs/outputs
clear_levcost_cache(): Clear cached levcost results
storage_duration(): Split a storage level into duration bands

Reporting

Rendered datasheets for models, scenarios and processes.

report(): Generate a summary report for an energyRt object
report_html(): Generate an HTML report for an energyRt object
report_pdf(): Generate a PDF report for an energyRt object
report_docx(): Generate a Word report for an energyRt object
report_tex(): Generate a LaTeX report for an energyRt object
report_templates(): List the available report templates
report_output() report_setup() report_layout() report_esc() report_fmt_val() report_img() report_img_row() report_pagebreak() report_fig_height() report_plot_png() report_fig() report_sec() report_tbl() report_css() report_header(): Report template helpers
clear_report_cache(): Delete rendered reports
set_reports_path() get_reports_path() set_levcost_cache_path() get_levcost_cache_path(): Report and levcost output locations

Comparison

Compare scenarios’ solved results (or runs of one scenario), models’ declarations, and interpolated model inputs.

compare_inputs() print(<inputs_cmp>): Compare two scenarios' model inputs
compare_interp_settings(): Compare interpolation settings (size & build time) for a model
compare_models() print(<models_cmp>): Compare two models' contents
compare_scenarios() print(<scenarios_cmp>) autoplot(<scenarios_cmp>) plot(<scenarios_cmp>): Compare solved scenarios (or runs of one scenario)
compare_solve_settings(): Compare interpolation settings AND solvers for a model

Visualisation

Plots and diagrams.

autoplot(<commodity>): Visualize a Commodity object
autoplot(<levcost_variants>): Compare levelized cost across a technology's variant grid
autoplot(<tax>) autoplot(<subsidy>) autoplot(<constraint>): Plot a tax, subsidy or user constraint over years
autoplot(<supply>) autoplot(<import>) autoplot(<export>) autoplot(<technology>) autoplot(<storage>): Visualize a process object over years
autoplot(<scenario>): Plot mixes from a solved scenario
compare_scenarios() print(<scenarios_cmp>) autoplot(<scenarios_cmp>) plot(<scenarios_cmp>): Compare solved scenarios (or runs of one scenario)
autoplot(<calendar>): Visualize a Calendar object
autoplot(<horizon>): Visualize a Horizon object
plot_trade_map() autoplot(<trade>): Map inter-regional trade routes
draw() draw.technology(): Draw a schematic representation of a process
plot_heatmap(): Heatmap of timeslice-indexed values over a calendar
plot_map(): Map model results by region
plot_trade_network(): Plot trade as a network: capacities and flows between regions
object_image(): Image or icon attached to a model object
theme_energyRt(): energyRt's default ggplot theme
ghost_options(): Geometry of the faded "ghost" vintages behind a drawn technology
design(): Generate an R script that recreates an energyRt object

Saving and loading

Models, repositories and scenarios on disk — Arrow-backed, so results larger than memory stay readable.

save_model() load_model(): Save a model to / load a model from the model store
save_repository() load_repository(): Save a repository to / load a repository from the repository store
save_scenario(): Save scenario object on disk in parquet format using arrow package.
load_scenario() load_scenarios(): Load scenario (in progress)
seal_model() unseal_model() seal_repository() unseal_repository() seal_dataset() unseal_dataset() seal_scenario() unseal_scenario() mark_delete() unmark_delete() delete_marked(): Seal and unseal store entries; mark them for deletion
model_hash() object_hash(): Content hash of a model
repository_hash(): Content hash of a repository
dataset_hash() save_dataset() load_dataset(): Content hash of a dataset payload
isInMemory(): Is object stored in memory?
isOnDisk(): Is object stored on disk?
obj2mem(): Loads objects from disk to memory
materialize_weather(): Materialize one weather transform

Scenario runs and artifacts

What a solved scenario leaves on disk, which solution to keep, and how to hand a folder to somebody else.

scenario_runs() scenario_run_info() drop_scenario_run(): List, inspect, and drop a scenario's runs
scenario_solutions(): What solutions does this scenario have, and which is worth importing?
scenario_artifacts(): Solver artifacts of a stored scenario
import_solution(): Import a run's solution and make it stick
promote_solution(): Make a run's solution the scenario's own
drop_solver_outputs(): Delete the regenerable part of a solve
upgrade_scenario_layout(): Upgrade a scenario folder to the current on-disk layout
store_dependents(): What depends on a stored model, repository or dataset
strip_user_info(): Remove machine and user information from a stored scenario
prepare_for_sharing(): Prepare a stored scenario for sharing
getScenario() getModel() getRepository() getDataset() open_project(): Access registered scenarios, models, repositories, and datasets by name
getObject(): Retrieve model objects from a repository, model or scenario
newRegistry() load_registry() save_registry() add_to_registry() add(<en_registry>) find_in_registry() refresh_registry(): Project registry of models, scenarios, and runs
set_registry_file() get_registry_file() set_models_path() get_models_path() set_repositories_path() get_repositories_path() set_datasets_path() get_datasets_path(): Registry file and model store locations
dataset_hash() save_dataset() load_dataset(): Content hash of a dataset payload
seal_model() unseal_model() seal_repository() unseal_repository() seal_dataset() unseal_dataset() seal_scenario() unseal_scenario() mark_delete() unmark_delete() delete_marked(): Seal and unseal store entries; mark them for deletion

Validation and diagnostics

Checks on a model’s inputs, on an interpolated scenario, and on a solved one. verify_solution() re-derives the model’s identities from the results.

validate_scenario_parameters(): Validate interpolated scenario parameters
verify_solution(): Verify accounting identities of a solved scenario
verify_checks(): Checks available to verify_solution()
audit_coefficients(): Coefficient-range audit of a written model
en_check_glpk() en_check_julia() en_check_python() en_check_pyomo() en_check_gams() en_check_gdx() en_check_julia_pkgs() en_check_dependencies(): Detect external solver software and dependencies
en_check_packages(): Check R package and external-tool dependencies
trim_parameters(): Trim numeric/bounds parameters to the domain of the maps that index them
update_parameter(): Update parameter in the scenario by adding data to it

Datasets

Data bundled with the package for the examples and articles.

topia: The TOPIA reference dataset
topia_profile(): Synthetic input shapes on a calendar (deterministic)
topia_profiles(): TOPIA input profiles (deterministic)
model_structure: Catalogue of the model vocabulary
prefix prefix_longname: Unit prefix multipliers
solver_options: Solver presets
vre_cf: Hourly wind and solar capacity factors, one site, one year
vre_storage_duration: Duration bands of a full-year battery, precomputed

Setup and environment

Installing and checking the solver toolchains.

en_setup(): Set up energyRt after installation
en_install_deps(): Install the energyRt dependency library layer
en_install_julia_pkgs(): Install Julia packages
en_install_python_deps(): Install Python/Pyomo dependencies (deprecated)
en_config_path() en_config_read() en_config_write(): The energyRt configuration file
en_config_show(): Show the effective energyRt configuration

Options and paths

Package options, and where energyRt reads and writes.

energyRt-options: energyRt Options
set_option() get_option(): Get or set an energyRt option
set_path_builder() get_path_builder(): Override how folder names are derived
set_scenarios_path() get_scenarios_path(): Set or get the directory with scenarios
set_registry_file() get_registry_file() set_models_path() get_models_path() set_repositories_path() get_repositories_path() set_datasets_path() get_datasets_path(): Registry file and model store locations
set_log_file() get_log_file() set_profile_dir() get_profile_dir() read_log(): Read the operation log
set_progress_bar() show_progress_bar(): Switch on/off and select/customize progress bar
get_default_value(): Return default value for one, several, or all parameters
isVerbose() isDebug(): Verbosity and debug level

Utilities

Small helpers, conversions and accessors.

get_process_aux(): Get auxiliary commodities for each process
get_process_class(): Get class of processes
get_process_comm(): Commodities associated with a processes
get_process_groups(): Technologies that may be merged into one clustered object
get_process_inputs(): Get inputs of processes
get_process_invest_window(): Start and end years for process by region
get_process_outputs(): Get output commodities for each process
get_process_region(): Get regions for each process
get_process_stored(): Stored commodities of each process
get_process_timeframe(): Get operational timeframe of processes
getUnits(<commodity>) getUnits(<technology>) getUnits(<supply>) getUnits(<demand>) getUnits(<import>) getUnits(<export>) getUnits(<storage>): Get parameter units for energyRt class objects
commodity_properties(): Recognised commodity properties
commodity_property(): Physical property of a commodity
convert_data: Basic units conversion database for convert methods
convert(<character>) convert(<numeric>) add_to_convert(<character>,<character>,<numeric>): Convert units
renameSets(): Rename data.frame columns of list of data.frames.
revalueSets(): Replace specified values with new values in factor or character columns of a data.frame.
register_weather_transform(): Register a weather transform for the session
print(): Print methods for the energyRt classes
summary(<model>) summary(<scenario>): Summarize a model or scenario