{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "5556432f",
   "metadata": {},
   "source": [
    "# Tutorial 5: Editing a SIR 3S model safely and effectively"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8899e69a",
   "metadata": {},
   "source": [
    "This Tutorial demonstrates how to change SIR 3S models properly by grouping changes and saving them."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8965dede",
   "metadata": {},
   "source": [
    "The database used for this Tutorial is based on [Network1](https://3sconsult.github.io/sir3stoolkit/examples.html#network-1)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2d40c36",
   "metadata": {},
   "source": [
    "## SIR 3S Installation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "7fb5a07b",
   "metadata": {},
   "outputs": [],
   "source": [
    "SIR3S_SIRGRAF_DIR = r\"C:\\3S\\SIR 3S Entwicklung\\SirGraf-90-15-00-16_Quebec_x64\" #change to local path"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7887be8d",
   "metadata": {},
   "source": [
    "## Imports"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bbfb80b5",
   "metadata": {},
   "source": [
    "Note: The SIR 3S Toolkit requires the Sir3S_Toolkit.dll included in SIR 3S installations (version Quebec and higher)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "48372080",
   "metadata": {},
   "outputs": [],
   "source": [
    "import sir3stoolkit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e12d61e9",
   "metadata": {},
   "source": [
    "The core of sir3stoolkit is a Python wrapper around basic functionality of SIR 3S, offering a low-level access to the creation, modification and simulation of SIR 3S models. In the future pure python subpackages may be added."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "f1baf699",
   "metadata": {},
   "outputs": [],
   "source": [
    "from sir3stoolkit.core import wrapper"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "89da1276",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<module 'sir3stoolkit' from 'C:\\\\Users\\\\aUsername\\\\3S\\\\sir3stoolkit\\\\src\\\\sir3stoolkit\\\\__init__.py'>"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "sir3stoolkit"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d982834",
   "metadata": {},
   "source": [
    "The [wrapper package](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.Initialize_Toolkit) has to be has to be initialized with reference to a SIR 3S (SirGraf) installation."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "817b0ebf",
   "metadata": {},
   "outputs": [],
   "source": [
    "wrapper.Initialize_Toolkit(SIR3S_SIRGRAF_DIR)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0352dd43",
   "metadata": {},
   "source": [
    "## Initialization"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e14ffe06",
   "metadata": {},
   "source": [
    "The SIR 3S Toolkit contains two classes: [SIR3S_Model](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model) (model and data) and [SIR3S_View](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_View) (depiction in SIR Graf). All SIR 3S functionality is accessed via the methods of these classes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "7e40a5af",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Initialization complete\n"
     ]
    }
   ],
   "source": [
    "s3s = wrapper.SIR3S_Model()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "3770c93f",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Initialization complete\n"
     ]
    }
   ],
   "source": [
    "s3s_view = wrapper.SIR3S_View()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c4a5bec",
   "metadata": {},
   "source": [
    "## Open Model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "cec957b0",
   "metadata": {},
   "outputs": [],
   "source": [
    "dbFilePath=r\"Toolkit_Tutorial5_Model.db3\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "546e92ff",
   "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": "5035ff6f",
   "metadata": {},
   "source": [
    "Now the model has been opened. All SIR 3S Toolkit operations now apply to this model until another one is opened."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "4da7e2b4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "NetworkType.Water\n"
     ]
    }
   ],
   "source": [
    "print(s3s.GetNetworkType()) # check that the correct model is responsive, model we are trying to open was created with type Water"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f31cf03f",
   "metadata": {},
   "source": [
    "## SIR 3S object types"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "017670dd",
   "metadata": {},
   "source": [
    "As we did with non-result values, we need to obtain the internal SIR 3S object types to later pass to our function for obtaining the attribute names."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "096876af",
   "metadata": {},
   "outputs": [],
   "source": [
    "node_type=s3s.ObjectTypes.Node"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "9905c01c",
   "metadata": {},
   "outputs": [],
   "source": [
    "pipe_type=s3s.ObjectTypes.Pipe"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a8e200b",
   "metadata": {},
   "source": [
    "## GetPropertiesofElementType()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7eb85f36",
   "metadata": {},
   "source": [
    "Now, we obtain the internal SIR 3S attribute names. These will be necessary for our value query."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b899287e",
   "metadata": {},
   "source": [
    "We use [GetPropertiesofElementType()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.GetPropertiesofElementType) to create a list of all properties of nodes and pipes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "a98e7614",
   "metadata": {},
   "outputs": [],
   "source": [
    "node_properties=s3s.GetPropertiesofElementType(node_type)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "a2ca0eda",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Name', 'Ktyp', 'Zkor', 'QmEin', 'Lfakt', 'Fkpzon', 'Fkfstf', 'Fkutmp', 'Fkfqps', 'Fkcont', 'Fk2lknot', 'Beschreibung', 'Idreferenz', 'Iplanung', 'Kvr', 'Qakt', 'Xkor', 'Ykor', 'NodeNamePosition', 'ShowNodeName', 'KvrKlartext', 'NumberOfVERB', 'HasBlockConnection', 'Tk', 'Pk', 'IsMarked', 'InVariant', 'GeometriesDiffer', 'SymbolFactor', 'bz.Drakonz', 'bz.Fk', 'bz.Fkpvar', 'bz.Fkqvar', 'bz.Fklfkt', 'bz.PhEin', 'bz.Tm', 'bz.Te', 'bz.PhMin']\n"
     ]
    }
   ],
   "source": [
    "print(node_properties)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15f3361d",
   "metadata": {},
   "source": [
    "## Start/EndTransaction()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d8ba7e83",
   "metadata": {},
   "source": [
    "The [StartTransaction()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.StartTransaction) function opens a transaction. All changes made to the model afterwards are grouped into this transaction until [EndTransaction()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.EndTransaction) is called. This allows the User to Undo/Redo changes on main UI. A meaningful name should be assigned to each transaction."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "9a57b2e5",
   "metadata": {},
   "outputs": [],
   "source": [
    "nodes=s3s.GetTksofElementType(ElementType=node_type)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3b9524da",
   "metadata": {},
   "source": [
    "Our goal is to reposition node 0 and 5 in our list. Their current position can be ckecked as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "49b7d131",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tk: 5176769967470325679, X: 200, Y: 700\n"
     ]
    }
   ],
   "source": [
    "print(f\"Tk: {s3s.GetValue(nodes[0], 'Tk')[0]}, X: {s3s.GetValue(nodes[0], 'Xkor')[0]}, Y: {s3s.GetValue(nodes[0], 'Ykor')[0]}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "92798a5d",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tk: 4906284669343590719, X: 500, Y: 400\n"
     ]
    }
   ],
   "source": [
    "print(f\"Tk: {s3s.GetValue(nodes[5], 'Tk')[0]}, X: {s3s.GetValue(nodes[5], 'Xkor')[0]}, Y: {s3s.GetValue(nodes[5], 'Ykor')[0]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bb954ff2",
   "metadata": {},
   "source": [
    "Start Transaction"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "id": "89698f13",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Now you can make changes to the model\n"
     ]
    }
   ],
   "source": [
    "s3s.StartTransaction(\"Change coords of nodes 5452027739517825954 and 5500965656985444769\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "a6876ef2",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.SetValue(Tk=nodes[0], propertyName=\"Ykor\", Value=str(int(s3s.GetValue(nodes[0], \"Ykor\")[0])+100)) # add 100 to y coord"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "id": "65f396ec",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.SetValue(Tk=nodes[5], propertyName=\"Xkor\", Value=str(int(s3s.GetValue(nodes[5], \"Xkor\")[0])-75)) # sub 75 from x coord"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "id": "f128dd6a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "s3s.SetValue(Tk=nodes[5], propertyName=\"Ykor\", Value=\"450\")  # set y coord to 450"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "id": "949f4d30",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Nothing done, because no Transaction is being in Use\n"
     ]
    }
   ],
   "source": [
    "s3s.EndTransaction()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "136f9023",
   "metadata": {},
   "source": [
    "As of now there appears to be a bug present that Transactions are closed without using EndTransaction().\n",
    "https://github.com/3SConsult/sir3stoolkit/issues/2"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d6c1916f",
   "metadata": {},
   "source": [
    "Now we can check our nodes and review the changes made."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "id": "239491ed",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tk: 5176769967470325679, X: 200, Y: 800\n"
     ]
    }
   ],
   "source": [
    "print(f\"Tk: {s3s.GetValue(nodes[0], 'Tk')[0]}, X: {s3s.GetValue(nodes[0], 'Xkor')[0]}, Y: {s3s.GetValue(nodes[0], 'Ykor')[0]}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "id": "6a333764",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Tk: 4906284669343590719, X: 425, Y: 450\n"
     ]
    }
   ],
   "source": [
    "print(f\"Tk: {s3s.GetValue(nodes[5], 'Tk')[0]}, X: {s3s.GetValue(nodes[5], 'Xkor')[0]}, Y: {s3s.GetValue(nodes[5], 'Ykor')[0]}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47472e50",
   "metadata": {},
   "source": [
    "## Start/EndEditSession()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d182166",
   "metadata": {},
   "source": [
    "The [StartEditSession()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.StartEditSession) and [EndEditSession()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.EndEditSession) function are applied the same way as [StartTransaction()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.StartTransaction) and [EndTransaction()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.EndTransaction). The difference is that a session compared to a transaction is designed for bulk changes like changing the values of 40 thousands nodes in a single task."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fbd86148",
   "metadata": {},
   "source": [
    "As so many nodes are a bit overkill for a simple tutorial, we will just show the usage by changing the Zkor of all 11 nodes in our model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "id": "a7e4cd76",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Now you can make changes to the model\n"
     ]
    }
   ],
   "source": [
    "s3s.StartEditSession(SessionName=\"Change Zkor of all nodes to 100\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "id": "ee06f32c",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n",
      "Value is set\n"
     ]
    }
   ],
   "source": [
    "for node in nodes:\n",
    "    s3s.SetValue(Tk=node, propertyName=\"Zkor\", Value=\"100\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "id": "ab38e155",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Edit Session has ended. Please open up a new session if you want to make further changes\n"
     ]
    }
   ],
   "source": [
    "s3s.EndEditSession()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4024f2cc",
   "metadata": {},
   "source": [
    "## SaveChanges()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91ea99d3",
   "metadata": {},
   "source": [
    "To save the changes you have made to a model whether grouped into transactions/edit-sessions or not grouped, you can use the [SaveChanges()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.SaveChanges) function to do so."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "50ee3cca",
   "metadata": {},
   "source": [
    "The below function will therefore save the changes made to the model if uncommented."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "id": "25881666",
   "metadata": {},
   "outputs": [],
   "source": [
    "#s3s.SaveChanges()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94031021",
   "metadata": {},
   "source": [
    "## RefreshViews()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1d0207d5",
   "metadata": {},
   "source": [
    "The [RefreshViews()](https://3sconsult.github.io/sir3stoolkit/references/sir3stoolkit.core.html#sir3stoolkit.core.wrapper.SIR3S_Model.RefreshViews) function can be helpful when working with SIR 3S Toolkit in the built-in python scripting environment in SIR Graf. The function will force the presenter (SIR Graf) to refresh it views. If you made changes such as inserting a new object or change visual aspects this function ensures that they will be displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "id": "516ee3d8",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Refresh successful\n"
     ]
    }
   ],
   "source": [
    "s3s.RefreshViews()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "18c0c05d",
   "metadata": {},
   "source": [
    "## General approach to changing models"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "31626beb",
   "metadata": {},
   "source": [
    "Below a recommendation on how to structure and encapsulate code that modifies models is given."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "a65ef4cc",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Now you can make changes to the model\n"
     ]
    }
   ],
   "source": [
    "s3s.StartTransaction(SessionName=\"Transaction Name\")  # or EditSession, depending on the 'size' of the change"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 31,
   "id": "17345c28",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Make all kinds of changes"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 32,
   "id": "c1efc29a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Transaction has ended. Please open up a new transaction if you want to make further changes\n"
     ]
    }
   ],
   "source": [
    "s3s.EndTransaction()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 33,
   "id": "96f6a74e",
   "metadata": {},
   "outputs": [],
   "source": [
    "#s3s.SaveChanges()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 34,
   "id": "6534b89a",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Refresh successful\n"
     ]
    }
   ],
   "source": [
    "s3s.RefreshViews()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1f6a0f25-1c89-420e-a49e-abc6d087fb57",
   "metadata": {},
   "source": [
    "__Next:__ Tutorial 6: Insert and Connect Elements"
   ]
  }
 ],
 "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
}