Hydro final lvl (CR 25) to merge in develop [ANT-1084] (#1521)

This PR attempts some code enhancements on branch **feature/final-reservoir-level-cr25**. Therefore, this PR's associated branch (**fix/hydro-final-levels-cr25--try-fixes**) is based on **feature/final-reservoir-level-cr25**. - [x] in class **FinalLevelInflowsModifier**, - try to reduce the number of data members, - making data members **private** whenever it's possible, - define a clear interface with a smallest number of public functions - and so make the more methods private as possible - [x] **Unit tests** : clarify their intention and reduce their size - [ ] **caution** : could not remove yet the **initialize** method. This method should be merged with the constructor, but when we call the constructor, all input pieces of data are not available. that's why **initialize** exists. We should try to make these pieces of data available, for instance by changing the order of data loading For any purpose, here are doc resources : - specs [here](https://rteinternational.sharepoint.com/:w:/r/sites/AntaresUser'sClub-Interne/_layouts/15/Doc.aspx?sourcedoc=%7B7774488E-7E4C-4AEC-B11F-1C9728B96AC0%7D&file=Functional_Specifications-Final_reservoir_level_V0.1-MA.docx&action=default&mobileredirect=true) - a discussion on that matter [here](#1145) --- ### CAUTION : **Some cleaning and corrections were introduced in a new pull request** (see [this PR](#2040)). This new PR was merged into this one. **This PR contains a test under the form of a study. This study should be downloaded and added to the right test repo.** --- ### Left to to - [ ] Merge from branch develop and remove conflicts - [ ] Check that all tests exist (unit test for raising failures and study case for fine working) - [ ] what else ? --------- Co-authored-by: Milos A <[email protected]> Co-authored-by: Milos <[email protected]> Co-authored-by: Florian Omnès <[email protected]> Co-authored-by: NikolaIlic <[email protected]>
AntaresSimulatorTeam · Jun 21, 2024 · b3f3fc0 · b3f3fc0
1 parent d233691
commit b3f3fc0
Show file tree

Hide file tree

Showing 34 changed files with 1,120 additions and 167 deletions.
diff --git a/docs/user-guide/04-migration-guides.md b/docs/user-guide/04-migration-guides.md
@@ -129,6 +129,10 @@ For each thermal cluster, in existing file **input/thermal/clusters/&lt;area&gt;
 
 For each thermal cluster, new files added **input/thermal/series/&lt;area&gt;/&lt;cluster&gt;/CO2Cost.txt** and **input/thermal/series/&lt;area&gt;/&lt;cluster&gt;/fuelCost.txt**. **fuelCost.txt** and **CO2Cost.txt** must either have one column, or the same number of columns as existing file **series.txt** (availability). The number of rows for these new matrices is 8760.
 
+#### Hydro Final Reservoir Level
+In the existing file **settings/scenariobuilder.dat**, under **&lt;ruleset&gt;** section following properties added (if final reservoir level specified, different from `init`):
+* **hfl,&lt;area&gt;,&lt;year&gt; = &lt;hfl-value&gt;**
+
 ### Output
 #### Scenarized RHS for binding constraints
 Add directory **bindingconstraints** to output directory **ts-numbers**. For every binding constraint group, add a file **ts-numbers/bindingconstraints/&lt;group&gt;.txt** containing the TS numbers used for that group.

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
@@ -5,6 +5,7 @@ set(ANTARES_VERSION_HI	      9)
 set(ANTARES_VERSION_LO	      1)
 set(ANTARES_VERSION_REVISION  0)
 
+
 # Beta release
 set(ANTARES_BETA 0)
 set(ANTARES_RC 0)

diff --git a/src/antares-deps b/src/antares-deps
diff --git a/src/libs/antares/study/CMakeLists.txt b/src/libs/antares/study/CMakeLists.txt
@@ -122,6 +122,8 @@ set(SRC_STUDY_PART_HYDRO
         include/antares/study/parts/hydro/allocation.h
         include/antares/study/parts/hydro/allocation.hxx
         parts/hydro/allocation.cpp
+        include/antares/study/parts/hydro/finalLevelValidator.h
+        parts/hydro/finalLevelValidator.cpp
         include/antares/study/parts/hydro/hydromaxtimeseriesreader.h
         parts/hydro/hydromaxtimeseriesreader.cpp
 )

diff --git a/src/libs/antares/study/area/area.cpp b/src/libs/antares/study/area/area.cpp
@@ -45,13 +45,15 @@ void Area::internalInitialize()
 }
 
 Area::Area():
+    hydro(*this),
     reserves(fhrMax, HOURS_PER_YEAR),
     miscGen(fhhMax, HOURS_PER_YEAR)
 {
     internalInitialize();
 }
 
 Area::Area(const AnyString& name):
+    hydro(*this),
     reserves(fhrMax, HOURS_PER_YEAR),
     miscGen(fhhMax, HOURS_PER_YEAR)
 {
@@ -62,6 +64,7 @@ Area::Area(const AnyString& name):
 
 Area::Area(const AnyString& name, const AnyString& id):
 
+    hydro(*this),
     reserves(fhrMax, HOURS_PER_YEAR),
     miscGen(fhhMax, HOURS_PER_YEAR)
 {

diff --git a/src/libs/antares/study/include/antares/study/parts/hydro/container.h b/src/libs/antares/study/include/antares/study/parts/hydro/container.h
@@ -21,6 +21,7 @@
 #ifndef __ANTARES_LIBS_STUDY_PARTS_HYDRO_CONTAINER_H__
 #define __ANTARES_LIBS_STUDY_PARTS_HYDRO_CONTAINER_H__
 
+#include <optional>
 #include "../../fwd.h"
 #include "allocation.h"
 #include "prepro.h"
@@ -80,7 +81,7 @@ class PartHydro
     /*!
     ** \brief Default Constructor
     */
-    PartHydro();
+    PartHydro(const Data::Area& area);
     //! Destructor
     ~PartHydro();
 
@@ -165,6 +166,8 @@ class PartHydro
     Matrix<double, double> dailyNbHoursAtGenPmax;
     Matrix<double, double> dailyNbHoursAtPumpPmax;
 
+    std::vector<std::optional<double>> deltaBetweenFinalAndInitialLevels;
+
 private:
     static bool checkReservoirLevels(const Study& study);
     static bool checkProperties(Study& study);

diff --git a/src/libs/antares/study/include/antares/study/parts/hydro/finalLevelValidator.h b/src/libs/antares/study/include/antares/study/parts/hydro/finalLevelValidator.h
@@ -0,0 +1,73 @@
+/*
+** Copyright 2007-2023 RTE
+** Authors: Antares_Simulator Team
+**
+** This file is part of Antares_Simulator.
+**
+** Antares_Simulator is free software: you can redistribute it and/or modify
+** it under the terms of the GNU General Public License as published by
+** the Free Software Foundation, either version 3 of the License, or
+** (at your option) any later version.
+**
+** There are special exceptions to the terms and conditions of the
+** license as they are applied to this software. View the full text of
+** the exceptions in file COPYING.txt in the directory of this software
+** distribution
+**
+** 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
+** GNU General Public License for more details.
+**
+** You should have received a copy of the GNU General Public License
+** along with Antares_Simulator. If not, see <http://www.gnu.org/licenses/>.
+**
+** SPDX-License-Identifier: licenceRef-GPL3_WITH_RTE-Exceptions
+*/
+#pragma once
+
+#include "antares/study/parts/hydro/container.h"
+
+namespace Antares::Data
+{
+class PartHydro;
+
+class FinalLevelValidator
+{
+public:
+    FinalLevelValidator(PartHydro& hydro,
+                        unsigned int areaIndex,
+                        const AreaName areaName,
+                        double initialLevel,
+                        double finalLevel,
+                        const unsigned int year,
+                        const unsigned int lastSimulationDay,
+                        const unsigned int firstMonthOfSimulation);
+    bool check();
+    bool finalLevelFineForUse();
+
+private:
+    bool wasSetInScenarioBuilder();
+    bool compatibleWithReservoirProperties();
+    bool skippingFinalLevelUse();
+    bool checkForInfeasibility();
+    bool hydroAllocationStartMatchesSimulation() const;
+    bool isFinalLevelReachable() const;
+    double calculateTotalInflows() const;
+    bool isBetweenRuleCurves() const;
+
+    // Data from simulation
+    unsigned int year_ = 0;
+    unsigned int lastSimulationDay_ = 0;
+    unsigned int firstMonthOfSimulation_ = 0;
+
+    // Data from area
+    PartHydro& hydro_;
+    unsigned int areaIndex_;
+    const AreaName areaName_;
+    double initialLevel_;
+    double finalLevel_;
+
+    bool finalLevelFineForUse_ = false;
+};
+} // namespace Antares::Data
diff --git a/src/libs/antares/study/include/antares/study/scenario-builder/hydroLevelsData.h b/src/libs/antares/study/include/antares/study/scenario-builder/hydroLevelsData.h
@@ -22,6 +22,7 @@
 #define __LIBS_STUDY_SCENARIO_BUILDER_DATA_HYDRO_LEVELS_H__
 
 #include "scBuilderDataInterface.h"
+#include <functional>
 
 namespace Antares
 {
@@ -39,7 +40,10 @@ class hydroLevelsData final: public dataInterface
     using MatrixType = Matrix<double>;
 
 public:
-    // We use default constructor and destructor
+    // Constructor
+
+    hydroLevelsData(const std::string& iniFilePrefix,
+                    std::function<void(Study&, MatrixType&)> applyToTarget);
 
     //! \name Data manupulation
     //@{
@@ -51,7 +55,7 @@ class hydroLevelsData final: public dataInterface
     /*!
     ** \brief Export the data into a mere INI file
     */
-    void saveToINIFile(const Study& study, Yuni::IO::File::Stream& file) const;
+    void saveToINIFile(const Study& study, Yuni::IO::File::Stream& file) const override;
 
     /*!
     ** \brief Assign a single value
@@ -71,11 +75,15 @@ class hydroLevelsData final: public dataInterface
 
     void set_value(uint x, uint y, double value);
 
-    bool apply(Study& study);
+    bool apply(Study& study) override;
 
 private:
     //! Hydro levels overlay (0 if auto)
     MatrixType pHydroLevelsRules;
+    // prefix to be added when calling saveToINIFileHydroLevel
+    const std::string addToPrefix_;
+
+    std::function<void(Study&, MatrixType&)> applyToTarget_;
 
 }; // class hydroLevelsData
 
@@ -105,6 +113,16 @@ inline double hydroLevelsData::get_value(uint x, uint y) const
     return pHydroLevelsRules.entry[y][x];
 }
 
+inline void initLevelApply(Study& study, Matrix<double>& matrix)
+{
+    study.scenarioInitialHydroLevels.copyFrom(matrix);
+}
+
+inline void finalLevelApply(Study& study, Matrix<double>& matrix)
+{
+    study.scenarioFinalHydroLevels.copyFrom(matrix);
+}
+
 } // namespace ScenarioBuilder
 } // namespace Data
 } // namespace Antares

diff --git a/src/libs/antares/study/include/antares/study/scenario-builder/rules.h b/src/libs/antares/study/include/antares/study/scenario-builder/rules.h
@@ -119,8 +119,10 @@ class Rules final: private Yuni::NonCopyable<Rules>
     //! Renewable (array [0..pAreaCount - 1])
     std::vector<renewableTSNumberData> renewable;
 
-    //! hydro levels
-    hydroLevelsData hydroLevels;
+    //! hydro initial levels
+    hydroLevelsData hydroInitialLevels = {"hl,", initLevelApply};
+    //! hydro final levels
+    hydroLevelsData hydroFinalLevels = {"hfl,", finalLevelApply};
 
     // Links NTC
     std::vector<ntcTSNumberData> linksNTC;
@@ -135,7 +137,8 @@ class Rules final: private Yuni::NonCopyable<Rules>
     bool readWind(const AreaName::Vector& instrs, String value, bool updaterMode);
     bool readHydro(const AreaName::Vector& instrs, String value, bool updaterMode);
     bool readSolar(const AreaName::Vector& instrs, String value, bool updaterMode);
-    bool readHydroLevels(const AreaName::Vector& instrs, String value, bool updaterMode);
+    bool readInitialHydroLevels(const AreaName::Vector& instrs, String value, bool updaterMode);
+    bool readFinalHydroLevels(const AreaName::Vector& instrs, String value, bool updaterMode);
     bool readLink(const AreaName::Vector& instrs, String value, bool updaterMode);
     bool readBindingConstraints(const AreaName::Vector& splitKey, String value);
 

diff --git a/src/libs/antares/study/include/antares/study/study.h b/src/libs/antares/study/include/antares/study/study.h
@@ -588,8 +588,9 @@ class Study: public Yuni::NonCopyable<Study>, public LayerData
     ScenarioBuilder::Sets* scenarioRules = nullptr;
     //@}
 
-    TimeSeries::TS scenarioHydroLevels;
-
+    TimeSeries::TS scenarioInitialHydroLevels;
+    // Hydro Final Levels
+    TimeSeries::TS scenarioFinalHydroLevels;
     /*!
     ** \brief Runtime informations
     **

diff --git a/src/libs/antares/study/parts/hydro/container.cpp b/src/libs/antares/study/parts/hydro/container.cpp
@@ -32,7 +32,7 @@ using namespace Yuni;
 
 namespace Antares::Data
 {
-PartHydro::PartHydro():
+PartHydro::PartHydro(const Data::Area& area) :
     interDailyBreakdown(0.),
     intraDailyModulation(2.),
     intermonthlyBreakdown(0),
@@ -161,6 +161,7 @@ bool PartHydro::LoadFromFolder(Study& study, const AnyString& folder)
           area.hydro.initializeReservoirLevelDate = 0;
           area.hydro.reservoirCapacity = 0.;
           area.hydro.pumpingEfficiency = 1.;
+          area.hydro.deltaBetweenFinalAndInitialLevels.resize(study.parameters.nbYears);
 
           if (study.header.version >= StudyVersion(9, 1))
           {