Variant management with API

In antaresEditObject: Edit an 'Antares' Simulation

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = TRUE
)

 # CRAN limite CPU usage
data.table::setDTthreads(2)
library(antaresEditObject)

The API behind Antares Web comes with a Variant Manager allowing to edit a study. Functions from {antaresEditObject} can be used send commands to the API or generate commands to be sent to the API.

Path to simulation and variant creation

First we need to declare which study we are going to use:

antaresRead::setSimulationPathAPI(
  host = "http://localhost:8080",
  study_id = "70a08fae-da67-444a-b2ed-df4c0f956a31", 
  token = NULL, 
  simulation = "input"
)

Then we can create a new variant from our study or use one created through the web interface:

# Create new variant
createVariant("variant-1")

# use an existing one
useVariant("variant-2")

A third option is to mock the web server behavior, it can be useful if we are offline or if we just want to generate API commands to be use afterwards:

mockSimulationAPI()

API editing mode

{antaresEditObject} allow to use two modes to use the API:

• async: record all API calls, but nothing is sent to the server, commands can be retrieved after calling {antaresEditObject}'s functions
• sync: send query to the API each time a function is used (commands are also internally recorded if needed).

setAPImode("async")
# or
setAPImode("sync")

Default is to used async mode. When using mockSimulationAPI() only async mode is available.

Get / export variant management commands

Variant commands generated after calling functions like createArea(), createLink(), ... can be retrieved at all time with:

getVariantCommands()

Last command generated can be viewed with:

getVariantCommands(last = TRUE)
# or use a numeric to get the last N commands
getVariantCommands(last = 3)

You can also filter type of commands with:

getVariantCommands(actions = "create_area")

Export commands with:

writeVariantCommands("path/to/commands.json")

Usage example

Below are listed all functions from {antaresEditObject} that can be used with the API. These functions will include the following badge in their documentation:

Create an area

Create a new area:

createArea(name = "area01")
createArea(name = "area02")
createArea(name = "area03")
getVariantCommands()

Create a second area with some default parameters:

createArea(
  name = "area04", 
  filtering = filteringOptions(filter_synthesis = c("hourly", "daily"))
)
getVariantCommands()

You can also edit an area or remove it:

createArea(name = "area000")
# editArea(name = "area000", ...)
removeArea(name = "area000")
getVariantCommands(last = TRUE)

Create a link

Create a new link between two areas like this:

createLink(from = "area01", to = "area02")
createLink(from = "area01", to = "area03")
getVariantCommands(last = 2)

Edit an existing link with:

editLink(
  from = "area01", 
  to = "area02",
  dataLink = matrix(data = c(rep(9, 8760*2), rep(6, 8760*6)), ncol = 8)
)
getVariantCommands(last = 2)

Remove a link with:

removeLink(from = "area01", to = "area03")
getVariantCommands(last = TRUE)

Create a cluster

Create a new cluster with:

createCluster(
  area = "area01", 
  cluster_name = "clus01"
)
getVariantCommands(last = TRUE)

With more parameters:

createCluster(
  area = "area01", 
  cluster_name = "clus02",
  unitcount = 1L,
  marginal_cost = 50,
  ts_interpretation = "production-factor",
  group = "Nuclear",
  add_prefix = FALSE,
  prepro_data = matrix(
    data = c(rep(9, times = 365 * 2),
             rep(7, times = 365 * 4)), 
    ncol = 6
  ),
  prepro_modulation = matrix(
    data = c(rep(8, times = 365 * 24 * 3),
             rep(6, times = 365 * 24 * 1)),
    ncol = 4
  ),
  time_series = matrix(
    data = c(rep(22, times = 365 * 24 * 8),
             rep(44, times = 365 * 24 * 4)),
    ncol = 12
  )
)
getVariantCommands(last = 2)

Edit a cluster with:

createCluster(
  area = "area02", 
  cluster_name = "clus02"
)
editCluster(
  area = "area02", 
  cluster_name = "clus02", 
  unitcount = 5L
)
getVariantCommands(last = TRUE)

Remove a cluster with (removeCluster() has been updated with endpoint and no longer uses an api command ):

createCluster(
  area = "area02", 
  cluster_name = "clus000"
)
removeCluster(
  area = "area02", 
  cluster_name = "clus000"
)
getVariantCommands(last = TRUE)

Create a binding constraint

Create a new binding constraint with:

createBindingConstraint(
  name = "myconstraint",
  values = NULL,
  enabled = FALSE,
  timeStep = "hourly",
  operator = "both",
  coefficients = c("area01%area02" = 1)
)
getVariantCommands(last = TRUE)

You can edit a binding constraint with editBindingConstraint() and remove one with removeBindingConstraint().

Update settings

Update general settings:

updateGeneralSettings(mode = "Adequacy", generate = c("thermal", "hydro"))
getVariantCommands(last = 2)

Update input settings:

updateInputSettings(import = c("hydro", "thermal"))
getVariantCommands(last = TRUE)

Update optimization settings:

updateOptimizationSettings(
  simplex.range = "week",
  power.fluctuations = "minimize ramping"
)
getVariantCommands(last = 2)

Update output settings:

updateOutputSettings(
  synthesis = TRUE,
  storenewset = FALSE,
  archives = c("load", "wind")
)
getVariantCommands(last = TRUE)

Scenario builder

Read data from scenario builder (here's it's empty since we're mocking the API):

readScenarioBuilder()

Create new data to use as scenario builder, since we're mocking the API parameters must be set explicitly, otherwise thez are retrieved from the study.

my_scenario <- scenarioBuilder(n_scenario = 3, areas = c("area01", "area02"), n_mc = 10)
my_scenario

Then you can update the scenario builder itself:

updateScenarioBuilder(ldata = my_scenario, series = "load")
getVariantCommands(last = TRUE)

Other functions

Write input time series:

writeInputTS("area01", type = "solar", data = matrix(rep(4, 8760*2), nrow = 8760))
getVariantCommands(last = TRUE)

Write water values:

writeWaterValues("area01", data = matrix(rep(0, 365*101), nrow = 365))
getVariantCommands(last = TRUE)

antaresEditObject documentation built on Nov. 5, 2025, 7:30 p.m.