doc/training/6_Model_Setup_and_Configuration.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": false,
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Putting the initialisation at the top now!\n",
    "import veneer\n",
    "%matplotlib inline\n",
    "import matplotlib.pyplot as plt\n",
    "import pandas as pd\n",
    "import numpy as np\n",
    "\n",
    "v = veneer.Veneer(port=9876)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Session 6 - Model Setup and Reconfiguration\n",
    "\n",
    "This session covers functionality in Veneer and veneer-py for making larger changes to model setup, including structural changes.\n",
    "\n",
    "Using this functionality, it is possible to:\n",
    "\n",
    "* Create (and remove) nodes and links\n",
    "* Change model algorithms, such as changing links from Straight Through Routing to Storage Routing\n",
    "* Assign input time series to model variables\n",
    "* Query and modify parameters across similar nodes/links/catchments/functional-units\n",
    "\n",
    "## Overview\n",
    "\n",
    "- (This is a Big topic)\n",
    "- Strengths and limitations of configuring from outside\n",
    "  - +ve repeatability\n",
    "  - +ve clarity around common elements - e.g. do one thing everywhere, parameterised by spatial data\n",
    "  - -ve feedback - need to query the system to find out what you need to do vs a GUI that displays it\n",
    "- Obvious and compelling use cases\n",
    "  - Catchments: Applying a constituent model everywhere and assigning parameters using spatial data\n",
    "  - Catchments: Climate data\n",
    "- How it works:\n",
    "  - The Python <-> IronPython bridge\n",
    "  - What’s happening under the hood\n",
    "  - Layers of helper functions\n",
    "  - How to discover parameters\n",
    "- Harder examples (not fully worked)\n",
    "  - Creating and configuring a storage from scratch\n",
    "- Extending the system\n",
    "\n",
    "\n",
    "## Which Model?\n",
    "\n",
    "**Note:** This session uses `ExampleProject/RiverModel2.rsproj`. You are welcome to work with your own model instead, however you will need to change the notebook text at certain points to reflect the names of nodes, links and functions in your model file.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Warning: Big Topic\n",
    "\n",
    "This is a big topic and the material in this session will only touch on some of the possibilities.\n",
    "\n",
    "Furthermore, its an evolving area - so while there is general purpose functionality that is quite stable, making the functionality easy to use for particular tasks is a case by case basis that has been tackled on an as-needed basis. **There are lots of gaps!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Motivations, Strengths and Limitations of Scripting configuration\n",
    "\n",
    "There are various motivations for the type of automation of Source model setup described here. Some of these motivations are more practical to achieve than others!\n",
    "\n",
    "### Automatically build a model from scratch, using an executable 'recipe'\n",
    "\n",
    "Could you build a complete Source model from scratch using a script?\n",
    "\n",
    "In theory, yes you could. However it is not practical at this point in time using Veneer. (Though the idea of building a catchments-style model is more foreseeable than building a complex river model).\n",
    "\n",
    "For some people, building a model from script would be desirable as it would have some similarities to configuring models in text files as was done with the previous generation of river models. A script would be more powerful though, because it has the ability to bring in adhoc data sources (GIS layers, CSV files, etc) to define the model structure. The scripting approach presented here wouldn't be the most convenient way to describe a model node-by-node, link-by-link - it would be quite cumbersome. However it would be possible to build a domain-specific language for describing models that makes use of the Python scripting.\n",
    "\n",
    "### Automate bulk changes to a model\n",
    "\n",
    "Most of the practical examples to date have involved applying some change across a model (whether that model is a catchments-style geographic model or a schematic style network). Examples include:\n",
    "\n",
    "* **Apply a new constituent generation model:** A new generation model was being tested and needed to be applied to every catchment in the model. Some of the parameters would subsequently be calibrated (using PEST), but others needed to be derived from spatial data.\n",
    "* **Add and configure nodes for point source inputs:** A series of point sources needed to be represented in the models. This involved adding inflow nodes for each point source, connecting those inflows to the most appropriate (and available) downstream node and computing and configuring time series inputs for the inflows.\n",
    "* **Bulk rename nodes and links based on a CSV file:** A complex model needed a large number of nodes and links renamed to introduce naming conventions that would allow automatic post-processing and visualisation. A CSV was created with old node/link names (extracted from Source using veneer-py). A second column in the CSV was then populated (by hand) with new node/link names. This CSV file was read into Python and used to apply new names to affected nodes/links.\n",
    "\n",
    "### Change multiple models in a consistent way\n",
    "\n",
    "* **Testing a plugin in multiple catchments:** A new plugin model was being tested across multiple catchments models, including calibration. A notebook was written to apply the plugin to a running Source model, parameterise the plugin and configure PEST. This notebook was then applied to each distinct Source model in turn.\n",
    "\n",
    "### Change a model without making the changes permanent\n",
    "\n",
    "There are several reasons for making changes to the Source model without wanting the changes to be permanently saved in the model.\n",
    "\n",
    "1. Testing an alternative setup, such as a different set of routing parameters. Automating the application of new parameters means you can test, and then re-test at a later date, without needing manual rework.\n",
    "2. Maintaining a single point-of-truth for a core model that needs to support different purposes and users.\n",
    "3. Persistence not available. In the earlier examples of testing new plugin models, the automated application of model setup allowed sophisticated testing, including calibration by PEST, to take place before the plugin was stable enough to be persisted using the Source data management system.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Example - Switching routing methods and configuring\n",
    "\n",
    "This example uses the earlier `RiverModel.rsproj` example file although it will work with other models.\n",
    "\n",
    "Here, we will convert all links to use Storage Routing except for links that lead to a water user.\n",
    "\n",
    "**Note:** To work through this example (and the others that follow), you will need to ensure the 'Allow Scripts' option is enabled in the Web Server Monitoring window."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### The `v.model` namepsace\n",
    "\n",
    "Most of our work in this session will involve the `v.model` namespace. This namespace contains functionality that provides query and modification of the model structure. Everything in `v.model` relies on the 'Allow Scripts' option.\n",
    "\n",
    "As with other parts of veneer-py (and Python packages in general), you can use `<tab>` completion to explore the available functions and the `help()` function (or the `?` suffix) to get help."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Finding the current routing type\n",
    "\n",
    "We can use `v.model.link.routing.get_models()` to find the routing models used on each link"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.LaggedFlowRoutingWrapper',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting']"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "existing_models = v.model.link.routing.get_models()\n",
    "existing_models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:**\n",
    "\n",
    "* The `get_models()` functions is available in various places through the `v.model` namespace. For example, `v.model.catchments.runoff.get_models()` queries the rainfall runoff models in subcatchments (actually in functional units). There are other such methods, available in multiple places, including:\n",
    "  * `set_models`\n",
    "  * `get_param_values`\n",
    "  * `set_param_values`\n",
    "* These functions are all *bulk* functions - that is they operate across *all* matching elements (all nodes, all links, etc).\n",
    "* Each of these functions accept parameters to restrict the search, such as only including links with certain names. These query parameters differ in different contexts (ie between runoff models and routing models), but they are consistent between the functions in a given context. Confused?\n",
    "* For example, in link routing you can look for links of certain names and you can do this with the different methods:\n",
    "```python\n",
    "v.model.link.routing.get_models(links='Default Link #3')\n",
    "v.model.link.routing.set_models('RiverSystem.Flow.LaggedFlowRoutingWrapper',links='Default Link #3')\n",
    "```\n",
    "Whereas, with runoff models, you can restrict by catchment or by fus:\n",
    "```python\n",
    "v.model.catchment.runoff.get_models(fus='Grazing')\n",
    "v.model.catchment.runoff.set_models('MyFancyRunoffModel',fus='Grazing')\n",
    "```\n",
    "* You can find out what query parameters are available by looking at the help, one level up:\n",
    "```python\n",
    "help(v.model.link.routing)\n",
    "```\n",
    "* The call to `get_models()` return a list of model names. Two observations about this:\n",
    "  1. The model name is the fully qualified class name as used internally in Source. This is a common pattern through the `v.model` namespace - it uses the terminology within Source. There are, however, help functions for finding what you need. For example:\n",
    "  ```python\n",
    "  v.model.find_model_type('gr4')\n",
    "  v.model.find_parameters('RiverSystem.Flow.LaggedFlowRoutingWrapper')\n",
    "  ```\n",
    "  2. Returning a list doesn't tell you which link has which model - so how are you going to determine which ones should be Storage Routing and which should stay as Straight Through? In general the `get_` functions return lists (although there is a `by_name` option being implemented) and the `set_` functions accept lists (unless you provide a single value in which case it is applied uniformly). It is up to you to interpret the lists returned by `get_*` and to provide `set_*` with a list in the right order. The way to get it right is to separately query for the _names_ of the relevant elements (nodes/links/catchments) and order accordingly. This will be demonstrated!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Identifying which link should stay as StraightThroughRouting\n",
    "\n",
    "We can ask for the names of each link in order to establish which ones should be Storage Routing and which should stay as Straight Through"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Default Link #1',\n",
       " 'Default Link #2',\n",
       " 'Default Link #3',\n",
       " 'Default Link #4',\n",
       " 'Default Link #5',\n",
       " 'Default Link #6',\n",
       " 'Lake Outflow',\n",
       " 'Default Link #13',\n",
       " 'Default Link #14',\n",
       " 'Default Link #15',\n",
       " 'Default Link #11']"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "link_names_order = v.model.link.routing.names()\n",
    "link_names_order"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OK - that gives us the names - but it doesn't help directly. We could look at the model in Source to\n",
    "work out which one is connected to the Water User - but that's cheating!\n",
    "\n",
    "More generally, we can ask Veneer for the network and perform a topological query"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "network = v.network()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that we've got the network, we want all the water users.\n",
    "\n",
    "Now, the information we've been returned regarding the network is in GeoJSON format and is intended for use in visualisation. It doesn't explicitly say 'this is a water user' at any point, but it does tell us indirectly tell us this by telling us about the icon in use:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'/resources/InjectedFlow',\n",
       " '/resources/ExtractionNodeModel',\n",
       " '/resources/WaterUserNodeModel',\n",
       " '/resources/GaugeNodeModel',\n",
       " '/resources/ConfluenceNodeModel',\n",
       " '/resources/MinimumFlowConstraintModel',\n",
       " None,\n",
       " '/resources/StorageNodeModel'}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "network['features']._unique_values('icon')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, we can find all the water users in the network, by finding all the network features with `'/resources/WaterUserNodeModel'` as their icon!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'Feature', 'properties': {'schematic_location': [329, 617], 'icon': '/resources/WaterUserNodeModel', 'name': 'Crop Fields', 'feature_type': 'node'}, 'id': '/network/nodes/94', 'geometry': {'type': 'Point', 'coordinates': [0, 0]}}]"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "water_users = network['features'].find_by_icon('/resources/WaterUserNodeModel')\n",
    "water_users"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we can query the network for links upstream of each water user.\n",
    "\n",
    "We'll loop over the `water_users` list (just one in the sample model)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'geometry': {'coordinates': [[0, 0], [0, 0]], 'type': 'LineString'},\n",
       "  'id': '/network/link/7',\n",
       "  'properties': {'feature_type': 'link',\n",
       "   'from_node': '/network/nodes/90',\n",
       "   'name': 'Default Link #13',\n",
       "   'to_node': '/network/nodes/94'},\n",
       "  'type': 'Feature'}]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "links_upstream_of_water_users=[]\n",
    "for water_user in water_users:\n",
    "    links_upstream_of_water_users += network.upstream_links(water_user)\n",
    "links_upstream_of_water_users"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Just one link (to be expected) in the sample model. Its the name we care about though:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Default Link #13']"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "names_of_water_user_links = [link['properties']['name'] for link in links_upstream_of_water_users]\n",
    "names_of_water_user_links"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To recap, we now have:\n",
    "\n",
    "* `existing_models` - A list of routing models used on links\n",
    "* `link_names_order` - The name of each link, in the same order as for `existing_models`\n",
    "* `names_of_water_user_links` - The names of links immediately upstream of water users. These links need to stay as Straight Through Routing\n",
    "\n",
    "We're ultimately going to call\n",
    "\n",
    "```python\n",
    "v.model.link.routing.set_models(new_models,fromList=True)\n",
    "```\n",
    "\n",
    "so we need to construct `new_models`, which will be a list of model names to assign to links, with the right mix and order of storage routing and straight through. We'll want `new_models` to be the same length as `existing_models` so there is one entry per link. (There are cases where you my use `set_models` or `set_param_values` with shorter lists. You'll get R-style 'recycling' of values, but its more useful in catchments where you're iterating over catchments AND functional units)\n",
    "\n",
    "The entries in `new_models` need to be strings - those long, fully qualified class names from the Source world. We can find them using `v.model.find_model_type`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Flow.StorageRouting']"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.find_model_type('StorageRo')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Flow.StraightThroughRouting']"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.find_model_type('StraightThrough')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can construct our list using a list comprehension, this time with a bit of extra conditional logic thrown in"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StraightThroughRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting',\n",
       " 'RiverSystem.Flow.StorageRouting']"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "new_models = ['RiverSystem.Flow.StraightThroughRouting' if link_name in names_of_water_user_links\n",
    "              else 'RiverSystem.Flow.StorageRouting'\n",
    "              for link_name in link_names_order]\n",
    "new_models"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is a more complex list comprehension than we've used before. It goes like this, reading from the end:\n",
    "\n",
    "* Iterate over all the link names. This will be the right number of elements - and it tells us which link we're dealling with\n",
    "```python\n",
    " for link_name in link_names_order]\n",
    "```\n",
    "* If the current `link_name` is present in the list of links upstream of water users, use straight through routing\n",
    "```python\n",
    "['RiverSystem.Flow.StraightThroughRouting' if link_name in names_of_water_user_links\n",
    "```\n",
    "* Otherwise use storage routing\n",
    "```python\n",
    " else 'RiverSystem.Flow.StorageRouting'\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "All that's left is to apply this to the model"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.link.routing.set_models(new_models,fromList=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Notes:**\n",
    "\n",
    "* The Source Applications draws links with different line styles based on their routing types - but it might not redraw until you prompt it - eg by resizing the window\n",
    "* The `fromList` parameter tells the `set_models` function that you want the list to be applied one element at a time."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now that you have Storage Routing used in most links, you can start to parameterise the links from the script.\n",
    "\n",
    "To do so, you could use an input set, as per the previous session. To change parameters via input sets, you would first need to know the wording to use in the input set commands - and at this stage you need to find that wording in the Source user interface.\n",
    "\n",
    "Alternatively, you can set the parameters directly using `v.model.link.routing.set_param_values`, which expects the variable name as used internally by Source. You can query for the parameter names for a particular model, using `v.model.find_parameters(model_type)` and, if that doesn't work `v.model.find_properties(model_type)`.\n",
    "\n",
    "We'll start by using `find_parameters`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['InflowBias',\n",
       " 'LossGainFlux',\n",
       " 'NetEvaporation',\n",
       " 'RoutingConstant',\n",
       " 'RoutingPower',\n",
       " 'TimeSeriesFlux']"
      ]
     },
     "execution_count": 13,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.find_parameters('RiverSystem.Flow.StorageRouting')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The function `v.model.find_parameters`, accepts a model type (actually, you can give it a list of model types) and it returns a list of parameters.\n",
    "\n",
    "This list is determined by the internal code of Source - a parameter will only be returned if it has a `[Parameter]` tag in the C\\# code.\n",
    "\n",
    "From the list above, we see some parameters that we expect to see, but not all of the parameters for a Storage Routing reach. For example, the list of parameters doesn't seem to say how we'd switch from Generic to Piecewise routing mode. This is because the model property in question (`IsGeneric`) doesn't have a `[Property]` attribute.\n",
    "\n",
    "We can find a list of all fields and properties of the model using `v.model.find_properties`. It's a lot more information, but it can be helpful:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": false,
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'AllowDeactivation': 'Boolean',\n",
       " 'AverageRegFlow': 'Double',\n",
       " 'Divisions': 'Int32',\n",
       " 'DownstreamFlow': 'Double',\n",
       " 'Inflow': 'Double',\n",
       " 'InflowBias': 'Double',\n",
       " 'InitFlow': 'Double',\n",
       " 'InitStorage': 'Double',\n",
       " 'IsGeneric': 'Boolean',\n",
       " 'IsInitFlow': 'Boolean',\n",
       " 'LateralInflow': 'Double',\n",
       " 'LiveStorage': 'Double',\n",
       " 'LossGainFlux': 'Double',\n",
       " 'LossReports': 'List`1',\n",
       " 'MappedTravelTime': 'Int32',\n",
       " 'Name': 'String',\n",
       " 'NetEvaporation': 'Double',\n",
       " 'ObserverCount': 'Int32',\n",
       " 'Observers': 'IList`1',\n",
       " 'Outflow': 'Double',\n",
       " 'OutflowVolumeOverridden': 'Boolean',\n",
       " 'Piecewises': 'IList`1',\n",
       " 'PreOverrideOutflowVolume': 'Double',\n",
       " 'PreOverrideStorageVolume': 'Double',\n",
       " 'PreviousInflow': 'Double',\n",
       " 'PreviousLateralInflow': 'Double',\n",
       " 'PreviousOutflow': 'Double',\n",
       " 'PreviousStorage': 'Double',\n",
       " 'ReachLength': 'Double',\n",
       " 'RoutingConstant': 'Double',\n",
       " 'RoutingPower': 'Double',\n",
       " 'Storage': 'Double',\n",
       " 'StorageAtStartOfTs': 'Double',\n",
       " 'StorageRoutingName': 'String',\n",
       " 'StorageVolumeOverridden': 'Boolean',\n",
       " 'TimeSeriesFlux': 'Double',\n",
       " 'UpstreamFlow': 'Double',\n",
       " 'UseAnalyticalSolution': 'Boolean',\n",
       " '_outflow': 'Double',\n",
       " 'id': 'Int32',\n",
       " 'link': 'Link',\n",
       " 'silence': 'Boolean',\n",
       " 'simulationNow': 'DateTime',\n",
       " 'subjectState': 'SubjectState',\n",
       " 'timeStepDuration': 'TimeSpan',\n",
       " 'timeStepInSeconds': 'Double'}"
      ]
     },
     "execution_count": 14,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.find_properties('RiverSystem.Flow.StorageRouting')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Lets apply an initial parameter set to every Storage Routing link by setting:\n",
    "\n",
    "* `RoutingConstant` to 86400, and\n",
    "* `RoutingPower` to 1\n",
    "\n",
    "We will call `set_param_values`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method set_param_values in module veneer.server_side:\n",
      "\n",
      "set_param_values(parameter, values, literal=False, fromList=False, instantiate=False, **kwargs) method of veneer.server_side.VeneerLinkRoutingActions instance\n",
      "    Set the values of a particular parameter used in a particular context\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(v.model.link.routing.set_param_values)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.link.routing.set_param_values('RoutingConstant',86400.0)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.link.routing.set_param_values('RoutingPower',1.0)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can check in the Source user interface to see that the parameters have been applied"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Setting parameters as a function of other values\n",
    "\n",
    "Often, you will want to calculate model parameters based on some other information, either within the model or from some external data source.\n",
    "\n",
    "The `set_param_values` can accept a list of values, where each item in the list is applied, in turn, to the corresponding models - in much the same way that we used the known link order to set the routing type.\n",
    "\n",
    "The list of values can be computed in your Python script based on any available information. A common use case is to compute catchment or functional unit parameters based on spatial data.\n",
    "\n",
    "We will demonstrate the list functionality here with a contrived example!\n",
    "\n",
    "We will set a different value of `RoutingPower` for each link. We will compute a different value of `RoutingPower` from 1.0 down to >0, based on the number of storage routing links"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "number_of_links = len(new_models) - len(names_of_water_user_links)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1. ,  0.9,  0.8,  0.7,  0.6,  0.5,  0.4,  0.3,  0.2,  0.1])"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "power_vals = np.arange(1.0,0.0,-1.0/number_of_links)\n",
    "power_vals"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 30,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.link.routing.set_param_values('RoutingPower',power_vals,fromList=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you open the Feature Table for storage routing, you'll now see these values propagated.\n",
    "\n",
    "The `fromList` option has another characteristic that can be useful - particularly for catchments models with multiple functional units: value recycling.\n",
    "\n",
    "If you provide a list with few values than are required, the system will start again from the start of the list.\n",
    "\n",
    "So, for example, the following code will assign the three values: `[0.5,0.75,1.0]`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 28,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.link.routing.set_param_values('RoutingPower',[0.5,0.75,1.0],fromList=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Check the Feature Table to see the effect.\n",
    "\n",
    "**Note:** You can run these scripts with the Feature Table open and the model will be updated - but the feature table won't reflect the new values until you Cancel the feature table and reopen it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How it Works\n",
    "\n",
    "As mentioned, everything under `v.model` works by sending an IronPython script to Source to be run within the Source software itself.\n",
    "\n",
    "IronPython is a native, .NET, version of Python and hence can access all the classes and objects that make up Source.\n",
    "\n",
    "When you call a function witnin `v.model`, veneer-py is *generating* an IronPython script for Source. \n",
    "\n",
    "To this point, we haven't seen what these IronPython scripts look like - they are hidden from view. We can see the scripts that get sent to Source by setting the option `veneer.general.PRINT_SCRIPTS=True`\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 47,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Generated Script\n",
      "import clr\n",
      "import System\n",
      "import FlowMatters.Source.Veneer.RemoteScripting.ScriptHelpers as H\n",
      "clr.ImportExtensions(System.Linq)\n",
      "result = []\n",
      "have_succeeded = False\n",
      "ignoreExceptions = True\n",
      "for i_0 in scenario.Network.Links.Where(lambda l:l.DisplayName in ['Default Link #3', 'Default Link #4']):\n",
      "    try:\n",
      "        result.append(i_0.FlowRouting.GetType().FullName)\n",
      "        have_succeeded = True\n",
      "    except:\n",
      "      if not ignoreExceptions: raise\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Flow.StorageRouting', 'RiverSystem.Flow.StorageRouting']"
      ]
     },
     "execution_count": 47,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "veneer.general.PRINT_SCRIPTS=True\n",
    "v.model.link.routing.get_models(links=['Default Link #3','Default Link #4'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 48,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "veneer.general.PRINT_SCRIPTS=False"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "*Writing these IronPython scripts from scratch requires an understanding of the internal data structures of Source. The functions under `v.model` are designed to shield you from these details.*\n",
    "\n",
    "That said, if you have an idea of the data structures, you may wish to try writing IronPython scripts, OR, try working with some of the lower-level functionality offered in `v.model`.\n",
    "\n",
    "Most of the `v.model` functions that we've used, are ultimately based upon two, low level thems:\n",
    "\n",
    "* `v.model.get` and\n",
    "* `v.model.set`\n",
    "\n",
    "Both `get` and `set` expect a query to perform on a Source scenario object. Structuring this query is where an understanding of Source data structures comes in.\n",
    "\n",
    "For example, the following query will return the number of nodes in the network. (We'll use the PRINT_SCRIPTS option to show how the query translates to a script):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 49,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Generated Script\n",
      "import clr\n",
      "import System\n",
      "import FlowMatters.Source.Veneer.RemoteScripting.ScriptHelpers as H\n",
      "clr.ImportExtensions(System.Linq)\n",
      "result = scenario.Network.Nodes.Count()\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "12"
      ]
     },
     "execution_count": 49,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "veneer.general.PRINT_SCRIPTS=True\n",
    "num_nodes = v.model.get('scenario.Network.Nodes.Count()')\n",
    "num_nodes"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The follow example returns the names of each node in the network. The `.*` notation tells veneer-py to generate a loop over every element in a collection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Generated Script\n",
      "import clr\n",
      "import System\n",
      "import FlowMatters.Source.Veneer.RemoteScripting.ScriptHelpers as H\n",
      "clr.ImportExtensions(System.Linq)\n",
      "result = []\n",
      "have_succeeded = False\n",
      "ignoreExceptions = True\n",
      "for i_0 in scenario.Network.Nodes:\n",
      "    try:\n",
      "        result.append(i_0.Name)\n",
      "        have_succeeded = True\n",
      "    except:\n",
      "      if not ignoreExceptions: raise\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "['Crab Creek',\n",
       " 'Fish Creek',\n",
       " 'Fish Creek Confluence',\n",
       " 'Shell Creek',\n",
       " 'Middle Gauge',\n",
       " 'Shell Creek Confluence',\n",
       " 'Lower Gauge',\n",
       " 'Evaluation Gauge',\n",
       " 'Recreational Lake',\n",
       " 'Lake Release',\n",
       " 'Supply Point 13',\n",
       " 'Crop Fields']"
      ]
     },
     "execution_count": 56,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "node_names = v.model.get('scenario.Network.Nodes.*Name')\n",
    "node_names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can see from the script output that veneer-py has generated a Python for loop to iterate over the nodes:\n",
    "\n",
    "```python\n",
    "for i_0 in scenario.Network.Nodes:\n",
    "```\n",
    "\n",
    "There are other characteristics in there, such as ignoring exceptions - this is a common default used in `v.model` to silently skip nodes/links/catchments/etc that don't have a particular property."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same query approach can work for `set`, which can set a particular property (on one or more objects) to a particular value (which can be the same value everywhere, or drawn from a list)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 60,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['New Name 0',\n",
       " 'New Name 1',\n",
       " 'New Name 2',\n",
       " 'New Name 3',\n",
       " 'New Name 4',\n",
       " 'New Name 5',\n",
       " 'New Name 6',\n",
       " 'New Name 7',\n",
       " 'New Name 8',\n",
       " 'New Name 9',\n",
       " 'New Name 10',\n",
       " 'New Name 11']"
      ]
     },
     "execution_count": 60,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Generate a new name for each node (based on num_nodes)\n",
    "names = ['New Name %d'%i for i in range(num_nodes)]\n",
    "names"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Generated Script\n",
      "import clr\n",
      "import System\n",
      "import FlowMatters.Source.Veneer.RemoteScripting.ScriptHelpers as H\n",
      "clr.ImportExtensions(System.Linq)\n",
      "origNewVal = ['New Name 0','New Name 1','New Name 2','New Name 3','New Name 4','New Name 5','New Name 6','New Name 7','New Name 8','New Name 9','New Name 10','New Name 11']\n",
      "origNewVal.reverse()\n",
      "newVal = origNewVal[:]\n",
      "have_succeeded = False\n",
      "ignoreExceptions = True\n",
      "for i_0 in scenario.Network.Nodes:\n",
      "    try:\n",
      "        ignoreExceptions = True\n",
      "        checkValueExists = i_0.Name\n",
      "        ignoreExceptions = False\n",
      "        i_0.Name = newVal.pop()\n",
      "        if len(newVal)==0: newVal = origNewVal[:]\n",
      "        \n",
      "        have_succeeded = True\n",
      "    except:\n",
      "      if not ignoreExceptions: raise\n",
      "result = have_succeeded\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 61,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.set('scenario.Network.Nodes.*Name',names,fromList=True,literal=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you look at the Source model now (you may need to trigger a redraw by resizing the window), all the nodes have been renamed.\n",
    "\n",
    "(Lets reset the names - note how we saved `node_names` earlier on!)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "# Generated Script\n",
      "import clr\n",
      "import System\n",
      "import FlowMatters.Source.Veneer.RemoteScripting.ScriptHelpers as H\n",
      "clr.ImportExtensions(System.Linq)\n",
      "origNewVal = ['Crab Creek','Fish Creek','Fish Creek Confluence','Shell Creek','Middle Gauge','Shell Creek Confluence','Lower Gauge','Evaluation Gauge','Recreational Lake','Lake Release','Supply Point 13','Crop Fields']\n",
      "origNewVal.reverse()\n",
      "newVal = origNewVal[:]\n",
      "have_succeeded = False\n",
      "ignoreExceptions = True\n",
      "for i_0 in scenario.Network.Nodes:\n",
      "    try:\n",
      "        ignoreExceptions = True\n",
      "        checkValueExists = i_0.Name\n",
      "        ignoreExceptions = False\n",
      "        i_0.Name = newVal.pop()\n",
      "        if len(newVal)==0: newVal = origNewVal[:]\n",
      "        \n",
      "        have_succeeded = True\n",
      "    except:\n",
      "      if not ignoreExceptions: raise\n",
      "result = have_succeeded\n",
      "\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 62,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.set('scenario.Network.Nodes.*Name',node_names,fromList=True,literal=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:** The `literal=True` option is currently necessary setting text properties using `v.model.set`. This tells the IronPython generator to wrap the strings in quotes in the final script. Otherwise, IronPython would be looking for symbols (eg classes) with the same names"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The examples of `v.model.get` and `v.model.set` illustrate some of the low level functionality for manipulating the source model.\n",
    "\n",
    "The earlier, high-level, functions (eg `v.model.link.routing.set_param_values`) take care of computing the query string for you, including context dependent code such as searching for links of a particular name, or nodes of a particular type. They then call the lower level functions, which takes care of generating the actual IronPython script.\n",
    "\n",
    "The `v.model` namespace is gradually expanding with new capabilities and functions - but at their essence, most new functions provide a high level wrapper, around `v.model.get` and `v.model.set` for some new area of the Source data structures. So, for example, you could envisage a `v.model.resource_assessment` which provides high level wrappers around resource assessment functionality.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Exploring the system\n",
    "\n",
    "Writing the high level wrappers (as with writing the query strings for `v.model.get/set`) requires an understanding of the internal data structures of Source. You can get this from the C# code for Source, or, to a degree, from a help function `v.model.sourceHelp`.\n",
    "\n",
    "Lets say you want to discover how to change the description of the scenario (say, to automatically add a note about the changes made by your script)\n",
    "\n",
    "Start, by asking for help on `'scenario'` and explore from there"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['AddConfiguration',\n",
       " 'AllPluginDataModels',\n",
       " 'AuxiliaryInformation',\n",
       " 'AvailableDateRanges',\n",
       " 'BoundariesForCatchments',\n",
       " 'BoundaryForCatchment',\n",
       " 'CatchmentForBoundary',\n",
       " 'CompareTo',\n",
       " 'ContainsName',\n",
       " 'CreateContainer',\n",
       " 'CropStore',\n",
       " 'CrossSections',\n",
       " 'CurrentConfiguration',\n",
       " 'CurrentRiverSystemConfiguration',\n",
       " 'DEM',\n",
       " 'DefaultNodeAngle',\n",
       " 'DefaultScenarioView',\n",
       " 'Description',\n",
       " 'DescriptionChanged',\n",
       " 'DisplayGrid',\n",
       " 'Dispose',\n",
       " 'Equals',\n",
       " 'FU_CATEGORIES',\n",
       " 'FU_MAP',\n",
       " 'FU_POLYGONS',\n",
       " 'FeatureProxy',\n",
       " 'GaugeLocationLookup',\n",
       " 'GeographicData',\n",
       " 'GetAutoName',\n",
       " 'GetCurrentRunConfiguration',\n",
       " 'GetHashCode',\n",
       " 'GetPluginModel',\n",
       " 'GetScenarioConfiguration',\n",
       " 'GetScenarioContainer',\n",
       " 'GetType',\n",
       " 'GetUniqueName',\n",
       " 'GridSize',\n",
       " 'INTERSECTED_FU_POLYGONS',\n",
       " 'INTERSECTED_SCFU_POLYGONS',\n",
       " 'INTERSECTED_SC_POLYGONS',\n",
       " 'IPokeContext',\n",
       " 'IconCategory',\n",
       " 'InitialiseRiverOperator',\n",
       " 'LinkAdded',\n",
       " 'LinkRemoved',\n",
       " 'LoadRuntimePluginDataModels',\n",
       " 'MemberwiseClone',\n",
       " 'ModelRunOrder',\n",
       " 'Name',\n",
       " 'NameChanged',\n",
       " 'Network',\n",
       " 'NodeAdded',\n",
       " 'NodeCount',\n",
       " 'NodeRemoved',\n",
       " 'OperationsForecastManager',\n",
       " 'OperationsMaster',\n",
       " 'POINTER_MAP',\n",
       " 'PluginDataModels',\n",
       " 'Poke',\n",
       " 'Poked',\n",
       " 'PokedEventArgs',\n",
       " 'PostCopy',\n",
       " 'PrepareScenarioForRun',\n",
       " 'Project',\n",
       " 'ProjectViewRows',\n",
       " 'ProjectViewTable',\n",
       " 'ReasonsForNotRunning',\n",
       " 'ReferenceEquals',\n",
       " 'ReloadInputData',\n",
       " 'RenameCatchment',\n",
       " 'RestrictionCurveSets',\n",
       " 'RiverSystemProject',\n",
       " 'RunManager',\n",
       " 'RuntimePluginDataModels',\n",
       " 'STREAM_DEFINE',\n",
       " 'STREAM_MAP',\n",
       " 'STREAM_THRESHOLD',\n",
       " 'SUBCATCHMENT_MAP',\n",
       " 'SUBCATCHMENT_OUTLINE',\n",
       " 'SelectFeature',\n",
       " 'ShowFakeLinks',\n",
       " 'ShowLinkLabel',\n",
       " 'ShowNodeLabel',\n",
       " 'ShowStraightLines',\n",
       " 'ShowTrack',\n",
       " 'Silent',\n",
       " 'SnapNodesToGrid',\n",
       " 'SystemConfiguration',\n",
       " 'SystemFunctionalUnitConfiguration',\n",
       " 'TabularColumnFormattingManager',\n",
       " 'ToString',\n",
       " '__class__',\n",
       " '__delattr__',\n",
       " '__doc__',\n",
       " '__enter__',\n",
       " '__exit__',\n",
       " '__format__',\n",
       " '__getattribute__',\n",
       " '__hash__',\n",
       " '__init__',\n",
       " '__new__',\n",
       " '__reduce__',\n",
       " '__reduce_ex__',\n",
       " '__repr__',\n",
       " '__setattr__',\n",
       " '__sizeof__',\n",
       " '__str__',\n",
       " '__subclasshook__',\n",
       " 'auxiliaryInformation',\n",
       " 'id',\n",
       " 'plugInDataModels',\n",
       " 'project',\n",
       " 'uncertainty']"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "veneer.general.PRINT_SCRIPTS=False\n",
    "v.model.sourceHelp('scenario')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This tells you everything that is available on a Source scenario. It's a lot, but `Description` looks promising:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "existing_description = v.model.get('scenario.Description')\n",
    "existing_description"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "OK. It looks like there is no description in the existing scenario. Lets set one"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v.model.set('scenario.Description','Model modified by script',literal=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Harder examples\n",
    "\n",
    "Lets look at a simple model building example.\n",
    "\n",
    "We will test out different routing parameters, by setting up a scenario with several parallel networks. Each network will consist of an Inflow Node and a Gauge Node, joined by a Storage Routing link.\n",
    "\n",
    "The inflows will all use the same time series of flows, so the only difference will be the routing parameters.\n",
    "\n",
    "To proceed, \n",
    "\n",
    "1. Start a new copy of Source (in the following code, I've assumed that you're leaving the existing copy open)\n",
    "2. Create a new schematic model - but don't add any nodes or links\n",
    "3. Open Tools|Web Server Monitoring\n",
    "4. Once Veneer has started, make a note of what port number it is using - it will probably be 9877 if you've left the other copy of Source open.\n",
    "5. Make sure you tick the 'Allow Scripts' option\n",
    "\n",
    "Now, create a new veneer client (creatively called `v2` here)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "v2 = veneer.Veneer(port=9877)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And check that the network has nothing in it at the moment"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'type': 'FeatureCollection', 'features': []}"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.network()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can create nodes with `v.model.node.create`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method create in module veneer.server_side:\n",
      "\n",
      "create(name, node_type, location=None, schematic_location=None, splitter=False) method of veneer.server_side.VeneerNodeActions instance\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(v2.model.node.create)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "There are also functions to create different node types:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method new_gauge in module veneer.server_side:\n",
      "\n",
      "new_gauge(node_name, location=None, schematic_location=None) method of veneer.server_side.VeneerNodeActions instance\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(v2.model.node.new_gauge)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "First, we'll do a bit of a test run. Ultimately, we'll want to create a number of such networks - and the nodes will definitely need unique names then"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Exception': None,\n",
       " 'Response': {'Value': 'The Inflow',\n",
       "  '__type': 'StringResponse:#FlowMatters.Source.Veneer.ExchangeObjects'},\n",
       " 'StandardError': '',\n",
       " 'StandardOut': 'Set location\\r\\n'}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "loc = [10,10]\n",
    "v2.model.node.new_inflow('The Inflow',schematic_location=loc,location=loc)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Exception': None,\n",
       " 'Response': {'Value': 'The Gauge',\n",
       "  '__type': 'StringResponse:#FlowMatters.Source.Veneer.ExchangeObjects'},\n",
       " 'StandardError': '',\n",
       " 'StandardOut': 'Set location\\r\\n'}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "loc = [20,10]\n",
    "v2.model.node.new_gauge('The Gauge',schematic_location=loc,location=loc)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:** At this stage (and after some frustration) we can't set the location of the node on the schematic. We can set the 'geographic' location - which doesn't have to be true geographic coordinates, so that's what we'll do here."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Creating a link can be done with `v2.model.link.create`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Help on method create in module veneer.server_side:\n",
      "\n",
      "create(from_node, to_node, name=None, allow_duplicates=False) method of veneer.server_side.VeneerLinkActions instance\n",
      "\n"
     ]
    }
   ],
   "source": [
    "help(v2.model.link.create)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Exception': None,\n",
       " 'Response': {'Value': 'The Link',\n",
       "  '__type': 'StringResponse:#FlowMatters.Source.Veneer.ExchangeObjects'},\n",
       " 'StandardError': '',\n",
       " 'StandardOut': ''}"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.link.create('The Inflow','The Gauge','The Link')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, lets look at the information from `v2.network()` to see that it's all there. (We should also see the model in the geographic view)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>feature_type</th>\n",
       "      <th>from_node</th>\n",
       "      <th>geometry</th>\n",
       "      <th>icon</th>\n",
       "      <th>name</th>\n",
       "      <th>schematic_location</th>\n",
       "      <th>to_node</th>\n",
       "      <th>id</th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>0</th>\n",
       "      <td>node</td>\n",
       "      <td>NaN</td>\n",
       "      <td>POINT (10 10)</td>\n",
       "      <td>/resources/InjectedFlow</td>\n",
       "      <td>The Inflow</td>\n",
       "      <td>[0, 0]</td>\n",
       "      <td>NaN</td>\n",
       "      <td>/network/nodes/0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>1</th>\n",
       "      <td>node</td>\n",
       "      <td>NaN</td>\n",
       "      <td>POINT (20 10)</td>\n",
       "      <td>/resources/GaugeNodeModel</td>\n",
       "      <td>The Gauge</td>\n",
       "      <td>[0, 0]</td>\n",
       "      <td>NaN</td>\n",
       "      <td>/network/nodes/0</td>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>2</th>\n",
       "      <td>link</td>\n",
       "      <td>/network/nodes/0</td>\n",
       "      <td>LINESTRING (10 10, 20 10)</td>\n",
       "      <td>NaN</td>\n",
       "      <td>The Link</td>\n",
       "      <td>NaN</td>\n",
       "      <td>/network/nodes/0</td>\n",
       "      <td>/network/link/0</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "  feature_type         from_node                   geometry  \\\n",
       "0         node               NaN              POINT (10 10)   \n",
       "1         node               NaN              POINT (20 10)   \n",
       "2         link  /network/nodes/0  LINESTRING (10 10, 20 10)   \n",
       "\n",
       "                        icon        name schematic_location           to_node  \\\n",
       "0    /resources/InjectedFlow  The Inflow             [0, 0]               NaN   \n",
       "1  /resources/GaugeNodeModel   The Gauge             [0, 0]               NaN   \n",
       "2                        NaN    The Link                NaN  /network/nodes/0   \n",
       "\n",
       "                 id  \n",
       "0  /network/nodes/0  \n",
       "1  /network/nodes/0  \n",
       "2   /network/link/0  "
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.network().as_dataframe()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, after all that, we'll delete everything we've created and then recreate it all in a loop to give us parallel networks"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'Exception': None, 'Response': None, 'StandardError': '', 'StandardOut': ''}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.node.remove('The Inflow')\n",
    "v2.model.node.remove('The Gauge')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So, now we can create (and delete) nodes and links, lets create multiple parallel networks, to test out our flow routing parameters. We'll create 20, because we can!\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "num_networks=20"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Creating network 1\n",
      "Creating network 2\n",
      "Creating network 3\n",
      "Creating network 4\n",
      "Creating network 5\n",
      "Creating network 6\n",
      "Creating network 7\n",
      "Creating network 8\n",
      "Creating network 9\n",
      "Creating network 10\n",
      "Creating network 11\n",
      "Creating network 12\n",
      "Creating network 13\n",
      "Creating network 14\n",
      "Creating network 15\n",
      "Creating network 16\n",
      "Creating network 17\n",
      "Creating network 18\n",
      "Creating network 19\n",
      "Creating network 20\n"
     ]
    }
   ],
   "source": [
    "for i in range(1,num_networks+1): # Loop from 1 to 20\n",
    "    veneer.log('Creating network %d'%i)\n",
    "    x = i\n",
    "    loc_inflow = [i,10]\n",
    "    loc_gauge = [i,0]\n",
    "    \n",
    "    name_inflow = 'Inflow %d'%i\n",
    "    name_gauge = 'Gauge %d'%i\n",
    "    \n",
    "    v2.model.node.new_inflow(name_inflow,location=loc_inflow,schematic_location=loc_inflow)\n",
    "    \n",
    "    v2.model.node.new_gauge(name_gauge,location=loc_gauge,schematic_location=loc_gauge)\n",
    "    \n",
    "    # Create the link\n",
    "    name_link = 'Link %d'%i\n",
    "    v2.model.link.create(name_inflow,name_gauge,name_link)\n",
    "    \n",
    "    # Set the routing type to storage routing (we *could* do this at the end, outside the loop)\n",
    "    v2.model.link.routing.set_models('RiverSystem.Flow.StorageRouting',links=name_link)\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll use one of the flow files from the earlier model to drive each of our inflow nodes. We need to know where that data is. Here, I'm assuming its in the `ExampleProject` directory within the same directory as this notebook. We'll need the absolute path for Source, and the Python `os` package helps with this type of filesystem operation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "import os"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "os.path.exists('ExampleProject/Fish_G_flow.csv')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'D:\\\\src\\\\projects\\\\veneer-py\\\\doc\\\\training\\\\ExampleProject\\\\Fish_G_flow.csv'"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "absolute_path = os.path.abspath('ExampleProject/Fish_G_flow.csv')\n",
    "absolute_path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can use `v.model.node.assign_time_series` to attach a time series of inflows to the inflow node. We could have done this in the for loop, one node at a time, but, like `set_param_values` we can assign time series to multiple nodes at once.\n",
    "\n",
    "One thing that we do need to know is the parameter that we're assigning the time series to (because, after all, this could be any type of node - veneer-py doesn't know at this stage). We can find the model type, then check `v.model.find_parameters` and, if that doesn't work, `v.model.find_inputs`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['RiverSystem.Nodes.Inflow.InjectedFlow']"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.node.get_models(nodes='Inflow 1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['ReplaceFlow']"
      ]
     },
     "execution_count": 20,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.find_parameters('RiverSystem.Nodes.Inflow.InjectedFlow')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['Flow']"
      ]
     },
     "execution_count": 21,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.find_inputs('RiverSystem.Nodes.Inflow.InjectedFlow')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "So `'Flow'` it is!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 22,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 22,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.node.assign_time_series('Flow',absolute_path,'Inflows')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": false
   },
   "source": [
    "Almost there.\n",
    "\n",
    "Now, lets set a range of storage routing parameters (much like we did before)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 23,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "array([ 1.  ,  0.95,  0.9 ,  0.85,  0.8 ,  0.75,  0.7 ,  0.65,  0.6 ,\n",
       "        0.55,  0.5 ,  0.45,  0.4 ,  0.35,  0.3 ,  0.25,  0.2 ,  0.15,\n",
       "        0.1 ,  0.05])"
      ]
     },
     "execution_count": 23,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "power_vals = np.arange(1.0,0.0,-1.0/num_networks)\n",
    "power_vals"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And assign those to the links"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 24,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "True"
      ]
     },
     "execution_count": 24,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.model.link.routing.set_param_values('RoutingConstant',86400.0)\n",
    "v2.model.link.routing.set_param_values('RoutingPower',power_vals,fromList=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, configure recording"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 25,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "v2.configure_recording(disable=[{}],enable=[{'RecordingVariable':'Downstream Flow Volume'}])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And one last thing - work out the time period for the run from the inflow time series"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 26,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('11/01/1998', '31/12/2013')"
      ]
     },
     "execution_count": 26,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "inflow_ts = pd.read_csv(absolute_path,index_col=0)\n",
    "start,end=inflow_ts.index[[0,-1]]\n",
    "start,end"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "That looks a bit much. Lets run for a year"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 27,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(302, 'runs/1')"
      ]
     },
     "execution_count": 27,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "v2.run_model(start='01/01/1999',end='31/12/1999')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, we can retrieve some results. Because we used a naming convention for all the nodes, its possible to grab relevant results using those conventions"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 28,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "upstream = v2.retrieve_multiple_time_series(criteria={'RecordingVariable':'Downstream Flow Volume','NetworkElement':'Inflow.*'})\n",
    "downstream = v2.retrieve_multiple_time_series(criteria={'RecordingVariable':'Downstream Flow Volume','NetworkElement':'Gauge.*'})"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 29,
   "metadata": {
    "collapsed": false
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "<matplotlib.axes._subplots.AxesSubplot at 0x8f2ac88>"
      ]
     },
     "execution_count": 29,
     "metadata": {},
     "output_type": "execute_result"
    },
    {
     "data": {
      "image/png": "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\nnDgx4/jtde+992rYsGHq3bu3TjzxRK1du1aSNGPGDL9qFY/H1b17d11xxRWSkn83cnNztWHDhq2e\nb/LkyVsFqEceeUT77befRowYIUl67bXXNGbMGBUWFuqQQw7RkiVLWlzbzJkzdfbZZ/u3KyoqFIlE\nlEgkJCXbfVdffbUOPfRQ9ejRQyeccIKqqqp01llnqaCgQIcccohWrVrlf/6KFSt09NFHq1evXtp3\n3331+OOPb+/bBgBuau0ieTvjj1q5mHBr97vghRdesNnZ2dbzvG0et2jRIvvee+9Za6199913bd++\nfe1TTz1lrbW2rKzMDhw4MOP4IUOG2Jdfftlaa+0VV1xhS0tL7caNG21lZaUdOXKkf3wikbAHHnig\nve6662w8HrdffPGFHTp0qH3xxRe3uZ5//vOftri4eKv7jzvuOHvjjTf6t40x9rPPPss4JhaL2ays\nLPvCCy9Ya609/PDD7dSpU21jY6MtLy+3e+yxh124cKG11tqSkhL7t7/9zVpr7dFHH2332Wcf//Mm\nTJjgvwfnnnuu7d27t12+fLn1PM+eeeaZdtKkSdZaa//xj3/Ygw46yFZXV1trrV2xYoVdu3at/3lX\nX331Vu/dAQccYCsrK219fX2b79Gbb75p33jjDZtIJGxFRYUdMWKEve222zLegxNPPNHW1NTYDz74\nwObk5NijjjrKrly50lZXV9sRI0bYOXPmtPg+/+Uvf7GHH354i4+lr/3ll1+2vXv3tuXl5baxsdFe\ncskldsKECdZaaxcsWGBHjhxprbX2tddes0OHDrVjx471P2/06NEtPn9dXZ3t2bOnffXVV/37xo0b\n539tVVVVtrCw0M6bN896nmcfeeQRW1hYaKuqqqy11paWltr77rvPWmvtjBkz7Nlnn+0/z8qVK20k\nEvH/3peWltphw4bZL774wn9Pvve979kFCxZYz/Ps5MmT7fnnn2+ttba2ttYOHDjQPvjggzaRSPh/\nZz788MMWv45tcfnfBgDffdrGxYRDU4EyZsf/bI9169apd+/eikS2vFWHHnqoCgsLlZeXp1deeUWS\nNGHCBO23336SpP33318TJ07UokWL2vUajz/+uKZNm6b8/Hz169cvY4Zm6dKlWrdunaZNm6ZoNKoh\nQ4boZz/7mebPn79dX8/TTz/d5nxMVlaWevfuraqqKn355ZdasmSJbrzxRmVnZ2vUqFH62c9+pjlz\n5vhf96JFi+R5nt555x1deumlWrRokRoaGrRs2TIdfvjh/vOedNJJOvDAAxWJRHTmmWeqvLxckpSd\nna1Nmzbpgw8+kLVW3/ve97Tnnntuc42//OUv1a9fP+Xk5GjZsmXbfI9+8IMfaMyYMTLGaNCgQfr5\nz3++1ffmiiuuULdu3bTvvvtq//3319FHH63BgwerR48eOvbYY/X222+3upYlS5aoqKhIhYWFKioq\n0tKlS7c65uGHH9YFF1ygUaNGKTs7W9dff72WLFmiVatWady4cfrkk0+0fv16LV68WBdccIEqKyu1\nefNmLV68WCUlJS2+bteuXXXKKaf434tPPvlEb731ls444wxJ0rPPPqvhw4frjDPOUCQS0cSJE/X9\n739fTz/99Dbf29acd955GjJkiP+eDB06VEcccYQikYhOPfVU/z165plnVFxcrMmTJ8sYo1GjRunk\nk0+mCgXgOyU0AcraHf+zPXr16qV169b5rQxJevXVV7V+/Xr17t3bv/+NN97QkUceqT59+qhnz566\n++67tW7duna9xpo1azRgwAD/dnr7btWqVaqsrFRRUZH/S/r666/X//3f/23fF9QO8Xhc33zzjYqK\nirRmzRoVFRUpLy/Pf3zw4MGqrKyUJJWUlGjhwoV66623NHLkSP3oRz9SWVmZXn/9dQ0bNkyFhYX+\n5/Xt29f/OC8vz2/1HXHEEZo6dar+8z//U3vuuad+8Ytf+I+1Jv39qqio2OZ79Mknn+j444/XXnvt\npZ49e2ratGlbfW/69Onjf5ybm5sR4HJzc7e5nnHjxqmqqkrr169XVVWVxowZs9Uxa9as0eDBg/3b\n3bp1U69evVRZWamuXbvqoIMOUllZmRYvXqzS0lKNHz9er7zyihYtWtRqgJKkc845R48//rgaGxs1\nd+5cHXPMMerdu3eLryllfu86qvl70tp7VFFRoddffz3j+/Hwww/7LUsA+C4ITYAKyrhx45STk6On\nnnpqq8dsWio788wzdeKJJ6qyslIbNmzQlClT/Me7deumzZs3+8d6nqdvvvnGv73XXnvpyy+/9G+n\nz5IMHDhQe++9t6qqqvxf0hs3btzuKkJ7PPnkk8rOztaYMWPUr18/VVVVqba2NmN9/fv3l5QcoP7o\no4/0v//7vyopKdH3v/99rVq1Ss8999w2f/E3N3XqVC1fvlwffPCBPvroI910002SkkPuLUm/v633\n6KKLLtK+++6rzz77TBs2bNDvfve7XX59tX79+mVcMLu2tlbffvut/z5OmDBBCxYsUHl5uQ4++GBN\nmDBB//jHP7Rs2TJNmDCh1ec97LDDVFRUpCeffFLz5s3TOeeck/GazS/Em/69S9f87+hXX321vV+q\nBg4cqNLS0ozvR3V1te64447tfk4AcA0Bqg2poeKLL75YTzzxhGpqamStVXl5ecYvnJqaGhUWFio7\nO1tLly7Vww8/7D82fPhw1dfX6/nnn1c8Htd1112nxsZG//HTTjtN119/vTZs2KDKysqMXzRjxoxR\njx49NGvWLNXX18vzPL3//vtavnx5i+u11qqhoUGNjY1KJBJqaGho95mC69ev17x58zR16lRdeeWV\nKiws1IABAzR+/HhdddVVamho0DvvvKP77rvPHzjOzc3VgQceqDvuuMMPTOPHj9fs2bPbHaCWL1+u\npUuXKh6PKzc3V127dvVbpnvuuac+//zzbX5+W+/Rpk2blJ+fr7y8PK1YsSKQ7ScmTZqkBx54QO+8\n844aGhr0P//zPxo7dqwGDRokKVnJmzNnjkaMGKGsrCyVlpbqz3/+s4qLi9WrV69tPvfZZ5+tK664\nQhs3btTxxx/v3//jH/9Yn3zyiebPny/P8/Too4/qww8/zDgmZfTo0Vq8eLFWr16tjRs36oYbbtju\nr/W4447Txx9/rIceekjxeFyxWEzLly/XihUrtvs5AcA1BKh2uPzyy/WHP/xBs2bNUt++fdW3b19d\ndNFFmjVrlsaPHy9JuvPOO3X11VeroKBA1113nU4//XT/8/Pz83XnnXfqggsu0IABA9SjR4+MFtQ1\n11yj/v37q7i4WEcffbROPfVU5eTkSEqeIfbMM8+ovLxcxcXF6tOnjy688EJVV1e3uNbFixcrNzdX\nxx13nFavXq28vDwdc8wx/uM//vGPM345pmZU8vPzNWzYMN1///267bbbNH36dP+YRx55RF988YX6\n9eunn/70p7r22mt1xBFH+I+XlJTI8zy/dVVSUqKampqMyklrlSQpeabjhRdeqKKiIhUXF6t37966\n/PLLJUkXXHCB3n//fRUVFenkk09u8bnaeo9uvvlmzZs3T/n5+ZoyZYomTpyY8fnNn29ba+2I9Of5\n4Q9/qGuvvVYnn3yy+vfvry+++CJjjm38+PGqr6/3Q+eIESOUm5vbrhA6efJkrV69WhMnTvTPCpWS\nZ1U+88wzuvnmm9W7d2/dfPPNevbZZ/22avr6jjrqKJ1++ukaOXKkDj744K1CVkfek+7du+vFF1/U\n/Pnz1a9fP/Xr109XXnllxn80AEDYmV3ZyjDG2JZezxizy1sqLps9e7YeffRRLVy4MOilAIHi3wYA\nQWr6N6jF/4KkAuWAtWvX6rXXXpO1Vh999JFuueUWv9oCAADckxX0AiA1NjZqypQpWrlypXr27KlJ\nkybpoosuCnpZAACgFbTwADiLfxsABIkWHgAAQCciQAEAAHQQAQoAAKCDCFAAAAAdRIACAADoIAIU\nEJBIJNLmZWqCUlFRoUgkknERbQDAFgSodpo/f77Gjh2r7t27q2/fvho3blwg11Rry80336z/+I//\nUH5+voYOHaqbb7454/GKigodeeSR6tatm0aMGKGXX3651ed68MEHlZWVpfz8fP/5zj//fH3yySc7\n+8toN5dDiCSVlpYqNzdX+fn56tGjh/Lz8/XGG29I6rxLxrTkxhtvbPEyMN9++61ycnL0wQcftPkc\nO3N92D7vfP1O0EsA0IQA1Q633HKLfvWrX+mKK67Q119/rbVr12r27Nl67bXX2n2h3l1p7ty52rBh\ng55//nn96U9/0mOPPeY/NmnSJB144IGqqqrSddddp1NOOUXffvttq881fvx4VVdXa+PGjfrnP//p\nXzy4Pb+Ad4W2fsl7nreLVtIyY4zuvPNOVVdXa9OmTaqurtYhhxwiSTt1f6OzzjpLS5YsUUVFRcb9\njzzyiEaOHKkRI0bstNfGzlHbWKvD7j8s6GUAaEKAakN1dbWmT5+uu+66SyeddJK6desmSRo1apTm\nzp3rX7z1ueee0w9+8AMVFBRo8ODBmjlzpv8cixYt0sCBAzOet7i4WAsWLJAk1dfX65xzzlFRUZH2\n228/3XTTTRnHf/XVVzrllFPUp08fDR06VH/84x9bXe9vfvMbjR49WpFIRMOHD9cJJ5ygV199VZL0\n8ccf6+2339aMGTOUk5Ojk08+WSNHjtQTTzzR5vtgjFFxcbHuuOMOlZSUaMaMGf5jf//737X//vur\nqKhIRx55pFasWCFJ+stf/qKf/OQn/nHDhg3LuMjyoEGD9M47yf+ijkQiuvvuuzV8+HAVFRVp6tSp\n/nGfffaZSktL1bNnT/Xp00eTJk2SlLxosbVWI0eOVH5+vh5//HH/vZ41a5b22msvnX/++ZKkZ555\nRgcccIAKCwt12GGH6d133/Wf/8Ybb9Q+++yj/Px87b///nryySf9xx588EEddthhuuyyy1RYWKh9\n9tlHS5Ys0YMPPqhBgwapb9++mjNnzjbfu/YEperqak2ePFl9+vRRcXGxfve73/mPDRkyRG+//bYk\nad68eYpEIvrwww8lSffff3+Ll/3p37+/jjjiCM2dOzfj/rlz52ry5Mn+uq677joNGTJEffv21bnn\nntvqRarT/75K0syZM3X22WdL2tLu+8tf/qJBgwapV69euvvuu7V8+XKNGjVKRUVFuuSSSzKe7/77\n79eIESPUq1cvHXvssVq1alWb79HuzrOePBvsfxAA2IIA1YYlS5aosbExIwi0pHv37po7d642btyo\nZ599VrNnz9bf//53//FtVUpmzJihVatWaeXKlXrppZf00EMP+cdba3X88cfrgAMO0FdffaWXX35Z\nt912m1566aV2rf9f//qX9t9/f0nSBx98oL333tsPgVIyCL7//vuSpNWrV6uoqEhffvnlNp/z5JNP\n1r/+9S9JyVB2xhln6Pbbb9c333yjY489Vscff7zi8bhKSkr0yiuvSEqGwFgspiVLlkiSPv/8c9XW\n1mrkyJH+8z777LN688039e9//1uPPfaYXnzxRUnS1VdfrWOOOUYbNmzQl19+6f8yXrRokSTp3Xff\nVXV1tU499VRJyWsLbtiwQatWrdI999yjt99+WxdccIHuvfdeVVVVacqUKfrJT37iVw/32Wcfvfrq\nq35YPuuss/T111/761q6dKlGjx6tqqoqTZo0SRMnTtTy5cv12Wefae7cuZo6dao2b97cru9Ha6ZO\nnapNmzZp5cqVKisr05w5c/TAAw9ISgbFsrIySdLixYs1dOhQLV682H8PWmrVSdI555yTEaA++ugj\n/fvf/9YZZ5whSXrggQc0Z84cLVq0SJ9//rk2bdqUEVzb0vzv9NKlS/Xpp5/q0Ucf1X/913/p97//\nvRYsWKD33ntPjz32mP935qmnntINN9ygJ598Ut98840OP/xwPxSjddZadmUHHBKaAGVmmh3+sz3W\nrVun3r17KxLZ8lYdeuihKiwsVF5enh8QJkyYoP3220+StP/++2vixIn+L/i2PP7445o2bZry8/PV\nr18/XXrppf5jS5cu1bp16zRt2jRFo1ENGTJEP/vZzzR//vw2n3f69Omy1urcc8+VJNXU1KigoCDj\nmPz8fG3atEmSNHDgQFVVVWnAgAHbfN5+/fqpqqpKkvTYY4/puOOO05FHHqloNKrf/OY3qqur02uv\nvabi4mL16NFD5eXlWrx4sY455hj169dPH3/8sRYvXqzDDz8843mvuuoq9ejRQwMHDtQRRxyh8vJy\nSVJ2drYqKipUWVmpLl26aPz48Rmf1/yXSjQa1cyZM5Wdna2cnBzde++9+sUvfqGDDjpIxhidffbZ\nysnJ0euvvy5J+ulPf6o999xTknTqqadq2LBhWrp0qf98xcXFmjx5sowxOv300/Xll19q+vTpys7O\n1o9+9CN16dJFn376aavv16WXXqqioiIVFhbqoIMO2urxRCKhRx99VDfccIPy8vI0ePBg/frXv/bD\nT0lJif936V//+peuuuoq//a2AtRJJ52kr7/+2v86586dq2OPPVa9evWSJD388MO67LLLNHjwYOXl\n5en666/X/Pnzt2tw3Bija665Rl26dNFRRx2lbt26adKkSerVq5f69eunww8/3K+i3X333brqqqs0\nfPhwRSIRXXnllSovL9fq1as7/Lq7GysCFOCK0FxM2E4P5h+OXr16ad26dUokEn6ISrXEBg0a5P+y\neeONN3TVVVfpvffeU2NjoxobG/2KSFvWrFmTEVrS23erVq1SZWWlioqKJCXDQiKR0IQJE7b5nH/6\n05/00EMP6ZVXXvHbjN27d9+qRbNx40b16NGjXetMSV/PmjVrNHjwYP8xY4wGDhyoyspKSclguXDh\nQn366acqLS1VYWGhysrKtGTJkq1+8adCjCTl5eWppqZGknTTTTfpt7/9rcaMGaOioiJddtllOu+8\n81pd3x577OF/zVKyxTRnzhy/9WmtVSwW05o1ayRJc+bM0a233qqVK1dKkmpra7Vu3boW15WbmytJ\n6t27d8Z9qbW25Pbbb/dbiS1Zt26d4vG4Bg0a5N83ePBg/z0sKSnR5ZdfrrVr1yqRSOi0007TjBkz\nVFFRoerqao0ePbrF583NzdUpp5yiOXPmaOzYsZo3b55uvfVW//Hm37vBgwcrHo9nVN86ok+fPhmv\n3fx9S71HFRUV+uUvf6lf//rXkpLfD2OMKisrt2p1YwvCE+CW0FSggjJu3Djl5OToqaee2uqx9MrH\nmWeeqRNPPFGVlZXasGGDpkyZ4j/erVu3jBaP53n65ptv/Nt77bVXRtssfR5k4MCB2nvvvVVVVaWq\nqiqtX79eGzdu1NNPP93qmu+//37NmjVLCxYs0F577eXfv99++/mts5R///vffuWsvf72t7/5Aa5f\nv35bDSqvXr1a/fv3l7Sl/fTKK6+opKREEyZM0KJFi7R48eJWKyfN9enTR/fcc48qKys1e/ZsXXzx\nxds88655a2ngwIGaNm1axntYU1Oj008/XatWrdLPf/5z3XnnnVq/fr3Wr1+v/fbbb5e2Snr37u1X\n2VIqKir893Do0KHKzc3VH//4R02YMME/E/See+7RYYdte6j4nHPO0WOPPaaXXnpJNTU1Ou644/zH\nmn/vKioqlJ2dnRF8Upr/HV67du12f70DBw7U3XffvdX3Y+zYsdv9nLsDWniAWwhQbSgoKNA111yj\niy++WE888YRqampkrVV5eXnGL5SamhoVFhYqOztbS5cu1cMPP+w/Nnz4cNXX1+v5559XPB7Xdddd\np8bGRv/x0047Tddff702bNigyspK3XHHHf5jY8aMUY8ePTRr1izV19fL8zy9//77Wr58eYvrnTdv\nnqZNm6aXXnopo7ogJYe4R48erZkzZ6qhoUF/+9vf9N577+mnP/1pq19/6h/sRCKhlStX6pJLLtHi\nxYs1ffp0f+3PPvusFi5cqHg8rptvvlldu3b122wlJSVauHCh6urq/FbOCy+8oG+//VYHHHBAu74H\nf/3rX/1qTM+ePRWJRPxqYN++fdvcxuDCCy/U7Nmz/bZcbW2tnnvuOdXW1qq2tlaRSES9e/dWIpHQ\nAw88oPfee2+bz9fZv8QikYhOO+00TZs2TTU1NaqoqNCtt97qD2lLyffxT3/6kx86S0tLM2635vDD\nD1dBQYF+/vOfa+LEicrK2lJ0njRpkl95q6mp0bRp0zRx4kT/vU3/OkePHq358+crHo9r+fLl+utf\n/5rxOh15T37xi1/o97//vX8m58aNG7d6PmzNNv0PgBsIUO1w+eWX6w9/+INmzZqlvn37qm/fvrro\noos0a9YsPyjceeeduvrqq1VQUKDrrrsu42yz/Px83Xnnnbrgggs0YMAA9ejRI6Nld80116h///4q\nLi7W0UcfrVNPPVU5OTmSkr9cn3nmGZWXl6u4uFh9+vTRhRde2OrZUldffbWqqqp08MEH+/sOXXzx\nxf7j8+fP17Jly1RYWKhp06bpiSee8GdiVq9erfz8/Ixq2Ouvv678/HwVFBToiCOOUE1NjZYtW+af\n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\n",
      "text/plain": [
       "<matplotlib.figure.Figure at 0x8f5b7b8>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "downstream[['Gauge 1:Downstream Flow Volume','Gauge 20:Downstream Flow Volume']].plot(figsize=(10,10))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you'd like to change and rerun this example, the following code block can be used to delete all the existing nodes. (Or, just start a new project in Source)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "#nodes = v2.network()['features'].find_by_feature_type('node')._all_values('name')\n",
    "#for n in nodes:\n",
    "#    v2.model.node.remove(n)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Conclusion\n",
    "\n",
    "This session has looked at structural modifications of Source using Veneer, veneer-py and the use of IronPython scripts that run within Source.\n",
    "\n",
    "Writing IronPython scripts requires a knowledge of internal Source data structures, but there is a growing collection of helper functions, under the `v.model` namespace to assist."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "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.4.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}