From 68ac0a176bf4818859948868af3b946ab019e648 Mon Sep 17 00:00:00 2001 From: Jerry Guo Date: Sat, 25 Oct 2025 19:13:37 +0200 Subject: [PATCH 1/9] added exception expectation Signed-off-by: Jerry Guo --- docs/user_manual/calculations.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index 2e4fc64b57..d164a5471d 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -952,6 +952,29 @@ along the exploitation direction. | linear search | Start with an initial guess and do a local search with step size 1 for each iteration step. | | binary search | Start with a large search region and reduce the search region by half for every iteration step. | +##### Error type `MaxIterationReached` + +When the regulator can not find a suitable voltage after iterations, error `MaxIterationReached` will be thrown. +We define the maximum iterations per transformer to be twice the amount of total taps possible. +The failure can happen in two types of scenarios: + +- The regulatable voltage range is (significantly) larger than the `u_band` set by the input data. + This will likely cause the regulator to go back and forth between two tap positions and eventually +reach a pre-defined limit. + +- The regulatad voltage at extreme tap positions still fall outside the `u_band`. + +This error is a result of the two types search method used; `linear` and `binary`: + +- Linear search method, used for `any_valid_tap` strategy, will try to go one tap up or down per iteration. +If there is no valid tap position available, linear search method will keep trying until the maximum iteration + for this transformer is reached. +- Binary search method, used for the rest three strategies, will iteratively narrow down search space by half and will + run into a state where the searchable space is no longer viable. This is equivalent to the maximum iteration + reached scenario for the linear search method. + +In conclusion, when there is no suitable tap, error `MaxIterationReached` will be thrown. + ## Batch Calculations Usually, a single power-flow or state estimation calculation would not be enough to get insights in the grid. From 8d81fa4e0dc595b2e5027f4b43c15745df8340be Mon Sep 17 00:00:00 2001 From: Jerry Guo Date: Sat, 25 Oct 2025 19:17:39 +0200 Subject: [PATCH 2/9] [skip ci] Signed-off-by: Jerry Guo From 7ee77ca58e42f6aba7c49a1b68bb405b9f827f0f Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Sat, 25 Oct 2025 19:19:08 +0200 Subject: [PATCH 3/9] Update docs/user_manual/calculations.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index d164a5471d..e3190e39ab 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -962,7 +962,7 @@ The failure can happen in two types of scenarios: This will likely cause the regulator to go back and forth between two tap positions and eventually reach a pre-defined limit. -- The regulatad voltage at extreme tap positions still fall outside the `u_band`. +- The regulated voltage at extreme tap positions still fall outside the `u_band`. This error is a result of the two types search method used; `linear` and `binary`: From e12f05662bd86b3e3dbb42d2938e6311ee077760 Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Sat, 25 Oct 2025 19:19:13 +0200 Subject: [PATCH 4/9] Update docs/user_manual/calculations.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index e3190e39ab..587ba8386d 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -969,7 +969,7 @@ This error is a result of the two types search method used; `linear` and `binary - Linear search method, used for `any_valid_tap` strategy, will try to go one tap up or down per iteration. If there is no valid tap position available, linear search method will keep trying until the maximum iteration for this transformer is reached. -- Binary search method, used for the rest three strategies, will iteratively narrow down search space by half and will +- Binary search method, used for the other three strategies, will iteratively narrow down search space by half and will run into a state where the searchable space is no longer viable. This is equivalent to the maximum iteration reached scenario for the linear search method. From e60a06a0bc4973a9d229e50ca2af0bf7ef808fc1 Mon Sep 17 00:00:00 2001 From: Jerry Guo Date: Mon, 27 Oct 2025 10:14:02 +0100 Subject: [PATCH 5/9] regulatable range out of target range behavior Signed-off-by: Jerry Guo --- docs/user_manual/calculations.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index d164a5471d..b29e8aef56 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -952,18 +952,22 @@ along the exploitation direction. | linear search | Start with an initial guess and do a local search with step size 1 for each iteration step. | | binary search | Start with a large search region and reduce the search region by half for every iteration step. | +##### Regulatable voltage range outside `u_band` + +In the case of an unrealistically set volatage and `u_band`, the viable voltage range regulatable can fall outside +this target band. +This will lead the regulator returning the tap that results in the closest voltage level to the target band. + ##### Error type `MaxIterationReached` When the regulator can not find a suitable voltage after iterations, error `MaxIterationReached` will be thrown. We define the maximum iterations per transformer to be twice the amount of total taps possible. -The failure can happen in two types of scenarios: +This failure happens in the following type of scenario: -- The regulatable voltage range is (significantly) larger than the `u_band` set by the input data. - This will likely cause the regulator to go back and forth between two tap positions and eventually +- The per tap voltage step size in the regulatable voltage range is (significantly) larger than the `u_band` set by the + input data. This will likely cause the regulator to go back and forth between two tap positions and eventually reach a pre-defined limit. -- The regulatad voltage at extreme tap positions still fall outside the `u_band`. - This error is a result of the two types search method used; `linear` and `binary`: - Linear search method, used for `any_valid_tap` strategy, will try to go one tap up or down per iteration. From df18aab3f3a9f3334fd38b93b47c042bf3f84e98 Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Mon, 27 Oct 2025 14:35:12 +0100 Subject: [PATCH 6/9] Update docs/user_manual/calculations.md Co-authored-by: Santiago Figueroa Manrique Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index f997dd0967..98015457c3 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -956,7 +956,7 @@ along the exploitation direction. In the case of an unrealistically set volatage and `u_band`, the viable voltage range regulatable can fall outside this target band. -This will lead the regulator returning the tap that results in the closest voltage level to the target band. +This will lead to the regulator returning the tap that results in the closest voltage level to the target band. ##### Error type `MaxIterationReached` From fab94221d0746f0db4d0abba5d8ff3adc2b97b31 Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Mon, 27 Oct 2025 14:35:19 +0100 Subject: [PATCH 7/9] Update docs/user_manual/calculations.md Co-authored-by: Santiago Figueroa Manrique Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index 98015457c3..1d758cae2f 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -960,7 +960,7 @@ This will lead to the regulator returning the tap that results in the closest vo ##### Error type `MaxIterationReached` -When the regulator can not find a suitable voltage after iterations, error `MaxIterationReached` will be thrown. +When the regulator cannot find a suitable voltage after all iterations, the MaxIterationReached error is thrown. We define the maximum iterations per transformer to be twice the amount of total taps possible. This failure happens in the following type of scenario: From 5c258f739e0afb7e7d6574f8bfb7af1f78300c41 Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Mon, 27 Oct 2025 14:35:39 +0100 Subject: [PATCH 8/9] Update docs/user_manual/calculations.md Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index 1d758cae2f..1cdb5efc05 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -954,7 +954,7 @@ along the exploitation direction. ##### Regulatable voltage range outside `u_band` -In the case of an unrealistically set volatage and `u_band`, the viable voltage range regulatable can fall outside +In the case of an unrealistically set voltage and `u_band`, the viable voltage range regulatable can fall outside this target band. This will lead to the regulator returning the tap that results in the closest voltage level to the target band. From 772a50d952cde30873635c1a20636563b7ea7e63 Mon Sep 17 00:00:00 2001 From: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Date: Mon, 27 Oct 2025 14:43:30 +0100 Subject: [PATCH 9/9] Update docs/user_manual/calculations.md Signed-off-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> --- docs/user_manual/calculations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user_manual/calculations.md b/docs/user_manual/calculations.md index 1cdb5efc05..0ebf618c1f 100644 --- a/docs/user_manual/calculations.md +++ b/docs/user_manual/calculations.md @@ -954,7 +954,7 @@ along the exploitation direction. ##### Regulatable voltage range outside `u_band` -In the case of an unrealistically set voltage and `u_band`, the viable voltage range regulatable can fall outside +In the case of an unrealistically set voltage and `u_band`, the regulatable-viable voltage range can fall outside this target band. This will lead to the regulator returning the tap that results in the closest voltage level to the target band.