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

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

@@ -109,6 +109,10 @@ For each thermal cluster, in existing file **input/thermal/clusters/<area>
 
 For each thermal cluster, new files added **input/thermal/series/<area>/<cluster>/CO2Cost.txt** and **input/thermal/series/<area>/<cluster>/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 **<ruleset>** section following properties added (if final reservoir level specified, different from `init`):
+* **hfl,<area>,<year> = <hfl-value>**
+
 ### 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/<group>.txt** containing the TS numbers used for that group.

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)

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
 )

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)
 {

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);

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

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

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);
 

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
     **

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))
           {