{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5556432f",
   "metadata": {},
   "source": [
    "# Tutorial 81: Groups"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8899e69a",
   "metadata": {},
   "source": [
    "This example demonstrates how add, remove, set elements to groups."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2d40c36",
   "metadata": {},
   "source": [
    "# SIR 3S Installation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 38,
   "id": "7fb5a07b",
   "metadata": {},
   "outputs": [],
   "source": [
    "SIR3S_SIRGRAF_DIR = r\"C:\\3S\\SIR 3S\\SirGraf-90-15-00-21_Quebec-Upd2\" #change to local path"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6773e12",
   "metadata": {},
   "source": [
    "# Imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 39,
   "id": "2a62aead",
   "metadata": {},
   "outputs": [],
   "source": [
    "from sir3stoolkit.core import wrapper"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 40,
   "id": "687f2fa2-afee-4376-bd8f-5a53f288b772",
   "metadata": {},
   "outputs": [],
   "source": [
    "from sir3stoolkit.mantle import mantle"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cdb23ce-d1bb-4f8c-a800-fb8c026e9266",
   "metadata": {},
   "source": [
    "The wrapper package has to be initialized with reference to a SIR 3S (SirGraf) installation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 41,
   "id": "ee4bc044",
   "metadata": {},
   "outputs": [],
   "source": [
    "wrapper.Initialize_Toolkit(SIR3S_SIRGRAF_DIR)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2007993a",
   "metadata": {},
   "source": [
    "## Additional imports"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 42,
   "id": "60659f01",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import matplotlib.pyplot as plt\n",
    "from matplotlib.colors import LinearSegmentedColormap\n",
    "import contextily as cx"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3ab6600-34d9-4bfc-a816-96385dff31b0",
   "metadata": {},
   "source": [
    "..."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0352dd43",
   "metadata": {},
   "source": [
    "# Initialization"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "id": "7e40a5af",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Initialization complete\n"
     ]
    }
   ],
   "source": [
    "s3s = mantle.SIR3S_Model_Mantle()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d0f6dc9",
   "metadata": {},
   "source": [
    "# Open Model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 44,
   "id": "c2f6ab2c",
   "metadata": {},
   "outputs": [],
   "source": [
    "dbFilePath=r\"Toolkit_Tutorial81_Model.db3\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 45,
   "id": "efbe536c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model is open for further operation\n"
     ]
    }
   ],
   "source": [
    "s3s.OpenModel(dbName=dbFilePath,\n",
    "              providerType=s3s.ProviderTypes.SQLite,\n",
    "              Mid=\"M-1-0-1\",\n",
    "              saveCurrentlyOpenModel=False,\n",
    "              namedInstance=\"\",\n",
    "              userID=\"\",\n",
    "              password=\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "acba48c8",
   "metadata": {},
   "source": [
    "# View current state of groups"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 46,
   "id": "3a2623a1",
   "metadata": {},
   "outputs": [],
   "source": [
    "group_tks = [] # tks of group objects"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "id": "b598d70f",
   "metadata": {},
   "outputs": [],
   "source": [
    "tks_of_group_elements = [] # tks of elements inside groups"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d9c97c1e",
   "metadata": {},
   "source": [
    "We can obtain the tks part of individual groups with the function [get_tks_of_group_elements()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.mantle.html#sir3stoolkit.mantle.advanced_operations.SIR3S_Model_Advanced_Operations.get_tks_of_group_elements)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "id": "ef8d7bb3",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "0: 5566604953098438347: Vorlauf\n",
      "1: 4645068345115859295: Rücklauf\n",
      "2: 5499257419847606859: Rohre\n"
     ]
    }
   ],
   "source": [
    "for index, tk in enumerate(s3s.GetTksofElementType(s3s.ObjectTypes.LAYR_Layer)):\n",
    "    tks = s3s.get_tks_of_group_elements(tk)\n",
    "    print(f\"{index}: {tk}: {s3s.GetValue(tk, 'Name')[0]}\")\n",
    "    tks_of_group_elements.append(tks)\n",
    "    group_tks.append(tk)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "id": "097f7b3f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5428054456958551597'),\n",
       " ('KNOT', '5099111544186125239'),\n",
       " ('ROHR', '4742112892005639406')]"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tks_of_group_elements[0]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 50,
   "id": "9fbf9485",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5743596851943449715'),\n",
       " ('KNOT', '5269793380005646745'),\n",
       " ('ROHR', '5531803347555043206'),\n",
       " ('KNOT', '5629554381987149893'),\n",
       " ('ROHR', '5164228635035739777')]"
      ]
     },
     "execution_count": 50,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tks_of_group_elements[1]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "06b1b4f2",
   "metadata": {},
   "source": [
    "Note that when using this function we get lists of tuples containing both the element type and tk of each element. The reason for this is that when adding elements to other classes, we need to now both their element type and tk."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d086f1a",
   "metadata": {},
   "source": [
    "# Remove "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94162d69",
   "metadata": {},
   "source": [
    "The last two elements in the Rücklauf (return) group were mistakenly placed there and actually belong to the Vorlauf (supply) group. First, we remove them from the Rücklauf group."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 51,
   "id": "8ed13214",
   "metadata": {},
   "outputs": [],
   "source": [
    "tks_to_be_moved = [tks_of_group_elements[1][i] for i in [3,4]]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 52,
   "id": "aa895529",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5629554381987149893'), ('ROHR', '5164228635035739777')]"
      ]
     },
     "execution_count": 52,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tks_to_be_moved"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97870ad7",
   "metadata": {},
   "source": [
    "Now we have the desired format of tks and can use it with the function [remove_elements_from_group()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.mantle.html#sir3stoolkit.mantle.advanced_operations.SIR3S_Model_Advanced_Operations.remove_elements_from_group). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 53,
   "id": "02e8a0ea",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-01-25 19:08:39,353] INFO in sir3stoolkit.mantle.advanced_operations: [remove elements from group] Check successful\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.remove_elements_from_group(group_tk=group_tks[1], element_tks=tks_to_be_moved,)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8bc93fdf",
   "metadata": {},
   "source": [
    "We can check whether the elements were removed"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 54,
   "id": "27a7e7c4",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5743596851943449715'),\n",
       " ('KNOT', '5269793380005646745'),\n",
       " ('ROHR', '5531803347555043206')]"
      ]
     },
     "execution_count": 54,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[1])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "107aeb1d",
   "metadata": {},
   "source": [
    "# Add tk list to group (supply)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b4df042",
   "metadata": {},
   "source": [
    "We can now add them to the Vorlauf (supply) group using [add_elements_to_group()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.mantle.html#sir3stoolkit.mantle.advanced_operations.SIR3S_Model_Advanced_Operations.remove_elements_from_group)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 55,
   "id": "e915bed8",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-01-25 19:08:39,435] INFO in sir3stoolkit.mantle.advanced_operations: [add elements to group] Check successful\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.add_elements_to_group(group_tk=group_tks[0], element_tks=tks_to_be_moved)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a628abf9",
   "metadata": {},
   "source": [
    "We can check whether they were added."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "id": "6bb5ced3",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5428054456958551597'),\n",
       " ('KNOT', '5099111544186125239'),\n",
       " ('ROHR', '4742112892005639406'),\n",
       " ('KNOT', '5629554381987149893'),\n",
       " ('ROHR', '5164228635035739777')]"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9a968ae7",
   "metadata": {},
   "source": [
    "Furthermore we have two tks given, that are outside any group, but we want them to be part of the Vorlauf (supply) group. We dont have their element types saved with them. We can use the [add_element_types_to_tk_list()](###) function to add the element types. Note that these element types are not directley equivalent to the s3s.ObjectTypes. This function only works for District Heating network, because for others the element types would carry different names."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 57,
   "id": "0421f454",
   "metadata": {},
   "outputs": [],
   "source": [
    "tks_given = [\"4651757704563987050\", \"5520138268724292357\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "id": "0983a004",
   "metadata": {},
   "outputs": [],
   "source": [
    "tks_given_with_element_types = s3s.add_element_types_to_tk_list(tks_given)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "id": "77e4e153",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('ROHR', '4651757704563987050'), ('KNOT', '5520138268724292357')]"
      ]
     },
     "execution_count": 59,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "tks_given_with_element_types"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2246714",
   "metadata": {},
   "source": [
    "Now we have the desired format of tks and can use it with the function [add_elements_to_group()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.mantle.html#sir3stoolkit.mantle.advanced_operations.SIR3S_Model_Advanced_Operations.remove_elements_from_group). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "id": "42b279ea",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-01-25 19:08:39,532] INFO in sir3stoolkit.mantle.advanced_operations: [add elements to group] Check successful\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.add_elements_to_group(group_tk=group_tks[0], element_tks=tks_given_with_element_types)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "85982532",
   "metadata": {},
   "source": [
    "We can check whether the elements were added."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "id": "760d8610",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5428054456958551597'),\n",
       " ('KNOT', '5099111544186125239'),\n",
       " ('ROHR', '4742112892005639406'),\n",
       " ('KNOT', '5629554381987149893'),\n",
       " ('ROHR', '5164228635035739777'),\n",
       " ('ROHR', '4651757704563987050'),\n",
       " ('KNOT', '5520138268724292357')]"
      ]
     },
     "execution_count": 61,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[0])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "20eecf73",
   "metadata": {},
   "source": [
    "# Overwrite Group tk list"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "16f6fa6f",
   "metadata": {},
   "source": [
    "Let's say we want to fill the group Rohre (global list of all pipes). As is is empty at the moment."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "id": "8207f473",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[2])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "id": "bb477d35",
   "metadata": {},
   "outputs": [],
   "source": [
    "pipe_tks = []"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 64,
   "id": "413a97e2",
   "metadata": {},
   "outputs": [],
   "source": [
    "for group_tk in group_tks:\n",
    "    element_tks_with_type = s3s.get_tks_of_group_elements(group_tk=group_tk)\n",
    "    for element in element_tks_with_type:\n",
    "        if element[0] == 'ROHR':\n",
    "            pipe_tks.append(element)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 65,
   "id": "3f054f65",
   "metadata": {},
   "outputs": [],
   "source": [
    "pipe_tks = list(set(pipe_tks)) # ensure uniqueness"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 66,
   "id": "d3a9e864",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-01-25 19:08:39,627] INFO in sir3stoolkit.mantle.advanced_operations: [set elements for group] Check successful\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.set_group_elements(group_tk=group_tks[2], element_tks=pipe_tks)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 67,
   "id": "827d474c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('ROHR', '4742112892005639406'),\n",
       " ('ROHR', '5164228635035739777'),\n",
       " ('ROHR', '4651757704563987050'),\n",
       " ('ROHR', '5531803347555043206')]"
      ]
     },
     "execution_count": 67,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[2])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 68,
   "id": "46aa134e",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 68,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.CloseModel(False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01377a3f",
   "metadata": {},
   "source": [
    "# Possible Issue"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a74cd9e2",
   "metadata": {},
   "source": [
    "If we were to add a node from the Rücklauf (return) group to the Vorlauf (supply) group, but accidentley use 'ROHR' instead of 'KNOT', it would be added to the tks of the group, as there is no safe guard against this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 69,
   "id": "dba44f76",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Model is open for further operation\n"
     ]
    }
   ],
   "source": [
    "s3s.OpenModel(dbName=dbFilePath,\n",
    "              providerType=s3s.ProviderTypes.SQLite,\n",
    "              Mid=\"M-1-0-1\",\n",
    "              saveCurrentlyOpenModel=False,\n",
    "              namedInstance=\"\",\n",
    "              userID=\"\",\n",
    "              password=\"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 70,
   "id": "2f316ae6",
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "[2026-01-25 19:08:43,689] INFO in sir3stoolkit.mantle.advanced_operations: [add elements to group] Check successful\n"
     ]
    },
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.add_elements_to_group(group_tk=group_tks[0], element_tks=[('ROHR', '5269793380005646745')])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 71,
   "id": "5f36792a",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5428054456958551597'),\n",
       " ('KNOT', '5099111544186125239'),\n",
       " ('ROHR', '4742112892005639406'),\n",
       " ('ROHR', '5269793380005646745')]"
      ]
     },
     "execution_count": 71,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 72,
   "id": "398ed669",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Changes saved successfully\n"
     ]
    }
   ],
   "source": [
    "s3s.SaveChanges()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c2ce1b00",
   "metadata": {},
   "source": [
    "But after saving the changes, it would we removed automatically from the list."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "id": "e7e8b932",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[('KNOT', '5428054456958551597'),\n",
       " ('KNOT', '5099111544186125239'),\n",
       " ('ROHR', '4742112892005639406')]"
      ]
     },
     "execution_count": 73,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.get_tks_of_group_elements(group_tk=group_tks[0])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 74,
   "id": "04864107",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 74,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "s3s.CloseModel(False)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "base",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}