8.8 solver parameters [ANT-2280] (#2466)

This pull request introduces several significant changes to the Antares
project, focusing on adding support for solver-specific parameters and
restructuring the optimization options. The key changes include the
creation of a new `optimization-options` module, refactoring of existing
code to use this module, and enhancements to error handling related to
solver parameters.

### New Module Addition:
* Added a new `optimization-options` module to encapsulate all options
related to optimization (`src/libs/antares/optimization-options/*`).
[[1]](diffhunk://#diff-ee6e20916ee5ef993486966e3faae50cf9f576a4a95b4509862b938ca2e6c727R1-R10)
[[2]](diffhunk://#diff-84ba1e006bb46acefe8a9cb151fdba2b9d88f78f95df8968720cd3c6c5a3b8b7R1-R37)

### Code Refactoring:
* Refactored `StudyLoadOptions` and `Parameters` classes to use the new
`OptimizationOptions` structure for managing solver-related options
(`src/libs/antares/study/load-options.h`,
`src/libs/antares/study/load-options.cpp`,
`src/libs/antares/study/parameters.h`,
`src/libs/antares/study/parameters.cpp`).
[[1]](diffhunk://#diff-62b049183af469564bc00c9d29667b0852c87a3276df305c2c654d127aaedc46L74-L75)
[[2]](diffhunk://#diff-62b049183af469564bc00c9d29667b0852c87a3276df305c2c654d127aaedc46L91-R93)
[[3]](diffhunk://#diff-b9d1a34fd795c63bd57de61deda1730a26298ee0145cebecbf3922fcfb764fa3R1075-R1085)
[[4]](diffhunk://#diff-b9d1a34fd795c63bd57de61deda1730a26298ee0145cebecbf3922fcfb764fa3L1460-R1470)

### Error Handling Enhancements:
* Introduced a new `InvalidSolverSpecificParameters` exception to handle
invalid solver-specific parameters
(`src/libs/antares/exception/LoadingError.hpp`,
`src/libs/antares/exception/LoadingError.cpp`).
[[1]](diffhunk://#diff-096cb984780cf8e90c60d8548064f714791bb090d76e26cc7403ff698ad36f20R138-R147)
[[2]](diffhunk://#diff-6e38f1694c7d675e3f9163ec7fcee449f43692023903446c96877e36c0d4a434L60-R82)

### Documentation Updates:
* Updated the command line reference guide to include the new
`--solver-parameters` option
(`docs/reference-guide/10-command_line.md`).

### Miscellaneous:
* Moved the `add_subdirectory(writer)` command in `CMakeLists.txt` to
ensure proper build order (`src/libs/antares/CMakeLists.txt`).
[[1]](diffhunk://#diff-9e299f60c14464c86511d6c9a4e7c081765abb4840b57ea4dc25238311006ce9L5)
[[2]](diffhunk://#diff-9e299f60c14464c86511d6c9a4e7c081765abb4840b57ea4dc25238311006ce9R21-R23)

---------

Co-authored-by: Florian Omnès <[email protected]>

docs/CHANGELOG.md

@@ -13,7 +13,8 @@ Antares Changelog
 
 8.8.9 (09/2024)
 --------------------
-* Revert "Fix bug hydro heuristic with mingen (ANT-1825) (#2258)"
+## Bugfix
+* Revert "Fix bug hydro heuristic with mingen (ANT-1825) (#2258)
 
 8.8.8 (09/2024)
 --------------------

docs/reference-guide/10-command_line.md

@@ -41,6 +41,7 @@ _In all cases, arguments " –h" or "–help" can be used to get help_
 |-m, --mps-export | Export anonymous mps weekly or daily optimal UC+dispatch linear |
 |-s, --named-mps-problems | Export named mps weekly or daily optimal UC+dispatch linear |
 |--solver-logs | Print solver logs |
+|--solver-parameters | Set solver-specific parameters, for instance `--solver-parameters="param1 value1 param2 value2"`. Syntax is solver-dependent, and only supported for SCIP & XPRESS. |
 
 - Misc.
 

src/libs/antares/CMakeLists.txt

@@ -2,7 +2,6 @@
 OMESSAGE("Antares Core library")
 
 add_subdirectory(args)
-add_subdirectory(writer)
 add_subdirectory(memory)
 
 add_subdirectory(array)
@@ -19,6 +18,9 @@ add_subdirectory(io)
 add_subdirectory(exception)
 
 add_subdirectory(sys)
+add_subdirectory(writer)
+
+add_subdirectory(optimization-options)
 
 set(SRC
     config.h

src/libs/antares/InfoCollection/StudyInfoCollector.cpp

@@ -122,17 +122,17 @@ void StudyInfoCollector::solverVersionToFileContent(FileContent& file_content)
 
 void StudyInfoCollector::ORToolsUsed(FileContent& file_content)
 {
-    const bool& ortoolsUsed = study_.parameters.ortoolsUsed;
+    const bool& ortoolsUsed = study_.parameters.optOptions.ortoolsUsed;
     file_content.addItemToSection("study", "ortools used", ortoolsUsed ? "true" : "false");
 }
 
 void StudyInfoCollector::ORToolsSolver(FileContent& file_content)
 {
-    const bool& ortoolsUsed = study_.parameters.ortoolsUsed;
+    const bool& ortoolsUsed = study_.parameters.optOptions.ortoolsUsed;
     std::string ortoolsSolver = "none";
     if (ortoolsUsed)
     {
-        ortoolsSolver = study_.parameters.ortoolsSolver;
+        ortoolsSolver = study_.parameters.optOptions.ortoolsSolver;
     }
     file_content.addItemToSection("study", "ortools solver", ortoolsSolver);
 }

src/libs/antares/checks/antares/checks/checkLoadedInputData.h

@@ -24,12 +24,16 @@
 **
 ** SPDX-License-Identifier: licenceRef-GPL3_WITH_RTE-Exceptions
 */
+#include "antares/optimization-options/options.h"
+
 namespace Antares::Check
 {
+
 void checkOrtoolsUsage(Antares::Data::UnitCommitmentMode ucMode,
                        bool ortoolsUsed,
                        const std::string& solverName);
 
+
 void checkStudyVersion(const AnyString& optStudyFolder);
 
 void checkSimplexRangeHydroPricing(Antares::Data::SimplexOptimization optRange,

src/libs/antares/exception/LoadingError.cpp

@@ -57,14 +57,29 @@ InvalidSolver::InvalidSolver(const std::string& solver, const std::string& avail
 {
 }
 
-InvalidStudy::InvalidStudy(const Yuni::String& study) :
- LoadingError(std::string("The folder `") + study.c_str() + "` does not seem to be a valid study")
+InvalidStudy::InvalidStudy(const std::string& study) :
+ LoadingError(std::string("The folder `") + study + "` does not seem to be a valid study")
 {
 }
 
 InvalidVersion::InvalidVersion(const char* version, const char* latest) :
  LoadingError(std::string("Invalid version for the study : found `") + version + "`, expected <=`"
               + latest + '`')
+{}
+
+static std::string InvalidSolverSpecificParametersHelper(const std::string& solver,
+                                                         const std::string& specificParameters)
+{
+    std::ostringstream message;
+    message << "Specific parameters '" << specificParameters
+            << "' are not valid or not supported for solver " << solver;
+    return message.str();
+}
+
+InvalidSolverSpecificParameters::InvalidSolverSpecificParameters(
+  const std::string& solver,
+  const std::string& specificParameters):
+    LoadingError(InvalidSolverSpecificParametersHelper(solver, specificParameters))
 {
 }
 

src/libs/antares/exception/antares/exception/LoadingError.hpp

@@ -135,10 +135,16 @@ class InvalidSolver : public LoadingError
     explicit InvalidSolver(const std::string& solver, const std::string& availableSolverList);
 };
 
+class InvalidSolverSpecificParameters : public LoadingError
+{
+public:
+    explicit InvalidSolverSpecificParameters(const std::string& solver, const std::string& specificParameters);
+};
+
 class InvalidStudy : public LoadingError
 {
 public:
-    explicit InvalidStudy(const Yuni::String& study);
+    explicit InvalidStudy(const std::string& study);
 };
 
 class NoStudyProvided : public LoadingError

src/libs/antares/optimization-options/CMakeLists.txt

@@ -0,0 +1,10 @@
+set(PROJ optimization-options)
+
+add_library(${PROJ} INTERFACE)
+
+target_include_directories(${PROJ}
+        INTERFACE
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+)
+
+add_library(Antares::${PROJ} ALIAS ${PROJ})

src/libs/antares/optimization-options/include/antares/optimization-options/options.h

@@ -0,0 +1,37 @@
+/*
+** 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/logs/logs.h>
+
+namespace Antares::Solver::Optimization
+{
+
+struct OptimizationOptions
+{
+    //! Force ortools use
+    bool ortoolsUsed = false;
+    //! The solver name, sirius is the default
+    std::string ortoolsSolver = "sirius";
+    bool solverLogs = false;
+    std::string solverParameters;
+};
+} // namespace Antares::Solver::Optimization

src/libs/antares/study/load-options.cpp

@@ -34,22 +34,21 @@ namespace Antares
 {
 namespace Data
 {
-StudyLoadOptions::StudyLoadOptions() :
- nbYears(0),
- prepareOutput(false),
- loadOnlyNeeded(false),
- forceYearByYear(false),
- forceDerated(false),
- noTimeseriesImportIntoInput(false),
- simplexOptimizationRange(sorUnknown),
- mpsToExport(false),
- ignoreConstraints(false),
- forceMode(SimulationMode::Unknown),
- enableParallel(false),
- forceParallel(false),
- maxNbYearsInParallel(0),
- usedByTheSolver(false),
- ortoolsUsed(false)
+StudyLoadOptions::StudyLoadOptions():
+    nbYears(0),
+    prepareOutput(false),
+    loadOnlyNeeded(false),
+    forceYearByYear(false),
+    forceDerated(false),
+    noTimeseriesImportIntoInput(false),
+    simplexOptimizationRange(sorUnknown),
+    mpsToExport(false),
+    ignoreConstraints(false),
+    forceMode(SimulationMode::Unknown),
+    enableParallel(false),
+    forceParallel(false),
+    maxNbYearsInParallel(0),
+    usedByTheSolver(false)
 {
 }
 

src/libs/antares/study/load-options.h

@@ -29,6 +29,9 @@
 
 #include <yuni/yuni.h>
 #include <yuni/core/string.h>
+
+#include <antares/optimization-options/options.h>
+
 #include "parameters.h"
 
 namespace Antares
@@ -71,8 +74,6 @@ class StudyLoadOptions
     bool mpsToExport;
     //! named problems
     bool namedProblems = false;
-    //! enable solver logs
-    bool solverLogs = false;
     //! Ignore all constraints
     bool ignoreConstraints;
     //! Simulation mode
@@ -88,10 +89,8 @@ class StudyLoadOptions
     //! A non-zero value if the data will be used for a simulation
     bool usedByTheSolver;
 
-    //! Force ortools use
-    bool ortoolsUsed;
-    //! THe solver name, sirius is the default
-    std::string ortoolsSolver = "sirius";
+    //! All options related to optimization
+    Antares::Solver::Optimization::OptimizationOptions optOptions;
 
     //! Temporary string for passing log message
     mutable Yuni::String logMessage;

src/libs/antares/study/parameters.cpp

@@ -321,7 +321,6 @@ void Parameters::reset()
     include.exportMPS = mpsExportStatus::NO_EXPORT;
     include.exportStructure = false;
     namedProblems = false;
-    solverLogs = false;
 
     include.unfeasibleProblemBehavior = UnfeasibleProblemBehavior::ERROR_MPS;
 
@@ -331,16 +330,15 @@ void Parameters::reset()
 
     hydroDebug = false;
 
-    ortoolsUsed = false;
-    ortoolsSolver = "sirius";
-
     resultFormat = legacyFilesDirectories;
 
     // Adequacy patch parameters
     adqPatchParams.reset();
 
     // Initialize all seeds
     resetSeeds();
+
+    optOptions = Antares::Solver::Optimization::OptimizationOptions();
 }
 
 bool Parameters::isTSGeneratedByPrepro(const TimeSeriesType ts) const
@@ -627,7 +625,7 @@ static bool SGDIntLoadFamily_Optimization(Parameters& d,
 
     if (key == "solver-logs")
     {
-        return value.to<bool>(d.solverLogs);
+        return value.to<bool>(d.optOptions.solverLogs);
     }
     return false;
 }
@@ -957,6 +955,7 @@ bool Parameters::loadFromINI(const IniFile& ini, uint version, const StudyLoadOp
 {
     // Reset inner data
     reset();
+
     // A temporary buffer, used for the values in lowercase
     using Callback = bool (*)(
       Parameters&,   // [out] Parameter object to load the data into
@@ -1048,12 +1047,9 @@ bool Parameters::loadFromINI(const IniFile& ini, uint version, const StudyLoadOp
     if (options.forceDerated)
         derated = true;
 
-    // Define ortools parameters from options
-    ortoolsUsed = options.ortoolsUsed;
-    ortoolsSolver = options.ortoolsSolver;
-
     namedProblems = options.namedProblems;
-    solverLogs = options.solverLogs || solverLogs;
+
+    handleOptimizationOptions(options);
 
     // Attempt to fix bad values if any
     fixBadValues();
@@ -1076,6 +1072,17 @@ bool Parameters::loadFromINI(const IniFile& ini, uint version, const StudyLoadOp
     return true;
 }
 
+void Parameters::handleOptimizationOptions(const StudyLoadOptions& options)
+{
+    // Options only set from the command-line
+    optOptions.ortoolsUsed = options.optOptions.ortoolsUsed;
+    optOptions.ortoolsSolver = options.optOptions.ortoolsSolver;
+    optOptions.solverParameters = options.optOptions.solverParameters;
+
+    // Options that can be set both in command-line and file
+    optOptions.solverLogs = options.optOptions.solverLogs || optOptions.solverLogs;
+}
+
 void Parameters::fixRefreshIntervals()
 {
     using T = std::
@@ -1457,9 +1464,10 @@ void Parameters::prepareForSimulation(const StudyLoadOptions& options)
         logs.info() << "  :: ignoring hurdle costs";
 
     // Indicate ortools solver used
-    if (ortoolsUsed)
+    if (options.optOptions.ortoolsUsed)
     {
-        logs.info() << "  :: ortools solver " << ortoolsSolver << " used for problem resolution";
+        logs.info() << "  :: ortools solver " << options.optOptions.ortoolsSolver
+                    << " used for problem resolution";
     }
 
     // indicated that Problems will be named
@@ -1468,8 +1476,7 @@ void Parameters::prepareForSimulation(const StudyLoadOptions& options)
         logs.info() << "  :: The problems will contain named variables and constraints";
     }
     // indicated whether solver logs will be printed
-    logs.info() << "  :: Printing solver logs : " << (solverLogs ? "True" : "False");
-
+    logs.info() << "  :: Printing solver logs : " << (optOptions.solverLogs ? "True" : "False");
 }
 
 void Parameters::resetPlaylist(uint nbOfYears)
@@ -1579,7 +1586,7 @@ void Parameters::saveToINI(IniFile& ini) const
         // Unfeasible problem behavior
         section->add("include-unfeasible-problem-behavior",
                      Enum::toString(include.unfeasibleProblemBehavior));
-        section->add("solver-logs", solverLogs);
+        section->add("solver-logs", optOptions.solverLogs);
     }
 
     // Adequacy patch