Edit on GitHub

Manual

The PSRClassesInterface module provides interfaces to access data structured by PSR to be used in its models. Currently there are two main interfaces.

  • The interface for studies. This interface is designed to read parameters from the files, some examples are deficit costs, fuel costs, currency, storage capacity etc.
  • The interface for reading and writing time series data. Time series data in the context of most studies have 4 dimensions (agents, stages, scenarios and blocks). Since studies of renewables with multiple agents, scenarios and stages can get quite big, we have designed different formats that are optimized to some objective (human readability, size, fast reading and writing, etc.).

Both interfaces are defined as a set of methods that need to be implemented to make a different file format work. In this manual we will describe the abstract methods and give concrete examples of code to perform the work needed.

When using the PSRClassesInterface package in your codebase we strongly advise you to create a constant PSRI to keep the code concise and explicitly declare that a certain function came from PSRClassesInterface. This can be done by adding the following code to the top of the code

using PSRClassesInterface
const PSRI = PSRClassesInterface

Initialize Study

PSRClassesInterface.load_study — Function
load_study(::AbstractStudyInterface; kwargs...)

Initialize all data structures of the study.

Differences between the OpenInterface and ClassicInterface

Each study interface has its own set of kwargs... The easiest way to inspect the current available options is searching for this function on the Github repo of the desired interface.

Example:

data = PSRI.load_study(
    PSRI.OpenInterface();
    data_path = PATH_CASE_EXAMPLE_BATTERIES,
)
source
PSRClassesInterface.max_elements — Function
max_elements(data::AbstractData, collection::String)

Returns an Int32 with the maximum number of elements for a given collection.

Example:

PSRI.max_elements(data, "PSRThermalPlant")
source

Study dimensions

PSRClassesInterface.StageType — Type
PSRI.StageType

Possible stage types used in for reading and writing time series files.

The current possible stage types are:

STAGE_UNKNOWN
STAGE_WEEK
STAGE_MONTH
STAGE_3MONTHS
STAGE_HOUR
STAGE_DAY
STAGE_13MONTHS
STAGE_2MONTHS
STAGE_4MONTHS
STAGE_6MONTHS
STAGE_YEAR
STAGE_DECADE
source

Study duration and blocking

PSRClassesInterface.BlockDurationMode
PSRClassesInterface.stage_duration
PSRClassesInterface.block_duration
PSRClassesInterface.block_from_stage_hour

Read Scalar Attributes

PSRClassesInterface.configuration_parameter — Function
configuration_parameter(
    data::AbstractData,
    attribute::String,
    default::T
) where T <: MainTypes

Returns the required configuration parameter from the case. If the parameter is not registered returns the default value.

configuration_parameter(
    data::AbstractData,
    attribute::String,
    default::Vector{T},
) where T <: MainTypes

Returns the rquired configuration parameters from the case that are vectors that are vectors. If the parameter is not registered returns the default value.

Examples:

PSRI.configuration_parameter(data, "MaximoIteracoes", 0)
PSRI.configuration_parameter(data, "MinOutflowPenalty", 0.0)
PSRI.configuration_parameter(data, "DeficitCost", [0.0])
source
PSRClassesInterface.get_code — Function
get_code(data::AbstractData, collection::String)

Returns a Vector{Int32} containing the code of each element in collection.

Example:

PSRI.get_code(data, "PSRThermalPlant")
source
PSRClassesInterface.get_name — Function
get_name(data::AbstractData, collection::String)

Returns a Vector{String} containing the name of each element in collection.

Example:

PSRI.get_name(data, "PSRThermalPlant")
PSRI.get_name(data, "PSRGaugingStation")
source
PSRClassesInterface.get_parm — Function
get_parm(
    data::AbstractData,
    collection::String,
    attribute::String,
    index::Integer,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a T containing the the value from attribute of collection. This function is used to get data from collections that don't vary over time.

Example:

PSRI.get_parm(data, "PSRBattery", "Einic", Float64, 1)
PSRI.get_parm(data, "PSRBattery", "ChargeRamp", Float64, 1)
PSRI.get_parm(data, "PSRBattery", "DischargeRamp", Float64, 1)
source
PSRClassesInterface.get_parm_1d — Function
get_parm_1d(
    data::AbstractData,
    collection::String,
    attribute::String,
    index::Integer,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a T containing the the value from attribute of collection. This function is used to get data from collections that don't vary over time.

Example:

PSRI.get_parm_1d(data, "PSRHydroPlant", "FP", Float64, 1)
PSRI.get_parm_1d(data, "PSRHydroPlant", "FP.VOL", Float64, 1)
source
PSRClassesInterface.get_parms — Function
get_parms(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T};
    validate::Bool = true,
    ignore::Bool = false,
    default::T = _default_value(T),
) where T

Returns a Vector{T} containing the elements in collection to a vector in julia. This function is used to get data from collections that don't vary over time

Example:

PSRI.get_parms(data, "PSRBattery", "Einic", Float64)
PSRI.get_parms(data, "PSRBattery", "ChargeRamp", Float64)
PSRI.get_parms(data, "PSRBattery", "DischargeRamp", Float64)
source
PSRClassesInterface.get_parms_1d — Function
get_parms_1d(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T};
    validate::Bool = true,
    ignore::Bool = false,
    default::T = _default_value(T),
) where T

Returns a Vector{T} containing the elements in collection to a vector in julia. This function is used to get data from collections that don't vary over time

Example:

PSRI.get_parm_1d(data, "PSRHydroPlant", "FP", Float64)
PSRI.get_parm_1d(data, "PSRHydroPlant", "FP.VOL", Float64)
source

Read Vector Attributes

Time controller

PSRClassesInterface.mapped_vector — Function
mapped_vector(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T},
    dim1::String="",
    dim2::String="";
    ignore::Bool=false,
    map_key = collection, # reference for PSRMap pointer, if empty use class name
    filters = String[], # for calling just within a subset instead of the full call
) where T

Maps a Vector{T} containing the elements in collection to a vector in julia. When the function update_vectors! is called the elements of the vector will be updated to the according elements registered at the current data.time_controller.

Example:

existing = PSRI.mapped_vector(data, "PSRThermalPlant", "Existing", Int32)
pot_inst = PSRI.mapped_vector(data, "PSRThermalPlant", "PotInst", Float64)

For more information please read the example Reading basic thermal generator parameters

Differences between the OpenInterface and ClassicInterface

When using mapped_vector in the OpenInterface mode the vector will be mapped with the correct values at first hand. When using mapped_vector in the ClassicInterface mode you should call update_vectors! to get the good values for the collection, otherwise you might only get a vector of zeros.

source
PSRClassesInterface.go_to_dimension — Function
go_to_dimension(data::AbstractData, name::String, value::Integer)

Moves time controller reference of vectors indexed by dimension name to the index value.

Example:

cesp = PSRI.mapped_vector(data, "PSRThermalPlant", "CEsp", Float64, "segment", "block")

PSRI.go_to_stage(data, 1)

PSRI.go_to_dimension(data, "segment", 1)
PSRI.go_to_dimension(data, "block", 1)
source
PSRClassesInterface.update_vectors! — Function
update_vectors!(data::AbstractData)

Update all mapped vectors according to the time controller inside data.

update_vectors!(data::AbstractData, filters::Vector{String})

Update filtered classes of mapped vectors according to the time controller inside data.

source

Direct access

PSRClassesInterface.get_vector — Function
PSRI.get_vector(
    data::AbstractData,
    collection::String,
    attribute::String,
    index::Integer,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a Vector{T} of entries of the attribute of collection at the element with index index.

Example:

PSRI.get_vector(data, "PSRGaugingStation", "Vazao", 1, Float64)
PSRI.get_vector(data, "PSRGaugingStation", "Data", 1, Dates.Date)
source
PSRClassesInterface.get_vector_1d — Function
PSRI.get_vector_1d(
    data::AbstractData,
    collection::String,
    attribute::String,
    index::Integer,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a Vector{Vector{T}} of entries of the attribute of collection at the element with index index. The outer vector contains one entry per index in dimension 1, while the inner vector is sized according to the main vector index which is tipicaaly time.

Example:

PSRI.get_vector_1d(data, "PSRArea", "Export", 1, Float64)
PSRI.get_vector_1d(data, "PSRLoad", "P", 1, Float64)
source
PSRClassesInterface.get_vector_2d — Function
PSRI.get_vector_2d(
    data::AbstractData,
    collection::String,
    attribute::String,
    index::Integer,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a Matrix{Vector{T}} of entries of the attribute of collection at the element with index index. The outer matrix contains one entry per index in dimension 1 and dimension 2, while the inner vector is sized according to the main vector index which is tipicaaly time.

Example:

PSRI.get_vector_2d(data, "PSRThermalPlant", "CEsp", 1, Float64)
PSRI.get_vector_2d(data, "PSRFuelConsumption", "CEsp", 1, Float64)
source
PSRClassesInterface.get_vectors — Function
PSRI.get_vectors(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T};
    default::T = _default_value(T),
) where T

Returns a Vector{Vector{T}} of entries of the attribute of collection. Each entry of the outer vector corresponding to an element of the collection.

Example:

PSRI.get_vectors(data, "PSRGaugingStation", "Vazao", Float64)
PSRI.get_vectors(data, "PSRGaugingStation", "Data", Dates.Date)
source
PSRClassesInterface.get_vectors_1d — Function
PSRI.get_vectors_1d(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T},
) where T

Returns a Vector{Vector{Vector{T}}} of entries of the attribute of collection. Each entry of the outer vector corresponding to an element of the collection. For the containt of the 2 inner vectors see get_vector_1d.

Example:

PSRI.get_vectors_1d(data, "PSRArea", "Export", Float64)
PSRI.get_vectors_1d(data, "PSRLoad", "P", Float64)
source
PSRClassesInterface.get_vectors_2d — Function
PSRI.get_vectors_2d(
    data::AbstractData,
    collection::String,
    attribute::String,
    ::Type{T},
) where T

Returns a Vector{Matrix{Vector{T}}} of entries of the attribute of collection. Each entry of the outer vector corresponding to an element of the collection. For the containt of the Matrix{Vector{T}} see get_vector_2d.

Example:

PSRI.get_vectors_2d(data, "PSRThermalPlant", "CEsp", Float64)
PSRI.get_vectors_2d(data, "PSRFuelConsumption", "CEsp", Float64)
source
PSRClassesInterface.get_nonempty_vector — Function
get_nonempty_vector(
    data::AbstractData,
    colllection::String,
    attribute::String,
)

Returns a vector of booleans with the number of elements of the collection. true means the vector associated with the given attribute is non-emepty, false means it is empty.

Example:

PSRI.get_nonempty_vector(data, "PSRThermalPlant", "ChroGerMin")
PSRI.get_nonempty_vector(data, "PSRThermalPlant", "SpinningReserve")
source
PSRClassesInterface.get_series — Function
function get_series(
    data::Data,
    collection::String,
    indexing_attribute::String,
    index::Int,
)

Retrieves a SeriesTable object with all attributes from an element that are indexed by index_attr.

Example

julia> PSRI.get_series(data, "PSRThermalPlant", "Data", 1)
Dict{String, Vector} with 13 entries:
  "GerMin"   => [0.0]
  "GerMax"   => [888.0]
  "NGas"     => [nothing]
  "IH"       => [0.0]
  "ICP"      => [0.0]
  "Data"     => ["1900-01-01"]
  "CoefE"    => [1.0]
  "PotInst"  => [888.0]
  "Existing" => [0]
  "sfal"     => [0]
  "NAdF"     => [0]
  "Unidades" => [1]
  "StartUp"  => [0.0]
source

Relations between collections

Missing docstring.

Missing docstring for PSRClassesInterface.RelationType. Check Documenter's build log for details.

PSRClassesInterface.get_references — Function
get_references(
    data::AbstractData,
    lst_from::String,
    lst_to::String;
    relation_type::RelationType = RELATION_1_TO_1, # type of the direct relation
)

Retrurn a Vector{String} with the references between collections given a certain RelationType.

source
PSRClassesInterface.get_vector_references — Function
get_vector_references(
    data::AbstractData,
    lst_from::String,
    lst_to::String;
    relation_type::RelationType = RELATION_1_TO_N, # type of the direct relation
)

Retrurn a Vector{Vector{String}} with the references between collections given a certain RelationType.

source
PSRClassesInterface.get_map — Function
get_map(
    data::AbstractData,
    lst_from::String,
    lst_to::String;
    allow_empty::Bool = true,
    relation_type::RelationType = RELATION_1_TO_1, # type of the direct relation
)

Returns a Vector{Int32} with the map between collections given a certain RelationType. If the map is a vector [3, 2, 1] it means that the element 1 of lst_from is related to the element 3 of lst_to. If the relation does not exist it might return -1 or some garbage value.

Examples:

PSRI.get_map(data, "PSRBattery", "PSRSystem")
PSRI.get_map(data, "PSRMaintenanceData", "PSRThermalPlant")

PSRI.get_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    relation_type = PSRI.PMD.RELATION_TURBINE_TO,
)
PSRI.get_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    relation_type = PSRI.PMD.RELATION_SPILL_TO,
)
PSRI.get_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    relation_type = PSRI.PMD.RELATION_INFILTRATE_TO,
)
PSRI.get_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    relation_type = PSRI.PMD.RELATION_STORED_ENERGY_DONWSTREAM,
)
source
PSRClassesInterface.get_vector_map — Function
get_vector_map(
    data::AbstractData,
    collection_from::String,
    collection_to::String;
    relation_type::RelationType = RELATION_1_TO_N,
)

Returns a Vector{Vector{Int32}} to represent the relation between each element of collection_from to multiple elements of collection_to.

Since multiple relations might be available one might need to specify relation_type.

Example:

PSRI.get_vector_map(data, "PSRInterconnectionSumData", "PSRInterconnection")
PSRI.get_vector_map(data, "PSRReserveGenerationConstraintData", "PSRHydroPlant")
PSRI.get_vector_map(
    data,
    "PSRReserveGenerationConstraintData",
    "PSRThermalPlant";
    relation_type = PSRI.PMD.RELATION_BACKED,
)
source
PSRClassesInterface.get_reverse_map — Function
get_reverse_map(
    data::AbstractData,
    lst_from::String,
    lst_to::String;
    original_relation_type::RelationType = RELATION_1_TO_1,
)

Obtains the relation between lst_from and lst_to though original_relation_type. But returns a Vector{Int32} with the relation reversed. Some relations cannot be reversed this way since they are not bijections, in this case use get_reverse_vector_map.

See also get_map, get_vector_map, get_reverse_vector_map.

Example:

PSRI.get_reverse_map(data, "PSRMaintenanceData", "PSRHydroPlant")
# which is te reverse of
PSRI.get_map(data, "PSRMaintenanceData", "PSRHydroPlant")

PSRI.get_reverse_map(data, "PSRGenerator", "PSRThermalPlant")
# which is the reverse of
PSRI.get_map(data, "PSRGenerator", "PSRThermalPlant")
source
PSRClassesInterface.get_reverse_vector_map — Function
get_reverse_vector_map(
    data::AbstractData,
    lst_from::String,
    lst_to::String;
    original_relation_type::RelationType = RELATION_1_TO_N,
)

Obtains the relation between lst_from and lst_to though original_relation_type. But returns a Vector{Vector{Int32}} with the relation reversed.

Some relations are bijections, in these cases it is also possible to use use get_reverse_map.

See also get_map, get_vector_map, get_reverse_vector_map.

Example:

# upstream turbining hydros
PSRI.get_reverse_vector_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    original_relation_type = PSRI.PMD.RELATION_TURBINE_TO,
)
# which is the reverse of
PSRI.get_map(
    data,
    "PSRHydroPlant",
    "PSRHydroPlant";
    relation_type = PSRI.PMD.RELATION_TURBINE_TO,
)

PSRI.get_reverse_vector_map(
    data,
    "PSRGenerator",
    "PSRBus";
    original_relation_type = PSRI.PMD.RELATION_1_TO_1,
)
# which is the reverse of
PSRI.get_map(data, "PSRGenerator", "PSRBus")
source
PSRClassesInterface.get_related — Function
get_related(
    data::AbstractData,
    source::String,
    target::String,
    source_index::Integer,
    relation_type = RELATION_1_TO_1,
)

Returns the index of the element in collection target related to the element in the collection source element indexed by source_index according to the scalar relation relation_type.

source
PSRClassesInterface.get_vector_related — Function
get_vector_related(
    data::AbstractData,
    source::String,
    target::String,
    source_index::Integer,
    relation_type = RELATION_1_TO_N,
)

Returns the vector of indices of the elements in collection target related to the element in the collection source element indexed by source_index according to the scalar relation relation_type.

source

Reflection

PSRClassesInterface.get_attribute_dim1 — Function
get_attribute_dim1(
    data::AbstractData,
    collection::String,
    attribute::string,
    index::Integer;
)

Returns the size of dimension 1 of attribute from collection at element index. Errors if attribute has zero dimensions.

source
PSRClassesInterface.get_attribute_dim2 — Function
get_attribute_dim2(
    data::AbstractData,
    collection::String,
    attribute::string,
    index::Integer;
)

Returns the size of dimension 2 of attribute from collection at element index. Errors if attribute has zero or one dimensions.

source
PSRClassesInterface.get_attribute_struct — Function
get_attribute_struct(
    data::AbstractData,
    collection::String,
    attribute::String,
)

Returns a struct of type Attribute with fields:

  • name::String = attribute name
  • is_vector::Bool = true if attribute is a vector (tipically, varies in time)
  • type::DataType = attribute type (tipically: Int32, Float64, String, Dates.Date)
  • dim::Int = number of additional dimensions
  • index::String = if a vector represents the indexing vector (might be empty)
source
PSRClassesInterface.get_data_struct — Function
get_attribute_struct(data::AbstractData)

Return a struct of type DataStruct with collection names (strings) as keys and maps from attributes names (string) to attributes data definitions Attribute.

source
PSRClassesInterface.get_attributes_indexed_by — Function
get_attributes_indexed_by(
    data::AbstractData,
    collection::String,
    indexing_attribute::String
)

Return Vector{String} of valid vector attributes from collection that are indexed by indexing_attribute.

source
PSRClassesInterface.get_relations — Function
get_relations(data::AbstractData, collection::String)

Returns a Tuple{String, Vector{PMD.Relation}} with relating collection and their relation type associated to collection.

source

Read and Write Graf files

Open and Close

PSRClassesInterface.open — Function
PSRI.open(::Type{<:AbstractWriter}, path::String; kwargs...)

Method for opening file and registering time series data. If specified file doesn't exist, the method will create it, otherwise, the previous one will be overwritten. Returns updated AbstractWriter instance.

Arguments:

  • writer: AbstractWriter instance to be used for opening file.

  • path: path to file.

Keyword arguments:

  • blocks: case's number of blocks.

  • scenarios: case's number of scenarios.

  • stages: case's number of stages.

  • agents: list of element names.

  • unit: dimension of the elements' data.

  • is_hourly: if data is hourly. If yes, block dimension will be ignored.

  • hour_discretization: sub-hour parameter to discretize an hour into minutes.

  • name_length: length of element names.

  • block_type: case's type of block.

  • scenarios_type: case's type of scenario.

  • stage_type: case's type of stage.

  • initial_stage: stage at which to start registry.

  • initial_year: year at which to start registry.

  • allow_unsafe_name_length: allow element names outside safety bounds.

Examples:

Method for opening file and reading time series data. Returns updated AbstractReader instance.

Arguments:

  • reader::Type{<:AbstractReader}: AbstractReader instance to be used for opening file.

  • path::String: path to file.

Keyword arguments:

  • is_hourly::Bool: if data to be read is hourly, other than blockly.

  • stage_type::PSRI.StageType: the PSRClassesInterface.StageType of the data, defaults to PSRI.STAGE_MONTH.

  • header::Vector{String}: if file has a header with metadata.

  • use_header::Bool: if data from header should be retrieved.

  • first_stage::Dates.Date: stage at which start reading.

  • verbose_header::Bool: if data from header should be displayed during execution.

Examples:

source

Write entire file

Write registry

PSRClassesInterface.write_registry — Function
PSRI.write_registry(
    iow::AbstractWriter,
    data::Vector{T},
    stage::Integer,
    scenario::Integer = 1,
    block::Integer = 1,
) where T <: Real

Writes a data row into opened file through PSRClassesInterface.AbstractWriter instance.

Arguments:

  • iow: PSRI.AbstractWriter instance to be used for accessing file.

  • data: elements data to be written.

  • stage: stage of the data to be written.

  • scenario: scenarios of the data to be written.

  • block: block of the data to be written.

source

Header information

Read entire file

PSRClassesInterface.file_to_array — Function
PSRI.file_to_array(::Type{T}, path::String; use_header::Bool = true, header::Vector{String} = String[]) where T <: AbstractReader

Write a file to an array

source

Read registry

PSRClassesInterface.goto — Function
PSRI.goto(
    ior::AbstractReader, 
    t::Integer, 
    s::Integer = 1, 
    b::Integer = 1
)

Goes to the registry of the stage t, scenario s and block b.

source

File conversion

Reader mapper

Missing docstring.

Missing docstring for PSRClassesInterface.add_reader!. Check Documenter's build log for details.

Modification API

PSRClassesInterface.create_element! — Function
create_element!(
    data::Data,
    collection::String,
    ps::Pair{String,<:Any};
    default::Union{Dict{String,Any},Nothing} = nothing
)

Creates a new instance of the given collection and returns its index.

Example:

index = PSRI.create_element!(data, "PSRClass")

PSRI.set_parm!(data, "PSRClass", index, "PSRAttr", value)
source
PSRClassesInterface.set_parm! — Function
set_parm!(
    data::Data,
    collection::String,
    attribute::String,
    index::Integer,
    value::T,
) where {T <: MainTypes}

Defines the value of a scalar parameter.

source
PSRClassesInterface.set_vector! — Function
function set_vector!(
    data::Data,
    collection::String,
    attribute::String,
    index::Int,
    buffer::Vector{T}
) where {T<:MainTypes}

Updates a data vector according to the given buffer. Note: Modifying current vector length is not allowed: use set_series! instead.

source
PSRClassesInterface.set_series! — Function
function set_series!(
    data::Data,
    collection::String,
    index_attr::String,
    index::Int,
    buffer::Dict{String,Vector}
)

Updates serial (indexed) data. All columns must be the same as before. The series length is allowed to be changed, but all vectors in the new series must have equal length.

julia> series = Dict{String, Vector}(
         "GerMin" => [0.0, 1.0],
         "GerMax" => [888.0, 777.0],
         "NGas" => [nothing, nothing],
         "IH" => [0.0, 0.0],
         "CoefE" => [1.0, 2.0],
         "PotInst" => [888.0, 777.0],
         "ICP" => [0.0, 0.0],
         "Data" => ["1900-01-01", "1900-01-02"],
         "Existing" => [0, 0],
         "sfal" => [0, 1],
         "NAdF" => [0, 0],
         "Unidades" => [1, 1],
         "StartUp" => [0.0, 2.0]
       );

julia> PSRI.set_series!(data, "PSRThermalPlant", 1, "Data", series)
source
PSRClassesInterface.set_related! — Function
set_related!(
    data::AbstractData,
    source::String,
    target::String,
    source_index::Integer,
    target_index::Integer;
    relation_type = RELATION_1_TO_1,
)

Sets the element source_index from collection source to be related to the element target_index from collection target in the scalar relation of type relation_type.

source
PSRClassesInterface.set_vector_related! — Function
set_vector_related!(
    data::AbstractData,
    source::String,
    target::String,
    source_index::Integer,
    target_index::Vector{<:Integer};
    relation_type = RELATION_1_TO_N,
)

Sets the element source_index from collection source to be related to the elements in target_index from collection target in the vector relation of type relation_type.

source