Feature/multiple rule curve cr 24

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

@@ -3,6 +3,27 @@
 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
+
+### 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.2.0
 
 ### Input

src/libs/antares/study/CMakeLists.txt

@@ -135,6 +135,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

@@ -277,6 +277,9 @@ static bool AreaListSaveToFolderSingleArea(const Area& area,
         {
             buffer.clear() << folder << SEP << "input" << SEP << "hydro" << SEP << "series";
             ret = area.hydro.series->saveToFolder(area.id, buffer, hydroPmax) && ret;
+
+            buffer.clear() << folder << SEP << "input" << SEP << "hydro";
+            ret = area.hydro.series->ruleCurves.saveToFolder(area.id, buffer) && ret;
         }
     }
 
@@ -972,6 +975,14 @@ 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.usedByTheSolver,
+                                                     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

@@ -398,6 +398,12 @@ class Parameters final
             Hourly
         };
         HydroPmax hydroPmax = HydroPmax::Daily;
+        enum class HydroRuleCurves
+        {
+            Single,
+            Scenarized
+        };
+        HydroRuleCurves hydroRuleCurves = HydroRuleCurves::Single;
     };
 
     Compatibility compatibility;
@@ -521,6 +527,10 @@ 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);
 
+const char* CompatibilityHydroRuleCurvesToCString(
+  const Parameters::Compatibility::HydroRuleCurves mode);
+bool StringToCompatibilityHydroRuleCurves(Parameters::Compatibility::HydroRuleCurves& mode,
+                                          const std::string& text);
 } // namespace Antares::Data
 
 #endif // __ANTARES_LIBS_STUDY_PARAMETERS_H__

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

@@ -208,9 +208,6 @@ class PartHydro
     //! 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;
 
@@ -234,7 +231,7 @@ class PartHydro
     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,198 @@
+/*
+** 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/>.
+*/
+#ifndef __ANTARES_LIBS_STUDY_PARTS_HYDRO_RESERVOIR_LEVELS_H__
+#define __ANTARES_LIBS_STUDY_PARTS_HYDRO_RESERVOIR_LEVELS_H__
+
+#include <antares/array/matrix.h>
+#include <antares/series/series.h>
+#include <antares/study/parameters.h>
+#include <antares/study/version.h>
+
+#include "../../fwd.h"
+
+namespace Antares
+{
+namespace Data
+{
+
+/*!
+** \brief Rule Curves class that support reservoir levels data
+*/
+
+class RuleCurves
+{
+public:
+    enum
+    {
+        //! The minimum value
+        minimum = 0,
+        //! The average value
+        average,
+        //! The maximum value
+        maximum,
+    };
+
+    //! \name Constructor
+    //@{
+    /*!
+    ** \brief Default constructor
+    */
+    explicit RuleCurves(TimeSeriesNumbers& timeseriesNumbers);
+
+    bool forceReload(bool reload = false) const;
+
+    void markAsModified() const;
+
+    bool saveToFolder(const std::string& areaID, const std::string& folder) const;
+
+    void averageTimeSeries();
+
+    TimeSeriesNumbers& timeseriesNumbers;
+
+    /*!
+     ** \brief Maximum Reservoir Levels (%)
+     **
+     ** Merely a matrix of TimeSeriesCount * DAYS_PER_YEAR values
+     */
+    TimeSeries max;
+
+    /*!
+    ** \brief Minimum Reservoir Levels (%)
+    **
+    ** Merely a matrix of TimeSeriesCount * DAYS_PER_YEAR values
+    */
+    TimeSeries min;
+
+    /*!
+    ** \brief Average Reservoir Levels (%)
+    **
+    ** Merely a matrix of TimeSeriesCount * DAYS_PER_YEAR values
+    */
+    TimeSeries avg;
+
+    /*!
+    ** \brief This matrix is used for UI communication
+    **
+    ** Merely a matrix of 3 * DAYS_PER_YEAR values
+    */
+
+    // The buffer facilitates communication with the UI.
+    // This functionality will no longer be required once the UI is fully deprecated.
+    Matrix<double> standardRuleCurvesGUI;
+};
+
+class RuleCurvesLoader
+{
+public:
+    RuleCurvesLoader(
+
+      const std::filesystem::path& baseFolder,
+      const std::string& areaID,
+      TimeSeries& max,
+      TimeSeries& avg,
+      TimeSeries& min):
+        baseFolder_(baseFolder),
+        areaID_(areaID),
+        max_(max),
+        avg_(avg),
+        min_(min)
+
+    {
+    }
+
+    virtual ~RuleCurvesLoader() = default;
+    virtual bool load() = 0;
+
+protected:
+    const std::filesystem::path& baseFolder_;
+    const std::string& areaID_;
+    TimeSeries& max_;
+    TimeSeries& avg_;
+    TimeSeries& min_;
+};
+
+class StandardRuleCurvesLoader: public RuleCurvesLoader
+{
+public:
+    StandardRuleCurvesLoader(const std::filesystem::path& baseFolder,
+                             const std::string& areaID,
+                             Matrix<double>& standardRuleCurvesGUI,
+                             TimeSeries& max,
+                             TimeSeries& avg,
+                             TimeSeries& min):
+        RuleCurvesLoader(baseFolder, areaID, max, avg, min),
+        standardRuleCurvesMatrixGUI_(standardRuleCurvesGUI)
+
+    {
+    }
+
+private:
+    Matrix<double>& standardRuleCurvesMatrixGUI_;
+    bool load() final;
+    void copyRuleCurvesFromBuffer();
+};
+
+class ScenarizedRuleCurvesLoader: public RuleCurvesLoader
+{
+public:
+    ScenarizedRuleCurvesLoader(const std::filesystem::path& baseFolder,
+                               const std::string& areaID,
+                               TimeSeries& max,
+                               TimeSeries& avg,
+                               TimeSeries& min):
+        RuleCurvesLoader(baseFolder, areaID, max, avg, min)
+    {
+    }
+
+private:
+    bool load() final;
+};
+
+class RuleCurvesLoaderService
+{
+private:
+    RuleCurves& ruleCurves_;
+
+public:
+    explicit RuleCurvesLoaderService(RuleCurves& ruleCurves):
+        ruleCurves_(ruleCurves)
+    {
+    }
+
+    bool LoadFromFolder(const std::string& areaID,
+                        const std::filesystem::path& folder,
+                        bool usedBySolver,
+                        Parameters::Compatibility::HydroRuleCurves hydroRuleCurves);
+
+private:
+    std::unique_ptr<RuleCurvesLoader> createRuleCurvesLoader(
+      Parameters::Compatibility::HydroRuleCurves hydroRuleCurves,
+      const std::filesystem::path& filePath,
+      const std::string& areaID,
+      Matrix<double>& standardRuleCurvesGUI,
+      TimeSeries& max,
+      TimeSeries& avg,
+      TimeSeries& min);
+};
+} // namespace Data
+} // namespace Antares
+
+#endif /* __ANTARES_LIBS_STUDY_PARTS_HYDRO_RESERVOIR_LEVELS_H__ */

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

@@ -27,6 +27,7 @@
 #include <antares/study/version.h>
 
 #include "../../fwd.h"
+#include "hydrorulecurves.h"
 
 namespace Antares
 {
@@ -135,6 +136,8 @@ class DataSeriesHydro
     */
     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

@@ -241,6 +241,40 @@ bool StringToCompatibilityHydroPmax(Parameters::Compatibility::HydroPmax& mode,
     return false;
 }
 
+const char* CompatibilityHydroRuleCurvesToCString(
+  const Parameters::Compatibility::HydroRuleCurves mode)
+{
+    switch (mode)
+    {
+    case Parameters::Compatibility::HydroRuleCurves::Single:
+        return "single";
+    case Parameters::Compatibility::HydroRuleCurves::Scenarized:
+        return "scenarized";
+    default:
+        return "Unknown";
+    }
+}
+
+bool StringToCompatibilityHydroRuleCurves(Parameters::Compatibility::HydroRuleCurves& mode,
+                                          const std::string& text)
+{
+    if (text.empty())
+    {
+        return false;
+    }
+    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;
@@ -1099,6 +1133,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;
 }
 
@@ -2012,6 +2051,8 @@ void Parameters::saveToINI(IniFile& ini) const
     {
         auto* section = ini.addSection("compatibility");
         section->add("hydro-pmax", CompatibilityHydroPmaxToCString(compatibility.hydroPmax));
+        section->add("hydro-rule-curves",
+                     CompatibilityHydroRuleCurvesToCString(compatibility.hydroRuleCurves));
     }
 }