add docs example

Signed-off-by: Nitish Bharambe <nitish.bharambe@alliander.com>

Author: nitbharambe

docs/api_reference/python-api-reference.md

@@ -14,6 +14,8 @@ This is the Python API reference for the `power-grid-model` library
 .. autoclass:: PowerGridModel
    :show-inheritance:
 .. autofunction:: initialize_array
+.. autofunction:: attribute_dtype
+.. autofunction:: attribute_empty_value
 
 .. py:data:: power_grid_meta_data
    :type: typing.PowerGridMetaData

docs/examples/Power Flow Example.ipynb

@@ -49,7 +49,7 @@
     "\n",
     "from power_grid_model import LoadGenType, ComponentType, DatasetType, ComponentAttributeFilterOptions\n",
     "from power_grid_model import PowerGridModel, CalculationMethod, CalculationType\n",
-    "from power_grid_model import initialize_array, power_grid_meta_data"
+    "from power_grid_model import initialize_array, attribute_dtype"
    ]
   },
   {
@@ -127,7 +127,7 @@
     "\n",
     "A columnar data format better integrates with most databases. In addition, it may bring memory and, in some cases, even computational performance improvements, because unused attribute columns can be omitted.\n",
     "\n",
-    "Make sure to provide the correct `dtype` to the numpy arrays, exposed for each dataset type, component and attribute via the `power_grid_meta_data` object."
+    "Make sure to provide the correct `dtype` to the numpy arrays, exposed for each dataset type, component and attribute via the helper function `attribute_dtype` function."
    ]
   },
   {
@@ -137,12 +137,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "source_attribute_dtypes = power_grid_meta_data[DatasetType.input][ComponentType.source].dtype\n",
     "source_columns = {\n",
-    "    \"id\": np.array([10], dtype=source_attribute_dtypes[\"id\"]),\n",
-    "    \"node\": np.array([1], dtype=source_attribute_dtypes[\"node\"]),\n",
-    "    \"status\": np.array([1], dtype=source_attribute_dtypes[\"status\"]),\n",
-    "    \"u_ref\": np.array([1.0], dtype=source_attribute_dtypes[\"u_ref\"]),\n",
+    "    \"id\": np.array([10], dtype=attribute_dtype(DatasetType.input, ComponentType.source, \"id\")),\n",
+    "    \"node\": np.array([1], dtype=attribute_dtype(DatasetType.input, ComponentType.source, \"node\")),\n",
+    "    \"status\": np.array([1], dtype=attribute_dtype(DatasetType.input, ComponentType.source, \"status\")),\n",
+    "    \"u_ref\": np.array([1.0], dtype=attribute_dtype(DatasetType.input, ComponentType.source, \"u_ref\")),\n",
     "    # We're not creating columns for u_ref_angle, sk, ... Instead, the default values are used. This saves us memory.\n",
     "}\n",
     "\n",
@@ -403,7 +402,7 @@
       "List of attribute types in line result\n",
       "['id', 'p_from']\n",
       "------line result------\n",
-      "{'id': array([3, 5, 8], dtype=int32), 'p_from': array([17360100.20222374, -3365613.74450156, 13854413.52498137])}\n"
+      "{'id': array([3, 5, 8]), 'p_from': array([17360100.20222374, -3365613.74450156, 13854413.52498137])}\n"
      ]
     }
    ],
@@ -674,10 +673,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "line_update_dtype = power_grid_meta_data[DatasetType.update][ComponentType.line].dtype\n",
     "columnar_update_line = {\n",
-    "    \"id\": np.array([3], dtype=line_update_dtype[\"id\"]),  # change line ID 3\n",
-    "    \"from_status\": np.array([0], dtype=line_update_dtype[\"from_status\"]),  # switch off at from side\n",
+    "    \"id\": np.array([3], dtype=attribute_dtype(DatasetType.update, ComponentType.line, \"id\")),  # change line ID 3\n",
+    "    \"from_status\": np.array(\n",
+    "        [0], dtype=attribute_dtype(DatasetType.update, ComponentType.line, \"from_status\")\n",
+    "    ),  # switch off at from side\n",
     "}\n",
     "# leave to-side swiching status the same, no need to specify\n",
     "\n",
@@ -699,11 +699,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "line_update_dtype = power_grid_meta_data[DatasetType.update][ComponentType.line].dtype\n",
     "columnar_no_ID_update_line = {\n",
     "    # Update IDs are not specified\n",
     "    \"from_status\": np.array(\n",
-    "        [0, 1, 1], dtype=line_update_dtype[\"from_status\"]\n",
+    "        [0, 1, 1], dtype=attribute_dtype(DatasetType.update, ComponentType.line, \"from_status\")\n",
     "    ),  # The update for the whole column needs to be specified\n",
     "}\n",
     "# leave to-side swiching status the same, no need to specify\n",
@@ -1404,16 +1403,16 @@
      "output_type": "stream",
      "text": [
       "Node data with invalid results\n",
-      "[[0.99940117 0.99268579 0.99452137]\n",
-      " [0.99934769 0.98622639 0.98935286]\n",
-      " [0.99928838 0.97965401 0.98409554]\n",
-      " [0.         0.         0.        ]\n",
-      " [0.99915138 0.96614948 0.97329879]\n",
-      " [0.99907317 0.95920586 0.96775071]\n",
-      " [0.9989881  0.95212621 0.96209647]\n",
-      " [0.         0.         0.        ]\n",
-      " [0.99879613 0.93753005 0.95044796]\n",
-      " [0.9986885  0.92999747 0.94444167]]\n",
+      "[[9.99401170e-001 9.92685785e-001 9.94521366e-001]\n",
+      " [9.99347687e-001 9.86226389e-001 9.89352855e-001]\n",
+      " [9.99288384e-001 9.79654011e-001 9.84095542e-001]\n",
+      " [6.95296562e-310 8.59448882e-312 6.95296562e-310]\n",
+      " [9.99151380e-001 9.66149483e-001 9.73298790e-001]\n",
+      " [9.99073166e-001 9.59205860e-001 9.67750710e-001]\n",
+      " [9.98988099e-001 9.52126208e-001 9.62096474e-001]\n",
+      " [8.59448882e-312 8.59448882e-312 6.95296562e-310]\n",
+      " [9.98796126e-001 9.37530046e-001 9.50447962e-001]\n",
+      " [9.98688504e-001 9.29997471e-001 9.44441670e-001]]\n",
       "Node data with only valid results\n",
       "[[0.99940117 0.99268579 0.99452137]\n",
       " [0.99934769 0.98622639 0.98935286]\n",
@@ -1456,7 +1455,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "venv",
+   "display_name": ".venv",
    "language": "python",
    "name": "python3"
   },
@@ -1470,7 +1469,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.13.0"
+   "version": "3.12.7"
   }
  },
  "nbformat": 4,