From b3775f5b703a4ffcce31ac3e62e68b45d09774e9 Mon Sep 17 00:00:00 2001 From: Zhen Wang Date: Wed, 5 Jun 2024 11:26:54 +0200 Subject: [PATCH 1/3] Editing error handling in PF Example notebook. Signed-off-by: Zhen Wang --- docs/examples/Power Flow Example.ipynb | 103 ++++++++++++------------ docs/examples/Validation Examples.ipynb | 2 +- 2 files changed, 51 insertions(+), 54 deletions(-) diff --git a/docs/examples/Power Flow Example.ipynb b/docs/examples/Power Flow Example.ipynb index e5224df5f7..236b5b8871 100644 --- a/docs/examples/Power Flow Example.ipynb +++ b/docs/examples/Power Flow Example.ipynb @@ -38,7 +38,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 141, "id": "ae11dc9a", "metadata": {}, "outputs": [], @@ -74,7 +74,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 142, "id": "6f008736", "metadata": {}, "outputs": [], @@ -133,7 +133,7 @@ }, { "cell_type": "code", - "execution_count": 3, + "execution_count": 143, "id": "f0c8c3e8", "metadata": {}, "outputs": [ @@ -169,12 +169,12 @@ "## Validation (optional)\n", "For efficiency reasons, most of the data is not explicitly validated in the power grid model. However, in most cases, a power flow calculation will fail/crash if the data is invalid. Often with a low level error message that is hard to relate to the original objects. Therfore, it is recommended to always validate your data before constructing a PowerGridModel instance.\n", "\n", - "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." + "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See `Error Handling` section in this example notebook and [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] }, { "cell_type": "code", - "execution_count": 4, + "execution_count": 144, "id": "40509eaf", "metadata": {}, "outputs": [], @@ -206,7 +206,7 @@ }, { "cell_type": "code", - "execution_count": 5, + "execution_count": 145, "id": "7ef134e9", "metadata": {}, "outputs": [], @@ -243,7 +243,7 @@ }, { "cell_type": "code", - "execution_count": 6, + "execution_count": 146, "id": "44c2de63", "metadata": {}, "outputs": [], @@ -268,7 +268,7 @@ }, { "cell_type": "code", - "execution_count": 7, + "execution_count": 147, "id": "a581a36e", "metadata": {}, "outputs": [ @@ -316,7 +316,7 @@ }, { "cell_type": "code", - "execution_count": 8, + "execution_count": 148, "id": "30fdf18a", "metadata": {}, "outputs": [ @@ -376,7 +376,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 149, "id": "ecbb8eeb", "metadata": {}, "outputs": [ @@ -435,7 +435,7 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 150, "id": "1d035c65", "metadata": {}, "outputs": [], @@ -462,12 +462,13 @@ "id": "3d9d3d45", "metadata": {}, "source": [ - "### Validation (optional)" + "### Validation (optional)\n", + "When performing batch calculation/updating dataset, 'power-grid-model' provides the functions to validate See `Error Handling` section in this example notebook\n" ] }, { "cell_type": "code", - "execution_count": 11, + "execution_count": 151, "id": "63ea4cc3", "metadata": {}, "outputs": [], @@ -489,7 +490,7 @@ }, { "cell_type": "code", - "execution_count": 12, + "execution_count": 152, "id": "188f6663", "metadata": {}, "outputs": [], @@ -511,7 +512,7 @@ }, { "cell_type": "code", - "execution_count": 13, + "execution_count": 153, "id": "a93c1e16", "metadata": {}, "outputs": [ @@ -600,7 +601,7 @@ }, { "cell_type": "code", - "execution_count": 14, + "execution_count": 154, "id": "42d5cd8f", "metadata": {}, "outputs": [], @@ -632,7 +633,7 @@ }, { "cell_type": "code", - "execution_count": 15, + "execution_count": 155, "id": "4e25006f", "metadata": { "scrolled": true @@ -675,7 +676,7 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 156, "id": "afccf7a2", "metadata": { "scrolled": true @@ -712,7 +713,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 157, "id": "9af1be38", "metadata": { "scrolled": true @@ -755,7 +756,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 158, "id": "041368dc", "metadata": {}, "outputs": [], @@ -791,7 +792,7 @@ }, { "cell_type": "code", - "execution_count": 19, + "execution_count": 159, "id": "34338ce3", "metadata": {}, "outputs": [ @@ -823,7 +824,7 @@ }, { "cell_type": "code", - "execution_count": 20, + "execution_count": 160, "id": "04e56690", "metadata": {}, "outputs": [], @@ -851,7 +852,7 @@ }, { "cell_type": "code", - "execution_count": 21, + "execution_count": 161, "id": "0d5b94c2", "metadata": {}, "outputs": [ @@ -916,18 +917,9 @@ "source": [ "## Error Handling\n", "\n", - "The error handeling of `power-grid-model` is using exceptions in all cases." - ] - }, - { - "attachments": {}, - "cell_type": "markdown", - "id": "cd824d12", - "metadata": {}, - "source": [ - "### Raise Exception\n", - "\n", - "If there is an error in the ctypes wrapper, a relevant exception will be raised (e.g. `KeyError`). If there is an error in the C++ core, the C++ exception will be translated into a `PowerGridError` in Python. Below we show some examples for the errors in the construction, update, and calculation." + "The error handeling of `power-grid-model` is using exceptions in all cases.\n", + "An optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions, most of them will just yield invalid results without warning.\n", + "Below we give examples of catching different error types in power grid model calculations. Refer to [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] }, { @@ -938,12 +930,12 @@ "source": [ "#### Construction\n", "\n", - "We try to construct a grid with a line connecting two nodes with different rated voltages. An error is raised in the construction." + "We try to construct a grid with a line connecting two nodes with different rated voltages. An `ConflictVoltage` error is caught in the construction." ] }, { "cell_type": "code", - "execution_count": 22, + "execution_count": 162, "id": "b5f10bae", "metadata": {}, "outputs": [ @@ -961,7 +953,8 @@ } ], "source": [ - "from power_grid_model.errors import PowerGridError\n", + "from power_grid_model.errors import PowerGridError, ConflictVoltage\n", + "from power_grid_model.validation import ValidationException\n", "\n", "# node\n", "node_error = initialize_array(\"input\", \"node\", 2)\n", @@ -980,14 +973,16 @@ "line_error[\"tan1\"] = [0.0]\n", "line_error[\"i_n\"] = [1000]\n", "\n", + "error_data = {\n", + " \"node\": node_error,\n", + " \"line\": line_error\n", + "}\n", + "\n", "try:\n", - " PowerGridModel(\n", - " {\n", - " \"node\": node_error,\n", - " \"line\": line_error\n", - " }\n", - " )\n", - "except PowerGridError as e:\n", + " assert_valid_input_data(error_data, symmetric=True)\n", + " model = PowerGridModel(error_data)\n", + " output_data = model.calculate_state_estimation(symmetric=True)\n", + "except ConflictVoltage as e:\n", " print(e)" ] }, @@ -1004,7 +999,7 @@ }, { "cell_type": "code", - "execution_count": 23, + "execution_count": 163, "id": "1a221507", "metadata": {}, "outputs": [ @@ -1020,6 +1015,8 @@ } ], "source": [ + "from power_grid_model.errors import IDNotFound\n", + "\n", "line_update_error = initialize_array(\"update\", \"line\", 1)\n", "line_update_error[\"id\"] = [12345] # non-existing\n", "line_update_error[\"from_status\"] = [1]\n", @@ -1027,7 +1024,7 @@ "\n", "try:\n", " model.update(update_data={\"line\": line_update_error})\n", - "except PowerGridError as e:\n", + "except IDNotFound as e:\n", " print(e)" ] }, @@ -1044,7 +1041,7 @@ }, { "cell_type": "code", - "execution_count": 24, + "execution_count": 164, "id": "541af620", "metadata": {}, "outputs": [ @@ -1094,7 +1091,7 @@ }, { "cell_type": "code", - "execution_count": 25, + "execution_count": 165, "id": "20d8285c", "metadata": {}, "outputs": [], @@ -1105,7 +1102,7 @@ }, { "cell_type": "code", - "execution_count": 26, + "execution_count": 166, "id": "b702eb15", "metadata": {}, "outputs": [ @@ -1118,7 +1115,7 @@ "\n", "Failed scenarios: [3 7]\n", "Succeeded scenarios: [0 1 2 4 5 6 8 9]\n", - "Error messages: ['The id cannot be found: 1000\\n', 'Iteration failed to converge after 20 iterations! Max deviation: 43691065954360128432752954469939668333328459052496602949289781148532517437499693334528.000000, error tolerance: 0.000000.\\n']\n" + "Error messages: ['The id cannot be found: 1000\\n', 'Iteration failed to converge after 20 iterations! Max deviation: 58117414400716408619540873986620695630846752310955626332790372168240900260914085756928.000000, error tolerance: 0.000000.\\n']\n" ] } ], @@ -1140,7 +1137,7 @@ }, { "cell_type": "code", - "execution_count": 27, + "execution_count": 167, "id": "1ba71901", "metadata": {}, "outputs": [ @@ -1218,7 +1215,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.12.2" + "version": "3.12.3" }, "vscode": { "interpreter": { diff --git a/docs/examples/Validation Examples.ipynb b/docs/examples/Validation Examples.ipynb index f19996cdfc..d961115d6b 100644 --- a/docs/examples/Validation Examples.ipynb +++ b/docs/examples/Validation Examples.ipynb @@ -7,7 +7,7 @@ "source": [ "# Validation Examples\n", "\n", - "As a result of optimizations, and the low level nature of the Power Grid Model's mathematical core, the core exceptions may not always be clear to the user. Therefore an optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions, most of them wil just yield invalid results without warning." + "As a result of optimizations, and the low level nature of the Power Grid Model's mathematical core, the core exceptions may not always be clear to the user. Therefore an optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions, most of them will just yield invalid results without warning." ] }, { From 8aaed34e2b61cd5b47880b6499055618a8eb624b Mon Sep 17 00:00:00 2001 From: Zhen Wang Date: Wed, 5 Jun 2024 15:23:14 +0200 Subject: [PATCH 2/3] minor changes in grammar and wipe the errors Signed-off-by: Zhen Wang --- docs/examples/Power Flow Example.ipynb | 64 ++++++++++++------------- docs/examples/Validation Examples.ipynb | 2 +- 2 files changed, 33 insertions(+), 33 deletions(-) diff --git a/docs/examples/Power Flow Example.ipynb b/docs/examples/Power Flow Example.ipynb index 236b5b8871..f12c1deb24 100644 --- a/docs/examples/Power Flow Example.ipynb +++ b/docs/examples/Power Flow Example.ipynb @@ -38,7 +38,7 @@ }, { "cell_type": "code", - "execution_count": 141, + "execution_count": 1, "id": "ae11dc9a", "metadata": {}, "outputs": [], @@ -74,7 +74,7 @@ }, { "cell_type": "code", - "execution_count": 142, + "execution_count": 2, "id": "6f008736", "metadata": {}, "outputs": [], @@ -133,7 +133,7 @@ }, { "cell_type": "code", - "execution_count": 143, + "execution_count": 3, "id": "f0c8c3e8", "metadata": {}, "outputs": [ @@ -169,12 +169,12 @@ "## Validation (optional)\n", "For efficiency reasons, most of the data is not explicitly validated in the power grid model. However, in most cases, a power flow calculation will fail/crash if the data is invalid. Often with a low level error message that is hard to relate to the original objects. Therfore, it is recommended to always validate your data before constructing a PowerGridModel instance.\n", "\n", - "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See `Error Handling` section in this example notebook and [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." + "The simplest and most effective way to validate your data is by using `assert_valid_input_data()` which will throw an error if it encounters any invalid data. See the [Error Handling](#error-handling) section in this example notebook and [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] }, { "cell_type": "code", - "execution_count": 144, + "execution_count": 4, "id": "40509eaf", "metadata": {}, "outputs": [], @@ -206,7 +206,7 @@ }, { "cell_type": "code", - "execution_count": 145, + "execution_count": 5, "id": "7ef134e9", "metadata": {}, "outputs": [], @@ -243,7 +243,7 @@ }, { "cell_type": "code", - "execution_count": 146, + "execution_count": 6, "id": "44c2de63", "metadata": {}, "outputs": [], @@ -268,7 +268,7 @@ }, { "cell_type": "code", - "execution_count": 147, + "execution_count": 7, "id": "a581a36e", "metadata": {}, "outputs": [ @@ -316,7 +316,7 @@ }, { "cell_type": "code", - "execution_count": 148, + "execution_count": 8, "id": "30fdf18a", "metadata": {}, "outputs": [ @@ -376,7 +376,7 @@ }, { "cell_type": "code", - "execution_count": 149, + "execution_count": 9, "id": "ecbb8eeb", "metadata": {}, "outputs": [ @@ -435,7 +435,7 @@ }, { "cell_type": "code", - "execution_count": 150, + "execution_count": 10, "id": "1d035c65", "metadata": {}, "outputs": [], @@ -463,12 +463,13 @@ "metadata": {}, "source": [ "### Validation (optional)\n", - "When performing batch calculation/updating dataset, 'power-grid-model' provides the functions to validate See `Error Handling` section in this example notebook\n" + "\n", + "When performing batch calculation/updating dataset, `power-grid-model` provides the functions to validate. See the [Error Handling](#error-handling) section in this example notebook, or [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] }, { "cell_type": "code", - "execution_count": 151, + "execution_count": 11, "id": "63ea4cc3", "metadata": {}, "outputs": [], @@ -490,7 +491,7 @@ }, { "cell_type": "code", - "execution_count": 152, + "execution_count": 12, "id": "188f6663", "metadata": {}, "outputs": [], @@ -512,7 +513,7 @@ }, { "cell_type": "code", - "execution_count": 153, + "execution_count": 13, "id": "a93c1e16", "metadata": {}, "outputs": [ @@ -601,7 +602,7 @@ }, { "cell_type": "code", - "execution_count": 154, + "execution_count": 14, "id": "42d5cd8f", "metadata": {}, "outputs": [], @@ -633,7 +634,7 @@ }, { "cell_type": "code", - "execution_count": 155, + "execution_count": 15, "id": "4e25006f", "metadata": { "scrolled": true @@ -676,7 +677,7 @@ }, { "cell_type": "code", - "execution_count": 156, + "execution_count": 16, "id": "afccf7a2", "metadata": { "scrolled": true @@ -713,7 +714,7 @@ }, { "cell_type": "code", - "execution_count": 157, + "execution_count": 17, "id": "9af1be38", "metadata": { "scrolled": true @@ -756,7 +757,7 @@ }, { "cell_type": "code", - "execution_count": 158, + "execution_count": 18, "id": "041368dc", "metadata": {}, "outputs": [], @@ -792,7 +793,7 @@ }, { "cell_type": "code", - "execution_count": 159, + "execution_count": 19, "id": "34338ce3", "metadata": {}, "outputs": [ @@ -824,7 +825,7 @@ }, { "cell_type": "code", - "execution_count": 160, + "execution_count": 20, "id": "04e56690", "metadata": {}, "outputs": [], @@ -852,7 +853,7 @@ }, { "cell_type": "code", - "execution_count": 161, + "execution_count": 21, "id": "0d5b94c2", "metadata": {}, "outputs": [ @@ -917,8 +918,8 @@ "source": [ "## Error Handling\n", "\n", - "The error handeling of `power-grid-model` is using exceptions in all cases.\n", - "An optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions, most of them will just yield invalid results without warning.\n", + "The error handeling of `power-grid-model` is done with exceptions in all cases.\n", + "We also provide an validation mechanism is supplied, which validates data structures and values offline. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions: most of them will just yield invalid results without warning.\n", "Below we give examples of catching different error types in power grid model calculations. Refer to [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] }, @@ -935,7 +936,7 @@ }, { "cell_type": "code", - "execution_count": 162, + "execution_count": 22, "id": "b5f10bae", "metadata": {}, "outputs": [ @@ -954,7 +955,6 @@ ], "source": [ "from power_grid_model.errors import PowerGridError, ConflictVoltage\n", - "from power_grid_model.validation import ValidationException\n", "\n", "# node\n", "node_error = initialize_array(\"input\", \"node\", 2)\n", @@ -999,7 +999,7 @@ }, { "cell_type": "code", - "execution_count": 163, + "execution_count": 23, "id": "1a221507", "metadata": {}, "outputs": [ @@ -1041,7 +1041,7 @@ }, { "cell_type": "code", - "execution_count": 164, + "execution_count": 24, "id": "541af620", "metadata": {}, "outputs": [ @@ -1091,7 +1091,7 @@ }, { "cell_type": "code", - "execution_count": 165, + "execution_count": 25, "id": "20d8285c", "metadata": {}, "outputs": [], @@ -1102,7 +1102,7 @@ }, { "cell_type": "code", - "execution_count": 166, + "execution_count": 26, "id": "b702eb15", "metadata": {}, "outputs": [ @@ -1137,7 +1137,7 @@ }, { "cell_type": "code", - "execution_count": 167, + "execution_count": 27, "id": "1ba71901", "metadata": {}, "outputs": [ diff --git a/docs/examples/Validation Examples.ipynb b/docs/examples/Validation Examples.ipynb index d961115d6b..2b2c8f126d 100644 --- a/docs/examples/Validation Examples.ipynb +++ b/docs/examples/Validation Examples.ipynb @@ -7,7 +7,7 @@ "source": [ "# Validation Examples\n", "\n", - "As a result of optimizations, and the low level nature of the Power Grid Model's mathematical core, the core exceptions may not always be clear to the user. Therefore an optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions, most of them will just yield invalid results without warning." + "As a result of optimizations, and the low level nature of the Power Grid Model's mathematical core, the core exceptions may not always be clear to the user. Therefore an optional validation mechanism is supplied, which validates data structures and values off-line. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions: most of them will just yield invalid results without warning." ] }, { From 455ed49551fb5bba8a96b44d5aa55331dd132cba Mon Sep 17 00:00:00 2001 From: Zhen Wang Date: Wed, 5 Jun 2024 15:36:49 +0200 Subject: [PATCH 3/3] Update docs/examples/Power Flow Example.ipynb Co-authored-by: Jerry Guo <6221579+Jerry-Jinfeng-Guo@users.noreply.github.com> Signed-off-by: Zhen Wang --- docs/examples/Power Flow Example.ipynb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/Power Flow Example.ipynb b/docs/examples/Power Flow Example.ipynb index f12c1deb24..ce94b6c853 100644 --- a/docs/examples/Power Flow Example.ipynb +++ b/docs/examples/Power Flow Example.ipynb @@ -919,7 +919,7 @@ "## Error Handling\n", "\n", "The error handeling of `power-grid-model` is done with exceptions in all cases.\n", - "We also provide an validation mechanism is supplied, which validates data structures and values offline. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions: most of them will just yield invalid results without warning.\n", + "We also provide an validation mechanism, which validates data structures and values offline. It is recommended to always validate your data before constructing a PowerGridModel instance. An alternative approach would be to validate only when an exception is raised, but be aware that not all data errors will raise exceptions: most of them will just yield invalid results without warning.\n", "Below we give examples of catching different error types in power grid model calculations. Refer to [Validation Examples](./Validation%20Examples.ipynb) for more detailed information on the validation functions." ] },