Variant management with API

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.

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")
#> i Command create_area registered, see all commands with `getVariantCommands()`
createArea(name = "area02")
#> i Command create_area registered, see all commands with `getVariantCommands()`
createArea(name = "area03")
#> i Command create_area registered, see all commands with `getVariantCommands()`
getVariantCommands()
#> [
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area01"
#>     }
#>   },
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area02"
#>     }
#>   },
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area03"
#>     }
#>   }
#> ]

Create a second area with some default parameters:

createArea(
  name = "area04", 
  filtering = filteringOptions(filter_synthesis = c("hourly", "daily"))
)
#> i Command create_area registered, see all commands with `getVariantCommands()`
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands()
#> [
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area01"
#>     }
#>   },
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area02"
#>     }
#>   },
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area03"
#>     }
#>   },
#>   {
#>     "action": "create_area",
#>     "args": {
#>       "area_name": "area04"
#>     }
#>   },
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "input/areas/area04/optimization/filtering",
#>       "data": {
#>         "filter-synthesis": "hourly, daily",
#>         "filter-year-by-year": "hourly, daily, weekly, monthly, annual"
#>       }
#>     }
#>   }
#> ]

You can also edit an area or remove it:

createArea(name = "area000")
#> i Command create_area registered, see all commands with `getVariantCommands()`
# editArea(name = "area000", ...)
removeArea(name = "area000")
#> i Command remove_area registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "remove_area",
#>     "args": {
#>       "id": "area000"
#>     }
#>   }
#> ]

Create a link

Create a new link between two areas like this:

createLink(from = "area01", to = "area02")
#> i Command create_link registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
createLink(from = "area01", to = "area03")
#> i Command create_link registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
getVariantCommands(last = 2)
#> [
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/links/area01/capacities/area03_direct",
#>       "matrix": [[0],[0],[0],[0],[0],[0]] [truncated]...
#>     }
#>   },
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/links/area01/capacities/area03_indirect",
#>       "matrix": [[0],[0],[0],[0],[0],[0]] [truncated]...
#>     }
#>   }
#> ]

Edit an existing link with:

editLink(
  from = "area01", 
  to = "area02",
  dataLink = matrix(data = c(rep(9, 8760*2), rep(6, 8760*6)), ncol = 8)
)
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
getVariantCommands(last = 2)
#> [
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/links/area01/capacities/area02_direct",
#>       "matrix": [[9],[9],[9],[9],[9],[9]] [truncated]...
#>     }
#>   },
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/links/area01/capacities/area02_indirect",
#>       "matrix": [[9],[9],[9],[9],[9],[9]] [truncated]...
#>     }
#>   }
#> ]

Remove a link with:

removeLink(from = "area01", to = "area03")
#> i Command remove_link registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "remove_link",
#>     "args": {
#>       "area1": "area01",
#>       "area2": "area03"
#>     }
#>   }
#> ]

Create a cluster

Create a new cluster with:

createCluster(
  area = "area01", 
  cluster_name = "clus01"
)
#> i Command create_cluster registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "create_cluster",
#>     "args": {
#>       "area_id": "area01",
#>       "cluster_name": "area01_clus01",
#>       "parameters": {
#>         "group": "Other",
#>         "name": "area01_clus01"
#>       }
#>     }
#>   }
#> ]

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
  )
)
#> i Command create_cluster registered, see all commands with `getVariantCommands()`
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
getVariantCommands(last = 2)
#> [
#>   {
#>     "action": "create_cluster",
#>     "args": {
#>       "area_id": "area01",
#>       "cluster_name": "clus02",
#>       "prepro": [[9,9,7,7,7,7],[9,9,7,7,7,7],[9,9,7,7,7,7],[9,9,7,7,7,7],[9,9,7,7,7,7],[9,9,7,7,7,7]] [truncated]...,
#>       "modulation": [[8,8,8,6],[8,8,8,6],[8,8,8,6],[8,8,8,6],[8,8,8,6],[8,8,8,6]] [truncated]...,
#>       "parameters": {
#>         "group": "Nuclear",
#>         "unitcount": 1,
#>         "marginal-cost": 50,
#>         "ts-interpretation": "production-factor",
#>         "name": "clus02"
#>       }
#>     }
#>   },
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/thermal/series/area01/clus02/series",
#>       "matrix": [[22,22,22,22,22,22,22,22,44,44,44,44],[22,22,22,22,22,22,22,22,44,44,44,44],[22,22,22,22,22,22,22,22,44,44,44,44],[22,22,22,22,22,22,22,22,44,44,44,44],[22,22,22,22,22,22,22,22,44,44,44,44],[22,22,22,22,22,22,22,22,44,44,44,44]] [truncated]...
#>     }
#>   }
#> ]

Edit a cluster with:

createCluster(
  area = "area02", 
  cluster_name = "clus02"
)
#> i Command create_cluster registered, see all commands with `getVariantCommands()`
editCluster(
  area = "area02", 
  cluster_name = "clus02", 
  unitcount = 5L
)
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "input/thermal/clusters/area02/list/area02_clus02/name",
#>       "data": "area02_clus02"
#>     }
#>   }
#> ]

Remove a cluster with:

createCluster(
  area = "area02", 
  cluster_name = "clus000"
)
#> i Command create_cluster registered, see all commands with `getVariantCommands()`
removeCluster(
  area = "area02", 
  cluster_name = "clus000"
)
#> i Command remove_cluster registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "remove_cluster",
#>     "args": {
#>       "area_id": "area02",
#>       "cluster_id": "area02_clus000"
#>     }
#>   }
#> ]

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)
)
#> i Command create_binding_constraint registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "create_binding_constraint",
#>     "args": {
#>       "name": "myconstraint",
#>       "enabled": false,
#>       "time_step": "hourly",
#>       "operator": "both",
#>       "coeffs": {
#>         "area01%area02": [
#>           1
#>         ]
#>       }
#>     }
#>   }
#> ]

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"))
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = 2)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/general/mode",
#>       "data": "Adequacy"
#>     }
#>   },
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/general/generate",
#>       "data": "thermal, hydro"
#>     }
#>   }
#> ]

Update input settings:

updateInputSettings(import = c("hydro", "thermal"))
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/input/import",
#>       "data": "hydro, thermal"
#>     }
#>   }
#> ]

Update optimization settings:

updateOptimizationSettings(
  simplex.range = "week",
  power.fluctuations = "minimize ramping"
)
#> i Command update_config registered, see all commands with `getVariantCommands()`
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = 2)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/optimization/simplex-range",
#>       "data": "week"
#>     }
#>   },
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/other preferences/power-fluctuations",
#>       "data": "minimize ramping"
#>     }
#>   }
#> ]

Update output settings:

updateOutputSettings(
  synthesis = TRUE,
  storenewset = FALSE,
  archives = c("load", "wind")
)
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/generaldata/output/result-format",
#>       "data": ""
#>     }
#>   }
#> ]

Scenario builder

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

readScenarioBuilder()
#> list()

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
#>        [,1] [,2] [,3] [,4] [,5] [,6] [,7] [,8] [,9] [,10]
#> area01 "1"  "2"  "3"  "1"  "2"  "3"  "1"  "2"  "3"  "1"  
#> area02 "2"  "3"  "1"  "2"  "3"  "1"  "2"  "3"  "1"  "2"

Then you can update the scenario builder itself:

updateScenarioBuilder(ldata = my_scenario, series = "load")
#> i Command update_config registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "update_config",
#>     "args": {
#>       "target": "settings/scenariobuilder/Default Ruleset",
#>       "data": {"l,area01,0":1,"l,area01,1":2,"l,area01,2":3,"l,area01,3":1,"l,area01,4":2,"l,area01,5":3} [truncated]...
#>     }
#>   }
#> ]

Other functions

Write input time series:

writeInputTS("area01", type = "solar", data = matrix(rep(4, 8760*2), nrow = 8760))
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/solar/series/solar_area01",
#>       "matrix": [[4,4],[4,4],[4,4],[4,4],[4,4],[4,4]] [truncated]...
#>     }
#>   }
#> ]

Write water values:

writeWaterValues("area01", data = matrix(rep(0, 365*101), nrow = 365))
#> i Command replace_matrix registered, see all commands with `getVariantCommands()`
getVariantCommands(last = TRUE)
#> [
#>   {
#>     "action": "replace_matrix",
#>     "args": {
#>       "target": "input/hydro/common/capacity/waterValues_area01",
#>       "matrix": [[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]] [truncated]...
#>     }
#>   }
#> ]