case_study_a5.rst

Case Study A5 tutorial

Welcome to Spine Toolbox's Case Study A5 tutorial. Case Study A5 is one of the Spine Project case studies designed to verify Toolbox and Model capabilities. To this end, it reproduces an already existing study about hydropower on the Skellefte river, which models one week of operation of the fifteen power stations along the river.

This tutorial provides a step-by-step guide to run Case Study A5 on Spine Toolbox and is organized as follows:

• Introduction
  • Model assumptions
  • Modelling choices
• Guide
  • Installing requirements
  • Creating a new project
    • Configuring SpineOpt
  • Setting up project
  • Entering input data
    • Importing the SpineOpt database template
    • Creating objects
    • Specifying object parameter values
    • Establishing relationships
    • Specifying relationship parameter values
  • Executing the workflow
  • Examining the results

Introduction

Model assumptions

For each power station in the river, the following information is known:

• The capacity, or maximum electricity output. This datum also provides the maximum water discharge as per the efficiency curve (see next point).
• The efficiency curve, or conversion rate from water to electricity. In this study, a piece-wise linear efficiency with two segments is assumed. Moreover, this curve is monotonically decreasing, i.e., the efficiency in the first segment is strictly greater than the efficiency in the second segment.
• The maximum magazine level, or amount of water that can be stored in the reservoir.
• The magazine level at the beginning of the simulation period, and at the end.
• The minimum amount of water that the plant needs to discharge at every hour. This is usually zero (except for one of the plants).
• The minimum amount of water that needs to be spilled at every hour. Spilled water does not go through the turbine and thus does not serve to produce electricity; it just helps keeping the magazine level at bay.
• The downstream plant, or next plant in the river course.
• The time that it takes for the water to reach the downstream plant. This time can be different depending on whether the water is discharged (goes through the turbine) or spilled.
• The local inflow, or amount of water that naturally enters the reservoir at every hour. In this study, it is assumed constant over the entire simulation period.
• The hourly average water discharge. It is assumed that before the beginning of the simulation, this amount of water has constantly been discharged at every hour.

The system is operated so as to maximize total profit over the week, while respecting capacity constraints, maximum magazine level constrains, and so on. Hourly profit per plant is simply computed as the product of the electricity price and the production, minus a penalty for changes on the water discharge in two consecutive hours. This penalty is computed as the product of a constant penalty factor, common to all plants, and the absolute value of the difference in discharge with respect to the previous hour.

Modelling choices

The model of the electric system is fairly simple, only two elements are needed:

• A common electricity node.
• A load unit that takes electricity from that node.

On the contrary, the model of the river system is more detailed. Each power station in the river is modelled using the following elements:

• An upper water node, located at the entrance of the station.
• A lower water node, located at the exit of the station.
• A power plant unit, that discharges water from the upper node into the lower node, and feeds electricity produced in the process to the common electricity node.
• A spillway connection, that takes spilled water from the upper node and releases it to the downstream upper node.
• A discharge connection, that takes water from the lower node and releases it to the downstream upper node.

Below is a schematic of the model. For clarity, only the Rebnis station is presented in full detail:

Guide

Installing requirements

Note

This tutorial is written for latest Spine Toolbox and SpineOpt development versions.

Follow the instructions here to install Spine Toolbox and SpineOpt in your system.

Creating a new project

Each Spine Toolbox project resides in its own directory, where the user can store data, programming scripts and other necessary material. The Toolbox application also creates its own special subdirectory .spinetoolbox, for project settings, etc.

To create a new project, select File -> New project... from Spine Toolbox main menu. Browse to a location where you want to create the project and create a new folder for it, called e.g. ‘Case Study A5’, and then click Open.

Configuring SpineOpt

1. To use SpineOpt in your project, you need to create a Tool specification for it. Click on the small arrow next to the Tool icon (in the Main section of the tool bar), and press New... The Tool specification editor will popup:

   

2. Type ‘SpineOpt’ as the name of the specification and select ‘Julia’ as the type. Unselect Execute in work directory.

3. Press next to Main program file to create a new Julia file. Enter a file name, e.g. ‘run_spineopt.jl’, and click Save.

4. Back in the Tool specification editor form, select the file you just created under Main program file. Then, enter the following text in the text editor to the right:

   using SpineOpt
   
   run_spineopt(ARGS...)

   At this point, the form should be looking similar to this:

   

5. Press Ctrl+S to save everything, then close the Tool specification editor.

Setting up project

1. Drag the Data Store icon from the tool bar and drop it into the Design View. This will open the Add Data Store dialog. Type ‘input’ as the Data Store name and click Ok.

2. Repeat the above procedure to create a Data Store called ‘output’.

3. Create a database for the ‘input‘ Data Store:

   1. Select the input Data Store item in the Design View to show the Data Store Properties (on the right side of the window, usually).
   2. In Data Store Properties, select the sqlite dialect at the top, and hit New Spine db.

4. Repeat the above procedure to create a database for the ‘output’ Data Store.

5. Click on the small arrow next to the Tool icon and drag the ‘SpineOpt’ item from the drop-down menu into the Design View. This will open the Add Tool dialog. Type ‘SpineOpt’ as the Tool name and click Ok.

   Note

   Each item in the Design view is equipped with three connectors (the small squares at the item boundaries).

6. Click on one of ‘input’ connectors and then on one of ‘SpineOpt’ connectors. This will create a connection from the former to the latter.

7. Repeat the procedure to create a connection from SpineOpt to output. It should look something like this:

   

8. Setup the arguments for the SpineOpt Tool:

   1. Select the SpineOpt Tool to show the Tool Properties (on the right side of the window, usually). You should see two elements listed under Available resources, {db_url@input} and {db_url@output}.

   2. Drag the first resource, {db_url@input}, and drop it in Command line arguments, just as shown in the image below.

      

   3. Drag the second resource, {db_url@output}, and drop it right below the previous one. The panel should be now looking like this:

      

   4. Double-check that the order of the arguments is correct: first, {db_url@input}, and second, {db_url@output}. (You can drag and drop to reorganize them if needed.)

9. From the main menu, select File -> Save project.

Entering input data

Importing the SpineOpt database template

1. Download the SpineOpt database template (right click on the link, then select Save link as...)

2. Select the input Data Store item in the Design View.

3. Go to Data Store Properties and hit Open editor. This will open the newly created database in the Spine DB editor, looking similar to this:

   
   
   

   Note

   The Spine DB editor is a dedicated interface within Spine Toolbox for visualizing and managing Spine databases.

4. Press Alt + F to display the main menu, select File -> Import..., and then select the template file you previously downloaded. The contents of that file will be imported into the current database, and you should then see classes like ‘commodity’, ‘connection’ and ‘model’ under the root node in the Object tree (on the left).

5. From the main menu, select Session -> Commit. Enter ‘Import SpineOpt template’ as message in the popup dialog, and click Commit.

Note

The SpineOpt template contains the fundamental object and relationship classes, as well as parameter definitions, that SpineOpt recognizes and expects. You can think of it as the generic structure of the model, as opposed to the specific data for a particular instance. In the remainder of this section, we will add that specific data for the Skellefte river.

Creating objects

1. Add power plants to the model. Create objects of class unit as follows:

   1. Select the list of plant names from the text-box below and copy it to the clipboard (Ctrl+C):

      Rebnis_pwr_plant
      Sadva_pwr_plant
      Bergnäs_pwr_plant
      Slagnäs_pwr_plant
      Bastusel_pwr_plant
      Grytfors_pwr_plant
      Gallejaur_pwr_plant
      Vargfors_pwr_plant
      Rengård_pwr_plant
      Båtfors_pwr_plant
      Finnfors_pwr_plant
      Granfors_pwr_plant
      Krångfors_pwr_plant
      Selsfors_pwr_plant
      Kvistforsen_pwr_plant
      

   2. Go to Object tree (on the top left of the window, usually), right-click on unit and select Add objects from the context menu. This will open the Add objects dialog.

   3. Select the first cell under the object name column and press Ctrl+V. This will paste the list of plant names from the clipboard into that column; the object class name column will be filled automatically with ‘unit‘. The form should now be looking similar to this:

      

   4. Click Ok.

   5. Back in the Spine DB editor, under Object tree, double click on unit to confirm that the objects are effectively there.

   6. Commit changes with the message ‘Add power plants’.

2. Add discharge and spillway connections. Create objects of class connection with the following names:

   Rebnis_to_Bergnäs_disch
   Sadva_to_Bergnäs_disch
   Bergnäs_to_Slagnäs_disch
   Slagnäs_to_Bastusel_disch
   Bastusel_to_Grytfors_disch
   Grytfors_to_Gallejaur_disch
   Gallejaur_to_Vargfors_disch
   Vargfors_to_Rengård_disch
   Rengård_to_Båtfors_disch
   Båtfors_to_Finnfors_disch
   Finnfors_to_Granfors_disch
   Granfors_to_Krångfors_disch
   Krångfors_to_Selsfors_disch
   Selsfors_to_Kvistforsen_disch
   Kvistforsen_to_downstream_disch
   Rebnis_to_Bergnäs_spill
   Sadva_to_Bergnäs_spill
   Bergnäs_to_Slagnäs_spill
   Slagnäs_to_Bastusel_spill
   Bastusel_to_Grytfors_spill
   Grytfors_to_Gallejaur_spill
   Gallejaur_to_Vargfors_spill
   Vargfors_to_Rengård_spill
   Rengård_to_Båtfors_spill
   Båtfors_to_Finnfors_spill
   Finnfors_to_Granfors_spill
   Granfors_to_Krångfors_spill
   Krångfors_to_Selsfors_spill
   Selsfors_to_Kvistforsen_spill
   Kvistforsen_to_downstream_spill
   

3. Add water nodes. Create objects of class node with the following names:

   Rebnis_upper
   Sadva_upper
   Bergnäs_upper
   Slagnäs_upper
   Bastusel_upper
   Grytfors_upper
   Gallejaur_upper
   Vargfors_upper
   Rengård_upper
   Båtfors_upper
   Finnfors_upper
   Granfors_upper
   Krångfors_upper
   Selsfors_upper
   Kvistforsen_upper
   Rebnis_lower
   Sadva_lower
   Bergnäs_lower
   Slagnäs_lower
   Bastusel_lower
   Grytfors_lower
   Gallejaur_lower
   Vargfors_lower
   Rengård_lower
   Båtfors_lower
   Finnfors_lower
   Granfors_lower
   Krångfors_lower
   Selsfors_lower
   Kvistforsen_lower
   

4. Next, create the following objects (all names in lower-case):

   1. instance of class model.
   2. water and electricity of class commodity.
   3. electricity_node of class node.
   4. electricity_load of class unit.
   5. some_week of class temporal_block.
   6. deterministic of class stochastic_structure.
   7. realization of class stochastic_scenario.

5. Finally, create the following objects to get results back from Spine Opt (again, all names in lower-case):

   1. my_report of class report.
   2. unit_flow, connection_flow, and node_state of class output.

Note

To modify an object after you enter it, right click on it and select Edit... from the context menu.

Specifying object parameter values

1. Specify the general behaviour of our model. Enter model parameter values as follows:

   1. Select the model parameter value data from the text-box below and copy it to the clipboard (Ctrl+C):

      .. literalinclude:: data/cs-a5-model-parameter-values.txt
      
      

   2. Go to Object parameter value (on the top-center of the window, usually). Make sure that the columns in the table are ordered as follows:

      object_class_name | object_name | parameter_name | alternative_name | value | database
      

   3. Select the first empty cell under object_class_name and press Ctrl+V. This will paste the model parameter value data from the clipboard into the table. The form should be looking like this:

      

2. Specify the resolution of our temporal block. Repeat the same procedure with the data below:

   .. literalinclude:: data/cs-a5-temporal_block-parameter-values.txt
   
   

3. Specify the behaviour of all system nodes. Repeat the same procedure with the data below, where:

   1. demand represents the local inflow (negative in most cases).
   2. fix_node_state represents fixed reservoir levels (at the beginning and the end).
   3. has_state indicates whether or not the node is a reservoir (true for all the upper nodes).
   4. state_coeff is the reservoir 'efficienty' (always 1, meaning that there aren't any loses).
   5. node_state_cap is the maximum level of the reservoirs.

   .. literalinclude:: data/cs-a5-node-parameter-values.txt
   
   
   
   

Establishing relationships

Tip

To enter the same text on several cells, copy the text into the clipboard, then select all target cells and press Ctrl+V.

1. Establish that (i) power plant units receive water from the station's upper node, and (ii) the electricity load unit takes electricity from the common electricity node. Create relationships of class unit__from_node as follows:

   1. Select the list of unit and node names from the text-box below and copy it to the clipboard (Ctrl+C).

      .. literalinclude:: data/cs-a5-unit__from_node.txt
      
      

   2. Go to Relationship tree (on the bottom left of the window, usually), right-click on unit__from_node and select Add relationships from the context menu. This will open the Add relationships dialog.

   3. Select the first cell under the unit column and press Ctrl+V. This will paste the list of plant and node names from the clipboard into the table. The form should be looking like this:

      

   4. Click Ok.

   5. Back in the Spine DB editor, under Relationship tree, double click on unit__from_node to confirm that the relationships are effectively there.

   6. From the main menu, select Session -> Commit to open the Commit changes dialog. Enter ‘Add from nodes of power plants‘ as the commit message and click Commit.

2. Establish that (i) power plant units release water to the station's lower node, and (ii) power plant units inject electricity to the common electricity node. Repeate the above procedure to create relationships of class unit__to_node with the following data:

   .. literalinclude:: data/cs-a5-unit__to_node.txt
   
   

   Note

   At this point, you might be wondering what's the purpose of the unit__node__node relationship class. Shouldn't it be enough to have unit__from_node and unit__to_node to represent the topology of the system? The answer is yes; but in addition to topology, we also need to represent the conversion process that happens in the unit, where the water from one node is turned into electricty for another node. And for this purpose, we use a relationship parameter value on the unit__node__node relationships (see :ref:`Specifying relationship parameter values`).

3. Establish that (i) discharge connections take water from the lower node of the upstream station, and (ii) spillway connections take water from the upper node of the upstream station. Repeat the procedure to create relationships of class connection__from_node with the following data:

   .. literalinclude:: data/cs-a5-connection__from_node.txt
   
   

4. Establish that both discharge and spillway connections release water onto the upper node of the downstream station. Repeat the procedure to create connection__to_node relationships with the following data:

   .. literalinclude:: data/cs-a5-connection__to_node.txt
   
   

   Note

   At this point, you might be wondering what's the purpose of the connection__node__node relationship class. Shouldn't it be enough to have connection__from_node and connection__to_node to represent the topology of the system? The answer is yes; but in addition to topology, we also need to represent the delay in the river branches. And for this purpose, we use a relationship parameter value on the connection__node__node relationships (see :ref:`Specifying relationship parameter values`).

5. Establish that water nodes balance water and the electricity node balances electricity. Repeat the procedure to create node__commodity relationships between all upper and lower reservoir nodes and the water commodity, as well as between the electricity_node and electricity.

   .. literalinclude:: data/cs-a5-node__commodity.txt
   
   

6. Establish that all nodes are balanced at each time slice in the one week horizon. Create relationships of class model__default_temporal_block between the model instance and the temporal_block some_week.

7. Establish that this model is deterministic. Create a relationships of class model__default_stochastic_structure between the model instance and deterministic, and a relationship of class stochastic_structure__stochastic_scenario between deterministic and realization.

8. Finally, create one relationship of class report__output between my_report and each of the following output objects: unit_flow, connection_flow, and node_state, as well as one relationship of class model__report between instance and my_report. This is so results from running Spine Opt are written to the ouput database.

Specifying relationship parameter values

1. Specify (i) the capacity of hydro power plants, and (ii) the variable operating cost of the electricity unit (equal to the negative electricity price). Enter unit__from_node parameter values as follows:

   1. Select the parameter value data from the text-box below and copy it to the clipboard (Ctrl+C):

      .. literalinclude:: data/cs-a5-unit__from_node-relationship-parameter-values.txt
      
      

   2. Go to Relationship parameter value (on the bottom-center of the window, usually). Make sure that the columns in the table are ordered as follows:

      relationship_class_name | object_name_list | parameter_name | alternative_name | value | database
      

   3. Select the first empty cell under relationship_class_name and press Ctrl+V. This will paste the parameter value data from the clipboard into the table.

2. Specify the conversion ratio from water to electricity and from water to water of different hydro power plants (the latter being equal to 1). Repeat the same procedure with the data below:

   .. literalinclude:: data/cs-a5-unit__node__node-relationship-parameter-values.txt
   
   
   

3. specify the average discharge and spillage in the first hours of the simulation. Repeat the same procedure with the data below:

   .. literalinclude:: data/cs-a5-connection__from_node-relationship-parameter-values.txt
   
   
   

4. Finally, specify the delay and transfer ratio of different water connections (the latter being equal to 1). Repeat the same procedure with the data below:

   .. literalinclude:: data/cs-a5-connection__node__node-relationship-parameter-values.txt
   
   
   

5. When you're ready, commit all changes to the database.

Executing the workflow

Once the workflow is defined and input data is in place, the project is ready to be executed. Hit the Execute project button on the tool bar.

You should see ‘Executing All Directed Acyclic Graphs’ printed in the Event log (on the lower left by default). SpineOpt output messages will appear in the Process Log panel in the middle. After some processing, ‘DAG 1/1 completed successfully’ appears and the execution is complete.

Examining the results

Select the output data store and open the Spine DB editor.

To checkout the flow on the electricity load (i.e., the total electricity production in the system), go to Object tree, expand the unit object class, and select electricity_load, as illustrated in the picture above. Next, go to Relationship parameter value and double-click the first cell under value. The Parameter value editor will pop up. You should see something like this: