Merge pull request #249 from PowerGridModel/feature/GUID-in-extra-info

Feature/Adding GUID info to the `extra_info` field

docs/converters/vision_converter.md

@@ -43,4 +43,9 @@ Some components are yet to be modeled for conversions because they might not hav
 - The conversions for load behaviors of `industry`, `residential` and `business` are not yet modeled. The load behaviors usually do not create a significant difference in power-flow results for most grids when the voltage at bus is close to `1 pu`. Hence, the conversion of the mentioned load behaviors is approximated to be of `Constant Power` type for the time being. 
 - The source bus in power-grid-model is mapped with a source impedance. `Sk"nom`, `R/X` and `Z0/Z1` are the attributes used in modeling source impedance. In Vision, these attributes are used only for short circuit calculations
 - The load rate for transformer is calculated in Vision by current i.e., `load_rate = max(u1 * I1, u2 * I2) * sqrt(3) / Snom * 100`. Whereas in power-grid-model, loading is calculated by power, i.e., `loading = max(s1,s2)/sn`. (Note: The attribute names are as per relevant notation in Vision and PGM respectively). This gives a slight difference in load rate of transformer.
-- A minor difference in results is expected since Vision uses a power mismatch in p.u. as convergence criteria whereas power-grid-model uses voltage mismatch.
+- A minor difference in results is expected since Vision uses a power mismatch in p.u. as convergence criteria whereas power-grid-model uses voltage mismatch.
+
+## Accomdation of UUID-based id system since Vision 9.7
+Vision introduced UUID based identifier system since version 9.7. It is implemented following the Microsoft naming scheme by replacing all the original identifier fields (i.e., '*Number', '*Subnumber', '*Nummber' and '*Subnummer') to GUID. This change brings the many benefits of UUIDs in general while on the other hand adds certain work on the conversion side. Since computations in PGM alone do not benefit from a string based identifier, we hence made the descision to perform UUID to integer conversion while maintaining the 'GUID' information in the `extra_info` field. Note that existing mapping files can still be used without significant changes, apart from adding `GUID` to the `extra` fields of interest.
+
+An examplery usage can be found in the example notebook as well as in the test cases.

docs/examples/vision_example.ipynb

@@ -415,6 +415,60 @@
     "    display(Markdown(f\"<pre style='max-height: 160px; overflow: scroll; white-space: pre'>{json_file.read()}</pre>\"))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### GUID (Vision 9.7 and later)\n",
+    "To accomdate GUIDs since version 9.7, we have internal conversion mechanism that converts GUID's to unique integers (persession). This change does not impact anything on the user side. Therefore, loading such new excel files is performed exactly as in previous versions. Here, we only show how one could add corresponding GUID information to the extra_info. \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In the custom mapping file, add `GUID` to the `extra` field of interest:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# custom yaml mapping file\n",
+    "...\n",
+    "grid:\n",
+    "  Nodes:\n",
+    "    node:\n",
+    "      id:\n",
+    "        auto_id:\n",
+    "          key: Number\n",
+    "      u_rated: Unom\n",
+    "      extra:\n",
+    "        - ID\n",
+    "        - Name\n",
+    "        - GUID\n",
+    "  Cables:\n",
+    "    line:\n",
+    "      id:\n",
+    "        auto_id:\n",
+    "          key: Number\n",
+    "      from_node:\n",
+    "        auto_id:\n",
+    "          table: Nodes\n",
+    "          key:\n",
+    "            Number: From.Number\n",
+    "..."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "When run excel conversion with mapping file that contains this change, `GUID` information will be part of the returned `extra_info`."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},