.. _api_hydropower: =========== Hydro power =========== The hydropower variants in LtmApi are: - :ref:`det_hydro` - :ref:`agg_hydro` - :ref:`Batteries ` (modelled as aggregated hydropower) - :ref:`pumps` .. _det_hydro: Detailed hydro modules ====================== Detailed description of detailed hydro modules in the LTM-API. The :ref:`ltm-hydropower` use the *standard hydro modules* which contains **both** a reservoir and a hydropower plant. In the LTM-API reservoirs and hydropower plants are two separate objects, as described in :ref:`api_reservoir` and :ref:`api_plant`. They can be connected to each other by the :ref:`connections` object to form a LTM standard hydro module. The definition of a minimal hydropower module specifying the energy equivalent and maximum discharge (omitting the tailrace elevation, pq-curve and volume curve) is not possible in the LtmApi. A minimal (synthetic) example in the LtmApi is provided below. - The gross head is set to 100 m - The tailrace elevation is set to 1000 m (100 m below the reservoir) - Two-point linear pq-curve from 0 MW production at 0 m3/s discharge to 10 MW production at 25 m3/s discharge .. collapse:: Minimal example .. code-block:: json "reservoirs": [ { "name": "upper_main", "average_spill_energy_equivalent": 0.7, "regulated_inflow_name": "ten", "average_regulated_inflow": 50.0, "max_discharge": 25.0, "reference_curve": { "timestamps": [ "2023-W17", "2023-W40" ], "scenarios": [ [ 200, 450 ] ] }, "initial_volume": 400, "max_volume": 500 } ], "plants": [ { "name": "plant", "discharge_energy_equivalent": { "scenarios": [ [ 0.113 ] ] }, "pq_curves": { "2024-01-01T00:00:00Z": { "y": [ 0.0, 10.0 ], "x": [ 0.0, 25.0 ] } }, "unregulated_inflow_name": "one", "average_unregulated_inflow": 1.0, "tailrace_elevation": 1000.0, "gross_head": 100.0, } ], "connections": [ { "from": "upper_main", "to": "plant" } ] .. _api_reservoir: Reservoir --------- See the discription of the LTM :ref:`ltm_reservoir`. The table below shows :ref:`table-req_res`. The parameters in *italics* means that one of the two must be specified, where the user choose the appropriate one. .. _table-req_res: .. list-table:: Required Reservoir Parameters :header-rows: 1 * - Parameter - Datatype - Description * - **name** - string - Object name * - **average_spill_energy_equivalent** - double - **Local** average energy equivalent for spills [kWh/m3]. See :ref:`energy_equivalents` and the importance for :ref:`pump_object`. * - **average_regulated_inflow** - double - Average yearly regulated :ref:`ltm_inflow` [m3/s]. * - **max_discharge** - double - **Global** maximum discharge from the reservoir [m^3/sec]. If the pq-curve on :ref:`api_plant` is defined for a higher discharge, the whole pq-curve is not used. * - **reference_curve** - :ref:`txy-label` - Reservoir reference curve [Mm^3] See reservoir curve here :ref:`ltm_reservoir`. * - *max_volume* - double - Mm3 * - *volume_curve* - :ref:`xy-label` - The volume curve show the functional relationship between the elevation above sea level and the reservoir volume [m - Mm3]. See :ref:`ltm_reservoir`. Below is a reservoir example: .. code-block:: json "reservoirs": [ { "name": "Example reservoir", "average_spill_energy_equivalent": 0.12, "average_regulated_inflow": 0.79492267, "initial_volume": 60, "max_discharge": 30, "reference_curve": { "timestamps": [ "2024-04-22T00:00:00Z", "2024-06-03T00:00:00Z", "2025-01-01T00:00:00Z" ], "scenarios": [ [ 0.0, 75.0, 85.0 ] ] }, "regulated_inflow": { "#comment": "Refers to unregulated inflow label", "external_reference": { "type": "csv", "filename": "constant_inflow.csv" } }, "volume_curve": { "x": [ 1050, 1100 ], "y": [ 0, 100 ] } } ] The optional reservoir parameters are listed in the table below :ref:`table_optional_res`. .. _table_optional_res: .. list-table:: Optional Reservoir Parameters :header-rows: 1 * - Parameter - Datatype - Description * - degree_of_regulation - double - Reservoir regulation degree [years]. Factor describes how many years it takes to fill the reservoir. * - reservoir_type - :ref:`reservoir_type` - Regulation or buffer reservoir. See :ref:`ltm_reservoir_types`. * - regulated_inflow - :ref:`txy-label` - Regulated inflow [m3/sec]. See :ref:`ltm_inflow`. * - regulated_inflow_name - string - Reference to a regulated inflow time series [m3/sec]. :ref:`inflow_series` * - initial_volume - double - Reservoir volume at simulation start. [Mm3] * - gross_head - double - Nominal gross head [m]. See :ref:`pq_curve_head_variation` * - tailrace_elevation - double - Tailrace elevation (utløpskote) [m]. See :ref:`pq_curve_head_variation` * - max_volume_curve - :ref:`txy-label` - Maximal allowed volume for given points in time [Mm3] * - max_volume_curve_hard_limit - bool - Reservoir has hard upper volume limit * - min_volume_curve - :ref:`txy-label` - Minimum allowed volume for given points in time [Mm3] * - min_volume_curve_hard_limit - bool - Reservoir has hard lower volume limit * - max_discharge_curve - :ref:`txy-label` - Maximum allowed discharge for given points in time [m3/sec] * - max_discharge_name - string - Reference to a time series for maximum discharge * - max_discharge_scale - double - Scaling factor for the maximum discharge time series * - min_discharge_curve - :ref:`txy-label` - Minimum allowed discharge for given points in time [m3/sec] * - min_discharge_name - string - Reference to a time series for minimum discharge * - min_discharge_scale - double - Scaling factor for the minimum discharge time series * - min_bypass_curve - :ref:`txy-label` - Minimum allowed bypass for given points in time [m3/sec] * - min_bypass_name - string - Reference to a time series for minimum bypass * - min_bypass_scale - double - Scaling factor for the minimum bypass time series * - max_bypass_curve - :ref:`txy-label` - Maximum allowed bypass for given points in time [m3/sec] * - max_bypass_name - string - Reference to a time series for maximum bypass * - max_bypass_scale - double - Scaling factor for the maximum bypass time series * - hc_max_flow - int - Maximum flow on hydraulic couplings [m3/s] * - hc_has_gate - int - Hydraulic coupling has gate/hatch [m3/s] * - #comment - string - * - metadata - json - output * - module_number - int - output .. _api_plant: Plant ----- See description of LTM :ref:`ltm_plant`. The required plant parameters are listed in the table below. .. list-table:: Required Plant Parameters Overview :header-rows: 1 * - Parameter - Datatype - Description * - **name** - string - Object name * - **discharge_energy_equivalent** - :ref:`txy-label` - **Local** discharge energy equivalent time series, given together with turbine PQ-curves. [kWh/m^3]. :ref:`ltm_plant` and :ref:`energy_equivalents`. * - **pq_curves** - xyt - PQ efficiency curves [MW - m3/s]. :ref:`pq_curve_head_variation`. The highest discharge on the pq-curve restricts the discharge through *the station* even though the maximum discharge from the reservoir may be larger (:ref:`api_reservoir`). * - **average_unregulated_inflow** - double - Average yearly unregulated inflow [m^3/s]. :ref:`ltm_inflow`. * - **gross_head** - double - Nominal gross head (brutto fallhoyde) [m]. Gross head **Hnom** in :ref:`pq_curve_head_variation`. Value must be **>0.0**. * - **tailrace_elevation*** - double - Plant tailrace elevation (utlopskote stasjon) [m] :ref:`pq_curve_head_variation`. Below is a minimal plant example. The "yearly_inflow_profile" is a reference to the name of a defined :ref:`inflow_series`. .. code-block:: json "plants": [ { "name": "plant", "discharge_energy_equivalent": { "scenarios": [ [ 0.12 ] ] }, "pq_curves": { "2024-01-01T00:00:00Z": { "y": [ 0.0, 9.89 ], "x": [ 0.0, 24.6 ] } }, "average_unregulated_inflow": 0.6, "gross_head": 40.0, "tailrace_elevation": 1030, "unregulated_inflow_name": "yearly_inflow_profile" } ] The optional plant parameters are listed in the table below. The parameters in *italics* means that one of the two must be specified, where the user choose the appropriate one. .. list-table:: Optional Plant Parameters Overview :header-rows: 1 * - Parameter - Datatype - Description * - *unregulated_inflow* - :ref:`txy-label` - Unregulated inflow time series [m3/sec]. :ref:`ltm_inflow`. * - *unregulated_inflow_name* - string - reference to the name of an inflow time series. :ref:`inflow_series` * - :ref:`ownership ` - double - % * - max_discharge_curve - :ref:`txy-label` - Maximum discharge constraint [m3/sec]. :ref:`time_dependent_constraints`. * - max_discharge_name - string - Name of time series * - max_discharge_scale - double - Scaling factor of the input series * - min_discharge_curve - :ref:`txy-label` - Minimum discharge constraint [m3/sec]. :ref:`time_dependent_constraints`. * - min_discharge_name - string - Name of time series * - min_discharge_scale - double - Scaling factor of the input series * - min_bypass_curve - :ref:`txy-label` - Minimum bypass constraint [m3/sec]. :ref:`time_dependent_constraints`. * - min_bypass_name - string - Name of time series * - min_bypass_scale - double - Scaling factor of the input series * - gross_head_max_discharge - xy - :ref:`max_discharge_head` as function of gross head [m3/s]. * - max_bypass_curve - :ref:`txy-label` - Maximum bypass constraint [m3/sec]. :ref:`time_dependent_constraints`. * - max_bypass_name - string - Name of time series * - max_bypass_scale - double - Scaling factor of the input series * - unavailable_capacity - :ref:`txy-label` - MW * - #comment - string - * - metadata - json - User meta data: Output .. _agg_hydro: Aggregated hydropower ===================== Input ----- The API expects input data to be given as a list of "**aggregated_hydro_modules**" objects. The aggregated hydro modules include the following input where the *Parameters* in **bold** are **required** and the others are optional: .. list-table:: Input :header-rows: 1 :widths: 25 25 105 * - Parameter - Type - Description * - **name** - string - Object name * - **reservoir_energy** - double - Maximum reservoir energy [MWh] * - **station_power** - double - Max station production [MW] * - **unregulated_power_inflow** - :ref:`txy-label` - Unregulated power inflow [MW], see :ref:`ltm_inflow` * - **regulated_power_inflow** - :ref:`txy-label` - Regulated power inflow [MW], see :ref:`ltm_inflow` * - **start_reservoir_energy** - double - Initial aggregated reservoir energy [MWh] * - upper_reservoir_limits - :ref:`txy-label` - Upper reservoir limits [MWh] * - lower_reservoir_limits - :ref:`txy-label` - Lower reservoir limits [MWh] * - upper_production_limits - :ref:`txy-label` - Upper production limits [MW] * - lower_production_limits - :ref:`txy-label` - Lower production limits [MW] * - metadata - json - User metadata: output