antaresEditObject: Edit an 'Antares' Simulation

Description

Edit an 'Antares' simulation before running it : create new areas, links, thermal clusters or binding constraints or edit existing ones. Update 'Antares' general & optimization settings. 'Antares' is an open source power system generator, more information available here : https://antares-simulator.org/.

Author(s)

Maintainer: Tatiana Vargas tatiana.vargas@rte-france.com

Other contributors:

• Frederic Breant [contributor]

• Victor Perrier [contributor]

• Baptiste Seguinot [contributor]

• Benoit Thieurmel [contributor]

• Titouan Robert [contributor]

• Jalal-Edine Zawam [contributor]

• Etienne Sanchez [contributor]

• Janus De Bondt [contributor]

• Assil Mansouri [contributor]

• Abdallah Mahoudi [contributor]

• Clement Berthet [contributor]

• Kamel Kemiha [contributor]

• Nicolas Boitard [contributor]

• RTE [copyright holder]

See Also

Useful links:

• https://github.com/rte-antares-rpackage/antaresEditObject

• https://rte-antares-rpackage.github.io/antaresEditObject/

• Report bugs at https://github.com/rte-antares-rpackage/antaresEditObject/issues

Edit area's parameters in API mode.

Description

Edit area's parameters in API mode.

Usage

.api_command_execute_edit_area(name, new_values, type, opts)

Arguments

Value

An updated list containing various information about the simulation.

Computation function for rebuild mc-ind weekly from daily data.

Description

Computation function for rebuild mc-ind weekly from daily data.

Usage

.dailyToWeekly(dailydata, opts = simOptions(), type)

Arguments

Format a value to a suitable format to rhs in an .ini file.

Description

Format a value to a suitable format to rhs in an .ini file.

Usage

.format_ini_rhs(value)

Arguments

Value

the formatted value

Generate playlist_year_weight section in the appropriate format.

Description

Generate playlist_year_weight section in the appropriate format.

Usage

.format_playlist_weights(weights, api_mode)

Arguments

Value

The playlist_year_weight section formatted.

Computation function for rebuild mc-ind daily, monthly and annual from hourly data.

Description

Computation function for rebuild mc-ind daily, monthly and annual from hourly data.

Usage

.hourlyToOther(hourlydata, timeStep, type)

Arguments

Initialize links data for a new area. For disk mode only.

Description

Initialize links data for a new area. For disk mode only.

Usage

.initializeLinksArea(name, overwrite, opts)

Arguments

Value

An updated list containing various information about the simulation.

Initialize renewables data for a new area. For disk mode only.

Description

Initialize renewables data for a new area. For disk mode only.

Usage

.initializeRenewablesArea(name, overwrite, opts)

Arguments

Value

An updated list containing various information about the simulation.

Initialize thermal data for a new area. For disk mode only.

Description

Initialize thermal data for a new area. For disk mode only.

Usage

.initializeThermalArea(name, overwrite, economic_options, opts)

Arguments

Value

An updated list containing various information about the simulation.

function that ensures the transition to 9

Description

basic tests on the version's writing format

Usage

.is_version_9(version)

Arguments

Value

logical if version >=9

Split list nodalOptimization by target file.

Description

Split list nodalOptimization by target file.

Usage

.split_nodalOptimization_by_target(nodalOptimization)

Arguments

Activate RES in an Antares study

Description

Helper to activate Renewables Energy Sources. This will update renewable.generation.modelling parameter and create appropriate structure for RES clusters.

Usage

activateRES(opts = antaresRead::simOptions(), quietly = !interactive())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

library(antaresEditObject)
tmp <- tempfile()
createStudy(path = tmp)
opts <- antaresRead::setSimulationPath(tmp)
activateRES()

# then you can use createClusterRES()...


## End(Not run)

Activate st-storage in an Antares study

Description

Activate st-storage in an Antares study

Usage

activateST(opts = antaresRead::simOptions(), quietly = !interactive())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

library(antaresEditObject)
tmp <- tempfile()
createStudy(path = tmp)
opts <- antaresRead::setSimulationPath(tmp)
activateST()

# then you can use createClusterST()...


## End(Not run)

Add week number column to a data.time of time series type

Description

If timeId column exists, add a week number column. A week is 168 consecutive hours (= 24 * 7).

Usage

add_week_number_column_to_ts(xts)

Arguments

Value

the data.table xts with a new column week.

Adequacy patch parameters for creating an area

Description

Adequacy patch parameters for creating an area

Usage

adequacyOptions(adequacy_patch_mode = "outside")

Arguments

Value

a named list

Examples

adequacyOptions()

API methods

Description

API methods

Usage

api_patch(opts, endpoint, ..., default_endpoint = "v1/studies")

Arguments

Value

Response from the API.

Examples

## Not run: 
# Simple example to update st-storages properties 

# read existing study 
opts <- setSimulationPath("path_to_the_study", "input")

# make list of properties
prop <- list(efficiency = 0.5,
  reservoircapacity = 350, 
  initialleveloptim = TRUE)
  
# convert to JSON
body <- jsonlite::toJSON(prop,
  auto_unbox = TRUE)   
  
# send to server (see /apidoc)
api_patch(opts = opts, 
  endpoint = file.path(opts$study_id, 
                     "areas", 
                      area,
                     "storages",
                     cluster_name), 
 body = body, 
 encode = "raw")   


## End(Not run)

Create a backup with an Antares Study

Description

Save an Antares Study or only inputs in a .tar.gz or .zip file

Usage

backupStudy(
  backupfile,
  what = "study",
  opts = antaresRead::simOptions(),
  extension = ".zip"
)

Arguments

Value

The path of the backup

Examples

## Not run: 
backupStudy()

## End(Not run)

Is study an Antares v7 study ?

Description

Is study an Antares v7 study ?

Usage

is_antares_v7(opts = antaresRead::simOptions())

is_antares_v820(opts = antaresRead::simOptions())

Arguments

Value

a logical, TRUE if study is v7 or above, FALSE otherwise.

Examples

## Not run: 
# setSimulationPath

is_antares_v7()


## End(Not run)

Seek for a removed area

Description

Check if it remains trace of a deleted area in the input folder

Usage

checkRemovedArea(area, all_files = TRUE, opts = antaresRead::simOptions())

Arguments

Value

a named list with two elements

Examples

## Not run: 
checkRemovedArea("myarea")

## End(Not run)

For a given area, check consistency between reservoir and reservoir capacity values

Description

For a given area, check consistency between reservoir and reservoir capacity values

Usage

check_consistency_reservoir_values(area, new_data, prev_data)

Arguments

Check if mingen data and hydro storage data are consistent

Description

At each weekly/monthly/annual time step, mingen must be less or equal than hydro storage.

Usage

check_mingen_vs_hydro_storage(area, opts = antaresRead::simOptions())

Arguments

Value

a list containing the boolean if the check is ok and the message to display.

Note

Function called only for an Antares version >= 860.

Check if mingen data and maxpower data are consistent

Description

At each hourly time step, mingen must be less or equal than generatingMaxPower.

Usage

check_mingen_vs_maxpower(area, opts = antaresRead::simOptions())

Arguments

Value

a list containing the boolean if the check is ok and the message to display.

Note

Function called only for an Antares version >= 860.

Clean up output based on geographic trimming

Description

Clean up output based on geographic trimming

Usage

cleanUpOutput(areas = NULL, opts = simOptions())

Arguments

Compute daily, weekly, monthly and annual mc-ind from hourly data multiyear. (new)

Description

Compute daily, weekly, monthly and annual mc-ind from hourly data multiyear. (new)

Usage

computeOtherFromHourlyMulti(
  opts = simOptions(),
  areas = "all",
  type = c("areas", "links", "clusters"),
  timeStep = c("daily", "monthly", "annual", "weekly"),
  mcYears = simOptions()$mcYears,
  writeOutput = FALSE,
  nbcl = 8,
  verbose = FALSE
)

Arguments

Note

Recommended only with studies spanning on two years.

See Also

computeOtherFromHourlyYear

Compute daily, weekly, monthly and annual mc-ind from hourly data for one year. (new)

Description

Compute daily, weekly, monthly and annual mc-ind from hourly data for one year. (new)

Usage

computeOtherFromHourlyYear(
  mcYear,
  type,
  areas = "all",
  opts = simOptions(),
  timeStep = c("daily", "monthly", "annual", "weekly"),
  writeOutput = FALSE
)

Arguments

Note

Recommended only with studies spanning on two years.

See Also

computeOtherFromHourlyMulti

Compute daily, weekly, monthly and annual mc-ind from hourly data.

Description

Compute daily, weekly, monthly and annual mc-ind from hourly data.

Usage

computeTimeStampFromHourly(
  opts,
  mcYears = "all",
  nbcl = 8,
  verbose = 1,
  type = c("areas", "links", "clusters")
)

Arguments

Note

Deprecated on studies v8 or higher.

Examples

## Not run: 

library(antaresEditObject)
opts <- setSimulationPath("my_study")
computeTimeStampFromHourly(opts)


## End(Not run)

Read adequacy patch config.yml into Antares (v8.5+)

Description

Use this function to load config.yml used in older Antares versions for adequacy patch. Areas in config will be updated to be included in adequacy patch perimeter.

Usage

convertConfigToAdq(opts = simOptions(), path = "default")

Arguments

See Also

updateAdequacySettings

Copy of the output files of an Antares study

Description

Copy of the output files of an Antares study.

Usage

copyOutput(opts, extname, mcYears = "all")

Arguments

Examples

## Not run: 

library(antaresRead)

# Set simulation path
opts = setSimulationPath(path = "PATH/TO/SIMULATION", simulation = "input")

# Create a new area
copyOutput(opts, "_adq")


## End(Not run)

Import physical study to Antares Web (managed study)

Description

Copy study from an existing workspace into a managed study. NOTE : The study must be present in a workspace (DRD, PPSE..) not just locally.

Usage

copyStudyWeb(
  opts = antaresRead::simOptions(),
  host,
  token,
  outputs = T,
  groups = NULL,
  suffix = "managedCopy"
)

Arguments

Value

New managed study ID

Create an empty Antares study

Description

Create study on disk or with AntaREST server through the API.

Usage

createStudy(path, study_name = "my_study", antares_version = "8.2.0")

createStudyAPI(
  host,
  token = NULL,
  study_name = "my_study",
  antares_version = "8.2.0",
  ...
)

Arguments

Value

Result of antaresRead::setSimulationPath() or antaresRead::setSimulationPathAPI() accordingly.

Warning

From Antares version 9.0 onwards, versioning is only done with one number for the major version number and a two-digit number for the minor version number (e.g. 9.0, 9.12, 10.58, ...).

Examples

## Not run: 

# with default values 
createStudy("path/to/simulation", 
  study_name = "my_study", 
  antares_version = "8.2.0")
  
# with Antares study version >= 9 (max 2 digits, ex : "9.15")  
createStudy("path/to/simulation", 
  study_name = "my_study", 
  antares_version = "9.15")


## End(Not run)

Create an area in an Antares study

Description

Create a new area in an Antares study.

Usage

createArea(
  name,
  color = grDevices::rgb(230, 108, 44, max = 255),
  localization = c(0, 0),
  nodalOptimization = nodalOptimizationOptions(),
  filtering = filteringOptions(),
  adequacy = adequacyOptions(),
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

editArea(), removeArea()

Examples

## Not run: 

library(antaresRead)

# Set simulation path
setSimulationPath(path = "PATH/TO/SIMULATION", simulation = "input")

# Create a new area
createArea("fictive_area")


## End(Not run)

Create a binding constraint

Description

Create a new binding constraint in an Antares study.

Usage

createBindingConstraint(
  name,
  id = tolower(name),
  values = NULL,
  enabled = TRUE,
  timeStep = c("hourly", "daily", "weekly"),
  operator = c("both", "equal", "greater", "less"),
  filter_year_by_year = "hourly, daily, weekly, monthly, annual",
  filter_synthesis = "hourly, daily, weekly, monthly, annual",
  coefficients = NULL,
  group = NULL,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Details

According to Antares version, usage may vary :

< v8.7.0 : For each constraint name, a .txt file containing 3 time series ⁠"less", "greater", "equal"⁠

>= v8.7.0 : For each constraint name, one file .txt containing ⁠<id>_lt.txt, <id>_gt.txt, <id>_eq.txt⁠ Parameter values must be named list ("lt", "gt", "eq") containing data.frame scenarized. see example section below.

Value

An updated list containing various information about the simulation.

See Also

Other binding constraints functions: createBindingConstraintBulk(), editBindingConstraint(), removeBindingConstraint()

Examples

## Not run: 
# < v8.7.0 :

# Create constraints with multi coeffs (only weight)

createBindingConstraint(
  name = "myconstraint", 
  values = matrix(data = rep(0, 8760 * 3), ncol = 3), 
  enabled = FALSE, 
  timeStep = "hourly",
  operator = "both",
  coefficients = list("area1%area2" = 1,
    "area1%area3" = 2)
)

# Create constraints with multi coeffs + offset

createBindingConstraint(
  name = "myconstraint", 
  values = matrix(data = rep(0, 8760 * 3), ncol = 3), 
  enabled = FALSE, 
  timeStep = "hourly",
  operator = "both",
  coefficients = list("area1%area2" = "1%1",
    "area1%area3" = "2%3")
)


# >= v8.7.0 :

# values are now named list containing `data.frame` according to   
 # `operator` parameter (for "less", build a list with at least "lt" floor in list)
 
# data values (hourly)
df <- matrix(data = rep(0, 8760 * 3), ncol = 3)
values_data <- list(lt=df)
 
# create bc with minimum value
createBindingConstraint(name = "bc_example", 
                        operator = "less", 
                        values = values_data, 
                        overwrite = TRUE)
                        
# or you can provide list data with all value
values_data <- list(lt=df, 
                   gt= df, 
                   eq= df)   
                   
createBindingConstraint(name = "bc_example", 
                        operator = "less", 
                        values = values_data, 
                        overwrite = TRUE)      
                        

## End(Not run)

Create multiple binding constraint at once.

Description

Usage

createBindingConstraintBulk(constraints, opts = antaresRead::simOptions())

Arguments

Details

According to Antares version, usage may vary :

>= v8.7.0 :

• For each constraint name, one file .txt containing ⁠<id>_lt.txt, <id>_gt.txt, <id>_eq.txt⁠.

• Parameter values must be named list ("lt", "gt", "eq") containing data.frame scenarized.

• Add parameter group in input list constraints

see example section below.

Value

An updated list containing various information about the simulation.

See Also

Other binding constraints functions: createBindingConstraint(), editBindingConstraint(), removeBindingConstraint()

Examples

## Not run: 
# For Study version < v8.7.0
# Create multiple constraints

# Prepare data for constraints 
bindings_constraints <- lapply(
  X = seq_len(100),
  FUN = function(i) {
    # use arguments of createBindingConstraint()
    # all arguments must be provided !
    list(
      name = paste0("constraints", i), 
      id = paste0("constraints", i), 
      values = matrix(data = rep(0, 8760 * 3), ncol = 3), 
      enabled = FALSE, 
      timeStep = "hourly",
      operator = "both",
      coefficients = list("area1%area2" = 1),
      overwrite = TRUE
    )
  }
)
# create all constraints
createBindingConstraintBulk(bindings_constraints)

# For Study version >= v8.7.0 (add parameter `group`)

# data values (hourly)
df <- matrix(data = rep(0, 8760 * 3), ncol = 3)
values_data <- list(lt=df, 
                    gt= df)   

# create multiple constraints
bindings_constraints <- lapply(
  X = seq_len(10),
  FUN = function(i) {
    # use arguments of createBindingConstraint()
    # all arguments must be provided !
    list(
      name = paste0("constraints_bulk", i), 
      id = paste0("constraints_bulk", i), 
      values = values_data, 
      enabled = FALSE, 
      timeStep = "hourly",
      operator = "both",
      coefficients = list("at%fr" = 1),
      group= "group_bulk",
     overwrite = TRUE
   )
  }
)
 
createBindingConstraintBulk(bindings_constraints)  

## End(Not run)

Create a cluster

Description

(thermal clusters only)

Create a new thermal or RES (renewable energy source) cluster.

Usage

createCluster(
  area,
  cluster_name,
  group = "Other",
  ...,
  list_pollutants = NULL,
  time_series = NULL,
  prepro_data = NULL,
  prepro_modulation = NULL,
  add_prefix = TRUE,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

createClusterRES(
  area,
  cluster_name,
  group = "Other RES 1",
  ...,
  time_series = NULL,
  add_prefix = TRUE,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Note

Parameter list_pollutants is only available for Antares studies >= v8.6.0.

You must provide named list (numerical values or NULL ) :

list( "nh3"= 0.25, "nox"= 0.45, "pm2_5"= 0.25, "pm5"= 0.25, "pm10"= 0.25, "nmvoc"= 0.25, "so2"= 0.25, "op1"= 0.25, "op2"= 0.25, "op3"= 0.25, "op4"= 0.25, "op5"= NULL, "co2"= NULL)

See Also

editCluster() or editClusterRES() to edit existing clusters, removeCluster() or removeClusterRES() to remove clusters.

Examples

## Not run: 

library(antaresRead)
library(antaresEditObject)

# Create a cluster :
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  group = "other", 
  unitcount = 1L, # or as.integer(1)
  marginal_cost = 50
)
# by default, cluster name is prefixed 
# by the area name
levels(readClusterDesc()$cluster)
# > "fr_my_cluster"

# To prevent this, use `add_prefix`
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  add_prefix = FALSE,
  group = "other", 
  marginal_cost = 50
)
levels(readClusterDesc()$cluster)
# > "my_cluster"


# Create a RES cluster :
createClusterRES(
  area = "fr", 
  cluster_name = "my_cluster_res",
  group = "other", 
  unitcount = 1L, # or as.integer(1)
  nominalcapacity = 50,
  ts_interpretation = "power-generation"
) 

# You can also specify that the Time-Series of the RES cluster are
# production factors :
createClusterRES(
  area = "fr", 
  cluster_name = "my_cluster_res",
  group = "other", 
  unitcount = 1L, # or as.integer(1)
  nominalcapacity = 50,
  ts_interpretation = "production-factor"
)


# Pre-process data : 

# this is the default data :
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  prepro_data = matrix(
    data = c(rep(1, times = 365 * 2),
             rep(0, times = 365 * 4)), 
    ncol = 6
  )
)

# with a data.frame
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  prepro_data = data.frame(
    v1 = rep(7, 365), # column name does not matter
    v2 = rep(27, 365),
    v3 = rep(0.05, 365),
    v4 = rep(0.12, 365),
    v5 = rep(0, 365),
    v6 = rep(1, 365)
  )
)


# Pre-process modulation : 
# this is the default data
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  prepro_modulation = matrix(
    data = c(rep(1, times = 365 * 24 * 3),
             rep(0, times = 365 * 24 * 1)),
    ncol = 4
  )
)

# with a data.frame
createCluster(
  area = "fr", 
  cluster_name = "my_cluster",
  prepro_modulation = data.frame(
    var1 = rep(0, 8760), # column name does not matter
    var2 = rep(1, 8760),
    var3 = rep(0, 8760),
    var4 = rep(1, 8760)
  )
)


## End(Not run)

Create serial thermal cluster

Description

For each area, the thermal cluster data are generated :

• Writing .ini files

• Writing time_series files

• Writing prepro_data files

• Writing prepro_modulation files

Usage

createClusterBulk(
  cluster_object,
  area_zone,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Details

see the example to write a cluster object, see the original function createCluster()

Structure of cluster_object :

The list must be structured with named items

• parameter : list of paramaters to write in .ini file

• overwrite : logical to choose to overwrite an existing cluster (if not present, set to FALSE)

• time_series : matrix or data.frame the "ready-made" 8760-hour time-series

• prepro_data : matrix or data.frame Pre-process data

• prepro_modulation : matrix or data.frame Pre-process modulation

Details for sublist cluster_object[["parameter"]] :

• name : Name for the cluster, it will prefixed by area name, unless you set add_prefix = FALSE

• group : Group of the cluster, depends on cluster type

• ... : Parameters to write in the Ini file

Value

An updated list containing various information about the simulation.

list containing meta information about the simulation

Examples

## Not run: 

# /!\/!\/!\ use or create a study /!\/!\/!\

# data preparation for sutructures
ts <- matrix(rep(c(0, 8000), each = 24*364), 
             ncol = 2)

df_pd <- matrix(rep(c(1, 1, 1, 0), each = 24*365), 
                ncol = 4)

df_pm <- matrix(data = c(rep(1, times = 365 * 24 * 3), rep(0, times = 365 * 24 * 1)), 
                ncol = 4)


# Example cluster object
zone_test_1 <- list(
  `CCGT old 1`= list(
  parameter= list(
  name= "CCGT old 1",
  group = "Other",
  unitcount= 10L,
  nominalcapacity= 100,
   enabled= "true",
   `min-stable-power`= 80L,
   `min-up-time`= 20L,
   `min-down_time`= 30L),
   overwrite= TRUE,
   time_series = ts_8760,
   prepro_data = df_pd,
   prepro_modulation = df_pm))
 
 # overwrite existing cluster
zone_test_2 <- list(
 `PEAK`= list(parameter= list(
   name= "PEAK",
   group = "Other"),
   overwrite= TRUE,
   time_series = ts,
   prepro_data = df_pd,
   prepro_modulation = df_pm))

# Create multiple areas with multiple clusters
list_areas <- antaresRead::getAreas()[1:5]

lapply(list_areas, createClusterBulk,
cluster_object = c(zone_test_1, zone_test_2),
add_prefix = TRUE)


## End(Not run)

Create a short-term storage cluster

Description

Create a new ST-storage cluster for >= v8.6.0 Antares studies.

Usage

createClusterST(
  area,
  cluster_name,
  group = "Other1",
  storage_parameters = storage_values_default(),
  PMAX_injection = NULL,
  PMAX_withdrawal = NULL,
  inflows = NULL,
  lower_rule_curve = NULL,
  upper_rule_curve = NULL,
  add_prefix = TRUE,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Note

To write parameters to the list.ini file. You have function storage_values_default() who is called by default. This function return list containing properties according study version for cluster st-storage.

Study version >= "8.6.0" :

• efficiency = 1 (numeric {0;1})

• reservoircapacity = 0 (integer >= 0)

• initiallevel = 0 (numeric {0;1})

• withdrawalnominalcapacity = 0 (integer >= 0)

• injectionnominalcapacity = 0 (integer >= 0)

• initialleveloptim = FALSE (logical TRUE/FALSE)

Study version >= "8.8.0" (update + new parameter) :

• initiallevel = 0.5 (numeric {0;1})

• enabled = TRUE (logical TRUE/FALSE)

By default, these values don't allow you to have an active cluster (See example section.)

See Also

All the functions needed to manage a storage cluster, antaresRead::readClusterSTDesc(), editClusterST(), removeClusterST().

Examples

## Not run: 

# list for cluster parameters : 
storage_values_default()

# create a cluster by default (with default parameters values + default data values):
createClusterST(area = "my_area", 
               "my_cluster") 
  
# Read cluster in study                            
 # by default, cluster name is prefixed 
 # by the area name
levels(readClusterSTDesc()$cluster)
# > "my_area_my_cluster"

# create cluster with custom parameter and data
  # use the function to create your own list of parameters (no Antares optim)
  # if you want optim (my_parameters$initialleveloptim <- TRUE)
my_parameters <- storage_values_default()
my_parameters$efficiency <- 0.5
my_parameters$initiallevel <- 10
my_parameters$withdrawalnominalcapacity <- 100
my_parameters$injectionnominalcapacity <- 1000
my_parameters$reservoircapacity <- 10000

  # time series 
inflow_data <- matrix(3, 8760)
ratio_data <- matrix(0.7, 8760)

createClusterST(area = "my_area", 
                "my_cluster",
                storage_parameters = my_parameters,
                PMAX_withdrawal = ratio_data, 
                inflows = inflow_data, 
                PMAX_injection = ratio_data, 
                lower_rule_curve = ratio_data, 
                upper_rule_curve = ratio_data)

## End(Not run)

Create a Demand Side Response (DSR)

Description

Create a Demand Side Response (DSR)

Usage

createDSR(
  areasAndDSRParam = NULL,
  spinning = 2,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

getCapacityDSR(area = NULL, opts = antaresRead::simOptions())

editDSR(
  area = NULL,
  unit = NULL,
  nominalCapacity = NULL,
  marginalCost = NULL,
  spinning = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

getCapacityDSR() returns DSR capacity (unit * nominalCapacity of virtual cluster) of the area

Examples

## Not run: 

library(antaresEditObject)
path <- pathToYourStudy
opts <- setSimulationPath(path, simulation = "input")

# area, unit, nominalCapacity and marginalCost
dsrData <- data.frame(area = c("a", "b"), unit = c(10,20), 
                    nominalCapacity = c(100, 120), marginalCost = c(52, 65), hour = c(3, 7))

createDSR(dsrData)

createDSR(dsrData, spinning = 3, overwrite = TRUE)
getAreas()


## End(Not run)
## Not run: 

getCapacityDSR("a")
editDSR("a", unit = 50, nominalCapacity = 8000)
getCapacityDSR("a")


## End(Not run)
## Not run: 

getCapacityDSR("a")
editDSR("a", unit = 50, nominalCapacity = 8000, marginalCost = 45, hour = 9)
getCapacityDSR("a")


## End(Not run)

Create a district

Description

Allows selecting a set of areas so as to bundle them together in a "district".

Usage

createDistrict(
  name,
  caption = NULL,
  comments = NULL,
  apply_filter = c("none", "add-all", "remove-all"),
  add_area = NULL,
  remove_area = NULL,
  output = FALSE,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 
createDistrict(
  name = "mydistrict",
  apply_filter = "add-all",
  remove_area = c("fr", "be")
)

## End(Not run)

Create a link between two areas

Description

Create a new link between two areas in an Antares study.

Usage

createLink(
  from,
  to,
  propertiesLink = propertiesLinkOptions(),
  dataLink = NULL,
  tsLink = NULL,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Details

The eight potential times-series are:

• NTC direct : the upstream-to-downstream capacity, in MW. Default to 1.

• NTC indirect : the downstream-to-upstream capacity, in MW. Default to 1.

• Hurdle cost direct : an upstream-to-downstream transmission fee, in euro/MWh. Default to 0.

• Hurdle cost indirect : a downstream-to-upstream transmission fee, in euro/MWh. Default to 0.

• Impedances : virtual impedances that are used in economy simulations to give a physical meaning to raw outputs, when no binding constraints have been defined to enforce Kirchhoff's laws. Default to 0.

• Loop flow : amount of power flowing circularly though the grid when all "nodes" are perfectly balanced (no import and no export). Default to 0.

• PST min : lower bound of phase-shifting that can be reached by a PST installed on the link, if any. Default to 0.

• PST max : upper bound of phase-shifting that can be reached by a PST installed on the link, if any. Default to 0.

According to Antares version, usage may vary :

< v7.0.0 : 5 first columns are used in the following order: NTC direct, NTC indirect, Impedances, Hurdle cost direct, Hurdle cost indirect.

>= v7.0.0 : 8 columns in order above are expected.

>= v8.2.0 : there's 2 cases :

• 8 columns are provided: 2 first are used in tsLink, other 6 are used for link data

• 6 columns are provided: you must provide NTC data in tsLink argument.

Value

An updated list containing various information about the simulation.

Note

In Antares, areas are sorted in alphabetical order to establish links between. For example, link between "fr" and "be" will appear under "be". So the areas are sorted before creating the link between them, and dataLink is rearranged to match the new order.

See Also

editLink(), removeLink()

Examples

## Not run: 

library(antaresRead)

# Set simulation path
setSimulationPath(path = "PATH/TO/SIMULATION", simulation = "input")

# Create a link between two areas
createLink(from = "first_area", to  = "second_area")


## End(Not run)

Create a Pumped Storage Power plant (PSP)

Description

Create a Pumped Storage Power plant (PSP)

Usage

createPSP(
  areasAndCapacities = NULL,
  namePumping = "Psp_In",
  nameTurbining = "Psp_Out",
  hurdleCost = 5e-04,
  timeStepBindConstraint = "weekly",
  efficiency = NULL,
  overwrite = FALSE,
  opts = antaresRead::simOptions()
)

getCapacityPSP(
  area = NULL,
  nameTurbining = "Psp_Out",
  timeStepBindConstraint = "weekly",
  opts = antaresRead::simOptions()
)

editPSP(
  area = NULL,
  capacity = NULL,
  namePumping = "Psp_In",
  nameTurbining = "Psp_Out",
  timeStepBindConstraint = "weekly",
  hurdleCost = 5e-04,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

getCapacityPSP() returns PSP capacity of the area

Examples

## Not run: 

library(antaresEditObject)
path<-pathToYourStudy
opts<-setSimulationPath(path, simulation = "input")
pspData<-data.frame(area=c("a", "b"), installedCapacity=c(800,900))

createPSP(pspData, efficiency = 0.8)

createPSP(pspData, efficiency = 0.66, overwrite = TRUE)
createPSP(pspData, efficiency = 0.98, timeStepBindConstraint = "daily")
getAreas()


## End(Not run)

## Not run: 

getCapacityPSP("a")
editPSP("a", capacity = 8000, hurdleCost = 0.1)
getCapacityPSP("a")

areaName<-"suisse"
createArea(areaName, overwrite = TRUE)
pspData<-data.frame(area=c(areaName), installedCapacity=c(9856))
createPSP(pspData, efficiency = 0.5, overwrite = TRUE, timeStepBindConstraint = "daily")

getCapacityPSP(areaName, timeStepBindConstraint = "daily")



## End(Not run)

Create the correspondence data frame between the symbol and the type in scenario builder

Description

Create the correspondence data frame between the symbol and the type in scenario builder

Usage

create_scb_referential_series_type()

Value

a data.frame.

Delete a study or a simulation

Description

Delete a study or a simulation

Usage

deleteStudy(opts = simOptions(), prompt_validation = FALSE, simulation = NULL)

Arguments

Detect a pattern in a binding constraint coefficient

Description

Detect a pattern in a binding constraint coefficient

Usage

detect_pattern_in_binding_constraint(pattern, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

the names of the binding constraints containing the pattern

Correspondence between arguments of updateAdequacySettings and actual Antares parameters.

Description

Correspondence between arguments of updateAdequacySettings and actual Antares parameters.

Usage

dicoAdequacySettings(arg)

Arguments

Value

The corresponding Antares general parameter.

Correspondence between arguments of updateGeneralSettings and actual Antares parameters.

Description

Correspondence between arguments of updateGeneralSettings and actual Antares parameters.

Usage

dicoGeneralSettings(arg)

Arguments

Value

The corresponding Antares general parameter.

Examples

dicoGeneralSettings("year.by.year") # "year-by-year"

Correspondence between arguments of updateOptimizationSettings and actual Antares parameters.

Description

Correspondence between arguments of updateOptimizationSettings and actual Antares parameters.

Usage

dicoOptimizationSettings(arg)

Arguments

Value

The corresponding Antares general parameter.

Examples

dicoGeneralSettings("year.by.year") # "year-by-year"

Correspondence between arguments of updateOutputSettings and actual Antares parameters.

Description

Correspondence between arguments of updateOutputSettings and actual Antares parameters.

Usage

dicoOutputSettings(arg)

Arguments

Value

The corresponding Antares general parameter.

Examples

dicoOutputSettings("result.format") # "result-format"

Edit an area in an Antares study

Description

Edit an existing area in an Antares study.

Usage

editArea(
  name,
  color = NULL,
  localization = NULL,
  nodalOptimization = NULL,
  filtering = NULL,
  adequacy = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

createArea(), removeArea()

Examples

## Not run: 

library(antaresRead)

# Set simulation path
setSimulationPath(path = "PATH/TO/SIMULATION", simulation = "input")

# Edit an existing area
editArea("area", color = grDevices::rgb(230, 108, 44, max = 255),
  localization = c(1, 1),
  opts = antaresRead::simOptions()) 

editArea("de",  nodalOptimization = list("spilledenergycost" = list(fr = 30)),
opts = antaresRead::simOptions())

editArea("de",  nodalOptimization = nodalOptimizationOptions(),
opts = antaresRead::simOptions())

editArea(
  "de",
  filtering = list("filter_synthesis"=paste(c("hourly","daily"),collapse = ", "))
)


## End(Not run)

Update an existing binding constraint

Description

Update an existing binding constraint in an Antares study. The key search value of the constraint is the id field

Usage

editBindingConstraint(
  name,
  id = tolower(name),
  values = NULL,
  enabled = NULL,
  timeStep = NULL,
  operator = NULL,
  filter_year_by_year = NULL,
  filter_synthesis = NULL,
  coefficients = NULL,
  group = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Warning

Put values with rights dimensions :

• hourly : 8784

• daily = 366

>= v8.7.0 : For each constraint name, one file .txt containing ⁠<id>_lt.txt, <id>_gt.txt, <id>_eq.txt⁠ Parameter values must be named list ("lt", "gt", "eq") containing data.frame scenarized. see example section below.

See Also

Other binding constraints functions: createBindingConstraintBulk(), createBindingConstraint(), removeBindingConstraint()

Examples

## Not run: 
 # < v8.7.0 :
editBindingConstraint(
  name = "myconstraint", 
  values = matrix(data = rep(0, 8784 * 3), ncol = 3), 
  enabled = FALSE, 
  timeStep = "hourly",
  operator = "both",
  coefficients = list("fr%de" = 1)
)

# update binding constraint with weight + offset 
editBindingConstraint(
  name = "myconstraint", 
  values = matrix(data = rep(0, 8784 * 3), ncol = 3), 
  enabled = FALSE, 
  timeStep = "hourly",
  operator = "both",
  coefficients = list("fr%de" = "1%-5")
)

 # >= v8.7.0 :
 
# data values scenarized (hourly)
df <- matrix(data = rep(0, 8784 * 3), ncol = 3)
 
# you can provide list data with all value 
# or just according with 'operator' (ex : 'lt' for 'less)
values_data <- list(lt=df, 
                   gt= df, 
                   eq= df)  
                     
editBindingConstraint(name = "myconstraint", 
                      values = values_data, 
                      enabled = TRUE, 
                      timeStep = "hourly", 
                      operator = "both", 
                      filter_year_by_year = "hourly", 
                      filter_synthesis = "hourly", 
                      coefficients = list("fr%de" = 1), 
                      group = "myconstraint_group")                   

## End(Not run)

Edit an existing cluster

Description

(thermal clusters only)

Edit parameters, pre-process data and time series of an existing cluster, thermal or RES (renewable energy source).

Usage

editCluster(
  area,
  cluster_name,
  ...,
  list_pollutants = NULL,
  time_series = NULL,
  prepro_data = NULL,
  prepro_modulation = NULL,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

editClusterRES(
  area,
  cluster_name,
  ...,
  time_series = NULL,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Note

Parameter list_pollutants is only available for Antares studies >= v8.6.0.

You must provide named list (numerical values or NULL ) :

list( "nh3"= 0.25, "nox"= 0.45, "pm2_5"= 0.25, "pm5"= 0.25, "pm10"= 0.25, "nmvoc"= 0.25, "so2"= 0.25, "op1"= 0.25, "op2"= 0.25, "op3"= 0.25, "op4"= 0.25, "op5"= NULL, "co2"= NULL)

See Also

createCluster() or createClusterRES() to create new clusters, removeCluster() or removeClusterRES() to remove clusters.

Examples

## Not run: 

# Update only nominalCapacity for an existing cluster
editCluster(
  area = "myarea", 
  cluster_name = "mycluster", 
  nominalcapacity = 10600.000
)


## End(Not run)

Edit a short-term storage cluster

Description

Edit parameters and time series of an existing st-storage cluster (Antares studies >= v8.6.0).

Usage

editClusterST(
  area,
  cluster_name,
  group = NULL,
  storage_parameters = NULL,
  PMAX_injection = NULL,
  PMAX_withdrawal = NULL,
  inflows = NULL,
  lower_rule_curve = NULL,
  upper_rule_curve = NULL,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

createClusterST() to edit existing clusters, removeClusterST() to remove clusters.

Edit a link between two areas

Description

Edit a link between two areas in an Antares study.

Usage

editLink(
  from,
  to,
  hurdles_cost = NULL,
  transmission_capacities = NULL,
  asset_type = NULL,
  display_comments = NULL,
  filter_synthesis = NULL,
  filter_year_by_year = NULL,
  dataLink = NULL,
  tsLink = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Note

See createLink() for more documentation

See Also

createLink(), removeLink()

Examples

## Not run: 
editLink(
  from = "area1",
  to = "area2",
  transmission_capacities = "infinite",
  filter_synthesis = c("hourly","daily"),
  filter_year_by_year = c("weekly","monthly")
)

## End(Not run)

Write default values in hydro.ini file if the section is empty

Description

For a given area, if the data is empty, pick value from default values for ⁠use heuristic⁠, ⁠follow load⁠ and reservoir sections.

Usage

fill_empty_hydro_ini_file(area, opts = antaresRead::simOptions())

Arguments

Write default input time series if mingen.txt or/and mod.txt is empty

Description

Write default input time series if mingen.txt or/and mod.txt is empty

Usage

fill_empty_hydro_ts_file(area, opts = antaresRead::simOptions())

Arguments

Output profile options for creating an area

Description

Output profile options for creating an area

Usage

filteringOptions(
  filter_synthesis = c("hourly", "daily", "weekly", "monthly", "annual"),
  filter_year_by_year = c("hourly", "daily", "weekly", "monthly", "annual")
)

Arguments

Value

a named list

Examples

filteringOptions(
  filter_synthesis=c("hourly","daily"),
  filter_year_by_year=c("weekly","monthly")
)

Retrieve job log from API

Description

Retrieve job log from API

Usage

getJobLogs(job_id, opts = antaresRead::simOptions())

Arguments

Value

Logs as character string.

Examples

## Not run: 

antaresRead::setSimulationPathAPI(
  host = "http://localhost:8080",
  study_id = "39c604fc-687f-46c4-9fa6-59b57ff9c8d1",
  token = NULL,
  simulation = "input"
)
job <- runSimulation()
getJobLogs(job)


## End(Not run)

Retrieve API jobs

Description

Retrieve API jobs

Usage

getJobs(job_id = NULL, opts = antaresRead::simOptions())

Arguments

Value

A data.table with information about jobs.

Examples

## Not run: 

getJobs()


## End(Not run)

Get default hydro.ini values

Description

Get default hydro.ini values

Usage

get_default_hydro_ini_values()

Get the type of control to execute using the 3 necessary booleans

Description

Get the type of control to execute using the 3 necessary booleans

Usage

get_type_check_mingen_vs_hydrostorage(hydro_params)

Arguments

Value

a character containing the type of control to execute.

Get the type of control to execute between mingen data and hydro storage data

Description

Compute the type of control to make between :

• input/hydro/series/<area>/mingen.txt

• input/hydro/series/<area>/mod.txt

This control is implemented in Antares too.

Usage

get_type_check_mingen_vs_hydrostorage_to_trigger(
  area,
  opts = antaresRead::simOptions()
)

Arguments

Value

a character containing the type of control to execute.

Note

Function called only for an Antares version >= 860.

Get the type of control to execute between mingen data and maxpower data

Description

Compute the type of control to make between :

• input/hydro/series/<area>/mingen.txt

• input/hydro/common/capacity/maxpower_<area>.txt

This control is implemented in Antares too. No control to execute if reservoir section in hydro.ini for the area is set to TRUE.

Usage

get_type_check_mingen_vs_maxpower_to_trigger(
  area,
  opts = antaresRead::simOptions()
)

Arguments

Value

a character containing the type of control to execute.

Note

Function called only for an Antares version >= 860.

Check dimension of time series for binding constraints

Description

Only needed for study version >= 870

Dimension of groups are compared with meta parameter binding returned by antaresRead::simOptions()

Usage

group_values_meta_check(
  group_value,
  values_data,
  operator_check,
  output_operator,
  opts = antaresRead::simOptions()
)

Arguments

Value

NULL if it's new group to add or error exceptions with dimension control

An updated list containing various information about the simulation.

Import a local study to Antares Web

Description

Import a local study to Antares Web

Usage

importZipStudyWeb(
  host,
  token,
  zipfile_name,
  delete_zipfile = TRUE,
  folder_destination = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Output pollutants list for thermal clusters

Description

Output pollutants list for thermal clusters

Usage

list_pollutants_values(multi_values = NULL)

Arguments

Value

a named list

Examples

list_pollutants_values()

Mock API usage

Description

Use this to generate command without an active API connection, it allow to use function to edit a study to later on get API commands.

Usage

mockSimulationAPI(force = FALSE, antares_version = "8.2.0")

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 
# Mock simulation API
mockSimulationAPI()
# Create an area
createArea("new area")
# Get commands
getVariantCommands()

## End(Not run)

Nodal optimization parameters for creating an area

Description

Nodal optimization parameters for creating an area

Usage

nodalOptimizationOptions(
  non_dispatchable_power = TRUE,
  dispatchable_hydro_power = TRUE,
  other_dispatchable_power = TRUE,
  spread_unsupplied_energy_cost = 0,
  spread_spilled_energy_cost = 0,
  average_unsupplied_energy_cost = 0,
  average_spilled_energy_cost = 0
)

Arguments

Value

a named list

Examples

nodalOptimizationOptions()

Get the playlist of an Antares study

Description

getPlaylist gives the identifier of the MC years which will be simulated in the Antares study, taking into account the potential use of a playlist which can skip some MC years

setPlaylist is a function which modifies the input file of an ANTARES study and set the playlist in order to simulate only the MC years given in input

Usage

getPlaylist(opts = antaresRead::simOptions())

setPlaylist(playlist, weights = NULL, opts = antaresRead::simOptions())

Arguments

Value

• getPlaylist returns a vector of the identifier of the simulated MC year.

• setPlaylist does not return anything. It is used to modify the input of an Antares study.

Examples

## Not run: 
setSimulationPath("PATH/TO/STUDY/")
# or 
setSimulationPathAPI(
  host = "http://localhost:8080",
  study_id = "6f98a393-155d-450f-a581-8668dc355235",
  token = NULL,
  simulation = "input"
)

# augment number of MC years
updateGeneralSettings(nbyears = 10)

# Get the actual playlist
getPlaylist()
# [1] 2 4 6

# set a new playlist
setPlaylist(c(3, 5, 7))

## End(Not run)

Properties for creating a link

Description

Properties for creating a link

Usage

propertiesLinkOptions(
  hurdles_cost = FALSE,
  transmission_capacities = "enabled",
  asset_type = "ac",
  display_comments = TRUE,
  filter_synthesis = c("hourly", "daily", "weekly", "monthly", "annual"),
  filter_year_by_year = c("hourly", "daily", "weekly", "monthly", "annual")
)

Arguments

Value

A named list that can be used in createLink().

Examples

## Not run: 
propertiesLinkOptions(
  hurdles_cost = TRUE,
  filter_synthesis=c("hourly","daily"),
  filter_year_by_year=c("weekly","monthly")
)

## End(Not run)

Remove an area from an Antares study

Description

Remove an area in an Antares study.

Usage

removeArea(name, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

See Also

createArea(), editArea()

Examples

## Not run: 
removeArea("fictive_area")

## End(Not run)

Remove a Binding Constraint

Description

Remove a binding constraint in an Antares study.

Usage

removeBindingConstraint(
  name = NULL,
  group = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Note

Starting with version v8.7.0, you can delete binding constraints by name or by group.

See Also

Other binding constraints functions: createBindingConstraintBulk(), createBindingConstraint(), editBindingConstraint()

Examples

## Not run: 
# < v8.7.0 :
removeBindingConstraint(name = "mybindingconstraint")

# >= v8.7.0 (delete by names group) :
# read
bc <- readBindingConstraints()

# select all groups
group_to_delete <- sapply(bc, function(x){
  x$properties$group
})

# delete all groups
removeBindingConstraint(group = group_to_delete)

## End(Not run)

Remove a cluster

Description

Delete cluster(s), thermal, renewable (renewable energy source) or short-term storage, along with all its data (properties + TS).

Usage

removeCluster(
  area,
  cluster_name,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

removeClusterRES(
  area,
  cluster_name,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

removeClusterST(
  area,
  cluster_name,
  add_prefix = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

createCluster(), createClusterRES() or createClusterST() to create new clusters, editCluster() or editClusterRES() or editClusterST() to edit existing clusters.

Examples

## Not run: 
createCluster(
  area = "fr", 
  cluster_name = "fr_gas",
  group = "other", 
  `marginal-cost` = 50
)

removeCluster(area = "fr", cluster_name = "fr_gas")

## End(Not run)

Remove a link between two areas

Description

Remove a link between two areas in an Antares study.

Usage

removeLink(from, to, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 
createLink(from = "myarea", to  = "myarea2")
removeLink(from = "myarea", to  = "myarea2")

## End(Not run)

Replicate a data.table as many times as needed to get the same number of time series between 2 data.tables

Description

Replicate a data.table as many times as needed to get the same number of time series between 2 data.tables

Usage

replicate_missing_ts(xts, yts)

Arguments

Value

the data.table x replicated to match the number of time series of y.

Rollback to previous hydro data if the data is not consistent

Description

Rollback the data to previous one if the check is KO. For a given area, check if the data is consistent and rollback to previous data if the check is KO.

Usage

rollback_to_previous_data(
  area,
  prev_data,
  rollback_type,
  opts = antaresRead::simOptions()
)

Arguments

Note

Function called only for an Antares version >= 860.

Run an Antares Simulation

Description

Run an ANTARES study

Usage

runSimulation(
  name,
  mode = "economy",
  path_solver = getOption("antares.solver"),
  wait = TRUE,
  show_output_on_console = FALSE,
  parallel = TRUE,
  ...,
  opts = antaresRead::simOptions()
)

Arguments

Value

In API mode it return a list with either the job id in case of success of the command or details about the error produce. In non-API mode the function does not return anything, it is used to launch an ANTARES simulation.

Run Time-Series Generator

Description

Usage

runTsGenerator(
  path_solver = getOption("antares.solver"),
  wait = TRUE,
  show_output_on_console = FALSE,
  opts = antaresRead::simOptions()
)

Arguments

Examples

## Not run: 
library(antaresRead)
setSimulationPath(path = "path/to/study")

library(antaresEditObject)
runTsGenerator(
  path_solver = "path/to/antares-6.0-solver.exe", 
  show_output_on_console = TRUE
)

## End(Not run)

Read, create, update & deduplicate scenario builder

Description

Read, create, update & deduplicate scenario builder.

Usage

scenarioBuilder(
  n_scenario = 1,
  n_mc = NULL,
  areas = NULL,
  areas_rand = NULL,
  group_bc = NULL,
  group_bc_rand = NULL,
  coef_hydro_levels = NULL,
  mode = NULL,
  opts = antaresRead::simOptions()
)

readScenarioBuilder(
  ruleset = "Default Ruleset",
  as_matrix = TRUE,
  opts = antaresRead::simOptions()
)

updateScenarioBuilder(
  ldata,
  ruleset = "Default Ruleset",
  series = NULL,
  clusters_areas = NULL,
  links = NULL,
  opts = antaresRead::simOptions()
)

clearScenarioBuilder(
  ruleset = "Default Ruleset",
  opts = antaresRead::simOptions()
)

deduplicateScenarioBuilder(
  ruleset = "Default Ruleset",
  opts = antaresRead::simOptions()
)

Arguments

Value

scenarioBuilder : a matrix

readScenarioBuilder : a list of matrix or list according to as_matrix parameters.

Note

• series = "ntc" is only available with Antares >= 8.2.0.

• For series = "hl", each value must be between 0 and 1.

• User must enable/disable custom-scenario property in settings/generaldata.ini by himself.

• series = "bc" is only available with Antares >= 8.7.0.

For a single matrix, value of series can be :

• h or hydro

• hl or hydrolevels

• l or load

• ntc

• r or renewables

• s or solar

• t or thermal

• w or wind

See Also

Scenario Builder vignette

Examples

## Not run: 

library(antaresRead)
library(antaresEditObject)

# simulation path
setSimulationPath(
  path = "pat/to/simulation",
  simulation = "input"
)

# Create a scenario builder matrix
sbuilder <- scenarioBuilder(
  n_scenario = 51,
  n_mc = 2040,
  areas_rand = c("fr", "be")
)
sbuilder[, 1:6]
dim(sbuilder)

# Create a scenario builder matrix for hydro levels (use case 1)
sbuilder <- scenarioBuilder(
  n_mc = opts$parameters$general$nbyears,
  areas = c("fr", "be"),
  coef_hydro_levels = c(0.1, 0.9)
)

# Create a scenario builder matrix for hydro levels (use case 2)
sbuilder <- scenarioBuilder(
  n_mc = opts$parameters$general$nbyears,
  areas = c("fr", "be"),
  coef_hydro_levels = c(runif(opts$parameters$general$nbyears)
  , runif(opts$parameters$general$nbyears)
  )
)

# Create a scenario builder matrix with 
 # bindings constraints groups (study version >= 8.7.0)
  # Use parameter "mode" with "bc"   
sbuilder <- scenarioBuilder(
  n_scenario = 51,
  n_mc = 2040,
  group_bc = c("my_bc_1", "my_bc_2"), 
  group_bc_rand = "my_bc_2",
  mode = "bc"
)

# Read previous scenario builder
# in a matrix format
prev_sb <- readScenarioBuilder()


# Update scenario builder

# Single matrix for load serie
updateScenarioBuilder(ldata = sbuilder, series = "load") # can be l instead of load

# equivalent as
updateScenarioBuilder(ldata = list(l = sbuilder))

# for binding constraints (study version >= 8.7.0)
updateScenarioBuilder(ldata = sbuilder, series = "bc")

# update several series

# same input
sbuilder
updateScenarioBuilder(
  ldata = sbuilder, 
  series = c("load", "hydro", "solar")
)

# List of matrix
updateScenarioBuilder(ldata = list(
  l = load_sb,
  h = hydro_sb,
  s = solar_sb
))

# Deduplicate scenario builder

deduplicateScenarioBuilder()

## End(Not run)

Search study in AntaREST

Description

Search study in AntaREST

Usage

searchStudy(
  workspace = NULL,
  folder = NULL,
  name = NULL,
  ...,
  host = NULL,
  token = NULL
)

Arguments

Value

a data.table with informations about studies on the server.

Examples

## Not run: 

searchStudies(host = "http://localhost:8080")


## End(Not run)

Set API mode

Description

Two modes are available when using the API:

• async: record all API calls, but nothing is sent to the server

• sync: send query to the API each time a function is used

Usage

setAPImode(mode = c("sync", "async"), opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 
# See vignette for complete documentation
vignette("api-variant-management")

# Usage :
setAPImode("sync")


## End(Not run)

Set path to Antares Solver

Description

Set path to Antares Solver

Usage

setSolverPath(path)

Arguments

Examples

## Not run: 

setSolverPath(path = "C:/antares/bin/antares-6.0-solver.exe")


## End(Not run)

Short Term Storage Property List

Description

Default values are returned according to study version

Usage

storage_values_default(opts = simOptions())

Arguments

Value

An updated list containing various information about the simulation.

a named list

Examples

## Not run: 
storage_values_default()

## End(Not run)

Update adequacy parameters of an Antares study

Description

Update adequacy parameters of an Antares study

Usage

updateAdequacySettings(
  include_adq_patch = NULL,
  set_to_null_ntc_from_physical_out_to_physical_in_for_first_step = NULL,
  set_to_null_ntc_between_physical_out_for_first_step = NULL,
  include_hurdle_cost_csr = NULL,
  check_csr_cost_function = NULL,
  enable_first_step = NULL,
  price_taking_order = NULL,
  threshold_initiate_curtailment_sharing_rule = NULL,
  threshold_display_local_matching_rule_violations = NULL,
  threshold_csr_variable_bounds_relaxation = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

updateAdequacySettings(
  include_adq_patch = TRUE,
  set_to_null_ntc_from_physical_out_to_physical_in_for_first_step = TRUE,
  set_to_null_ntc_between_physical_out_for_first_step = TRUE
)


## End(Not run)

Update general parameters of an Antares study

Description

Update general parameters of an Antares study

Usage

updateGeneralSettings(
  mode = NULL,
  horizon = NULL,
  nbyears = NULL,
  simulation.start = NULL,
  simulation.end = NULL,
  january.1st = NULL,
  first.month.in.year = NULL,
  first.weekday = NULL,
  leapyear = NULL,
  year.by.year = NULL,
  derated = NULL,
  custom.scenario = NULL,
  custom.ts.numbers = deprecated(),
  user.playlist = NULL,
  filtering = NULL,
  active.rules.scenario = NULL,
  generate = NULL,
  nbtimeseriesload = NULL,
  nbtimeserieshydro = NULL,
  nbtimeserieswind = NULL,
  nbtimeseriesthermal = NULL,
  nbtimeseriessolar = NULL,
  refreshtimeseries = NULL,
  intra.modal = NULL,
  inter.modal = NULL,
  refreshintervalload = NULL,
  refreshintervalhydro = NULL,
  refreshintervalwind = NULL,
  refreshintervalthermal = NULL,
  refreshintervalsolar = NULL,
  readonly = NULL,
  geographic.trimming = NULL,
  thematic.trimming = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

Antares General Reference Guide

Examples

## Not run: 

# Update number of Monte-Carlo years
updateGeneralSettings(nbyears = 42)

# Use a vector to update a parameter that
# can take multiple values
updateGeneralSettings(generate = c("thermal", "hydro"))


## End(Not run)

Update input parameters of an Antares study

Description

Update input parameters of an Antares study

Usage

updateInputSettings(import, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

updateInputSettings(import = c("thermal"))
updateInputSettings(import = c("hydro", "thermal"))


## End(Not run)

Update optimization parameters of an Antares study

Description

Update optimization parameters and other preferences of an Antares study

Usage

updateOptimizationSettings(
  simplex.range = NULL,
  transmission.capacities = NULL,
  include.constraints = NULL,
  include.hurdlecosts = NULL,
  include.tc.min.stable.power = NULL,
  include.tc.min.up.down.time = NULL,
  include.dayahead = NULL,
  include.strategicreserve = NULL,
  include.spinningreserve = NULL,
  include.primaryreserve = NULL,
  include.exportmps = NULL,
  solver.log = NULL,
  power.fluctuations = NULL,
  shedding.strategy = NULL,
  shedding.policy = NULL,
  unit.commitment.mode = NULL,
  number.of.cores.mode = NULL,
  renewable.generation.modelling = NULL,
  day.ahead.reserve.management = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

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


## End(Not run)

Update output parameters of an Antares study

Description

Update output parameters of an Antares study

Usage

updateOutputSettings(
  synthesis = NULL,
  storenewset = NULL,
  archives = NULL,
  result.format = NULL,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

See Also

Antares General Reference Guide

Examples

## Not run: 

updateOutputSettings(
  synthesis = TRUE,
  storenewset = FALSE,
  archives = c("load", "wind"),
  result.format = "zip"
)


## End(Not run)

Update a specific section in generaldata.ini file

Description

Update a specific section in generaldata.ini file

Usage

update_generaldata_by_section(opts, section, new_params)

Arguments

Value

An updated list containing various information about the simulation.

Create a study's variant

Description

API: create a new variant for a given study or use a pre-existing one.

Usage

createVariant(name, opts = antaresRead::simOptions())

useVariant(name, variant_id = NULL, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 
# See vignette for complete documentation
vignette("api-variant-management")

## End(Not run)

Get API commands generated

Description

Get API commands generated

Usage

getVariantCommands(
  last = NULL,
  actions = NULL,
  opts = antaresRead::simOptions()
)

writeVariantCommands(
  path,
  last = NULL,
  actions = NULL,
  ...,
  opts = antaresRead::simOptions()
)

Arguments

Value

a list of commands to edit a variant

Write configuration options in file or API

Description

Write configuration options in file or API

Usage

writeIni(
  listData,
  pathIni,
  opts = antaresRead::simOptions(),
  ...,
  default_ext = ".ini"
)

writeIniFile(listData, pathIni, overwrite = FALSE)

writeIniAPI(listData, pathIni, opts)

Arguments

Examples

## Not run: 
pathIni <- "D:/exemple_test/settings/generaldata.ini"
generalSetting <- readIniFile(pathIni)
generalSetting$output$synthesis <- FALSE
writeIni(generalSetting, pathIni)

## End(Not run)

Write Economic Options

Description

This function allows to create or edit economic options. Areas/options present in the input dataframe are edited, while all other values are left unchanged.

Usage

writeEconomicOptions(x, opts = antaresRead::simOptions())

Arguments

Examples

## Not run: 

library(antaresRead)

# Set simulation path
setSimulationPath(path = "PATH/TO/SIMULATION", simulation = "input")

# Write some economic options for areas a, b and c
writeEconomicOptions(data.frame(
  area = c("a", "b", "c"),
  dispatchable_hydro_power = c(TRUE, FALSE, FALSE),
  spread_unsupplied_energy_cost = c(0.03, 0.024, 0.01),
  average_spilled_energy_cost = c(10, 8, 8),
  stringsAsFactors = FALSE
))


## End(Not run)

Write Hydro Values

Description

Write waterValues, reservoirLevels, maxpower, inflowPattern and creditModulations data for a given area.

Usage

writeHydroValues(
  area,
  type,
  data,
  overwrite = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Warning

For an Antares version >= 860, control of data consistency between mingen.txt and ⁠maxpower_<area>.txt⁠ can be executed.

This control depends on the values you find in hydro.ini file.

Examples

## Not run: 

writeHydroValues("fictive_area", type = "inflowPattern", data = matrix(rep(0, 365*1), nrow = 365))


## End(Not run)

Edit hydro.ini values

Description

For a given area, write its data in the hydro.ini file.

Usage

writeIniHydro(area, params, mode = "other", opts = antaresRead::simOptions())

Arguments

Warning

For an Antares version >= 860, control of data consistency between mingen.txt and mod.txt can be executed.

For an Antares version >= 860, control of data consistency between mingen.txt and ⁠maxpower_<area>.txt⁠ can be executed.

These controls depend on the values you find in hydro.ini file.

Examples

## Not run: 
opts <- setSimulationPath(studypath, simulation = "input")
createArea("fictive_area") 
writeIniHydro(area = "fictive_area"
, params = list("leeway low" = 2.5, "leeway up" = 25))


## End(Not run)

Write input time series

Description

This function writes input time series in an Antares project.

Usage

writeInputTS(
  data,
  type = c("load", "hydroROR", "hydroSTOR", "mingen", "wind", "solar", "tsLink"),
  area = NULL,
  link = NULL,
  overwrite = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Value

An updated list containing various information about the simulation.

Warning

You cannot use area and link arguments at the same time.

For an Antares version >= 860, control of data consistency between mingen.txt and mod.txt can be executed.

These controls depend on the values you find in hydro.ini file.

Note

For an Antares version >= 860, the mingen.txt file is created.

The mingen.txt file can be created under two conditions:

• The number of columns must be equal to either 1 or the number in mod.txt

• If the mod.txt file is empty or has one column, then there is no dimension constraint

Examples

## Not run: 

# Write solar time series
writeInputTS(
  area = "fictive_area",
  type = "solar",
  data = matrix(rep(4, 8760*2), nrow = 8760)
)


## End(Not run)

Write Misc Gen data

Description

Usage

writeMiscGen(data, area, opts = antaresRead::simOptions())

Arguments

Value

An updated list containing various information about the simulation.

Examples

## Not run: 

writeMiscGen(matrix(data = c(rep(0, 8760 * 7), rep(-100000, 8760)), ncol = 8), "area1")


## End(Not run)

Write output value for Antares

Description

This function write all output values for an Antares study.

Usage

writeOutputValues(data, opts = NULL)

Arguments

Examples

## Not run: 

library(antaresRead)
library(data.table)
opts <- setSimulationPath("my_study")
data <- readAntares(links = "all", areas = "all", clusters = "all")
writeOutputValues(data)


## End(Not run)

Write prepro data

Description

This function allows to write load, wind and solar prepro data. Using character(0) allows to erase data (cf Examples).

Usage

writeSeriesPrepro(
  area,
  type = c("load", "wind", "solar"),
  coefficients = NULL,
  daily_profile = NULL,
  translation = NULL,
  conversion = NULL,
  overwrite = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Examples

## Not run: 

writeSeriesPrepro("fictive_area", type = "solar", daily_profile = matrix(rep(1, 24*12), nrow = 24))

# Erase daily profile data:
writeSeriesPrepro("fictive_area", type = "solar", daily_profile = character(0))


## End(Not run)

Write water values

Description

Write water values for a given area.

Usage

writeWaterValues(
  area,
  data = NULL,
  overwrite = TRUE,
  opts = antaresRead::simOptions()
)

Arguments

Examples

## Not run: 

writeWaterValues("fictive_area", data = matrix(rep(0, 365*101), nrow = 365))


## End(Not run)