---
title: "Antares new features v9.3"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Antares new features v9.3}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(antaresEditObject)
```

This article will present the new features in line with **Antares v9.3** (cf  [Antares Simulator](https://antares-simulator.readthedocs.io/en/latest/user-guide/04-migration-guides/#v930))

## Create new study v9.3

```{r init}
dir_path <- tempdir()
suppressWarnings(
  createStudy(path = dir_path, 
            study_name = "test930", 
            antares_version = "9.3")
)

```

For Antares Simulator, format version is now "9.3". For packages, we make the adjustment and we keep "930". 

**Check version of my current study** : 

```{r}
current_study_opts <- simOptions()
current_study_opts$antaresVersion
```

Some minor changes to the creation of the study. 

Initializes the study by updating the `generaldata.ini` file :  

  - The following properties were removed from settings/generaldata.ini.

    - refreshtimeseries
    - refreshintervalload
    - refreshintervalhydro
    - refreshintervalwind
    - refreshintervalthermal
    - refreshintervalsolar

## Create area 

We just need create *areas* to create *st-storages*. 
```{r areas}
createArea(name = "fr")
createArea(name = "it")
```

## Short term storage

We can create new clusters, st-storage (from v8.6), with function `createClusterST()`. You can see function documentation with `?createClusterST`.  

By default you can call function only with two parameters (`area`, `cluster_name`). 

Clusters are created with default properties and time series.


### New properties

you can create or edit new clusters with new properties (see doc `?createClusterST`). 

```{r default values}
# new properties (default values)
rmarkdown::paged_table(as.data.frame(storage_values_default(), check.names = FALSE))
```

```{r creation/properties}
# creation
my_parameters <- storage_values_default()
my_parameters$`allow-overflow` <- TRUE

createClusterST(area = "fr", 
                cluster_name = "test_storage", 
                group = "new_properties", 
                storage_parameters = my_parameters, 
                overwrite = TRUE)

createClusterST(area = "it", 
                cluster_name = "test_storage", 
                group = "new_properties", 
                storage_parameters = my_parameters,
                overwrite = TRUE)

# read cluster properties 
tab <- readClusterSTDesc()
rmarkdown::paged_table(tab)
```

```{r edit/properties}
# edit properties of existing st-storage cluster
my_parameters$`allow-overflow` <- FALSE

editClusterST(area = "fr", 
              cluster_name = "test_storage",
              storage_parameters = my_parameters)

# read cluster properties 
tab <- readClusterSTDesc()
rmarkdown::paged_table(tab)
```

### New dimension of **time series**

All matrices will be of (8760, N), noting that N >= 1
  

```{r create/ts}
# creation
ratio_value <- matrix(0.7, 8760,2)
  
# default properties with new optional TS
createClusterST(area = "fr", 
                cluster_name = "good_ts_value", 
                cost_injection = ratio_value, 
                cost_withdrawal = ratio_value, 
                cost_level = ratio_value, 
                cost_variation_injection = ratio_value,
                cost_variation_withdrawal = ratio_value)

# read cluster TS values 
tab <- readInputTS(st_storage = "all", 
                   showProgress = FALSE)
rmarkdown::paged_table(head(tab))
```

```{r edit/ts}
# edit TS values of existing st-storage cluster
new_ratio_value <- matrix(0.85, 8760,3)

# edit everything or anyone you want 
editClusterST(area = "fr",
              cluster_name = "good_ts_value",
              cost_injection = new_ratio_value, 
              cost_withdrawal = new_ratio_value)

# read cluster TS values 
tab <- readInputTS(st_storage = "all", 
                   showProgress = FALSE)
rmarkdown::paged_table(head(tab))
```

### Additional 

All RHS will be of (8760, N), noting that N >= 1

```{r, message=FALSE}
# Create
good_ts <- matrix(0.7, nrow = 8760, ncol =3)
createClusterST(area = "fr",
                cluster_name = "RHS_new_dimensions",
                storage_parameters = my_parameters, 
                PMAX_injection = NULL, 
                PMAX_withdrawal = NULL, 
                inflows = NULL, 
                lower_rule_curve = NULL, 
                upper_rule_curve = NULL,
                cost_injection = NULL, 
                cost_withdrawal = NULL,
                cost_level = NULL,
                cost_variation_injection = NULL, 
                cost_variation_withdrawal =NULL,
                constraints_properties = list(
                  "test"=list(
                    variable = "withdrawal",
                    operator = "equal",
                    hours = c("[1,3,5]",
                              "[120,121,122,123,124,125,126,127,128]")
                    #enabled = FALSE
                  ),
                  "test2"=list(
                    variable = "netting",
                    operator = "less",
                    hours = c("[1, 168]")
                  )),
                # constraints_ts 
                constraints_ts = list(
                  "test" = good_ts,
                  "test2"    = good_ts
                ))

# Edit
good_ts <- matrix(0.7, nrow = 8760, ncol =2)
editClusterST (area = "fr",
                cluster_name = "RHS_new_dimensions",
               constraints_ts = list(
                 "test" = good_ts,
                 "test2"    = good_ts
               )  ,
               add_prefix = TRUE)
#Read
res=read_storages_constraints()
```


```{r, echo=FALSE, message=FALSE, warning=FALSE}
library(data.tree)
as.Node(res)
```

### Remove clusters

Nothing has changed to remove clusters.

```{r remove}
# read cluster names
levels(readClusterSTDesc()$cluster)

# remove a cluster
removeClusterST(area = "fr", 
                cluster_name = "good_ts_value")

# read cluster 
tab <- readClusterSTDesc()
rmarkdown::paged_table(tab)
```


## Generaldata

The “generaldata.ini” settings file (*settings/generaldata.ini*) contains several sections.

Antares Simulator v9.3 deletes some parameters: 

  - *general/refreshtimeseries*
  - *general/refreshintervalload*
  - *general/refreshintervalhydro*
  - *general/refreshintervalwind*
  - *general/refreshintervalthermal*
  - *general/refreshintervalsolar*

A message is displayed.

```{r generaldata}
# user messages
updateGeneralSettings(
  refreshtimeseries = 100,
  refreshintervalload = 100,
  refreshintervalhydro = 100,
  refreshintervalwind = 100,
  refreshintervalthermal = 100,
  refreshintervalsolar = 100)
 
```


## Scenario builder

The scenario builder allows you to use a new code `sts` for short-term storage inflows in the following format : sts,area,year,storage = TS number. 
The scenario builder allows you to use a new code `sta` for short-term storage additional constraints in the following format : sta,area,year,storage,constraint = TS number. 

```{r scenariobuilder}
#Add sts
createClusterST(area = "fr",
                cluster_name = "Scenario_builder_sts")
 
ldata <- scenarioBuilder(
  n_scenario = 5,
  n_mc = 5,
  areas = "fr"
)
 
updateScenarioBuilder(ldata = ldata,
                      series = "sts")

#Add sta
name_no_prefix <- "add_constraints_sta"
 
constraints_properties <- list(
  "withdrawal-1"=list(
    variable = "withdrawal",
    operator = "equal",
    hours = c("[1,3,5]",
              "[120,121,122,123,124,125,126,127,128]")
  ),
  "netting-1"=list(
    variable = "netting",
    operator = "less",
    hours = c("[1, 168]")
  ))
 
createClusterST(area = "fr",
                cluster_name = name_no_prefix,
                constraints_properties = constraints_properties)
 
ldata <- scenarioBuilder(
  n_scenario = 5,
  n_mc = 5,
  areas = "fr"
)
 
updateScenarioBuilder(ldata = ldata,
                      series = "sta")
  
readScenarioBuilder(as_matrix = TRUE) 
```

## Thematic

In settings/generaldata.ini, in section variables selection, the following variables were removed:

- *variables selection/NUCLEAR*
- *variables selection/LIGNITE*
- *variables selection/COAL*
- *variables selection/BATTERY*
- *variables selection/GAS*
- *variables selection/OIL*
- *variables selection/MIX. FUEL*
- *variables selection/MISC. DTG*
- *variables selection/MISC. DTG 2*
- *variables selection/MISC. DTG 3*
- *variables selection/MISC. DTG 4*
They're replaced by the dynamic variable DISPATCH. GEN.

The following variables were removed:

- *variables selection/WIND OFFSHORE*
- *variables selection/WIND ONSHORE*
- *variables selection/SOLAR CONCRT.*
- *variables selection/SOLAR PV*
- *variables selection/SOLAR ROOFT*
- *variables selection/RENW. 1*
- *variables selection/RENW. 2*
- *variables selection/RENW. 3*
- *variables selection/RENW. 4*
They're replaced by the dynamic variable RENEWABLE GEN.

```{r}
#List of variables version >=9.3
vector_select_vars= list_thematic_variables()
#Add all variables
list_thematic=setThematicTrimming(selection_variables = vector_select_vars$col_name[68:72])
list_thematic$parameters$`variables selection`
```


```{r delete study, include=FALSE}
# Delete study
unlink(current_study_opts$studyPath, 
       recursive = TRUE)
# clean global options
options(antares = NULL)
```


