Format input data for different turbine and reservoir models

Many formulations require to properly specify the data models appropriately to be used correctly in the different available formulations

Turbine Data

Docstring provide good information on how to include data for turbines.

julia> using PowerSystems
julia> @doc HydroTurbine  mutable struct HydroTurbine <: HydroUnit
      name::String
      available::Bool
      bus::ACBus
      active_power::Float64
      reactive_power::Float64
      rating::Float64
      active_power_limits::MinMax
      reactive_power_limits::Union{Nothing, MinMax}
      base_power::Float64
      operation_cost::Union{HydroGenerationCost, MarketBidCost}
      powerhouse_elevation::Float64
      ramp_limits::Union{Nothing, UpDown}
      time_limits::Union{Nothing, UpDown}
      outflow_limits::Union{Nothing, MinMax}
      efficiency::Float64
      turbine_type::HydroTurbineType
      conversion_factor::Float64
      prime_mover_type::PrimeMovers
      travel_time::Union{Nothing, Float64}
      services::Vector{Service}
      dynamic_injector::Union{Nothing, DynamicInjection}
      ext::Dict{String, Any}
      internal::InfrastructureSystemsInternal
  end

  A hydropower generator that must have a HydroReservoir attached, suitable
  for modeling independent turbines and reservoirs.

  Arguments
  ≡≡≡≡≡≡≡≡≡

    •  name::String: Name of the component. Components of the same type
       (e.g., PowerLoad) must have unique names, but components of
       different types (e.g., PowerLoad and ACBus) can have the same name
    •  available::Bool: Indicator of whether the component is connected
       and online (true) or disconnected, offline, or down (false).
       Unavailable components are excluded during simulations
    •  bus::ACBus: Bus that this component is connected to
    •  active_power::Float64: Initial active power set point of the unit
       in MW. For power flow, this is the steady state operating point of
       the system. For production cost modeling, this may or may not be
       used as the initial starting point for the solver, depending on
       the solver used
    •  reactive_power::Float64: Initial reactive power set point of the
       unit (MVAR), validation range: reactive_power_limits
    •  rating::Float64: Maximum AC side output power rating of the unit.
       Stored in per unit of the device and not to be confused with
       base_power, validation range: (0, nothing)
    •  active_power_limits::MinMax: Minimum and maximum stable active
       power levels (MW), validation range: (0, nothing)
    •  reactive_power_limits::Union{Nothing, MinMax}: Minimum and maximum
       reactive power limits. Set to Nothing if not applicable
    •  base_power::Float64: Base power of the unit (MVA) for per
       unitization, validation range: (0.0001, nothing)
    •  operation_cost::Union{HydroGenerationCost, MarketBidCost}:
       (default: HydroGenerationCost(nothing)) OperationalCost of
       generation
    •  powerhouse_elevation::Float64: (default: 0.0) Height level in
       meters above the sea level of the powerhouse on which the turbine
       is installed., validation range: (0, nothing)
    •  ramp_limits::Union{Nothing, UpDown}: (default: nothing) ramp up
       and ramp down limits in MW/min, validation range: (0, nothing)
    •  time_limits::Union{Nothing, UpDown}: (default: nothing) Minimum up
       and Minimum down time limits in hours, validation range: (0,
       nothing)
    •  outflow_limits::Union{Nothing, MinMax}: (default: nothing) Turbine
       outflow limits in m3/s. Set to Nothing if not applicable
    •  efficiency::Float64: (default: 1.0) Turbine efficiency [0, 1.0],
       validation range: (0, 1)
    •  turbine_type::HydroTurbineType: (default:
       HydroTurbineType.UNKNOWN) Type of the turbine
    •  conversion_factor::Float64: (default: 1.0) Conversion factor from
       flow/volume to energy: m^3 -> p.u-hr
    •  prime_mover_type::PrimeMovers: (default: PrimeMovers.HY) Prime
       mover technology according to EIA 923. Options are listed here
    •  travel_time::Union{Nothing, Float64}: (default: nothing)
       Downstream (from reservoir into turbine) travel time in hours.
    •  services::Vector{Service}: (default: Device[]) Services that this
       device contributes to
    •  dynamic_injector::Union{Nothing, DynamicInjection}: (default:
       nothing) corresponding dynamic injection device
    •  ext::Dict{String, Any}: (default: Dict{String, Any}()) An extra
       dictionary for users to add metadata that are not used in
       simulation.
    •  internal::InfrastructureSystemsInternal: (Do not modify.)
       PowerSystems.jl internal reference

Energy Models

Energy models are characterized by their data is specified in power units (MW and per-unit) and energy units (MWh and per-unit-h). For turbines this is usually set-up with providing data in per-unit dependent on its base_power. powerhouse_elevation and outflow_limits are only relevant for water models.

TimeSeries data

Energy models for turbine such as HydroTurbineEnergyDispatch and HydroTurbineEnergyCommitment do not require time series input data.

Water Models

Water models still have their data specified in power units, but the powerhouse_elevation must be specified in meters, and outflow_limits specified in m³/s, bounds the water flowing through the turbine.

TimeSeries data

HydroTurbineBilinearDispatch and HydroWaterFactorModel models for turbine do not require time series input data.

Reservoir Data

Docstring provide good information on how to include data for reservoirs.

julia> using PowerSystems
julia> @doc HydroReservoir  mutable struct HydroReservoir <: Device
      name::String
      available::Bool
      storage_level_limits::MinMax
      initial_level::Float64
      spillage_limits::Union{Nothing, MinMax}
      inflow::Float64
      outflow::Float64
      level_targets::Union{Nothing, Float64}
      intake_elevation::Float64
      head_to_volume_factor::ValueCurve
      upstream_turbines::Vector{HydroUnit}
      downstream_turbines::Vector{HydroUnit}
      upstream_reservoirs::Vector{Device}
      operation_cost::HydroReservoirCost
      level_data_type::ReservoirDataType
      ext::Dict{String, Any}
      internal::InfrastructureSystemsInternal
  end

  A hydropower reservoir that have attached HydroTurbine(s) or
  HydroPumpTurbine(s) used to generate power. See How to Define Hydro
  Generators with Reservoirs for supported configurations.

  Arguments
  ≡≡≡≡≡≡≡≡≡

    •  name::String: Name of the component. Components of the same type
       (e.g., PowerLoad) must have unique names, but components of
       different types (e.g., PowerLoad and ACBus) can have the same name
    •  available::Bool: Indicator of whether the component is connected
       and online (true) or disconnected, offline, or down (false).
       Unavailable components are excluded during simulations
    •  storage_level_limits::MinMax: Storage level limits for the
       reservoir in m^3, m, or MWh, based on the ReservoirDataType
       selected for level_data_type
    •  initial_level::Float64: Initial level of the reservoir relative to
       the storage_level_limits.max.
    •  spillage_limits::Union{Nothing, MinMax}: Amount of water allowed
       to be spilled from the reservoir. If nothing, infinite spillage is
       allowed.
    •  inflow::Float64: Amount of water refilling the reservoir in m^3/h
       or MW (if level_data_type is ReservoirDataType.ENERGY).
    •  outflow::Float64: Amount of water naturally going out of the
       reservoir in m^3/h or MW (if level_data_type is
       ReservoirDataType.ENERGY).
    •  level_targets::Union{Nothing, Float64}: Reservoir level targets at
       the end of a simulation as a fraction of the
       storage_level_limits.max.
    •  intake_elevation::Float64: Height of the intake of the reservoir,
       towards the downstream turbines, in meters above the sea level.
    •  head_to_volume_factor::ValueCurve: Head to volume relationship for
       the reservoir.
    •  upstream_turbines::Vector{HydroUnit}: (default: Device[]) Vector
       of HydroUnit(s) that are immediately upstream of this reservoir.
       This reservoir is the tail reservoir for these units, and their
       flow goes into this reservoir.
    •  downstream_turbines::Vector{HydroUnit}: (default: Device[]) Vector
       of HydroUnit(s) that are immediately downstream of this reservoir.
       This reservoir is the head reservoir for these units, and its feed
       flow into these units.
    •  upstream_reservoirs::Vector{Device}: (default: Device[]) Vector of
       Device(s) reservoirs that are immediately upstream of this
       reservoir. This reservoir receives the spillage flow from
       upstream_reservoirs.
    •  operation_cost::HydroReservoirCost: (default:
       HydroReservoirCost(nothing)) OperationalCost of reservoir.
    •  level_data_type::ReservoirDataType: (default:
       ReservoirDataType.USABLE_VOLUME) Reservoir level data type. See
       ReservoirDataType for reference.
    •  ext::Dict{String, Any}: (default: Dict{String, Any}()) An extra
       dictionary for users to add metadata that are not used in
       simulation.
    •  internal::InfrastructureSystemsInternal: (Do not modify.)
       PowerSystems.jl internal reference

Reservoir store which turbines are upstream and downstream via their upstream_turbines and downstream_turbines field.

Energy Models

To specify a reservoir to use data in energy format, on which their inflows/outflows are in MW, and their capacity is in MWh, the user must specify the level_data_type = ReservoirDataType.ENERGY. The field storage_level_limits must be added in MWh, while the inflow/outflow should be specified in system base per-unit. For example if the system base is 100 MW, and the inflow is 400 MW, then set_inflow!(reservoir, 4.0) will be set correctly the multiplier for the inflow timeseries.

Timeseries data

The HydroEnergyModelReservoir can set-up three different timeseries:

The inflow timeseries is used as a fraction of the inflow field to add energy into the reservoir storage at every time step. The term $\text{inflow} \cdot \text{inflowTimeSeries}_t \cdot \text{resolution in hours} \cdot \text{system basepower}$ represents how much MWh are added per time to the reservoir storage.
The storage_target timeseries is used as a fraction of the level_targets • storage_level_limits.max to include a target at any specified hour. The user must provide a timeseries for every hour, but the constraint is only generated for the last time step of the decision model.
The hydro_budget timeseries is used as a fraction of the storage_level_limits.max to specify an hourly energy budget at any specified hour. The user must provide a timeseries for every hour, but a single constraint is generated for the sum of all time steps of the decision model.

Water Models

To specify a reservoir data in water format, on which their inflows/outflows are in m³/s, the user must must specify the level_data_type as the following options:

ReservoirDataType.HEAD if the data is provided for the hydraulic head in meters. The storage_level_limits must specify the minimum and maximum hydraulic head in meters above the sea level. The intake_elevation must be specified in meters, and the head_to_volume_factor must be specified to transform the head into the effective available volume for the reservoir in m³.
ReservoirDataType.USABLE_VOLUME if the data is provided in usable volume in cubic meters. The storage_level_limits must specify the minimum and maximum effective volume of the reservoir in cubic meters. Typically the usable volume is relative to the minimum allowed volume in the reservoir, such that that total volume is represented as a zero usable volume. The intake_elevation must be specified in meters, and the head_to_volume_factor must be specified to transform the effective usable volume for the reservoir in m³ into the absolute hydraulic head in meters.
ReservoirDataType.TOTAL_VOLUME if the data is provided in usable volume in cubic meters. The storage_level_limits must specify the minimum and maximum volume of the reservoir in cubic meters. The total volume must specify the minimum volume in cubic meters for operation. The intake_elevation must be specified in meters, and the head_to_volume_factor must be specified to transform the total volume for the reservoir in m³ into the absolute hydraulic head in meters.

The inflow and outflow fields are not necessary to be specified since the mandatory timeseries data must be specified in m³/s.

Timeseries data

As mentioned, the HydroWaterModelReservoir must set-up two different timeseries:

The inflow timeseries is added in average m³/s external water inflow. The term $\text{inflowTimeSeries}_t \cdot \text{resolution in hours} \cdot \text{Seconds in 1 hour}$ represents how much m³ are added per time to the reservoir storage.
The inflow timeseries is added in average m³/s external water outflow. The term $\text{outflowTimeSeries}_t \cdot \text{resolution in hours} \cdot \text{Seconds in 1 hour}$ represents how much m³ is lost per time to the reservoir storage. It is typically used to represent evaporation or filtration losses.