Feature / Binary search in Automatic Tap Changer

docs/user_manual/calculations.md

@@ -588,12 +588,13 @@ These {hoverxreftooltip}`user_manual/components:Transformer Tap Regulator`s try
 The $U_{\text{control}}$ may be compensated for the voltage drop during transport.
 Power flow calculations that take the behavior of these regulators into account may be toggled by providing one of the following strategies to the {py:meth}`tap_changing_strategy <power_grid_model.PowerGridModel.calculate_power_flow>` option.
 
-| Algorithm                                                              | Default  | Speed    | Algorithm call                                                                                              |
-| ---------------------------------------------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
-| No automatic tap changing (regular power flow)                         | &#10004; | &#10004; | {py:class}`TapChangingStrategy.disabled <power_grid_model.enum.TapChangingStrategy.disabled>`               |
-| Optimize tap positions for any value in the voltage band               |          | &#10004; | {py:class}`TapChangingStrategy.any_valid_tap <power_grid_model.enum.TapChangingStrategy.any_valid_tap>`     |
-| Optimize tap positions for lowest possible voltage in the voltage band |          |          | {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` |
-| Optimize tap positions for lowest possible voltage in the voltage band |          |          | {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` |
+| Algorithm                                                                   | Default  | Speed    | Algorithm call                                                                                              |
+| --------------------------------------------------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------- |
+| No automatic tap changing (regular power flow)                              | &#10004; | &#10004; | {py:class}`TapChangingStrategy.disabled <power_grid_model.enum.TapChangingStrategy.disabled>`               |
+| Optimize tap positions for any value in the voltage band                    |          | &#10004; | {py:class}`TapChangingStrategy.any_valid_tap <power_grid_model.enum.TapChangingStrategy.any_valid_tap>`     |
+| Optimize tap positions for lowest possible voltage in the voltage band      |          |          | {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` |
+| Optimize tap positions for lowest possible voltage in the voltage band      |          |          | {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` |
+| Optimize tap positions for any value in the voltage band with binary search |          | &#10004; | {py:class}`TapChangingStrategy.fast_any_tap <power_grid_model.enum.TapChangingStrategy.fast_any_tap>`       |
 
 ##### Control logic for power flow with automatic tap changing
 
@@ -647,11 +648,21 @@ Hence, this assumption is reflected in the requirements mentioned in {hoverxreft
 
 Internally, to achieve an optimal regulated tap position, the control algorithm sets initial tap positions and exploits neighborhoods around local optima, depending on the strategy as follows.
 
-| strategy                                                                                                    | initial tap position | exploitation direction | description                                                                           |
-| ----------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
-| {py:class}`TapChangingStrategy.any_valid_tap <power_grid_model.enum.TapChangingStrategy.any_valid_tap>`     | current tap position | no exploitation        | Find any tap position that gives a control side voltage within the `u_band`           |
-| {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` | `tap_max`            | step up                | Find the tap position that gives the lowest control side voltage within the `u_band`  |
-| {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` | `tap_min`            | step down              | Find the tap position that gives the highest control side voltage within the `u_band` |
+| strategy                                                                                                    | initial tap position | exploitation direction | search method | description                                                                           |
+| ----------------------------------------------------------------------------------------------------------- | -------------------- | ---------------------- | ------------- | ------------------------------------------------------------------------------------- |
+| {py:class}`TapChangingStrategy.any_valid_tap <power_grid_model.enum.TapChangingStrategy.any_valid_tap>`     | current tap position | no exploitation        | linear_search | Find any tap position that gives a control side voltage within the `u_band`           |
+| {py:class}`TapChangingStrategy.min_voltage_tap <power_grid_model.enum.TapChangingStrategy.min_voltage_tap>` | `tap_max`            | step up                | binary_search | Find the tap position that gives the lowest control side voltage within the `u_band`  |
+| {py:class}`TapChangingStrategy.max_voltage_tap <power_grid_model.enum.TapChangingStrategy.max_voltage_tap>` | `tap_min`            | step down              | binary_search | Find the tap position that gives the highest control side voltage within the `u_band` |
+| {py:class}`TapChangingStrategy.fast_any_tap <power_grid_model.enum.TapChangingStrategy.fast_any_tap>`       | current tap position | no exploitation        | binary_search | Find any tap position that gives a control side voltage within the `u_band`           |
+
+##### Search methods used for tap changing optimization
+
+Given the discrete nature of the finite tap ranges, we use the following search methods to find the next tap position along the exploitation direction.
+
+| Search method | Description                                                                            |
+| ------------- | -------------------------------------------------------------------------------------- |
+| linear search | In the context of finite discrete range search, go one value at a time.                |
+| binary search | In the context of finite discrete range search, go half the remaining range at a time. |
 
 
 ## Batch Calculations

power_grid_model_c/power_grid_model/include/power_grid_model/common/common.hpp

@@ -25,11 +25,16 @@ using IntS = int8_t;
 // struct of indexing to sub modules
 struct Idx2D {
     Idx group; // sequence number of outer module/groups
-    Idx pos;   //  sequence number inside the group
+    Idx pos;   // sequence number inside the group
 
     friend constexpr bool operator==(Idx2D x, Idx2D y) = default;
 };
 
+struct Idx2Du {
+    size_t x;
+    size_t y;
+};
+
 struct Idx2DHash {
     std::size_t operator()(const Idx2D& idx) const {
         size_t const h1 = std::hash<Idx>{}(idx.group);

power_grid_model_c/power_grid_model/include/power_grid_model/common/enum.hpp

@@ -114,6 +114,12 @@ enum class OptimizerStrategy : IntS { // Conventions for optimization strategies
     global_maximum = 2,               // global_maximum = argmax{f(x) \in Range} for x in Domain
     local_minimum = 3,                // local_minimum = Any{argmin{f(x) \in Range}} for x in Domain
     local_maximum = 4,                // local_maximum = Any{argmax{f(x) \in Range}} for x in Domain
+    fast_any = 5,                     // fast_any = Any{f(x) \in Range} for x \in Domain, but faster
+};
+
+enum class SearchMethod : IntS { // Which type of tap search method for finite element optimization process
+    linear_search = 0,           // use linear_search method: one step per iteration
+    binary_search = 1,           // use binary search: half a tap range at a time
 };
 
 } // namespace power_grid_model

power_grid_model_c/power_grid_model/include/power_grid_model/common/exception.hpp

@@ -255,4 +255,13 @@ class UnreachableHit : public PowerGridError {
     }
 };
 
+class TapSearchStrategyIncompatibleError : public InvalidArguments {
+  public:
+    template <typename T1, typename T2>
+    TapSearchStrategyIncompatibleError(std::string const& method, const T1& value1, const T2& value2)
+        : InvalidArguments{
+              method, std::string{typeid(T1).name()} + " #" + detail::to_string(static_cast<IntS>(value1)) + " and " +
+                          std::string{typeid(T2).name()} + " #" + detail::to_string(static_cast<IntS>(value2))} {}
+};
+
 } // namespace power_grid_model

power_grid_model_c/power_grid_model/include/power_grid_model/main_model_fwd.hpp

@@ -19,7 +19,8 @@ struct MainModelOptions {
 
     CalculationMethod calculation_method{CalculationMethod::default_method};
     OptimizerType optimizer_type{OptimizerType::no_optimization};
-    OptimizerStrategy optimizer_strategy{OptimizerStrategy::any};
+    OptimizerStrategy optimizer_strategy{OptimizerStrategy::fast_any};
+    SearchMethod search_method{SearchMethod::binary_search};
 
     double err_tol{1e-8};
     Idx max_iter{20};

power_grid_model_c/power_grid_model/include/power_grid_model/main_model_impl.hpp

@@ -656,7 +656,7 @@ class MainModelImpl<ExtraRetrievableTypes<ExtraRetrievableType...>, ComponentLis
                    options.optimizer_type, options.optimizer_strategy,
                    calculate_power_flow_<sym>(options.err_tol, options.max_iter),
                    [this](ConstDataset update_data) { this->update_component<permanent_update_t>(update_data); },
-                   *meta_data_)
+                   *meta_data_, options.search_method)
             ->optimize(state_, options.calculation_method);
     }
 

power_grid_model_c/power_grid_model/include/power_grid_model/optimizer/optimizer.hpp

@@ -18,7 +18,8 @@ template <typename State, typename UpdateType, typename StateCalculator, typenam
     requires detail::state_calculator_c<StateCalculator, State> &&
              std::invocable<std::remove_cvref_t<StateUpdater>, UpdateType>
 constexpr auto get_optimizer(OptimizerType optimizer_type, OptimizerStrategy strategy, StateCalculator calculator,
-                             StateUpdater updater, meta_data::MetaData const& meta_data) {
+                             StateUpdater updater, meta_data::MetaData const& meta_data,
+                             SearchMethod search = SearchMethod::binary_search) {
     using enum OptimizerType;
     using namespace std::string_literals;
     using BaseOptimizer = detail::BaseOptimizer<StateCalculator, State>;
@@ -31,7 +32,7 @@ constexpr auto get_optimizer(OptimizerType optimizer_type, OptimizerStrategy str
                       std::invocable<std::remove_cvref_t<StateUpdater>, ConstDataset const&> &&
                       main_core::component_container_c<typename State::ComponentContainer, TransformerTapRegulator>) {
             return BaseOptimizer::template make_shared<TapPositionOptimizer<StateCalculator, StateUpdater, State>>(
-                std::move(calculator), std::move(updater), strategy, meta_data);
+                std::move(calculator), std::move(updater), strategy, meta_data, search);
         }
         [[fallthrough]];
     default: