feat: Multiple Hydro Rule Curves

docs/user-guide/04-migration-guides.md

@@ -3,10 +3,30 @@
 This is a list of all recent changes that came with new Antares Simulator features. The main goal of this document is to
 lower the costs of changing existing interfaces, both GUI and scripts.
 
-## v9.3.0
+## v10.1.0
 
 ### Input
 
+#### New optional feature and compatibility flag for scenarized hydro reservoir levels
+
+In file settings/generaldata.ini, in section `compatibility`, new property `hydro-rule-curves` is added with possible values
+
+- `single` (default)
+- `scenarized`.
+
+If flag is set to `scenarized`, user must create for each area in `input/hydro/series/<area id>/` following files:
+
+- `"maxDailyReservoirLevels.txt"`
+- `"minDailyReservoirLevels.txt"`
+- `"avgDailyReservoirLevels.txt"`
+
+Antares-Simulator will read hydro reservoir levels from mentioned files, data from `input/hydro/common/capacity/reservoir_<area_id>` will be disregarded.
+
+The number of time series for the reservoir levels must match the number of time series used for the other hydro components (run of river, minimum generation etc.), ensuring that scenarized reservoir level data is fully integrated within the same Scenario Builder framework as the rest of the hydro time series. However, number of hydro reservoir levels times series can indeed be 1 for each type, min, avg and max.
+
+
+## v9.3.0
+
 #### Removed properties
 
 The following properties were removed from **settings/generaldata.ini**.
@@ -76,6 +96,7 @@ For short-term storage additional constraints, the format is
 sta,area,year,storage,constraint = TS number
 ```
 
+
 ## v9.2.0
 
 ### Input

src/libs/antares/study/CMakeLists.txt

@@ -122,6 +122,8 @@ set(SRC_STUDY_PART_HYDRO
         parts/hydro/allocation.cpp
         include/antares/study/parts/hydro/hydromaxtimeseriesreader.h
         parts/hydro/hydromaxtimeseriesreader.cpp
+        include/antares/study/parts/hydro/hydrorulecurves.h
+        parts/hydro/hydrorulecurves.cpp
 )
 source_group("study\\part\\hydro" FILES ${SRC_STUDY_PART_HYDRO})
 

src/libs/antares/study/area/list.cpp

@@ -499,6 +499,13 @@ static bool AreaListLoadFromFolderSingleArea(Study& study,
               "Value not supported for study.parameters.compatibility.hydroPmax");
         }
 
+        RuleCurvesLoaderService ruleCurvesLoaderService(area.hydro.series->ruleCurves);
+
+        ret = ruleCurvesLoaderService.LoadFromFolder(area.id,
+                                                     pathHydro,
+                                                     study.parameters.compatibility.hydroRuleCurves)
+              && ret;
+
         area.hydro.series->resizeTSinDeratedMode(study.parameters.derated,
                                                  studyVersion,
                                                  study.parameters.compatibility.hydroPmax);

src/libs/antares/study/include/antares/study/parameters.h

@@ -337,6 +337,12 @@ class Parameters final
             Hourly
         };
         HydroPmax hydroPmax = HydroPmax::Daily;
+        enum class HydroRuleCurves
+        {
+            Single,
+            Scenarized
+        };
+        HydroRuleCurves hydroRuleCurves = HydroRuleCurves::Single;
     };
 
     Compatibility compatibility;
@@ -467,7 +473,6 @@ bool StringToSimulationMode(SimulationMode& mode, Yuni::CString<20, false> text)
 
 const char* CompatibilityHydroPmaxToCString(const Parameters::Compatibility::HydroPmax);
 bool StringToCompatibilityHydroPmax(Parameters::Compatibility::HydroPmax&, const std::string& text);
-
 } // namespace Antares::Data
 
 #endif // __ANTARES_LIBS_STUDY_PARAMETERS_H__

src/libs/antares/study/include/antares/study/parts/hydro/container.h

@@ -179,9 +179,6 @@ class PartHydro final
     //! Daily Inflow Patern ([default 1, 0<x<dayspermonth]x365)
     Matrix<double> inflowPattern;
 
-    //! Daily reservoir level ({min,avg,max}x365)
-    Matrix<double> reservoirLevel;
-
     //! Daily water value ({0,1,2%...100%}x365)
     Matrix<double> waterValues;
 
@@ -205,7 +202,7 @@ class PartHydro final
     double overflowSpilledCostDifference = 1.;
 
 private:
-    static bool checkReservoirLevels(const Study& study);
+    static bool checkInflowPatternAndCredModul(const Study& study);
     static bool checkProperties(Study& study);
 
 }; // class PartHydro

src/libs/antares/study/include/antares/study/parts/hydro/hydrorulecurves.h

@@ -0,0 +1,78 @@
+/*
+** Copyright 2007-2024, RTE (https://www.rte-france.com)
+** See AUTHORS.txt
+** SPDX-License-Identifier: MPL-2.0
+** This file is part of Antares-Simulator,
+** Adequacy and Performance assessment for interconnected energy networks.
+**
+** Antares_Simulator is free software: you can redistribute it and/or modify
+** it under the terms of the Mozilla Public Licence 2.0 as published by
+** the Mozilla Foundation, either version 2 of the License, or
+** (at your option) any later version.
+**
+** Antares_Simulator is distributed in the hope that it will be useful,
+** but WITHOUT ANY WARRANTY; without even the implied warranty of
+** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+** Mozilla Public Licence 2.0 for more details.
+**
+** You should have received a copy of the Mozilla Public Licence 2.0
+** along with Antares_Simulator. If not, see <https://opensource.org/license/mpl-2-0/>.
+*/
+#pragma once
+
+#include <antares/series/series.h>
+#include <antares/study/parameters.h>
+
+namespace Antares::Data
+{
+
+class RuleCurves
+{
+public:
+    enum
+    {
+        minimum = 0,
+        average,
+        maximum,
+    };
+
+    explicit RuleCurves(TimeSeriesNumbers& timeseriesNumbers);
+
+    void averageTimeSeries();
+
+    TimeSeriesNumbers& timeseriesNumbers;
+
+    /*!
+     ** \brief max, min, average Reservoir Levels (%)
+     **
+     ** Matrices of dimensions TimeSeriesCount * DAYS_PER_YEAR values
+     */
+    TimeSeries max;
+    TimeSeries min;
+    TimeSeries avg;
+};
+
+class RuleCurvesLoader;
+
+class RuleCurvesLoaderService
+{
+private:
+    RuleCurves& ruleCurves_;
+
+public:
+    explicit RuleCurvesLoaderService(RuleCurves& ruleCurves):
+        ruleCurves_(ruleCurves)
+    {
+    }
+
+    bool LoadFromFolder(const std::string& areaID,
+                        const std::filesystem::path& folder,
+                        Parameters::Compatibility::HydroRuleCurves hydroRuleCurves);
+
+private:
+    std::unique_ptr<RuleCurvesLoader> createRuleCurvesLoader(
+      Parameters::Compatibility::HydroRuleCurves hydroRuleCurves,
+      const std::filesystem::path& filePath,
+      const std::string& areaID);
+};
+} // namespace Antares::Data

src/libs/antares/study/include/antares/study/parts/hydro/series.h

@@ -10,6 +10,7 @@
 #include <antares/study/version.h>
 
 #include "../../fwd.h"
+#include "hydrorulecurves.h"
 
 namespace Antares::Data
 {
@@ -111,6 +112,8 @@ class DataSeriesHydro final
     */
     TimeSeries maxHourlyPumpPower;
 
+    RuleCurves ruleCurves;
+
     // Getters for generation (ror, storage and mingen) and
     // max power (generation and pumping) number of TS
     uint TScount() const;

src/libs/antares/study/parameters.cpp

@@ -185,10 +185,6 @@ const char* CompatibilityHydroPmaxToCString(const Parameters::Compatibility::Hyd
 bool StringToCompatibilityHydroPmax(Parameters::Compatibility::HydroPmax& mode,
                                     const std::string& text)
 {
-    if (text.empty())
-    {
-        return false;
-    }
     if (text == "daily")
     {
         mode = Parameters::Compatibility::HydroPmax::Daily;
@@ -202,6 +198,22 @@ bool StringToCompatibilityHydroPmax(Parameters::Compatibility::HydroPmax& mode,
     return false;
 }
 
+bool StringToCompatibilityHydroRuleCurves(Parameters::Compatibility::HydroRuleCurves& mode,
+                                          const std::string& text)
+{
+    if (text == "single")
+    {
+        mode = Parameters::Compatibility::HydroRuleCurves::Single;
+        return true;
+    }
+    if (text == "scenarized")
+    {
+        mode = Parameters::Compatibility::HydroRuleCurves::Scenarized;
+        return true;
+    }
+    return false;
+}
+
 bool Parameters::economy() const
 {
     return mode == SimulationMode::Economy;
@@ -985,6 +997,11 @@ static bool SGDIntLoadFamily_Compatibility(Parameters& d,
         return StringToCompatibilityHydroPmax(d.compatibility.hydroPmax, value);
     }
 
+    if (key == "hydro-rule-curves")
+    {
+        return StringToCompatibilityHydroRuleCurves(d.compatibility.hydroRuleCurves, value);
+    }
+
     return false;
 }
 

src/libs/antares/study/parts/hydro/container.cpp

@@ -57,9 +57,6 @@ void PartHydro::reset()
 
     inflowPattern.reset(1, DAYS_PER_YEAR, true);
     inflowPattern.fillColumn(0, 1.0);
-    reservoirLevel.reset(3, DAYS_PER_YEAR, true);
-    reservoirLevel.fillColumn(average, 0.5);
-    reservoirLevel.fillColumn(maximum, 1.);
     waterValues.reset(101, DAYS_PER_YEAR, true);
     dailyNbHoursAtGenPmax.reset(1, DAYS_PER_YEAR, true);
     dailyNbHoursAtGenPmax.fillColumn(0, 24.);
@@ -271,15 +268,6 @@ bool PartHydro::LoadFromFolder(Study& study, const fs::path& folder)
                                                             &study.dataBuffer)
                 && ret;
 
-          std::string reservoirId = "reservoir_" + area.id + ".txt";
-          fs::path reservoirPath = capacityPath / reservoirId;
-          ret = area.hydro.reservoirLevel.loadFromCSVFile(reservoirPath.string(),
-                                                          3,
-                                                          DAYS_PER_YEAR,
-                                                          Matrix<>::optFixedSize,
-                                                          &study.dataBuffer)
-                && ret;
-
           std::string waterValueId = "waterValues_" + area.id + ".txt";
           fs::path waterValuePath = capacityPath / waterValueId;
           ret = area.hydro.waterValues.loadFromCSVFile(waterValuePath.string(),
@@ -302,7 +290,7 @@ bool PartHydro::LoadFromFolder(Study& study, const fs::path& folder)
     return ret;
 }
 
-bool PartHydro::checkReservoirLevels(const Study& study)
+bool PartHydro::checkInflowPatternAndCredModul(const Study& study)
 {
     bool ret = true;
 
@@ -319,21 +307,6 @@ bool PartHydro::checkReservoirLevels(const Study& study)
                 ret = false;
             }
         }
-        bool errorLevels = false;
-        auto& colMin = area->hydro.reservoirLevel[minimum];
-        auto& colAvg = area->hydro.reservoirLevel[average];
-        auto& colMax = area->hydro.reservoirLevel[maximum];
-        for (unsigned int day = 0; day < DAYS_PER_YEAR; day++)
-        {
-            if (!errorLevels
-                && (colMin[day] < 0 || colAvg[day] < 0 || colMin[day] > colMax[day]
-                    || colAvg[day] > 100 || colMax[day] > 100))
-            {
-                logs.error() << areaName << ": invalid reservoir level value";
-                errorLevels = true;
-                ret = false;
-            }
-        }
 
         for (int i = 0; i < 101; i++)
         {
@@ -431,7 +404,7 @@ bool PartHydro::checkProperties(Study& study)
 
 bool PartHydro::validate(Study& study)
 {
-    bool ret = checkReservoirLevels(study);
+    bool ret = checkInflowPatternAndCredModul(study);
     return checkProperties(study) && ret;
 }
 
@@ -584,10 +557,7 @@ bool PartHydro::SaveToFolder(const AreaList& areas,
           buffer.clear() << folder << SEP << "common" << SEP << "capacity" << SEP
                          << "inflowPattern_" << area.id << ".txt";
           ret = area.hydro.inflowPattern.saveToCSVFile(buffer, /*decimal*/ 3) && ret;
-          // reservoir
-          buffer.clear() << folder << SEP << "common" << SEP << "capacity" << SEP << "reservoir_"
-                         << area.id << ".txt";
-          ret = area.hydro.reservoirLevel.saveToCSVFile(buffer, /*decimal*/ 3) && ret;
+          // water values
           buffer.clear() << folder << SEP << "common" << SEP << "capacity" << SEP << "waterValues_"
                          << area.id << ".txt";
           ret = area.hydro.waterValues.saveToCSVFile(buffer, /*decimal*/ 2) && ret;
@@ -612,12 +582,6 @@ void PartHydro::copyFrom(const PartHydro& rhs)
         inflowPattern.unloadFromMemory();
         rhs.inflowPattern.unloadFromMemory();
     }
-    // reservoir levels
-    {
-        reservoirLevel = rhs.reservoirLevel;
-        reservoirLevel.unloadFromMemory();
-        rhs.reservoirLevel.unloadFromMemory();
-    }
     // water values
     {
         waterValues = rhs.waterValues;