From bd3d9a2ac9114f26ec60c1b8a9c0ed76c3a85ea1 Mon Sep 17 00:00:00 2001
From: Juha Kiviluoma <juha.kiviluoma@vtt.fi>
Date: Tue, 7 May 2024 14:48:22 +0300
Subject: [PATCH] Deployed 60db643 with MkDocs version: 1.5.3

---
 how_to/index.html        |  36 +++++++++++++++++++++++++-----------
 reference/index.html     |  22 ++++++++++++++++------
 results/index.html       |   2 ++
 search/search_index.json |   2 +-
 sitemap.xml.gz           | Bin 127 -> 127 bytes
 5 files changed, 44 insertions(+), 18 deletions(-)

diff --git a/how_to/index.html b/how_to/index.html
index f5cc063c..db404654 100755
--- a/how_to/index.html
+++ b/how_to/index.html
@@ -1245,10 +1245,10 @@ <h1 id="how-to">How-to</h1>
 <p>Building parts of the model:</p>
 <ul>
 <li><a href="#how-to-create-basic-temporal-structures-for-your-model">How to create basic temporal structures for your model</a></li>
-<li><a href="#How-to-create-a-PV,-wind-or-run---of---river-hydro-power-plant">How to create a PV, wind or run-of-river hydro power plant</a></li>
-<li><a href="#How-to-connect-nodes-in-the-same-energy-network">How to connect nodes in the same energy network</a></li>
-<li><a href="#How-to-set-the-demand-in-a-node">How to set the demand in a node</a></li>
-<li><a href="#How-to-add-a-storage-unit-(battery)">How to add a storage unit (battery)</a></li>
+<li><a href="#how-to-create-a-pv-wind-or-run-of-river-hydro-power-plant">How to create a PV, wind or run-of-river hydro power plant</a></li>
+<li><a href="#how-to-connect-nodes-in-the-same-energy-network">How to connect nodes in the same energy network</a></li>
+<li><a href="#how-to-set-the-demand-in-a-node">How to set the demand in a node</a></li>
+<li><a href="#how-to-add-a-storage-unit-battery">How to add a storage unit (battery)</a></li>
 <li><a href="#how-to-make-investments-storageunit">How to make investments (storage/unit)</a></li>
 <li><a href="#how-to-create-combined-heat-and-power-chp">How to create combined heat and power (CHP)</a></li>
 <li><a href="#how-to-create-a-hydro-reservoir">How to create a hydro reservoir</a></li>
@@ -1265,7 +1265,7 @@ <h1 id="how-to">How-to</h1>
 <li><a href="#how-to-create-a-multi-year-model">How to create a multi-year model</a></li>
 <li><a href="#how-to-use-a-rolling-window-for-a-dispatch-model">How to use a rolling window for a dispatch model</a></li>
 <li><a href="#how-to-use-nested-rolling-window-solves-investments-and-long-term-storage">How to use Nested Rolling window solves (investments and long-term storage)</a></li>
-<li><a href="#how-to-use-stochastics">How to use stochastics (representing uncertainty)</a></li>
+<li><a href="#how-to-use-stochastics-representing-uncertainty">How to use stochastics (representing uncertainty)</a></li>
 </ul>
 <p>General:</p>
 <ul>
@@ -1422,17 +1422,30 @@ <h2 id="how-to-make-investments-storageunit">How to make investments (storage/un
 <p>The solve will invest only if it has an array of <code>invest_periods</code> set, telling the periods where it is allowed to make investment decisions. In a multi solve investment model (rolling investments) it can be useful to separately set <code>invest_realized_periods</code> so that the investment results get reported only from the chosen periods from each solve (in order to avoid overlapping reporting of investment decisions that are replaced by  investment decisions in later solves). Furthermore, <code>realized_periods</code> will define the solves and periods from which the dispatch results are output into results.</p>
 <p>First, the investment parameters need to be included both for the <em>battery_inverter</em> and <em>battery</em> objects:</p>
 <ul>
-<li><code>invest_method</code> - the modeller needs to choose between <em>only_invest</em>, <em>only_retire</em>, <em>invest_and_retire</em> or <em>not_allowed</em></li>
-<li><code>invest_cost</code> - overnight investment cost new capacity [currency/kW] for the <em>battery_inverter</em> and [currency/kWh] for the <em>battery</em>. Other one can be left empty or zero, since they will be tied together in the next phase. Here we will assume a fixed relation between kW and kWh for this battery technology, but for example flow batteries could have separate investments for storage and charging capacities.</li>
+<li>
+<p><code>invest_method</code> - the modeller has options to limit the investment and retirement. Options are <em>not_allowed</em>, invest, retire or invest and retire. These have the sub options of no limit <em>invest_no_limit</em>, limit the amount per period: <em>invest_period</em>, limit the total amount invested <em>invest_total</em> or limit both the total investment and the investment per period <em>invest_period_total</em>. </p>
+</li>
+<li>
+<p>If the investment is limited, it requires the corresponding maximum/minimum investment (power [MW] or energy [MWh]) to the virtual capacity. This can be set to individual entities or groups of entities:</p>
+<ul>
+<li><code>invest_max_total</code></li>
+<li><code>invest_max_period</code></li>
+<li><code>invest_min_total</code></li>
+<li><code>invest_min_period</code></li>
+<li><code>retire_max_total</code></li>
+<li><code>retire_max_period</code></li>
+<li><code>retire_min_total</code></li>
+<li><code>retire_min_period</code></li>
+</ul>
+</li>
+<li>
+<p><code>invest_cost</code> - overnight investment cost new capacity [currency/kW] for the <em>battery_inverter</em> and [currency/kWh] for the <em>battery</em>. Other one can be left empty or zero, since they will be tied together in the next phase. Here we will assume a fixed relation between kW and kWh for this battery technology, but for example flow batteries could have separate investments for storage and charging capacities.</p>
+</li>
 <li><code>interest_rate</code> - an interest rate [e.g. 0.05 means 5%] for the technology that is sufficient to cover capital costs. The chosen interest rate should reflect the assumption that in the model economic lifetime equals the technical lifetime.</li>
 <li><code>lifetime</code> - technical lifetime of the technology to calculate investment annuity (together with the interest rate)</li>
 </ul>
 <p>Additional parameters:</p>
 <ul>
-<li><code>invest_max_total</code>: maximum investment (power [MW] or energy [MWh]) to the virtual capacity of a group of units or to the storage capacity of a group of nodes. <ul>
-<li>In the same way investment limits can be set for total and period, investment and retirement, min and max</li>
-</ul>
-</li>
 <li><code>lifetime_method</code>: Model can either be forced to reinvest when the lifetime ends <code>reinvest_automatic</code> or have a choice <code>reinvest_choice</code></li>
 <li><code>salvage_value</code>: Sets the extra value that can be gained for retiring [CUR/kW]</li>
 <li><code>fixed_cost</code>: Annual cost for capacity [CUR/kW]</li>
@@ -2026,6 +2039,7 @@ <h3 id="rolling-horizon-stochastics">Rolling horizon stochastics</h3>
 <p>The stochastic data should be given so that it can serve the rolling structure: <code>rolling_solve_jump</code> dictates the duration of the initial non-stochastic part of the model horizon. This period needs only data for the 'realized' branch. The stochastic branches will begin only after that and need data only after <code>rolling_solve_jump</code> has been reached. So, for every 'analysis_time' there needs to be a time series in each stochastic branch that extends to the end of horizon (as defined by <code>rolling_solve_horizon</code>). The branches continue to the end of the horizon without branching again.</p>
 <p>For the <em>solve</em> parameter <code>stochastic_branches</code> this means analysis times (t0001, t0025, t0049, t0073, t0097, t0121 and t0145). t0001 is there only to tell which branch is the realized one.</p>
 <p>Otherwise there is no difference to the previous example.</p>
+<p>Realized scenario should not typically be used as a forecast branch in a stochastic model. However, this would happen, if the realized branch has weight other than zero. So, to avoid this, its weight should be set to zero but its realized status to "yes". Then the values from the realized scenario are not included in the forecast branches, but they are used in the realized part of the timeline. This happens because the weight of the realized part of the timeline is always forced to be one (even though its weight has been set to zero).</p>
 <p><img alt="Rolling Branching" src="../branching_rolling.PNG" /></p>
 <p><img alt="1Week stochastics" src="../1week_stochastics.PNG" /></p>
 <h3 id="multi-periodic-stochastics">Multi periodic stochastics</h3>
diff --git a/reference/index.html b/reference/index.html
index 7fa4dfe6..17f61725 100755
--- a/reference/index.html
+++ b/reference/index.html
@@ -1513,11 +1513,20 @@ <h3 id="defining-how-the-unit-functions">Defining how the unit functions</h3>
 <h3 id="main-data-items-for-units">Main data items for units</h3>
 <ul>
 <li>Capacity: <code>existing</code> (and the investment and retirement parameters below)</li>
-<li>Technical: <code>efficiency</code>, <code>min_load</code>, <code>efficiency_at_min_load</code>, <code>min_uptime</code>, <code>min_downtime</code><ul>
-<li><code>min_load</code> - [0-1] Minimum load of the unit. Applies only if the unit has an online variable. With linear startups, it is the share of capacity started up. Constant or time.</li>
+<li>
+<p>Technical: <code>efficiency</code>, <code>min_load</code>, <code>efficiency_at_min_load</code>, <code>min_uptime</code>, <code>min_downtime</code></p>
+<ul>
+<li>
+<p><code>min_load</code> - [0-1] Minimum load of the unit. Applies only if the unit has an online variable. With linear startups, it is the share of capacity started up. Constant or time. Calculated for all timesteps: </p>
+</li>
+<li>
+<p>the sum of output flows &gt;= minimum_load * capacity</p>
+</li>
 </ul>
 </li>
-<li><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for flows from/to the unit. For online units, the online variable is multiplied by the availability. Constant or time.</li>
+<li>
+<p><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for flows from/to the unit. For online units, the online variable is multiplied by the availability. Constant or time.</p>
+</li>
 <li>Economic: <code>startup_cost</code>, <code>fixed_cost</code> (fuel cost comes through the use of fuel commodities and other variable costs are defined for flows between unit and node, see below)</li>
 </ul>
 <h3 id="investment-parameters-for-capacity-expansion">Investment parameters for capacity expansion</h3>
@@ -1534,8 +1543,8 @@ <h3 id="investment-parameters-for-capacity-expansion">Investment parameters for
 <li><code>interest_rate</code> - [unitless, e.g. 0.05 means 5%] Interest rate for investments. Constant or period.</li>
 <li><code>invest_max_total</code> - [MW] Maximum capacity investment over all solves. Constant.</li>
 <li><code>invest_max_period</code> - [MW] Maximum capacity investment for each period. Period.</li>
-<li><code>invest_min_total</code> - [MW] Maximum capacity investment over all solves. Constant.</li>
-<li><code>invest_min_period</code> - [MW] Maximum capacity investment for each period. Period.</li>
+<li><code>invest_min_total</code> - [MW] Minimum capacity investment over all solves. Constant.</li>
+<li><code>invest_min_period</code> - [MW] Minimum capacity investment for each period. Period.</li>
 <li><code>retire_cost</code> - [CUR/kW] Retirement cost for new capacity. Constant or period.</li>
 <li><code>retire_max_total</code> - [MW] Maximum capacity retirement over all solves. Constant.</li>
 <li><code>retire_max_period</code> - [MW] Maximum capacity retirement for each period. Period.</li>
@@ -1562,7 +1571,8 @@ <h3 id="relationship-of-a-unit-to-a-node-and-determination-of-the-type-of-relati
 <h3 id="properties-of-unit-inputnode-and-unit-outputnode-relationships">Properties of unit--inputNode and unit--outputNode relationships</h3>
 <ul>
 <li><code>is_non_synchronous</code> - Chooses whether the unit is synchronously connected to this node.</li>
-<li><code>coefficient</code> - [factor] Coefficient to scale the output from a unit to a particular node. Can be used e.g. to change unit of measurement or to remove the flow by using zero as the coefficient (the flow variable can still be used in user constraints). Constant.</li>
+<li><code>coefficient</code> - [factor] Coefficient to scale the output from a unit to a particular node or the input from a node. Can be used e.g. to change unit of measurement or to remove the flow by using zero as the coefficient (the flow variable can still be used in user constraints).
+Note that in the case of unit--outputNode the <code>coefficient</code> affects <em>after</em> the capacity and the other unit constraints. Constant.</li>
 <li><code>other_operational_cost</code> - [CUR/MWh] Other operational variable costs for energy flows. Constant or time. </li>
 <li><code>inertia_constant</code> - [MWs/MW] Inertia constant for a synchronously connected unit to this node. Constant.</li>
 <li><code>ramp_method</code> - Choice of ramp method. 'ramp_limit' poses a limit on the speed of ramp. 'ramp_cost' poses a cost on ramping the flow (NOT FUNCTIONAL AS OF 19.3.2023).</li>
diff --git a/results/index.html b/results/index.html
index 01a6580e..0c716b28 100755
--- a/results/index.html
+++ b/results/index.html
@@ -917,6 +917,8 @@ <h2 id="reserves">Reserves</h2>
 <h2 id="inertia-and-non-synchronous-generation">Inertia and non-synchronous generation</h2>
 <ul>
 <li><code>group</code> object <code>inertia_t</code> parameter - [MWs] the amount of inertia (MWs) in the group of nodes in each timestep</li>
+<li><code>group</code> object <code>inertia_largest_flow_t</code> parameter - [MW] The largest individual flow coming into the group of nodes that <em>has_inertia</em></li>
+<li><code>group</code> object <code>inertia_unit_node_t</code> parameter - [MW] the amount of inertia between units and the nodes of the group</li>
 <li><code>group</code> object <code>slack_inertia_t</code> parameter - [MWs] use of slack variable and the associated penalty cost to fulfill the inertia requirement in each timestep</li>
 <li><code>group</code> object <code>slack_nonsync_t</code> parameter - [MWh] use of slack variable and the associated penalty cost to fulfill the non-synchronous share maximum share constraint in each timestep </li>
 </ul>
diff --git a/search/search_index.json b/search/search_index.json
index eb7d6e69..6e6ff8e4 100755
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>IRENA FlexTool is an energy systems optimisation model developed for power and energy systems with high shares of wind and solar power. It can be used to find cost-effective sources of flexibility across the energy system to mitigate the increasing variability arising from the power systems. It can perform multi-year capacity expansion as well as unit commitment and economic dispatch in a user-defined sequence of solves. The aim has been to make it fast to learn and easy to use while including lot of functionality especially in the time scales relevant for investment planning and operational scheduling of energy systems.</p>"},{"location":"#documentation-structure","title":"Documentation structure","text":"<ul> <li>You can find the installation instructions for IRENA FlexTool using Spine Toolbox as its interface (recommended in most cases): Install with Toolbox</li> <li>Follow video tutorial for installation with Spine Toolbox here: Link to YouTube</li> <li> <p>You can also use IRENA FlexTool with a web browser, but you will need to install a web server first: Install with web server</p> </li> <li> <p>If using FlexTool with Spine Toolbox, learn how the Spine Toolbox workflow functions: Spine Toolbox workflow.</p> </li> <li> <p>If using FlexTool with a web-browser, read how it works: Browser interface</p> </li> <li> <p>The tutorial is recommended for the new users of FlexTool: Tutorial</p> </li> <li>How-to section has examples on how to add specific features to a model: How to</li> <li>More advanced users can find the model parameter descriptions useful: Model parameters</li> <li>Finally, result parameters are documented here: Model results</li> </ul>"},{"location":"#monthly-user-support-telcos","title":"Monthly user support telcos","text":"<p>The monthly user support telco is held on the last Monday of each month at 12-13 UTC (skipping December and July). (Notice that time is according to UTC and in places where day-light saving time is applied, the time of the meeting may change between winter/summer) Each 1 h session starts with a ~15 min presentation on simple IRENA FlexTool demos or tutorials, followed by 45 min Q&amp;A session</p> <p>Teams link</p> <p>Please contact nelli.putkonen@vtt.fi for an Outlook calendar invitation</p>"},{"location":"#background-for-the-flextool-modelling-approach","title":"Background for the FlexTool modelling approach","text":"<p>The theory slides below give some background how FlexTool is formulated. There are also examples that show some ways how FlexTool can be used (including examples from other similar models). The slides were made for training in the OASES project (funded by LEAP-RE, project no: 963530, co-funding from European Commission and national funding agencies). The files can also be found in the folder docs/theory_slides.</p> <p>1: Energy planning and types of modelling approaches</p> <p>2: Modelling tools process and IRENA Flextool approach</p> <p>3: IRENA Flextool in practice</p> <p>4: Examples of studies done with IRENA Flextool approach</p>"},{"location":"browser_interface/","title":"Browser interface in brief","text":"<p>The browser interface connects to an instance of FlexTool web interface.  It can show and edit the same data as the Spine Toolbox. The workflow is not directly visible,  but it is executed in the background when models are run.</p> <p>The main page shows the projects available for the user.</p> <p></p> <p>The front page for the data editor shows all the data classes that can be shown and edited.  Different data classes can be opened to separate browser tabs for convenience.</p> <p></p> <p>Parameter data can be shown and edited once the user chooses an object and an alternative.</p> <p></p> <p>On the 'Run' page, the user can select and execute scenarios.</p> <p></p> <p>Finally, the results page shows the model outputs taken from the result database.  The results database can also be opened with Spine Toolbox for more control  over the shown data as well as export capabilities.</p> <p></p>"},{"location":"how_to/","title":"How-to","text":"<p>How-to section contains examples on how to include common energy system components in your model. The examples assume that you have sufficient understanding of FlexTool basics (e.g. by doing the tutorial). Each example will either include an example database file that is located in the 'how to examples databases' folder or the example is included in the init.sqlite as a scenario. If the example is in its own database, you can switch to that database by selecting the 'input' data store in the workflow and then changing the database by clicking the folder icon next to the current database file path in the 'Data store properties' widget. Navigate to the 'how to example databases' folder and choose the appropriate database.</p> <p>This section is divided into two parts: </p> <p>Building parts of the model:</p> <ul> <li>How to create basic temporal structures for your model</li> <li>How to create a PV, wind or run-of-river hydro power plant</li> <li>How to connect nodes in the same energy network</li> <li>How to set the demand in a node</li> <li>How to add a storage unit (battery)</li> <li>How to make investments (storage/unit)</li> <li>How to create combined heat and power (CHP)</li> <li>How to create a hydro reservoir</li> <li>How to create a hydro pump storage</li> <li>How to add a reserve</li> <li>How to add a minimum load, start-up and ramp</li> <li>How to add CO2 emissions, costs and limits</li> <li>How to create a non-synchronous limit</li> <li>How to see the VRE curtailment and VRE share results for a node</li> </ul> <p>Setting different solves:</p> <ul> <li>How to run solves in a sequence (investment + dispatch)</li> <li>How to create a multi-year model</li> <li>How to use a rolling window for a dispatch model</li> <li>How to use Nested Rolling window solves (investments and long-term storage)</li> <li>How to use stochastics (representing uncertainty)</li> </ul> <p>General:</p> <ul> <li>How to use CPLEX as the solver</li> <li>How to create aggregate outputs</li> <li>How to enable/disable outputs</li> <li>How to make the Flextool run faster</li> </ul>"},{"location":"how_to/#how-to-create-basic-temporal-structures-for-your-model","title":"How to create basic temporal structures for your model","text":"<p>(time_settings_only.sqlite)</p> <p>FlexTool allows to build models for different kinds of purposes and has therefore a flexible temporal structure, which requires some learning at first. To get you started, this how-to creates three different timelines: a full year, a 48h timeline and a timeline with five one-week periods to represent a full year. To be able to choose which of these are used in a given scenario, three alternatives are created: init, init_2day-test, init_5week-invest. </p> <p>The names of these alternatives hint at the intended use of each timeline. Even when you are building a large model with a long timeline, it is better to use a short 48 hour timeline for testing purposes when building the model. Using five one-week periods, i.e. \"a representative periods\", in an investment model is a method to reduce the model size and consequently solve time. More about that in How to run solves in a sequence (investment + dispatch)</p> <p></p> <p>To define a temporal structure for a model instance, you need to create the following objects and relationships:</p> <ul> <li><code>timeline</code> object called y2020 with a map-type parameter <code>timestep_duration</code> that defines the timeline the time series data in the model will need to use. It contains, in the first column, the name of each timestep (e.g. t0001 or 2022-01-01-01) and, in the second column, the length of the timestep in hours (e.g. 1.0). The timestep names here must match the timestep names in other time series like <code>inflow</code> or <code>profile</code>. Here all of the three options use the same full year timeline i.e. timesteps from t0001 to t8760 with a step size of one hour.</li> <li><code>timeblockset</code> objects called full-year, 2day and 5week. Each of them need a map-type parameter <code>block_duration</code> to define a time block using a timestep name to indicate where the timeblock starts and a number to define the duration of the timeblock in timesteps: (t0001, 8760) for the full-year and (t4001 and 48.0) for the 48h. The timeline is larger than the 48 hours, but this way the solver uses 48 hours specified. The 5week needs five starting points t2521, t4538, t5041, t7057 and t8233 with all having the length of 168.0</li> <li><code>timeblockset</code> needs to be connected to the timeline. This is done by adding the <code>timeblockset__timeline</code> relationships (full-year| y2020), (2day| y2020), (5weeks| y2020). From the <code>relationship tree</code> right-click on the <code>timeblockset__timeline</code> relationship class to 'Add relationships...'.</li> <li> <p><code>solve</code> objects called full-year-dispatch, 2day-dispatch and 5week-invest. In addition, they need the following parameters:</p> </li> <li> <p>a map-type parameter <code>period_timeblockSet</code> to define the timeblockset to be used by each period. Here each of the three use their <code>timeblockSet</code> to describe the same period p2020. The first column of the map has the period: p2020 and the second column the <code>timeblockSet</code>: full-year, 2day or 5week</p> </li> <li>an array-type parameter <code>realized_periods</code> to define the periods that are realised from the <code>solve</code> named by the object (the first column of an array is an index number starting with 0, the second column contains the period to be realized in the results: p2020 for all the solves here)</li> <li> <p>a parameter <code>solve_mode</code>, to be set to single_solve in these examples</p> </li> <li> <p>Finally, a <code>model</code> object will define the solves to be included in a one model instance. They are defined in the array parameter <code>solves</code>. For these examples, the model name is flextool and for each <code>solve</code> the name of the <code>solve</code> should be given in the <code>solves</code> array (distinguished by the alternative): full-year-dispatch, 2day-dispatch or 5week-invest.</p> </li> </ul> <p>Be careful when choosing datatypes! Maps need to be maps not arrays. (In the future, an update is coming to toolbox to ensure compliance.) </p> <p></p>"},{"location":"how_to/#how-to-create-a-pv-wind-or-run-of-river-hydro-power-plant","title":"How to create a PV, wind or run-of-river hydro power plant","text":"<p>(init.sqlite scenario: wind) init - west - wind</p> <p>These three power plant types don't use any commodities (i.e. fuels), but are instead dependant on a timeseries profile. To create these plants one needs an output node, an unit and a profile.</p> <p>The unit only needs parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: [The maximum capacity of the plant]  Additionally these parameters should be at their default values:</li> <li><code>conversion_method</code>: constant_efficiency</li> <li><code>efficiency</code>: 1</li> </ul> <p>The <code>profile</code> object only has one parameter: <code>profile</code>. It is a timeseries map which tells what fraction of the capacity the plant can produce at each timestep.</p> <p>The relationships </p> <ul> <li><code>unit__outputnode</code>: (plant|output node) and </li> <li><code>unit__node__profile</code>: (plant|output node|profile) need to be both created.</li> </ul> <p>The <code>unit__node__profile</code> relationship needs a parameter <code>profile_method</code> that has three options: <code>upper_limit</code>, <code>lower_limit</code> and <code>exact</code>. It states how the profile is considered. In most cases the <code>upper_limit</code> option should be used as it allows the plant to curtail the production if there is more supply than demand. Otherwise the output node might have to use <code>downward_penalty</code> to spill energy.</p> <p>The same profile can be used for multiple <code>unit__outputnode</code>s (and that is why the profile is not a unit parameter but its own entity).</p> <p></p>"},{"location":"how_to/#how-to-connect-nodes-in-the-same-energy-network","title":"How to connect nodes in the same energy network","text":"<p>(connections.sqlite)</p> <p>Typically nodes are used to maintain an energy balance and therefore they are used to represent a location with demand or a storage. The nodes can pass energy to each other through a connection entity. This is often an electricity connection but it can be any form of energy (or matter)  moving between two nodes. To create a connection one needs:</p> <ul> <li>two <code>nodes</code> </li> <li><code>connection</code></li> <li>relationship <code>connection__node__node</code> to tie these three together.</li> </ul> <p>The connection needs the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: The maximum capacity of the connection [MW]. Applies to both directions.</li> <li><code>efficiency</code>: represents the losses in transferring the energy. Same in both directions.</li> </ul> <p>Optional parameters:</p> <ul> <li><code>is_DC</code>: yes, flag if the connection is counted as non-synchronous for the possible non-synchronous limit. If <code>is_DC</code> (direct current) is yes, then the connection is non-synchronous. More at: How-to create a non-synchronous limit</li> <li><code>transfer_method</code>: Four options: regular (default), exact, variable_cost_only, no_losses_no_variable_cost. </li> </ul> <p>In most cases regular should be used. The downside of it is that it allows the flows to both directions at the same time, but the model does this only in specific circumstances when its beneficial to leak energy through the connection losses. For example, if connection capacity is 500 and efficiency 0.8, both nodes can send 500, but recive only 400 reducing the incoming energy by 100 in both nodes without any cost. Typically the model does not want to produce extra energy as it usually has costs, but it can happen if there is a cost to curtailing energy generation from a free source or if a unit is forced to generate at some level ('e.g. using <code>profile_method</code>: 'equal'). If <code>non-synchronous</code> constraint is used with a node using this connection, use exact instead as regular connections can circumvent this limit.</p> <p>Exact method does not allow flow in both directions at the same time, but it requires a binary variable, which will be computationally heavier (especially if the model would otherwise be fully linear). </p> <p>Variable_cost_only can be used when there are no losses associated with the flow. It allows costs related to the flow, but if losses are to be included, it should not be used.</p> <p>The no_losses_no_variable_cost can be used when the connection has no losses and no variable costs accociated with the flow. It is computationally the most efficient method, as it uses only one variable for the flow (the variable becomes negative for the other direction, but this can work only when there are no losses or variable costs). It also prevents simultanoues flow to both directions.</p> <p>The results of connections can be seen from the node_balance table. However, these are the results from all the connections connected to the node. If you want to have the results from an individual connection or specified connections, you can create a group of connection_nodes (<code>group_connection_node</code>) with a parameter <code>output_results</code> set to yes. This will produce sum_flow` results from the connection to the node. </p> <p>The example database shows a connection between a two node system where the other node has a wind power plant and the other node has a coal power plant. </p> <p></p>"},{"location":"how_to/#how-to-set-the-demand-in-a-node","title":"How to set the demand in a node","text":"<p>(demand.sqlite)</p> <p>The demand in a node is set with the inflow parameter. When the node is consuming energy or matter, the values should be negative and when the node is supplying energy (or matter) the values should be positive. The inflow parameter accepts two types of data:</p> <ul> <li>Constant</li> <li>Timeseries map</li> </ul> <p>If the model is using multiple periods, then the same timeseries profile is used for every period. However, the inflow can be scaled for different periods with the <code>inflow_method</code> parameter: - <code>scale_to_annual_flow</code>: This will multiply the demand with a constant to make the summed inflow to match the <code>annual_flow</code>. This requires the node parameter <code>annual_flow</code> that is a map of periods containing the annual flow for each period. The sum of inflows is divided by the period's share of the year (hours in period /8760) before scaling (so that the annual energy demand/supply matches the <code>annual_flow</code> no matter what parts of the year are used to represent the full year).  - <code>scale_in_proportion</code>: calculates a scaling factor by dividing <code>annual_flow</code> with the sum of time series inflow (after it has been annualized using <code>timeline_duration_in_years</code>). This does not force the demand/supply to match annual flow in case the representative periods are not representing the full year, but the time series will still be scaled to capture the proportional change in the <code>annual_flow</code> parameter.  - <code>scale_to_annual_and_peak_flow</code>: The inflow scaled so that the peak is at the given <code>peak_flow</code> and the inflow sums to annual flow of the period. This is done by the following equation:</p> <pre><code>new_inflow = (peak/peak_old)*(1+c)*old_inflow-peak*c\n\nwhere c = \n[(peak/peak_old)*(8760/hours_in_period)*sum(old_inflow) - annual_flow] \n/ [peak*8760 - (peak/peak_old)*(8760/hours_in_period)*sum(old_inflow)]\n</code></pre> <p>Examples of all these options are shown in the demand.sqlite.</p> <p></p>"},{"location":"how_to/#how-to-add-a-storage-unit-battery","title":"How to add a storage unit (battery)","text":"<p>(init.sqlite, scenario: wind_battery) init - west - wind - battery</p> <p>In the Init SQLite database, there is a <code>scenario</code> wind_battery. In the example, the wind_plant alone is not able to meet the load in all conditions, but the battery will help it to improve the situation.</p> <p>In FlexTool, only <code>nodes</code> can have storage. <code>Nodes</code> can therefore be demand nodes, storage nodes or both. To make a storage node one the required parameters are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>existing</code>: The maximum storage size of battery as the potential energy [MWh]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: a large number to prefer not creating energy from nowhere</li> </ul> <p>Additional parameters:</p> <ul> <li><code>self_discharge_loss</code> The fraction of energy loss in each hour.</li> </ul> <p>Storage states can be tied to a value. For this three methods are introduced:</p> <ul> <li><code>storage_start_end_method</code>: Fixes start and/or end state of the storage to a chosen value. This is for the start and the end of the whole model timeline (not for individual solves in case the model is rolling forward).<ul> <li><code>storage_state_start</code> and <code>storage_state_end</code> set these values.</li> </ul> </li> <li><code>storage_bind_method</code>: Forces the start and end values to be the same for the chosen  time interval (timeblock, period or solve)</li> <li><code>storage_solve_horizon_method</code>: Fixes the state of the storage at the end of the solve horizon or sets a price for the stored energy at the end of the solve horizon<ul> <li><code>storage_state_reference_value</code> and <code>storage_state_reference_price</code> set these values</li> </ul> </li> </ul> <p>Having multiple storage methods can create infeasible problems. This is why some of the combinations shouldn't (and cannot) be used at the same time. If multiple methods are used, some of them might be ignored by the method hierarchy. More information can be found from Model Parameters: Using nodes as storages. </p> <p>Battery also needs charging and discharging capabilities. These could be presented either with a <code>connection</code> or by having a charging <code>unit</code> and a discharging <code>unit</code>. In here, we are using a <code>connection</code> called battery_inverter. Please note that the <code>efficiency</code> parameter of the <code>connection</code> applies to both directions, so the round-trip <code>efficiency</code> will be <code>efficiency</code> squared.</p> <p>The <code>transfer_method</code> can be used by all types of connections, but in this case it is best to choose regular, which tries to avoid simultaneous charging and discharing, but can still do it when the model needs to dissipate energy. exact method would prevent that, but it would require integer variables and make the storage computationally much more expensive. Model leakage will be reported in the results (forthcoming).</p> <p>The required paremeters of the connection are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: The capacity of energy transsmission [MW]</li> <li><code>transfer_method</code>: (see above)</li> </ul> <p>Additional parameters:</p> <ul> <li><code>efficiency</code>: by default 1</li> </ul> <p>Finally <code>connection_node_node</code> relationship is needed between inverter, the battery and the demand node (west). </p> <p></p>"},{"location":"how_to/#how-to-make-investments-storageunit","title":"How to make investments (storage/unit)","text":"<p>(init.sqlite scenario: wind_battery_invest) init - west - wind - battery - battery_invest</p> <p>Here we will use the previous battery scenario to represent the investment options in the tool.</p> <p>The solve will invest only if it has an array of <code>invest_periods</code> set, telling the periods where it is allowed to make investment decisions. In a multi solve investment model (rolling investments) it can be useful to separately set <code>invest_realized_periods</code> so that the investment results get reported only from the chosen periods from each solve (in order to avoid overlapping reporting of investment decisions that are replaced by  investment decisions in later solves). Furthermore, <code>realized_periods</code> will define the solves and periods from which the dispatch results are output into results.</p> <p>First, the investment parameters need to be included both for the battery_inverter and battery objects:</p> <ul> <li><code>invest_method</code> - the modeller needs to choose between only_invest, only_retire, invest_and_retire or not_allowed</li> <li><code>invest_cost</code> - overnight investment cost new capacity [currency/kW] for the battery_inverter and [currency/kWh] for the battery. Other one can be left empty or zero, since they will be tied together in the next phase. Here we will assume a fixed relation between kW and kWh for this battery technology, but for example flow batteries could have separate investments for storage and charging capacities.</li> <li><code>interest_rate</code> - an interest rate [e.g. 0.05 means 5%] for the technology that is sufficient to cover capital costs. The chosen interest rate should reflect the assumption that in the model economic lifetime equals the technical lifetime.</li> <li><code>lifetime</code> - technical lifetime of the technology to calculate investment annuity (together with the interest rate)</li> </ul> <p>Additional parameters:</p> <ul> <li><code>invest_max_total</code>: maximum investment (power [MW] or energy [MWh]) to the virtual capacity of a group of units or to the storage capacity of a group of nodes. <ul> <li>In the same way investment limits can be set for total and period, investment and retirement, min and max</li> </ul> </li> <li><code>lifetime_method</code>: Model can either be forced to reinvest when the lifetime ends <code>reinvest_automatic</code> or have a choice <code>reinvest_choice</code></li> <li><code>salvage_value</code>: Sets the extra value that can be gained for retiring [CUR/kW]</li> <li><code>fixed_cost</code>: Annual cost for capacity [CUR/kW]</li> </ul> <p>In many cases some of the investment decisions are tied to each other. Here the battery capacity and the connection capacity of the battery_inverter will be tied as they are simultaneously limited by the choice of the battery technology to be invested in. To model this, a new constraint needs to be created that ties together the storage capacity of the battery and the charging/discharging capacity of the battery_inverter. A new <code>constraint</code> object battery_tie_kW_kWh is created and it is given parameters <code>constant</code>, <code>is_active</code> and <code>sense</code>. Constant could be left out, since it is zero, but <code>is_active</code> must be defined in order to include the constraint in the battery_invest <code>alternative</code>. The <code>sense</code> of the constraint must be equal to enforce the kw/kWh relation.</p> <p>Both battery_inverter and battery need a coefficient to tell the model how they relate to each other. The equation has the capacity variables on the left side of the equation and the constant on the right side.</p> <pre><code>sum_i(`constraint_capacity_coefficient` * `invested_capacity`) = `constant` \n      where i is any unit, connection or node that is part of the constraint\n</code></pre> <p>When the <code>constraint_capacity_coefficient</code> for battery is set at 1 and for the battery_inverter at -8, then the equation will force battery_inverter <code>capacity</code> to be 8 times smaller than the battery <code>capacity</code>. The negative term can be arranged to the right side of the equation, which yields:</p> <p><code>1 x *battery* = 8 x *battery_inverter*, which can be true only if *battery_inverter* is 1/8 of *battery*</code></p> <p><code>constraint_capacity_coefficient</code> is not a parameter with a single value, but a map type parameter (index: constraint name, value: coefficient). It allows the object to participate in multiple constraints.</p> <p>Finally, FlexTool can actually mix three different types of constraint coefficients: <code>constraint_capacity_coefficient</code>, <code>constraint_state_coefficient</code> and <code>constraint_flow_coefficient</code> allowing the user to create custom constraints between any types of objects in the model for the main variables in the model (flow, state as well as invest and divest). So, the equation above is in full form:</p> <pre><code>  + sum_i [constraint_capacity_coefficient(i) * invested_capacity]\n           where i contains [node, unit, connection] belonging to the constraint\n  + sum_j [constraint_flow_coefficient(j) * capacity]\n           where j contains [unit--node, connection--node] belonging to the constraint\n  + sum_k [constraint_state_coefficient(k) * capacity] \n           where k contains [node] belonging to the constraint\n  = \n  constant\n\n  where 'capacity' is existing capacity plus invested capacity\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-combined-heat-and-power-chp","title":"How to create combined heat and power (CHP)","text":"<p>(init.sqlite scenario: coal_chp) init - west - coal_chp - heat</p> <p>First, a new heat <code>node</code> is added with the necessary parameters. The <code>nodes</code> can be used for energy form of energy or matter, so the heat demand node does not differ from the electricity demand node. </p> <p>The required parameters are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>inflow</code>: Map for the heat demand (negative) [MW]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: a large number to prefer not creating energy from nowhere</li> </ul> <p>The heating systems tend to have some level of storage capability, so one could also add storage parameters to the node as well, but here they are not used.</p> <p>Then the coal_chp <code>unit</code> is made with a high <code>efficiency</code> parameter, since CHP units convert fuel energy to power and heat at high overall rates. In FlexTool, <code>efficiency</code> is a property of the unit - it demarcates at what rate the sum of inputs is converted to the sum of outputs. However, without any additional constraints, the <code>unit</code> is free to choose in what proportion to use inputs and in what proportion to use outputs. In units with only one input and output, this freedom does not exist, but in here, the coal_chp needs to be constrained as otherwise the unit could produce only electricity and no heat at 90% efficiency, which is not feasible. </p> <p>This CHP plant is an another example where the user defined <code>constraint</code> (see the last equation in the previous example) is used to achieve the desired behaviour. In a backpressure CHP, heat and power outputs are fixed - increase one of them, and you must also increase the other. In an extraction CHP plant the relation is more complicated - there is an allowed operating area between heat and power. Both can be represented in FlexTool, but here a backpressure example is given. An extraction plant would require two or more greater_than and/or lesser_than <code>constraints</code> to define an operating area.</p> <p>Electricity and heat outputs are fixed by adding a new <code>constraint</code> coal_chp_fix where the heat and power co-efficients are fixed. You need to create the two relationships <code>unit__outputNode</code>, for coal_chp--heat and coal_chp--west. As can be seen in the bottom part of the figure below, the <code>constraint_flow_coefficient</code> parameter for the coal_chp--heat and coal_chp--west is set as a map value where the <code>constraint</code> name matches with the coal_chp_fix <code>constraint</code> object name. The values are set so that the constraint equation forces the heat output to be twice as large as the electricity output.</p> <p>Create constraint  coal_chp_fix object with parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>Create <code>unit_outputNode</code> (coal_chp|heat):</p> <ul> <li><code>constraint_flow_coefficient</code> : coal_chp_fix, -0.5</li> </ul> <p>Create <code>unit_outputNode</code> (coal_chp|west):</p> <ul> <li><code>constraint_flow_coefficient</code> : coal_chp_fix, 2</li> </ul> <p>Again, the negative value can be turned positive by arranging it to the right side of the equality, creating this:</p> <pre><code>1 x *electricity* = 0.5 x *heat*, which is true only if *heat* is 2 x *electricity*\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-a-hydro-reservoir","title":"How to create a hydro reservoir","text":"<p>hydro_reservoir.sq</p>"},{"location":"how_to/#simple-hydro-reseroir","title":"Simple hydro reseroir","text":"<p>(scenario: hydro)</p> <p>The objective is to create a hydro power plant with a reservoir and connect it to a demand node.</p> <p>Hydro reservoir power plant requires three components:</p> <ul> <li>Reservoir <code>node</code></li> <li>Hydro <code>unit</code></li> <li>Output <code>node</code></li> </ul> <p>It can be useful to create a new alternative for these components to be able to include and exclude them from the scenarios.</p> <p>The reservoir is made with a node as only nodes can have storage in FlexTool. The incoming water can be represented by the inflow parameter. It can be a constant or a time variant. </p> <p>There are two ways to handle the water to electricity coefficient. In this example we store the water as volume and convert it to electricity in the unit.  This option is better when modelling river systems with multiple reservoirs. Note that in the results, the state of the reservoir is then as volume. For the other option of converting the volume to potential energy in the reservoir, look at the start of the 'How to create a hydro pump storage'.</p> <p>In this implementation of reservoir hydro power, there is an option to spill water from the storage so that it does not run through the plant. The simplest way of allowing spilling is setting the downward penalty of the node to 0. This way the energy can disappear from the storage without a cost. The quantity of spilled water can be seen from the results as the 'downward slack' of the node.</p> <p>The required parameters of the reservoir node are (node_c and node_t sheets if using Excel input data):</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>inflow</code>: Mapping of the incoming water as volume [m^3/h]</li> <li><code>existing</code>: The maximum size of the reservoir [m^3]</li> <li><code>penalty_up</code>: a larger number than with the demand node to not allow creating extra water if not enough electricity is being created</li> <li><code>penalty_down</code>: 0 or a large number (spilling or not)</li> <li>a <code>storage_method</code> to set the behaviour on how the storage levels should be managed - for short duration storages bind_within_timeblock may be best and for seasonal storages it could be best to use bind_within_solve. If historical storage level time series are available, it can be beneficial to use fix_start in the <code>storage_start_end_method</code> together with <code>storage_solve_horizon_method</code> use_reference_value, which will pick the storage level at the end of each solve from the time series provided as a reference (storage_state_reference_value).</li> </ul> <p>The <code>unit</code> is connected to the reservoir <code>node</code> and the output <code>node</code> demand_node (unit_c and unit_node_c in excel):</p> <ul> <li>The <code>efficiency</code> of the plant is the coefficient of transfering an unit of volume to an unit of electricity (using piecewise linear efficiency is naturally possible), here we use 0.57. </li> <li>Set <code>existing</code> capacity [MW]</li> <li><code>is_active</code>: yes </li> <li>Create relations <code>unit__inputNode</code>: hydro_plant|reservoir and <code>unit__outputNode</code>: hydro_plant|demand_node.</li> </ul> <p></p>"},{"location":"how_to/#river-system-with-multiple-reservoirs","title":"River system with multiple reservoirs","text":"<p>(scenario: hydro_with_downriver_spill_unit) (scenario: river_system)</p> <p>In this example, we create a hydro system with multiple reseroirs and downriver water demand. Here the water in the reservoir is represented as volume and the conversion to electricity is done in the units.</p> <p>The reservoir and demand node are the same as above. The <code>penalty_down</code> of the reservoir now needs to be the other than 0 as the spilled water needs to flow to the downriver node</p> <p>Let's start with the downriver demand. </p> <p>The downriver node represents the requirement to pass a minimum amount of water through the plant to not dry out the river. The downriver node needs:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>inflow</code>: Minimum requirement of water flow as the potential power (Map or constant)[m^3/h]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: 0, this makes the requirement to be at least the amount of water as the demand, not the equal to it</li> </ul> <p>The hydro plant unit now also needs the relation <code>unit_outputNode</code>: hydro_plant|downriver . </p> <p>The hydro plant now needs to both pass the water to downriver and the electricity to the demand node. Also, it needs to handle the water to electricity transformation as the reservoir now has volume not energy. The user needs to get the water to electricity coefficient ie. how much energy does one unit of volume create when passing the unit in this example the coefficient is 0.57. As the unit creates both the water and the electricity, the efficiency now is the sum of the two. </p> <ul> <li><code>efficiency</code>: 1 + coefficient</li> </ul> <p>Now the unit creates enough stuff to output, but the model can still choose how it will distribute it between the two output nodes. We still need to fix the ratio of output flows. This is done with an user constraint. Here we call this constraint hydro_split. The constraint needs parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0</li> </ul> <p>As we are fixing the output flows, the we need to add the flows with their coefficients to this constraint. This is done with the unit_outputNode parameter <code>constraint_flow_coefficient</code>:</p> <ul> <li><code>unit_outputNode</code>(hydro_plant|downriver): <code>constraint_flow_coefficient</code>: Map (hydro_split| 0.57)  </li> <li><code>unit_outputNode</code>(hydro_plant|demand_node): <code>constraint_flow_coefficient</code>: Map (hydro_split| -1)</li> </ul> <p>These create the constraint: </p> <pre><code>-flow_to_demand_node + 0.57 flow_to_downriver = 0\n</code></pre> <p>The capacity of an unit limits both outputs. Here the flow to downriver is larger than to the demand node. The capacity of the unit should be the electrical capacity divided by the water to electricity coefficient. With the electrical capacity of 500MW and water to elecricity coefficient of 0.57 the capacity of the unit becomes 878. Now at full power, 878 units of water flow to downriver and 500MW of electricity flow to the demand node.</p> <p>To add a spill option to the reservoir we need to create another unit. This is because just making extra water disappear with the <code>penalty_down</code>: 0, will not transfer this water to the downriver node to fulfil its needs.  This spill unit has the relations: - <code>unit_inputNode</code> (spill_unit|reservoir) - <code>unit_outputNode</code> (spill_unit|downriver)</p> <p>And parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>efficiency</code>: 1</li> <li><code>existing</code>: A large enough number to not be a limit</li> </ul> <p></p> <p>The database also includes an example of a river system with two additional reservoirs and plants. Both of them flow to the reservoir already made in this how to. These two are created the exact same way as above, but with just different values and the relation <code>unit_outputNode</code>: (hydro_plant_2| reservoir) and <code>unit_outputNode</code>: (hydro_plant_3| reservoir).</p> <p>In principle you can create as large river systems as you want, but each reservoir adds extra computational burden. Think about the possibility to combine the reservoirs and plants in the system and what information you lose with this approximation.</p> <p></p>"},{"location":"how_to/#how-to-create-a-hydro-pump-storage","title":"How to create a hydro pump storage","text":"<p>(hydro_with_pump.sqlite)</p> <p>For a hydro pump storage one needs the following components:</p> <ul> <li>Demand <code>node</code> </li> <li>hydro_plant <code>unit</code> with </li> <li>storage <code>node</code>, </li> <li>hydro_pump <code>unit</code> with </li> <li>pump storage <code>node</code> </li> <li>a source for external energy (pumped storage plant will lose energy due to charging losses). Wind power plant will be used as a source for external energy.</li> </ul> <p>There are two ways to handle the water to electricity coefficient. Here, we convert the reservoir capacity and inflow to potential energy.  The unit of the inflow should be the power that can be created from the quantity of the incoming water at maximum efficiency [MW]. In the same way, the existing storage capacity should be the maximum amount of stored energy that the reservoir can hold [MWh]. In this implementation of reservoir hydro power, there is an option to spill water (energy) from the storage so that it does not run through the plant. The simplest way of allowing spilling is setting the downward penalty of the node to 0. This way the energy can disappear from the storage without a cost. The quantity of spilled energy can be seen from the results as the 'downward slack' of the node.</p> <p>The required parameters of the reservoir node are (node_c and node_t sheets if using Excel input data):</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>inflow</code>: Mapping of the incoming water as the potential power [MW]</li> <li><code>existing</code>: The maximum size of the reservoir as the potential energy [MWh]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: 0 or a large number (spilling or not)</li> <li>a <code>storage_method</code> to set the behaviour on how the storage levels should be managed - for short duration storages bind_within_timeblock may be best and for seasonal storages it could be best to use bind_within_solve. If historical storage level time series are available, it can be beneficial to use fix_start in the <code>storage_start_end_method</code> together with <code>storage_solve_horizon_method</code> use_reference_value, which will pick the storage level at the end of each solve from the time series provided as a reference (storage_state_reference_value).</li> </ul> <p>The <code>unit</code> is connected to the reservoir <code>node</code> and the output <code>node</code> nodeA (unit_c and unit_node_c in excel):</p> <ul> <li>The <code>efficiency</code> of the unit can be set to 1 as the inflow time series are directly expressed in MWh (using piecewise linear efficiency is naturally possible).</li> <li>Set <code>existing</code> capacity [MW]</li> <li><code>is_active</code>: yes </li> <li>Create relations <code>unit__inputNode</code>: hydro_plant|reservoir and <code>unit__outputNode</code>: hydro_plant|nodeA.</li> </ul> <p></p> <p>Next create the pump_storage. This is the downstream storage from the hydro plant. Again it should have the parameters as the reservoir:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>existing</code>: The maximum size of the storage [MWh]. Note that this really represents the mass of the water and it should be converted as the potential of the energy of the reservoir-plant system. So that 1 liter of water has the same energy in both storages.</li> <li><code>penalty_up</code>: a large number to avoid creating energy from nowhere</li> <li><code>penalty_down</code>: 0 </li> </ul> <p>In this example database, we have both a closed system and a river system. The difference is that in the closed system the inflow is zero in both reservoir and pump_storage. In river system we have the incoming water for the reservoir as in the reservoir example. In the downstream pump storage, we implement an outflow as the negative inflow representing the minimum amount of water that has to flow out of the system at each timestep to not dry out the river. The <code>penalty_down</code> is set as 0 to allow it let more water go when it needs to, otherwise the storages will keep filling up if the incoming water is larger than the minimum outgoing water.</p> <p>The storage level fixes should be the same in both storages (reservoir and pump storage). Here:</p> <ul> <li><code>fix_start_end_method</code>: fix_start</li> <li><code>storage_state_start</code>: 0.5</li> <li><code>bind_storage_method</code>: bind_with_timeblock</li> </ul> <p>This sets the starting storage levels to be 50%. The binding will also constrain the state of the storage at the end of of each timeblock to be the same as in the beginning of the timeblock.</p> <p>Then create the pump unit. It only needs three parameters:</p> <ul> <li><code>efficiency</code> = 1, The real efficiency of the pump is set elsewhere, so use 1.0 here. </li> <li><code>existing</code>: The wanted capacity</li> <li><code>is_active</code>: yes </li> </ul> <p>Set the relationships as follows:</p> <ul> <li><code>unit_outputNode</code> for (hydro_plant | nodeA), (hydro_plant | pump_storage ), (hydro_pump | reservoir)</li> <li><code>unit_inputNode</code> for (hydro_plant | reservoir), (hydro_pump | pump_storage), (hydro_pump | nodeA)</li> </ul> <p>Your system should look something like:</p> <p></p> <p>Next comes the tricky part of preserving the water and energy as both are represented as generic energy in the model. This is done by setting extra coefficents and constraints to the flows. First the hydro_plant needs to both create the energy for the demand node and pass the mass to the pump_storage. This is done by doubling the efficiency in this example to 2 and setting a extra constraint to force the output flows to both the demand node and the storage to be the same. </p> <p>For the hydro plant:</p> <ul> <li><code>Efficiency</code>:  2 </li> </ul> <p>Create a new constraint (here plant_storage_nodeA_split) and add the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>And for the <code>unit_outputNodes</code>:</p> <ul> <li>(hydro_plant | nodeA) <code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , 1</li> <li>(hydro_plant | pump_storage) <code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , -1</li> <li>Meaning: </li> </ul> <pre><code>flow to nodeA - flow to pump_storage = 0\n</code></pre> <p>As for the pump storage, we will have to make sure that the same amount of water leaves the pump_storage and enters the reservoir. Also it still should use electricity from the demand node without increasing the amount of water that is moving from storage to another.  First to prevent the energy from the demand node from increasing the water flow, add a coefficient to the flow between the demand node and the pump.</p> <p><code>unit_inputNode</code> (hydro_pump|nodeA): - <code>Coefficient</code>: 0 (Default is 1) </p> <p>This prevents the water amount from increasing as:</p> <pre><code>unit_output_flow = coeff1 * unit_input_flow1 + coeff2 * unit_input_flow2.\n</code></pre> <p>We still have to make the unit to consume electricity even though it does not affect the unit output directly. This is done by setting a new constraint to tie the flows to the pump unit from pump storage and the nodeA. Add a constraint (here pump_storage_nodeA_fix) the with the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>And setting parameters for <code>unit_inputNode</code>:</p> <ul> <li>(hydro_pump | nodeA) <code>constraint_flow_coefficient</code> Map: pump_storage_nodeA_fix , 2</li> <li>(hydro_pump | pump_storage) <code>constraint_flow_coefficient</code> Map: pump_storage_nodeA_fix , -1</li> </ul> <pre><code>2 * flow_from_nodeA - flow_from_pump_storage = 0\n</code></pre> <p>Note that here the (<code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , 2) actually sets the efficiency of the pump.  This means that here only half of the electricity used by the pump can be recovered when that amount of water is used by the hydro_plant. (Two units of energy are used to move 1 unit of water_energy) The <code>constraint_flow_coefficient</code> for pump_input should therefore be (1/efficiency)</p> <p> </p>"},{"location":"how_to/#how-to-add-a-reserve","title":"How to add a reserve","text":"<p>(init.sqlite: scenario network_coal_wind_reserve)</p> <p>In FlexTool, reserves are defined for a group of nodes. If there is a need to have a reserve requirement for a single node, it needs its own group. Therefore, when creating a reserve, the first step is to add a new <code>group</code> (e.g. electricity) with all member nodes (e.g. west, east and north) using the <code>group__node</code> relationship class. Then, a new reserve categories can be added (e.g. primary) to the <code>reserve</code> object class.  Finally, make sure there are up and down objects in the `UpDown' object class. These are hard-coded names in FlexTool and need to be used when creating reserves.</p> <p>Next, the reserve requirement will be defined. A relationship between in the <code>reserve__upDown__group</code> class (e.g. primary--up--electricity) allows to define the reserve parameters <code>reserve_method</code>, <code>reservation</code> (i.e. the amount of reserve) and <code>penalty_reserve</code> (i.e. the penalty cost in case of lack of reserve). For example, a constant of 10 MW could be used. Even though the name of the <code>reserve_method</code> is timeseries_only, it can also accept a constant value - it's an exogenous reserve requirement whereas the other two reserve methods are endogenous. Dynamic reserve method calculates the reserve requirement from generation and loads according to user defined factors (<code>increase_reserve_ratio</code>). Largest failure method will force enough reserve to cope with a failure of the chosen unit and connection flows.</p> <p>Parameters from the <code>reserve__upDown__unit__node</code> class should be used to define how different units can contribute to different reserves. Parameter <code>max_share</code> says how large share of the total capacity of the timestep (existing * efficiency * (profile)) of the unit can contribute to this reserve category (e.g. coal_plant may be limited by ramp constraint to provide only 1% of its capacity to an upward primary reserve.) Meanwhile, parameter <code>reliability</code> affects what portion of the reserved capacity actually contributes to the reserve (e.g. wind_plant may contribute only 80% of its generation to reserve due to uncertainty).</p> <p></p>"},{"location":"how_to/#how-to-add-a-minimum-load-start-up-and-ramp","title":"How to add a minimum load, start-up and ramp","text":"<p>(ramp_and_start_up.sqlite)</p> <p>Some plants cannot vary their output freely, but have some cost and limits associated with it. In this example we will add the minimum load behaviour to a coal_plant <code>unit</code> and add the cost and limits for starting up and ramping the plant respectively.</p> <p>Minimum load requires that the unit must have an online variable in addition to flow variables and therefore a <code>startup_method</code> needs to be defined and an optional <code>startup_cost</code> can be given. The <code>startup_cost</code> is added to the total cost every time the unit is required to start-up. Here we use a value 1000 (Currency/MW started up).</p> <p>The options for the <code>startup_method</code> are no_startup, linear and binary. binary would require an integer variable so linear is chosen. However, this means that the unit can startup partially. The minimum online will still apply, but it is the minimum of the online capacity in any given moment (flow &gt;= min_load x capacity x online), where 0 &lt;= online &lt;= 1.</p> <p>The online variable also allows to change the efficiency of the plant between the minimum and full loads. A unit with a part-load efficiency will obey the following equation:</p> <pre><code>  + sum_i[ input(i) * input_coefficient(i) ]\n  =\n  + sum_o[ output(o) * output_coefficient(o) ] * slope\n  + online * section\n\nwhere   slope = 1 / efficiency - section\n  and section = 1 / efficiency \n                - ( 1 / efficiency - min_load / efficiency_at_min_load) / ( 1 - min_load )\n</code></pre> <p>By default, <code>input_coefficient</code> and <code>output_coefficient</code> are 1, but if there is a need to tweak their relative contributions, these coefficients allow to do so (e.g. a coal plant might have lower efficiency when using lignite than when using brown coal).</p> <p>The input is required at different ouput levels is shown in the figure below, when Capacity = 100, Efficiency = 0.8, Minimum load = 0.6 and Efficiency at minimum load = 0.5.</p> <p></p> <p>Next we will add ramp limits. With the ramping limits, the user can force the change of a flow from a unit to be below a certain value each timestep. The ramping is an attribute of the flow. Therefore it does not require the minimum load behaviour and its parameters are added to the <code>unit_outputNode</code> relationship:</p> <ul> <li><code>ramp_method</code>: ramp_cost, ramp_limit or both. Only ramp limit is currently implemented (August 2023).</li> <li><code>ramp_speed_up</code>: Limit on how fast the plant can ramp up. (fraction of unit / min) ie. Value 0.01 allows the change of 60% of capacity per hour. </li> <li><code>ramp_speed_down</code>: Limit on how fast the plant can ramp down. (fraction of unit / min) ie. Value 0.01 allows the change of 60% of capacity per hour.</li> <li><code>ramp_cost</code>: NOT YET IMPLEMENTED. The cost of ramping the capacity. [CUR/MW] </li> </ul> <p></p>"},{"location":"how_to/#how-to-add-co2-emissions-costs-and-limits","title":"How to add CO2 emissions, costs and limits","text":"<p>(init.sqlite scenario: coal_co2 ) init - west - coal - co2_price - co2_limit</p> <p>Carbon dioxide emissions are added to FlexTool by associating relevant <code>commodities</code> (e.g. coal) with a <code>co2_content</code> parameter (CO2 content (tons per MWh) of energy contained in the fuel).  The other CO2 parameters are handeled through a group of nodes (Here coal_price or coal_limit <code>groups</code>). Therefore one needs to create a group and add all the nodes that supply these commodities (eg. coal_market) to a group with a <code>group_node</code> relationship. (Here the relationship co2_price--coal_market) To set a price one needs to create set the co2_method parameter to price (constant) and create the <code>co2_price</code> parameter with the desired value. This price is added to the price of the commodity. </p> <p>Alternatively one can set a limit on the co2 used by setting the <code>co2_method</code> parameter to period or total and setting the <code>co2_max_period</code> (periodic map [tCO2]) parameter or <code>co2_max_total</code> (constant [tCO2]) parameter. </p> <p>There methods can be combined by setting the <code>co2_method</code> to price_period, price_total, period_total or price_period_total.</p> <p></p>"},{"location":"how_to/#how-to-create-a-non-synchronous-limit","title":"How to create a non-synchronous limit","text":"<p>(non_sync_and_curtailment.sqlite) (scenario: non_sync)</p> <p>Non-synchronous limit is a property of a <code>group</code> of nodes. It states that the non-synchronous flow to the group of nodes cannot exceed a set share of the input flows at any timestep. To demonstrate this, we have set a system with a coal plant, a wind plant and a single demand node. However, it can be done to a group of nodes with unlimited number of plants or connections connected. So, one can limit the non-synchronous share of individual nodes or of the whole system. The flows between the nodes of the group are excluded.</p> <p>The non-synchronous limit is set to a <code>group</code> of nodes with one or multiple members. Note: These are set to the group with <code>group_node</code> relationship, not with <code>group_node_unit</code> relationship!</p> <p>Create a group (here nodeA_group) and set a <code>group_node</code> relationship (nodeA_group |nodeA). Then add parameters:</p> <ul> <li><code>has_non_synchronous</code>: yes</li> <li><code>non_synchronous_limit</code>: 0.5</li> <li><code>penalty_non_synchronous</code>: 4000</li> </ul> <p>This forces the non-sync flow to be at max 50% of the incoming flow to the nodeA.  The penalty should be always set as in some cases there is no other way to keep the constraint feasible (and it will be difficult to find the reason why the model does not solve). The existence of the non-synchronous penalty in your results indicates that this constraint has been violated and you should investigate the reason for this in your system. If the <code>penalty_non_synchronous</code> is lower than the <code>upward_penalty</code> of the demand <code>node</code>, the system will prefer breaking the non-sync constraint instead of the <code>node</code> balance equation. In other words, it will not curtail the production of <code>profile</code> plants if the demand is not satisfied even though it will break the non-synchronous penalty. If it is higher, the curtailment will take place instead.</p> <p>When having a connection to a storage from a node with this constraint, the best practice is to add this storage node to the group as well. This excludes the flows to and from the storage in the calculation of the non-synchronous ratio. However, if you want to have these flows in the calculation, you have two options depending on if you want the flow to be synchronous or not. If it is non-synchronous, just set the connection parameter <code>is_DC</code>: yes. If it is synchronous (e.g., some flywheels), an issue arises with the reqular connection as it now can reduce the ratio with equal simultaneous flow in both directions. To prevent the simultaneous flow to both directions you need to set the <code>transfer_method</code>: exact. This will increase the solving time significantly as it will use integer variables (so, better to add the storage node to the node group with a non-synchronous limit).</p> <p>Then set which plants and connections are considered non-synchronous by adding parameters:</p> <p><code>unit_outputNode</code>: - <code>is_non_synchronous</code>: yes </p> <p><code>Connection_node_node</code>: - <code>is_DC</code>: yes </p> <p>Here the (wind_plant|nodeA) relation has the <code>is_non_synchronous</code> parameter and battery connection <code>is_DC</code> parameter.</p> <p>A connection with <code>transfer_method</code>: no_losses_no_variables between a node included in a group with a non-synchronous limit and a node outside of the group is not allowed. The flow in this kind of a connection is presented with a single variable, which would not function correctly with the non-synchronous limit constraints (there is a non-linearity at zero that requires two variables). </p> <p>If you want to see the individual flows in the results you can create separate <code>groups</code> for the flows and add <code>group_unit_node</code> relations to it. To produce the flow results, the groups need the parameter.</p> <ul> <li><code>output_results</code>: yes </li> </ul> <p>Here we have coal_flow <code>group</code> with <code>group_unit_node</code> relation coal_flow|coal_plant|nodeA and wind_flow <code>group</code> with <code>group_unit_node</code> relation wind_flow|wind_plant|nodeA.</p> <p></p>"},{"location":"how_to/#how-to-see-the-vre-curtailment-and-vre-share-results-for-a-node","title":"How to see the VRE curtailment and VRE share results for a node","text":"<p>(non_sync_and_curtailment.sqlite) (scenario: curtailment)</p> <p>When the system has profile-units with the <code>profile_method</code>: upper_limit, the model can curtail the unit's flow to avoid penalties.</p> <p>The curtailment could take place for several reasons:</p> <ul> <li>the supply is higher than the demand and the energy cannot be stored or transferred (further)</li> <li>non-synchronous limit</li> <li>extra flow constraints have been set</li> <li>other unit specific constraint affecting how VRE units or other units are forced to behave (ramp, start-up ...)</li> </ul> <p>To see the curtailment results you need to add a <code>group</code> of nodes (<code>group_node</code> not <code>group_unit_node</code> !) with one or more members. The group then needs the parameter:</p> <ul> <li><code>output_results</code>: yes</li> </ul> <p>This produces the <code>group</code>: indicator result to the Results database and group_summary table to the excel.</p> <p>These changes were done to the previous non-sync example database. </p> <p>Note: The results are the share of curtailment in relation to the inflow (demand) so it can exceed 100% as seen in the figure.</p> <p></p> <p></p>"},{"location":"how_to/#how-to-run-solves-in-a-sequence-investment-dispatch","title":"How to run solves in a sequence (investment + dispatch)","text":"<p>(init.sqlite scenario: 5weeks_invest_fullYear_dispatch_coal_wind)</p> <p>In this example, investment decisions are made using a five week sample of a year and then the dispatch is solved with the full year timeline using these investments. </p> <p>To do this you need two solves:</p> <ul> <li>Investment solve </li> <li>Dispatch solve</li> </ul> <p>Both solves should solve the same periods using different <code>timeblockSet</code> to represent these periods. This example has only one period p2020 describing a year. The investment solve uses a representative sample <code>timeblockSet</code> 5weeks to do the investment decisions. These are then passed to the dispatch solve that uses complete timeline fullYear.</p> <p>Investment solve requires the parameters:</p> <ul> <li><code>Invest_periods</code>: Array of periods where investments can be made</li> <li><code>realised_invest_periods</code>: Array of periods that are output for investment decisions</li> <li><code>period_timeblockSet</code>: Uses the 5weeks as the timeblock </li> </ul> <p>Note that the <code>realized_invest_periods</code> is used instead of <code>realized_periods</code>, because we want the investment solve to only output investments. Additionally some of the units, connections or storages will need investment parameters (<code>invest_cost</code>, <code>lifetime</code>...) see How to make investments (storage/unit)</p> <p>The dispatch solve requires the parameters:</p> <ul> <li><code>realized_periods</code>: Array of output periods</li> <li><code>period_timeblockSet</code>: Uses the fullYear as the timeblock</li> </ul> <p>The sequence of solves is defined by the <code>model</code> parameter <code>solves</code>. Here it is an array where the first item is an investment_solve 5weeks_only_invest and the second is the dispatch solve y2020_fullYear_dispatch. This is enough for the model to know to pass the investment decisions of the period to the period of the same name in the second solve.</p> <p>Note that the picture has two <code>model</code>: solves parameters defined one for each alternative. Only the parameter from the 5weeks_only_invest is used as the lower alternatives in the scenario tree override the values from the higher alternatives and only one model can be run.</p> <p></p>"},{"location":"how_to/#how-to-create-a-multi-year-model","title":"How to create a multi-year model","text":"<p>A multi-year model is constructed from multiple periods, each presenting one year. In the example case, each year is otherwise the same, but the demand is increasing in the west <code>node</code>. This means that all periods can use the same timeblockset 5weeks from the same timeline y2020, but one can also make separate timelines for each year, if data is available for this. The <code>inflow</code> time series are scaled to match the value in <code>annual_flow</code> that is mapped for each period. The model is using the <code>inflow_method</code> scale_to_annual in order to achieve this (default is use_original that would not perform scaling). There should also be a <code>discount_rate</code> parameter set for the <code>model</code> object flexTool if something else than the model default of 5% (0.05 value) is to be used.</p> <p></p> <p>A multi-year model could be solved at one go (multi_year_one_solve) or by rolling through several solves (multi-year) where each solve has a foresight horizon and a realisation horizon. Next we will go through both options.</p>"},{"location":"how_to/#multi-year-with-one-solve","title":"Multi year with one solve","text":"<p>(init.sqlite scenario: multi_year_one_solve)</p> <p>In this example, one solve is used for all the four periods. All the four periods need to be added to the solve arrays <code>invest_periods</code> and <code>realized_periods</code>. Here the same timeblock is used for all the four periods, so only difference between them is the increasing inflow set above. The parameters that need to be added to the <code>solve</code> object:</p> <ul> <li><code>years_represented</code> parameter is used by the model to calculate the discounting factors for the periods in the model (often future years). It should state the number of years each period will be representing. For example, a period for 2025 could represent the years 2025-2029 if its <code>years_represented</code> is set to 5. Any investments would be taking place at the start of 2025 and discounted to the beginning of 2025, but the operational costs would accrue from each year in 2025-2029 each with a different discounting factor (decreasing based on the interest rate).</li> <li><code>invest_periods</code> the periods in which the model is allowed to make investments.</li> <li><code>realized_periods</code> the periods that will be realized in this solve (outputs dispatch results for these periods).</li> <li><code>period_timeblockset</code> defines the set of representative 'periods' (timeblocks in FlexTool) to be used in each FlexTool <code>period</code>.</li> </ul> <p></p>"},{"location":"how_to/#multi-year-with-rolling-solves","title":"Multi year with rolling solves","text":"<p>(init.sqlite scenario: multi_year)</p> <p>If the solving time gets too big, there is an option to split the timeline into overlapping parts and solve them separately. This shortens the solving time as it increases exponentially as the model grows. Therefore, collection of smaller solves is faster. The drawback is that the accuracy will be affected if there are dependencies with a larger time interval than the split size. </p> <p>When dealing with investments the splitting only works if the different periods are similar, in most cases complete years. If the first solve is really windy, it would invest too much on wind which wouldn't produce enough energy in later solves and then it would need to invest again to something else. It can also be challenging to consider lifetimes. If the option of retiring is allowed, it might retire something that is needed for later solves. In this example, the periods are complete years and the only difference between periods is increased demand.</p> <p>The model rolls through several solves and therefore, the <code>model</code> object flexTool has four values in the <code>solves</code> array. Each value represents one solve and it's position in the sequence of solves. The next figure illustrates the realization (blue) and foresight horizons (grey). The first solve will solve both the year 2020 and year 2025, but it will only output the year 2020. The next will solve both 2025 and 2030 but only output 2025.</p> <p></p> <p>Next figure shows the values needed to define one solve (out of the four solves in the example). Each of these need to be repeated for each solve in the model.</p> <ul> <li><code>years_represented</code> parameter is used by the model to calculate the discounting factors for the periods in the model (often future years). It should state the number of years each period will be representing. For example, a period for 2025 could represent the years 2025-2029 if its <code>years_represented</code> is set to 5. Any investments would be taking place at the start of 2025 and discounted to the beginning of 2025, but the operational costs would accrue from each year in 2025-2029 each with a different discounting factor (decreasing based on the interest rate).</li> <li><code>invest_periods</code> the periods in which the model is allowed to make investments. To be given for each solve.</li> <li><code>realized_periods</code> the periods that will be realized in this solve (outputs dispatch results for these periods). To be given for each solve.</li> <li><code>invest_realized_periods</code> parameter states the periods that will realize the investment decisions. If not stated, it will use <code>realized_periods</code>.</li> <li><code>period_timeblockset</code> defines the set of representative 'periods' (timeblocks in FlexTool) to be used in each FlexTool <code>period</code>.</li> </ul> <p>Note the the <code>solve_mode</code>: rolling_window is not used! This is not for investment runs (without nesting) as it rolls freely, and investments should only be made at the start of the period. This example is called 'manual rolling' later when those are discussed.</p> <p>In the init.sqlite, the solve objects have solver parameters: <code>highs_method</code>, <code>highs_parallel</code> and <code>highs_presolve</code>. They only affect the speed and not the results, but usually the default values are good enough and the user should only change them if they understand how the solvers work.</p> <p></p>"},{"location":"how_to/#how-to-use-a-rolling-window-for-a-dispatch-model","title":"How to use a rolling window for a dispatch model","text":"<p>A rolling window can be used for example when a dispatch model gets too big to be solved on one go. It splits the problem into multiple consecutive smaller problems.</p> <p>The rolling window solve splits the time dimension into overlapping parts and solves each one of them separately but in a sequence (and can therefore pass state information from the previous solve to the next one). For example, instead of a solving the full year in one go, you can split the year into six four-month long solves where each solve outputs only the first two months. The solves would therefore include the months:</p> <ul> <li>Roll: Solve months -&gt; Output months</li> <li>1: [1,2,3,4] -&gt; [1,2]</li> <li>2: [3,4,5,6] -&gt; [3,4]</li> <li>3: [5,6,7,8] -&gt; [5,6]</li> <li>4: [7,8,9,10] -&gt; [7,8]</li> <li>5: [9,10,11,12] -&gt;[9,10]</li> <li>6: [11,12] -&gt; [11,12]</li> </ul> <p></p> <p>The rolling solve could be setup also manually as described in the 'How to run a multi year model' - just using shorter periods. </p> <p>However, this would be tedious if there are many solves. In a rolling window model, the user can set the <code>rolling_jump</code> and <code>rolling_horizon</code> parameters, which are expressed in hours. </p> <ul> <li> <p><code>rolling_horizon</code>: sets the length of the whole solve, in hours. In previous example 4 months (2880 hours). Horizon allows the model to see bit further in the future to improve the decision making for the period that will be output.</p> </li> <li> <p><code>rolling_jump</code>: sets the interval for the length of each 'jump' the model takes forward in reach roll. It is then both the interval of roll starting points and the length of the output for each roll. The <code>rolling_jump</code> must be smaller than the <code>rolling_horizon</code>. In the previous example the <code>rolling_jump</code> would be 2 months (1440 hours).</p> </li> </ul> <p>In addition, the user can set the duration for how long the model will roll:</p> <ul> <li><code>rolling_duration</code>: Optional (hours), the length of combined rolls. In the example, it could be set to 8640 hours which would divide evenly, or 8760 hours which means that the last roll will be shorter than the others. It is nicer to use <code>rolling_jump</code> that is divisable with the <code>rolling_duration</code> to keep rolls even. If <code>rolling_duration</code> is not set, it defaults to rolling through the whole timeline.</li> </ul> <p>When using rolling window solve, you are solving the model with less information. Therefore, the results will be less optimal since the model will not have the full information at once. It is therefore important to know how this could affect the results and what things to consider when implementing a rolling window model. It will have an impact on time dependant parts of the model: for example, storages or cumulative flow constraints. If the model can see only a few months to the future, it can't see how much energy needs to be stored after that. </p> <p>Investments should not be used with this free rolling solve (<code>solve_mode</code>: rolling_window) as investments should only be done at the start of the periods. Both the long-term storage and the investments can be taken into account with nested rolling solves that have a separate how-to.</p> <p>Short term storages also are operated less optimally in a rolling window model. There is a positive side to this as well, since perfect foresight linear optimization models are 'too optimal'. They don't reflect the forecast errors present in real life. So, a rolling window model might operate a bit more realistically than a single_solve model. A single_solve model can consider things happening far in the future when setting the storage level at present, even though in reality that information is not available. So, the total cost of a rolling_window model should always be higher than the total cost from a complete single_solve model that has perfect information.</p> <p>To set a dispatch rolling window model you need to set the object <code>solve</code> parameters:</p> <ul> <li><code>solve_mode</code>: rolling_window</li> <li><code>rolling_jump</code>: Hours, the desired length of the solve interval</li> <li><code>rolling_horizon</code>: Hours, the desired length of each roll solve</li> <li><code>rolling_duration</code>: (Optional) Hours, the length of the combined outputs. If not set, the whole timeline is used.</li> </ul> <p>Considerations on the rolling times:</p> <ul> <li>The <code>rolling_jump</code> and <code>rolling_horizon</code> must be large enough to make the model faster. If too small intervals are used, the creation of solves and moving data from solve to another might take too much time.</li> <li>If you are not using 1-hour timesteps, preferably use multiples of the timestep you are using as the <code>rolling_jump</code> and <code>rolling_horizon</code>. The steps included in each solve are calculated by summing the step durations until they are larger or equal to the hours given. So, if multiples are not used, the rolls might not be exactly the same size.</li> <li>The model can roll over timeblock and period jumps, which might cause some issues if storage constraints are used. Using timeblock length or its multiples is therefore recommended. For example, the <code>rolling_jump</code> could be a half of a timeblock and the <code>rolling_horizon</code> whole timeblock or <code>rolling_jump</code> a timeblock and <code>rolling_horizon</code> three timeblocks. Of course, when running e.g. a full year dispatch, there is only one timeblock of 8760 hours, which makes the choices more simple.</li> </ul> <p>Considerations on storage parameters:</p> <ul> <li><code>storage_solve_horizon_method</code> use_reference_value or use_reference_price are the preferred means to bind storage values. They can be used together with the <code>storage_state_start_end_method</code>: start, which would then set the initial storage state. These methods bind either the storage value or the storage price at the end of horizon (not the end of jump). This allows the storage to use the part of the horizon that is not output to improve the behaviour of the storage in the part that is output (as defined by <code>rolling_horizon</code> and <code>rolling_jump</code>). </li> <li><code>bind_within_timeblock</code> does not work correctly if the rolls don't include whole timeblocks. Instead, it will bind the first step of the roll (whatever it is) to the end of the timeblock. Do not use in nested solves if you are not using whole timeblocks or its multiples as <code>rolling_jump</code></li> <li>the same applies to the <code>bind_within_period</code> (but in relation to periods - do not use this unless you are <code>rolling_jump</code> is as long as a period or its multiples).</li> <li><code>storage_start_end_method</code> can be used to set the first timestep of the first roll and/or the last timestep of the last roll (in conjunction with <code>storage_state_start</code> and <code>storage_state_end</code>).</li> <li><code>bind_within_solve</code> binds the start state to the end state of each roll not the start and end of the whole model timeline. Use with caution (and probably best not to use together with <code>storage_solve_horizon_method</code> use_reference_value).</li> </ul>"},{"location":"how_to/#how-to-use-nested-rolling-window-solves-investments-and-long-term-storage","title":"How to use Nested Rolling window solves (investments and long-term storage)","text":"<p>The basic rolling solve can have problems in dealing with long term storage and with investments. If the model only sees a few weeks to the future, it really can't see how much energy should be stored in long term storages. Problems with investments can also be serious: If the first roll is really windy, the model would overinvest in wind power that is not profitable in the later rolls. Similarly, if the model is allowed to retire capacity, it might retire something that is actually needed in the later rolls. </p> <p>Nested solve sequences can first solve the investments and long-term storage levels and pass them to the dispatch solve. Both storage solve and dispatch solve can be rolling solves. The dispatch solves can then send the end storage values to the investment and long-term storage solves as start values to reduce the error of these solves.</p> <p>When to use nested solves?</p> <ul> <li>Dispatch model is taking too long to solve, but simple rolling window solve would not represent the long-term storages correctly. (Nesting without the investment solve)</li> <li>Investment model takes too long to solve, even with manual rolling How to create a multi-year model. With nesting you can have smaller rolls for dispatch solve than the investment solve. (Nesting without the storage solve)</li> <li>Investment model takes too long and you have long term storages to consider. (Three level nesting, graph below)</li> </ul> <p></p> <p>However, the obvious issue is that investment and storage solves cannot be solved using the old complete solve as it wouldn't make the solve time any shorter. Therefore, we need to decrease the information for investment and storage solves as well. There are a few options for this:</p> <ol> <li>Use lower resolution (longer timesteps). This can work quite well for a long-term storage.</li> <li>Use representative periods from the full timeline when performing investments. There is a large body of literature and methods on how to pick the representative weeks.</li> <li>Split the investment timeline (myopic investments) by manually creating a solve sequence for the investment solves like in: How to create a multi-year model section. This can be combined with the first or second option. </li> </ol> <p>Each of these have their pros and cons:</p> <ul> <li>Using the lower resolution can speed-up the model considerably, but it also means that everything that happens faster than the new timestep duration will be lost as the timestep varying parameters are averaged or summed for the new timestep. For example, consider a model with investment options to solar and storage. If the step duration is changed to 24 hours, the model won't invest in enough storage to mitigate the diurnal variation in PV. When these investments are then passed to the dispatch solve, the invested portfolio will have trouble meeting the demand.</li> <li>Using the sample can be effective if the sample is chosen well, but all the needs that are not in these samples are not included. The speed is heavily dependent on the number and size of those samples.</li> <li>Splitting the investment timeline for multi-year models can be seen as a relatively realistic approach, since investment decisions would have a lot of uncertainty in the longer time frame anyway.</li> </ul> <p>The investment decisions with less information are always less optimal than with complete solves. Therefore, when they are passed to the dispatch solve, it will in some cases cause penalties in the results when the invested portfolio is not sufficient to meet the demand at all times.</p> <p>The long term storage solve can be implemented using a lower resolution solve. The storage state values from the storage solves will be used to fix the storage value (or price) at the end of each dispatch solve. This means that on the last step of the roll (or the period), the storage quantity (or price) will have to match the quantity (or price) in the storage solve. The <code>rolling_jump</code> and <code>rolling_horizon</code> in the storage solve have to be longer than in the dispatch solve. You can set which storages are included as \"long term storages\" whose value will be transferred to the dispatch solve.</p> <p>To create a nested solve sequence, you need two or three <code>solve</code> objects. Either the investment solve or the storage solve can be left out. When using nested solve sequence, the sequence is not set with the <code>model</code>: <code>solves</code> parameter. Only the topmost solve is put there. Instead, the nested levels are set by the <code>solve</code> parameter <code>contains_solve</code>: solve_name. The investment solve is always on the top followed by the storage solve and dispatch solve:</p> <ul> <li>investment_solve <code>solve</code> parameter <code>contains_solve</code>: storage_solve_name </li> <li>storage_solve <code>solve</code> parameter <code>contains_solve</code>: dispatch_solve_name</li> </ul> <p>To create a storage solve:</p> <ul> <li><code>solve</code> parameter <code>fix_storage_period</code>: Array of periods where the storage values are fixed in the lower solve. Should be the same as <code>realized_periods</code> for the dispatch solve.</li> <li><code>node</code> parameter <code>storage_nested_fix_method</code>: fix_quantity or fix_price, includes this storage to be fixed. fix_price requires storage_state_reference_price to be set.</li> </ul> <p>To create an investment_solve:</p> <ul> <li><code>solve</code> parameter <code>invest_periods</code>: Array of periods where the model can invest.</li> <li><code>solve</code> parameter <code>realized_invest_periods</code>: Array of periods where the model will realize investment decisions to the lower solves and results.</li> <li><code>solve</code> parameter <code>realized_periods</code>: Should not be used in this solve! You don't want the dispatch results from this solve, but from the dispatch solve.</li> </ul> <p>In addition, the rolling dispatch solve should be created as in the How to use rolling window solve for dispatch. To set a dispatch rolling window model you need to set the object <code>solve</code> parameters:</p> <ul> <li><code>solve_mode</code>: rolling_window</li> <li><code>rolling_jump</code>: Hours, the desired length of the solve interval</li> <li><code>rolling_horizon</code>: Hours, the desired length of each roll solve</li> <li><code>rolling_duration</code>: (Optional) Hours, the length of the combined outputs. If not set, the whole timeline is used.</li> <li><code>realized_periods</code>: Array of periods that are realized</li> </ul> <p>The other model parameters apply to all of the solves. Therefore, the considerations of the storage value binding that were discussed in the How to use a rolling window for a dispatch model should be taken into account here as well.</p> <ul> <li>Storage levels can be fixed with <code>storage_solve_horizon_method</code>: use_reference_value or use_reference_price, these will fix the end of each horizon not each jump.</li> <li><code>storage_start_end_method</code> fixes the starts and/or ends of each solve level, meaning the first step of the first roll and the last step of the last roll.</li> <li>In most cases the <code>bind_storage_method</code> should be left as bind_forward_only</li> <li>Do not use <code>bind_within_timeblock</code> if you are not using full timeblock or its multiples as the <code>rolling_jump</code> in the dispatch model, otherwise you might cause an infeasible problem. </li> <li>Do not use <code>bind_within_period</code> if you are not using full periods or its multiples as the <code>rolling_jump</code> in the dispatch model, otherwise you might cause an infeasible problem. </li> <li>Do not use <code>bind_within_solve</code></li> </ul> <p>The recommended storage parameters with nested solves are: - <code>storage_start_end_method</code>: fix_start - <code>storage_solve_horizon_method</code>: fix_quantity - <code>storage_state_start</code> and <code>storage_state_reference_value</code>: use the same value</p> <p>This way the start and end states of the system are the same. Each end of the horizon (not the output) has that value as well, which keeps the model from emptying the storages at the end of the roll. In the dispatch solve, the fixed storage value from the storage solve overrides the horizon end value if a conflict exist. </p> <p>How to create the three lower information solve types for investment and storage solves discussed above?</p> <p>To create a lower resolution (longer timesteps) solve:</p> <ul> <li>Make a new <code>timeblockSet</code>, but use the same <code>timeline</code> and <code>block_duration</code> for it as with the high resolution solve</li> <li>Set <code>timeblockSet</code> parameter <code>new_stepduration</code>: Hours</li> <li>In the <code>solve</code> use this new <code>timeblockSet</code> in the <code>period_timeblockSet</code></li> </ul> <p>The model will create a new timeline for this solve with the <code>new_stepduration</code>. All the timestep map data like <code>inflow</code> or <code>profile</code> will be either summed or averaged for the new timeline. Again, the <code>new_stepduration</code> should be multiple of the old step duration. If the <code>block_duration</code> is not a multiple of the <code>new_stepduration</code> the last timestep will be shorter than the rest. </p> <p>Note that if the last timestep of the dispatch horizon is not in the storage solve timeline, it will use the last available timestep to fix the storage. This can happen at the end of the timeline when the dispatch solve with a lower step size can fit an extra step after the last time step of the storage solve. Other reason might be that both dispatch and storage solves are aggregated with the <code>new_stepduration</code>. In that case, it is usually best to use values for the <code>new_stepduration</code> that are dividable.  </p> <p>To create a sample solve with representative periods:</p> <p>The tutorial contains an example of representaive periods under alternative 5weeks where the year is represented with five sample weeks. It is done with the <code>timeblockSet</code> parameter <code>block_duration</code> where instead of choosing the whole timeline by setting the first timestep and the duration of whole timeline, you choose multiple starting points with smaller durations. The example for the 5weeks is below.</p> <p></p> <p>To create an investment solve sequence, you have two options:</p> <ul> <li>Create manually a series of solves and set the <code>invest_periods</code> and <code>realized_invest_periods</code> individually for the solves. How to create a multi-year model has an example of this with the difference that here you use <code>realized_invest_periods</code> instead of <code>realized_periods</code> and that each of the higher level solves requires the <code>contains_solve</code> parameter. </li> </ul> <p>If you have many splits, this option can get tedious and prone to mistakes.</p> <p>The other option is to use only one investment <code>solve</code> object:</p> <ul> <li>The <code>invest_periods</code> and <code>realized_invest_periods</code> should then be set with a 2D map where the first column tells the solve (you don't have to create separate <code>solve</code> objects for these) and the second column tells the period. To get a 2D map, choose the parameter type as Map and then right click the table and choose Insert column after/before. The value column does not matter. The model will generate these solves, with the periods given. Note that the solve names should match in both 2D-maps.  </li> </ul> <p>You can use the same lower level solve with each the investment solves as the lower level solves will exclude the periods that are not included in either of the upper level realized periods: <code>realized_invest_periods</code> or <code>fix_storage_periods</code>. So, the lower level solve should have all the periods that it is used for in any the solves.</p> <p></p> <p>Note that the results of a nested rolling solve run are not fully optimal, because the information in the model is decreased. This is the price you pay for the speed. Therefore, the results should not be taken as they are, instead it is important to know how to interpret the results: What phenomena are missing? How will they affect the results? Where should extra investments go to satisfy the demand (there is a possibility to use the <code>capacity_margin</code> method to force extra investments)?</p> <p>In the init.sqlite there are four example scenarios related to this:</p> <ul> <li>multi_fullYear_battery: The four period full year single solve, with coal, wind, battery storage with unlimited investment possibilities. Running this is still possible but takes a few minutes. This is here as a reference for the nested solves.</li> <li>multi_fullYear_battery_nested_24h_invest_one_solve: This has the nested structure and the investment solve is done with 24h timesteps and storage solve 6h timesteps.</li> <li>multi_fullYear_battery_nested_sample_invest_one_solve: This has the investment solve as 5weeks sample but all the four periods are included in the same investment solve. Nested structure with 6h storage solve timesteps.</li> <li>multi_fullYear_battery_nested_multi_invest: This has split the investment to four solves with each having two period 5weeks sample period horizon. Nested structure with 6h storage solve timesteps.</li> </ul> <p>The 24h timestep is clearly too long as it invests too little for storage and coal. A large upward penalty ensues.</p> <p>The sample one solve invest also invests too little, as the largest demand-supply ratio weeks are not in the five week sample. However, the investments are spread more accurately.</p> <p>The split sample investment run produces in this case similar results as the one solve sample run. This is not always the case! Here the only difference between the periods was linearly increased demand.  </p>"},{"location":"how_to/#how-to-use-stochastics-representing-uncertainty","title":"How to use stochastics (representing uncertainty)","text":"<p>(stochastics.sqlite)</p> <p>Stochastics are used to represent the uncertainty of the future in the decision making. The main idea of it is to connect multiple scenarios (branches) of the future to the realized timeline. The model then optimizes the system to get the minimize the total cost all the branches (weighted by their probability). Only the  realized timeline, shared between all branches, will be output. </p> <p>For the stochastics to have an effect on the results, the system needs parameters that change between the stochastic branches. These could be e.g. wind power generation or fuel prices. The model will then have separate variables in every branch for all the decision the model can take ((e.g. invesment, storage state, online, flow). As a consequence, the realization phase will also be dependent on the things that happen in the stochastic branches - weighted by the probablity given to each branch. </p> <p></p> <p>In this example, we show three ways to use stochastics: Single solve, rolling horizon and multiperiod single solve. They all share the same test system that includes: </p> <ul> <li>A demand node </li> <li>Coal, gas and wind power plants </li> <li>Hydro power plant with a reservoir and a downriver nodes</li> </ul> <p>The demand and the downriver nodes have a constant negative inflow. Therefore, the hydro plant capacity is partly in use at all times. The varying timeseries are the wind profile and the water inflow the reservoir. The coal commodity is more expensive than the gas, so the system will try to use the reservoir water to minimize the usage of coal. This will be affected by the forecast of the wind and the forecast of the water inflow. These are the stochastic timeseries in these examples. </p> <p>You can have stochastics in multiple timeseries in the same solve, but these will have to share the branches. This means that for example if you have two wind plants with two different stochastic wind profiles with three branches (upper, mid and lower estimates) you need to think if it is best to use only three branches and put both of the upper estimates to the same 'upper' branch or should you use combinatorics to make nine branches. However, note that the tool will not do the combinatorics for you and the solving time will be heavily affected by extra branches. Consequently, the usual practice is to present all the stochastics using just e.g. three branches and consider the correlations between the stochastic parameters in the pre-processing of the input data.</p> <p>Notes about the storage options with stochastics:</p> <ul> <li> <p>The best options to use are:</p> </li> <li> <p><code>Storage_state_start_end_method</code>: fix_start or fix_start_end (and the their values)</p> </li> <li> <p><code>storage_solve_horizon_method</code>: fix_value or fix_price (and their values)</p> </li> <li> <p>Do not use any of the <code>storage_binding_methods</code>, they do not work correctly with stochastics (there is no unambigious end state that could circle back to the first time step). </p> </li> </ul> <p></p>"},{"location":"how_to/#single-solve-stochastics","title":"Single solve stochastics","text":"<p>(stochastics.sqlite scenario: 2_day_stochastic_dispatch)</p> <p>In this scenario, 24 hours are realized with an uncertain forecast for the next day. The timeblock length is therefore 48 hours and the branching will happen at the timestep t0025.  To set up a stochastic solve, we need three things: The stochastic branch information, the stochastic timeseries and choosing which parts of the model use stochastic timeseries.</p> <p>The information about the branches are set with the solve parameter <code>stochastic_branches</code>. This is a 4 dimensional map. (Edit -&gt; choose map -&gt; right click -&gt; add columns). The columns are: period, branch, analysis_time (starting time of the branch), realized (yes/no) and the value is the weight of the branch. Each starting time, including the first timestep, should have one and only one realized branch. This realized branch is used for the non-stochastic parts of the model with a stochastic timeseries. In this example we have three branches: mid, upper and lower representing the three wind forecasts. The weight will influence the relative weight of each branch in the objective function (model costs). The weights are normalized, so that the total weight is always one in each timestep.</p> <p>The stochastic wind timeseries are set with the same profile parameter <code>profile</code> but with a three dimensional map instead of the regular one dimesional map. The tool recognizes a stochastic timeseries from the dimensions of the data. The three dimensions are: branch, analysis_time and time. Here the realized part of the model (t0001-t0024) uses also the branch 'mid', which is one of the forecast branches as well. In the stochastic part, 'mid' is also set to be 'realized'. It is not actually realized (since the stochastic part is not realized), but it helps the model to choose which branch to use when there is no stochastic data available.</p> <p>The parts of the model that will use stochastic data is chosen with a group parameter <code>include_stochastics</code>. The units, nodes and connections that are added to this group use stochastic timeseries connected to them (if available). Here we add the unit wind_plant to this group. There is a possiblity that to have two wind plants with the same profile, but use the stochastics on only one of them. The other would then use only the realized branch.</p> <p>An option exists to output the stochastic horizons for debugging your system. This is done with the model parameter <code>output_horizon</code>. It will cause errors in the calculation of the cost in each solve (the costs of the unrealized branches will be included) so turn it off when you want the final results.</p> <p>If you change the weights of the stochastic branches, you should see the results change.</p> <p></p>"},{"location":"how_to/#rolling-horizon-stochastics","title":"Rolling horizon stochastics","text":"<p>(stochastics.sqlite scenario: 1_week_rolling_wind)</p> <p>In this scenario we extend the previous timeline to one week and roll through it one day at a time with additional three day stochastic horizon:</p> <p>solve: <code>rolling_solve_jump</code> = 24 and <code>rolling_solve_horizon</code> = 96. </p> <p>The stochastic data should be given so that it can serve the rolling structure: <code>rolling_solve_jump</code> dictates the duration of the initial non-stochastic part of the model horizon. This period needs only data for the 'realized' branch. The stochastic branches will begin only after that and need data only after <code>rolling_solve_jump</code> has been reached. So, for every 'analysis_time' there needs to be a time series in each stochastic branch that extends to the end of horizon (as defined by <code>rolling_solve_horizon</code>). The branches continue to the end of the horizon without branching again.</p> <p>For the solve parameter <code>stochastic_branches</code> this means analysis times (t0001, t0025, t0049, t0073, t0097, t0121 and t0145). t0001 is there only to tell which branch is the realized one.</p> <p>Otherwise there is no difference to the previous example.</p> <p></p> <p></p>"},{"location":"how_to/#multi-periodic-stochastics","title":"Multi periodic stochastics","text":"<p>(stochastics.sqlite scenario: 2_year_stochastic_invest)</p> <p>Here we solve investment run with one realized year and other year as the stochastic horizon. When using stochastics on multiple periods, they should not use the same timeblock as the stocastics are set for a timestep not (period, timestep). This means that the same value would be used for all the periods with this timestep. Instead use consecutive timeblocks from the same timeline. Here the first timeblock has timesteps t0001-t8760 and the second timeblock has the timesteps t8761-t17520.</p> <p>The <code>stochastic_branches</code> has one branching spot at the first timestep of the period2. This example uses the water inflow of the reservoir as the stochastic timeseries. If you run this scenario, you can see that it takes some time. When planning the stochastic data to be used, you should take into account that it will increase the solving time of the model significantly.</p> <p></p>"},{"location":"how_to/#how-to-use-cplex-as-the-solver","title":"How to use CPLEX as the solver","text":"<p>Using CPLEX requires that you have installed the software, have a licence for it and have added it to PATH or to the environment where you are using the FlexTool, so that the tool can find the solver.</p> <p>CPLEX is used when the solve parameter solver is set to 'cplex'. The tool passes the built optimization model to the CPLEX solver and converts the solution file to a filetype suitable for CPLEX. The solver will produce two additional files to the work directory: 'cplex.log' and 'flexModel3_cplex.sol'. The former is the logfile of the solver and the latter contains the solution in the CPLEX format.</p> <p>The tool uses Interactive Optimizer to pass the problem to the solver. The default command used:</p> <pre><code>cplex -c 'read flexModel3.mps' 'opt' 'write flexModel3_cplex.sol' 'quit'\n</code></pre> <p>Additional parameters:</p> <ul> <li><code>solver_precommand</code> creates a text in front of the cplex call. This is useful when dealing with floating licences. The command allows to call the licence server to reserve the licence for the duration of the cplex program with a command line argument.</li> <li><code>solver_arguments</code> is an array containing additional CPLEX solver commands</li> </ul> <p>With these parameters, the command line call is:</p> <pre><code>'solver_precommand' cplex -c 'read flexModel3.mps' 'solver_command1' 'solver_command2' ... 'solver_command_last' 'opt' 'write flexModel3_cplex.sol' 'quit'\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-aggregate-outputs","title":"How to create aggregate outputs","text":"<p>It is often desirable to output results that focus on particular aspects of the model. For example, it can be useful to output all flows going in and out of all electricity nodes without the corresponding flows for other energy carriers (e.g. fuels used to produce the electricity). And if the model is large, some of those flows could be aggregated (summed). </p> <p>The first aspect, choosing a group of nodes for which to output results for, is achieved by:</p> <ul> <li>creating or re-using a <code>group</code> (e.g. electricity)</li> <li>set the group's parameter output_node_flows to yes</li> <li>assigning all the relevant nodes to the group (using <code>group__node</code>, e.g. electricity__west)</li> </ul> <p>The second aspect, aggregating flows into one, is achieved by:</p> <ul> <li>creating or re-using a <code>group</code> (e.g. all_VRE)</li> <li>set the group's parameter output_aggregate_flows to yes</li> <li>assigning all flows that should be part of the group (using <code>group__unit__node</code> or <code>group__connection__node</code>, e.g. all_VRE__wind1__west)</li> </ul> <p>All flows that are part of a group that has output_aggregate_flows set to yes will then be output only as part of the aggregate in the <code>group</code> flow_t. In all other outputs, they will remain independent.</p> <p>\"How to database\" (aggregate_output.sqlite) aggregates results for the nodeA and nodeB. Both of the nodes have a wind power plant and nodeA has a coal power plant. The demand is divided to the electricity, heat and irrigiation needs. This means that,  besides an internal demand (inflow), both nodes output to the heat node while nodeA also outputs to the irrigation node. Additionally the nodes are connected to each other and the node_country_y1. The nodeA is connected to the node_country_x1 and nodeB is connected to the node_country_x2. </p> <p>For the sake of the example, we are only interested in the nodeA and nodeB. Therefore, <code>group</code> focus_nodes is created and the nodes are added to it with <code>group__node</code> relationships. To simplify the results, the flows from the two wind plants are aggregated as one. Same applies to the heat pumps. This is done by creating the <code>group</code>s wind_aggregated and heat_aggregated. The flows are added to the group with the <code>group_unit_node</code> relationship. </p> <p>Note that here the <code>node</code> has to be either nodeA or nodeB, not the heat node! E.g. the nodes from the wind_aggregated <code>group_unit_node</code> are tied to the nodes from the focus_nodes <code>group_node</code> only when they share same nodes (e.g. wind_aggregated__wind_plant_1__nodeA and focus_nodes__nodeA have nodeA in common). The <code>group_unit_node</code> can include other flows but only the ones that are have a node that is inside the focus_nodes group are included in the result table under the focus_nodes group.</p> <p>Connections are simplified by creating groups connections_country_x and connections_country_y and adding the relevant connections with <code>group_connection_node</code> relationship. Again the <code>node</code> has to be either nodeA or nodeB to be included in the results.</p> <p></p> <p>The focus_nodes group needs the parameter <code>output_node_flows</code>: yes and the unit and connection groups need the parameter <code>output_aggregate_flows</code>: yes. </p> <p></p> <p>The resulting table has the flows to the focus_nodes group from units and connections. Additionally, the internal losses of the group are calculated. These are the flows between the nodes of the group and the storage losses. Here the losses come from the connection between nodeA and nodeB. Additionally the possible slacks to balance the nodes are included.</p> <p></p>"},{"location":"how_to/#how-to-enabledisable-outputs","title":"How to enable/disable outputs","text":"<p>Some of the outputs are optional. Some of these optional outputs are output by default while some are not (see below). Removing outputs speeds up the post-processing of results. The user can enable/disable them by changing the following parameters of the <code>model</code> entity:</p> <ul> <li><code>output_node_balance_t</code>: Default: yes. Produces detailed inflows and outflows for all the nodes for all timesteps. Mainly useful to diagnose what is wrong with the model. </li> <li><code>output_connection__node__node_flow_t</code>: Default: yes. The flows between the nodes for each timestep.</li> <li><code>output_unit__node_flow_t</code>: Default, yes. The flows from units to the nodes for each timestep.</li> <li><code>output_ramp_envelope</code>: Default, no. Includes seven parameters that form the ramp room envelope. Shows the actual ramp as well as different levels of available ramping  capability in a given node - for both directions, upward and downward. The first level includes ramproom in all the units, except VRE. The second level adds ramping room in VRE units (typically only downward, unless they have been curtailed. Finally, the last level adds potential ramping capability in the connections, which reflects only the ramproom in the connections themselves - the units/nodes behind the connection may or may not have capability to provide that ramp. (Parameter node_ramp_t)</li> <li><code>output_connection_flow_separate</code>: Default, no. Produces the connection flows separately for both directions.</li> <li><code>output_unit__node_ramp_t</code>: Default, no. Produces the ramps of individual units for all timesteps.</li> <li><code>output_horizon</code>: Outputs the timesteps of the horizon outside the realized timesteps. Useful when constructing a stochastic model.</li> </ul> <p></p>"},{"location":"how_to/#how-to-make-the-flextool-run-faster","title":"How to make the Flextool run faster","text":"<p>The list below contains potential ways to decrease the run-time of FlexTool models.</p> <p>External changes (results will remain the same):</p> <ul> <li>Keep both the input database and Flextool on the same drive. If the database is on a different drive, it can slow the process. Avoid network drives.</li> <li>Try to ensure that there is sufficient memory available by closing other programs that use lot of memory. Linear optimization problems can require lot of memory.</li> <li>Use as fast computer as available. Both faster processors and more processors can decrease computation time.</li> </ul> <p>Model changes (results will remain the same):</p> <ul> <li>Disable outputs that you don't need. This will speed up the result processing. See: How to enable/disable outputs</li> <li>When using HiGHS solver: in your solve's parameters, you can set highs_presolve = on, and highs_parallel = on to speed up the optimisation. However, it can be better to turn HiGHS parallel off when executing multiple scnearios in parallel.</li> <li>Especially with MIP problems, considering using a commercial solver like CPLEX (license required). See: How to use CPLEX as the solver</li> </ul> <p>Model changes (results will be affected):</p> <ul> <li>Get rid of integer variables. Mixed integer programming can increase the solving time manyfold compared to the linear version especially if commercial solver is not available. MIP parameters are:</li> <li><code>transfer_method</code>: exact, change to reqular</li> <li><code>startup_method</code>: binary, change to linear</li> </ul> <p>Model changes (potentially large changes to the results --&gt; need to understand how the particular analysis will be affected):</p> <ul> <li>Use representative periods for investment decisions. See: How to create a multi-year model</li> <li>Split the timeline into parts. The solving time increases exponentially with the model size. Multiple smaller solves can be faster. Splitting is best done with Rolling window solve and Nested rolling solve. See: How to use a rolling window for a dispatch model, How to use Nested Rolling window solves (investments and long-term storage)</li> <li>Aggregate data. Technological: Combine power plants that are using the same technology. Spatial: Combine nodes. Temporal: Use longer timesteps.</li> </ul>"},{"location":"install_toolbox/","title":"Installing IRENA FlexTool - SpineToolbox","text":""},{"location":"install_toolbox/#installing-spine-toolbox-and-irena-flextool-on-a-local-computer","title":"Installing Spine Toolbox and IRENA FlexTool on a local computer","text":"<p>Follow video tutorial for installation here: Link to YouTube.</p> <ul> <li>Install Miniconda (or Anaconda)  [Can be ignored if already installed]</li> <li>Start Anaconda prompt</li> <li>Create new Python environment [Also possible to use existing, up-to-date, Spine Toolbox environment]</li> </ul> <pre><code>conda create -n flextool python=3.8\n</code></pre> <ul> <li>Activate the environment</li> </ul> <pre><code>conda activate flextool\n</code></pre> <ul> <li>Install Git to the environment [Also possible to use existing Git installation]</li> </ul> <pre><code>conda install git\n</code></pre> <ul> <li><code>cd</code> to a directory into which both FlexTool and Spine Toolbox will make their own folders</li> <li>Clone the FlexTool Git repository</li> </ul> <pre><code>git clone https://github.com/irena-flextool/flextool\n</code></pre> <p>Install Spine Toolbox [Can be skipped if using existing Toolbox environment]</p> <ul> <li>Clone the Toolbox repository</li> </ul> <pre><code>git clone https://github.com/Spine-project/Spine-Toolbox.git\n</code></pre> <ul> <li>cd to the freshly created folder</li> </ul> <pre><code>cd Spine-Toolbox\n</code></pre> <ul> <li>Make sure Pip is up-to-date</li> </ul> <pre><code>python -m pip install --upgrade pip\n</code></pre> <ul> <li>Install packages required by Toolbox</li> </ul> <pre><code>python -m pip install -r requirements.txt\n</code></pre> <p>In case of problems when installing Spine Toolbox, more instructions are available at: https://github.com/Spine-project/Spine-Toolbox#installation</p> <p>Generate databases from templates:</p> <ul> <li><code>cd</code> back to the flextool repository folder. Most likely:</li> </ul> <pre><code>cd ../flextool\n</code></pre> <ul> <li>Run update_flextool.py script. This will generate the Input_data.sqlite and Results.sqlite from their templates. These are not directly in the repository to avoid future overwrites. Update_flextool.py can also be used later when one wants to update the tool.  </li> </ul> <pre><code>python update_flextool.py\n</code></pre>"},{"location":"install_toolbox/#starting-irena-flextool-in-spine-toolbox","title":"Starting IRENA FlexTool in Spine Toolbox","text":"<ol> <li>Open a conda prompt.</li> <li> <p>Activate the environment</p> <p><code>conda activate flextool</code></p> </li> <li> <p>Launch Spine Toolbox</p> <p><code>python -m spinetoolbox</code></p> </li> <li> <p>Open FlexTool3 project in Spine Toolbox (Choose the flextool folder from File &gt; Open project dialog)</p> </li> </ol>"},{"location":"install_toolbox/#updating-irena-flextool","title":"Updating IRENA FlexTool","text":""},{"location":"install_toolbox/#updates-for-version-314-or-later","title":"Updates for version 3.1.4 or later:","text":"<ul> <li>Start anaconda/miniconda prompt</li> <li><code>conda activate flextool</code> (or whatever is your conda environment name for IRENA FlexTool)</li> </ul> <p>If using Spine Toolbox, start by updating Spine Toolbox:</p> <ul> <li>cd to the repository folder Spine-Toolbox, where you cloned it.  For example <code>cd C:\\Users\\YourUser\\Documents\\Spine-Toolbox</code></li> <li><code>git pull</code></li> <li><code>python -m pip install -U -r requirements.txt</code></li> <li>cd back to FlexTool directory, where you cloned it.  For example <code>cd C:\\Users\\YourUser\\Documents\\flextool</code></li> </ul> <p>Update IRENA FlexTool:</p> <ul> <li>cd to the FlexTool directory</li> <li><code>python update_flextool.py</code></li> <li>This will pull the new version of the tool as well as migrating the input databases to the new version without destroying the data. Making a backup copy of the input data is still a good practice. The input_data_template.sqlite should not be used directly but by making a copy of it. <ul> <li>The updated databases are: <ul> <li>The database chosen as the input data in the tool!!!</li> <li>init.sqlite</li> <li>input_data_template.sqlite</li> <li>time_settings_only.sqlite</li> <li>how to example databases</li> </ul> </li> </ul> </li> <li>If the git complains about merge conflicts, it is probably due to you modifying the template files. Use <code>git restore .</code>  and <code>git pull</code>. This will restore ALL the files downloaded from the repository to their original states. Then repeat <code>python update_flextool.py</code></li> <li> <p>The Results.sqlite will only get additive changes, as we do not want to destroy your data. This causes old parameter definitions to linger in the database. You can remove them by replacing the database with a copy of the Results_template.sqlite that is kept up to date.</p> </li> <li> <p>One can also migrate other input databases to the new version by calling:</p> <ul> <li><code>python migrate_database.py *absolute_path_to_database*</code> or</li> <li><code>python migrate_database.py database_name.sqlite</code> if in the main flextool folder</li> </ul> </li> </ul>"},{"location":"install_toolbox/#old-version-release-313-or-earlier","title":"Old version (release 3.1.3 or earlier):","text":"<p>Update of IRENA FlexTool to the latest version is done as follows:</p> <ul> <li>Start anaconda prompt</li> <li><code>conda activate flextool</code> (or whatever is your conda environment name for IRENA FlexTool)</li> <li>cd to the FlexTool directory</li> <li><code>git restore .</code> (THIS WILL DELETE YOUR LOCAL CHANGES TO THE FILES IN THE WORKFLOW. This will be improved in the future. Currently you can work around this by making your own input files (Excel or SQLite) and pointing the workflow items (Excel_input_data or Input_Data) to your own files instead of the input_data.sqlite or FlexTool_import_template.xlsx.) </li> <li><code>git pull</code> Then do the update_flextool discribed above to migrate the databases:</li> <li><code>python update_flextool.py</code></li> </ul>"},{"location":"install_web_interface/","title":"Installing IRENA FlexTool - Web interface","text":""},{"location":"install_web_interface/#installing-irena-flextool-with-a-web-server","title":"Installing IRENA FlexTool with a web server","text":"<p>Installation instructions are in the FlexTool web server repository: here. The browser interface is shown here.</p>"},{"location":"interface_overview/","title":"Overview of the interfaces to Flextool","text":"<ul> <li>Install a front-end: Install Spine Toolbox and run IRENA FlexTool as a Spine Toolbox project. This gives you the graphical user interface of Spine Toolbox. https://github.com/Spine-project/Spine-Toolbox. The interface and instructions to it are shown Toolbox interface</li> <li>Use a browser: IRENA FlexTool can be accessed with a web browser if you have an account for an IRENA FlexTool server. However, no public servers are available at the moment. The browser interface is introduced here.</li> <li>Local server: It is possible to setup a local server and then use a browser to access that server. See https://github.com/irena-flextool/flextool-web-interface</li> </ul>"},{"location":"reference/","title":"Main entities to define a power/energy system","text":"<p>Elemental entities (one dimensional):</p> <ul> <li><code>node</code>: maintain a balance between generation, consumption, transfers and storage state changes (nodes can also represent storages)</li> <li><code>unit</code>: power plants or other conversion devices that take one or more inputs and turn them into one or more outputs</li> <li><code>connection</code>: transmission lines or other transfer connections between nodes</li> <li><code>commodity</code>: fuels or other commodities that are either purchased or sold at a price outside of the model scope</li> <li><code>profile</code>: timeseries that can be used to constraint the behaviour of units, connections or storages</li> <li><code>reserve</code>: reserve categories to withhold capacity to cope with issues outside of model scope</li> </ul> <p>Entities with two or more dimensions:</p> <ul> <li><code>unit__inputNode</code> and <code>unit__outputNode</code>: defines the inputs, outputs and their properties for the conversion units</li> <li><code>connection__node__node</code>: defines which nodes a connection will connect</li> <li><code>unit__node__profile</code> and <code>connection__profile</code>: defines a profile limit (upper, lower or fixed) for an energy flow</li> <li><code>node__profile</code>: defines a profile limit (upper, lower, or fixed) for the storage state of the node</li> <li><code>commodity__node</code>: defines if a node is a source or sink for a commodity</li> <li><code>reserve__upDown__unit__node</code> and <code>reserve__upDown__connection__node</code>: reserve capacity from a source to the target node</li> </ul> <p>See below for more detailed explanations.</p> <p></p>"},{"location":"reference/#how-to-define-the-temporal-properties-of-the-model","title":"How to define the temporal properties of the model","text":""},{"location":"reference/#timesteps-and-periods","title":"Timesteps and periods","text":"<p>FlexTool has two different kinds of time varying parameters. The first one represents a regular timeline based on timesteps. The duration of each timestep can be defined by the user. There can be multiple timelines in the database - the user needs to define which timeline to use (and what parts of the timeline should be used, as will be explained later). The timestep names in the timeline are defined by the user - they can be abstract like 't0001' or follow a datetime format of choice. However, the timestep names between different timelines must remain unique (usually there should be only one timeline in a database and therefore no issues).</p> <p>The second time varying dimension is <code>period</code>, which is typically used to depict assumptions about the future. One model can include multiple <code>solves</code> that the model will solve in sequence (to allow multi-stage modelling). Each solve can include multiple <code>periods</code> (so that the user can change parameter values for different parts of the future).</p> <p>A parameter of particular type can be either constant/time-varying or constant/period-based. For example <code>inflow</code> is either a constant or time-varying, but it cannot be period-based.</p>"},{"location":"reference/#timeblocksets","title":"Timeblocksets","text":"<p>Timeblocks pick one or more sections from the <code>timeline</code> to form a <code>timeblockset</code>. Each timeblock defines a start and a duration. The aim of timeblocksets is to allow the modeller to create models with representative periods often used in the investment planning.</p>"},{"location":"reference/#definitions","title":"Definitions","text":"<ul> <li> <p><code>model</code>: model defines the sequence of solves to be performed (e.g. first an investment solve and then a dispatch solve)</p> </li> <li> <p>solves: sequence of solves in the model represented with an array of solve names.</p> </li> <li>discount_offset_investment: [years] Offset from the period (often year) start to the first payment of the investment cost annuity.</li> <li> <p>discount_offset_operations: [years] Offset from the period (often year) start to the payment of operational costs.</p> </li> <li> <p><code>solve</code>: each solve is built from an array of periods (e.g. one period for 2025 and another for 2030). Periods use timeblocksets to connect with a timeline.</p> </li> <li> <p>period_timeblockset: map of periods with associated timeblocks that will be included in the solve. Index: period name, value: timeblockSet name.</p> </li> <li>realized_periods: these are the periods the model will 'realize' - i.e., what periods will be reported in the results from this solve</li> <li>realized_invest_periods Array of the periods that will realize the investment decisions. If this is not defined when the invest_periods exist, the realized_periods are used to realize the invests as well</li> <li>invest_periods: array of periods where investements are allowed in this solve (applies only to objects that can be invested in)</li> <li>years_represented: Map to indicate how many years the period represents before the next period in the solve. Used for discounting. Can be below one (multiple periods in one year). Index: period, value: years.</li> <li>solver: choice of a solver ('highs'(default), 'glpsol', 'cplex' (requires a licence))</li> <li>highs_method: HiGHS solver method ('simplex' or 'ipm' which is interior point method). Should use 'choose' for MIP models, since 'simplex' and 'ipm' will not work.</li> <li>highs_parallel: HiGHS parallelises single solves or not ('on' or 'off'). It can be better to turn HiGHS parallel off when executing multiple scnearios in parallel.</li> <li>highs_presolve: HiGHS uses presolve ('on') or not ('off'). Can have a large impact on solution time when solves are large. </li> <li>solve_mode: a single solve or a set of rolling optimisation windows solved in a sequence </li> <li> <p>Rolling window parameters:</p> <ul> <li>rolling_solve_jump: Hours, (Required if rolling_window solve). Interval between the start points of the rolls. Also the output interval. This should be smaller than the horizon</li> <li>rolling_solve_horizon: Hours, (Required if rolling_window solve). The length of the horizon of the roll. How long into the future the roll sees. For an individual roll, horizon is the solve length and jump is the output length.</li> <li>rolling_duration: Hours, (Optional). Duration of rolling, if not stated, assumed to be the whole timeline of the solve</li> </ul> </li> <li> <p>Nested solve sequence parameters:</p> <ul> <li>contains_solve: Array of solves that are run with after this solve using the realized data of this solve. Read 'How to use Nested Rolling window solves (investments and long term storage)'</li> <li>fix_storage_periods: Array of periods where the last storage value of the long term storage node is passed to the contained solve as a target. (Defined using the node parameter <code>storage_nested_fix_method</code>)</li> </ul> </li> <li> <p>Stochastic parameters:</p> <ul> <li>stochastic_branches: 4D-map to set up the stochastic branches, their weights and to choose which of them are realized. See 'How to use stochastics' for more information.</li> </ul> </li> <li> <p>For commercial solvers:</p> <ul> <li>solver_precommand the commandline text in front of the call for the commercial (CPLEX) solver. For a possibility of reserving a floating licence for the duration of the solve</li> <li>solver_arguments Array of additional commands passed to the commercial solver. Made for setting optimization parameters.</li> </ul> </li> <li> <p><code>timeblockset</code>: timeblocksets are sets of timeblocks with a start (from timeline) and a duration (number of time steps)</p> </li> <li> <p>block_duration a map with index timestep_name that starts the timeblock and value that defines the duration of the block (how many timesteps)</p> </li> <li> <p>new_stepduration: Hours. Creates a new <code>timeline</code> from the old for this <code>timeblockSet</code> with this timestep duration. The new timeline will sum or average the other timeseries data like <code>profile</code> and <code>inflow</code> for the new timesteps. </p> </li> <li> <p><code>timeline</code>: continuous timeline with a user-defined duration for each timestep. Timelines are used by time series data.</p> </li> <li> <p>timestep_duration: a map with timestep_name as an index and duration as a value.</p> </li> <li> <p>timeline_duration_in_years Total duration of the timeline in years. Used to relate operational part of the model with the annualized part of the model.</p> </li> <li> <p><code>timeblockset__timeline</code>: defines which timeline object particular timeblockset is using.</p> </li> </ul>"},{"location":"reference/#nodes","title":"Nodes","text":""},{"location":"reference/#defining-how-the-node-functions","title":"Defining how the node functions","text":"<p>These parameters will define how the node will behave and use the data it is given (available choices are marked in italics):</p> <ul> <li><code>name</code> - unique name identifier (case sensitive)</li> <li><code>is_active</code> - is the model/node/unit active in a specific scenario: yes (if not defined, then not active)</li> <li><code>has_balance</code> - does the node maintain a balance for inputs and outputs: yes (if not defined, then balance is not maintained)</li> <li><code>has_storage</code> - does the node represent a storage and therefore have a state: yes (if not defined, then no storage)</li> <li><code>invest_method</code> - Choice of investment method: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>inflow_method</code> - choice how to treat inflow time series<ul> <li>use_original - does not scale the original time series (no value defaults here)</li> <li>no_inflow - ignores any inserted inflow time series</li> <li>scale_to_annual_flow - will scale the time series to match the <code>annual_flow</code> so that the sum of inflow is multiplied by 8760/<code>hours_in_solve</code></li> <li>scale_in_proprotion - calculates a scaling factor by dividing <code>annual_flow</code> with the sum of time series inflow (after it has been annualized using <code>timeline_duration_in_years</code>)</li> <li>scale_to_annual_and_peak_flow - scales the time series to match the 'annual_flow' target while transforming the time series to match the highest load with the 'peak_inflow'</li> </ul> </li> </ul> <p></p>"},{"location":"reference/#data-for-nodes","title":"Data for nodes","text":"<p>Input data is set with the following parameters:</p> <ul> <li><code>inflow</code> - [MWh] Inflow into the node (negative is outflow). Constant or time series.</li> <li><code>annual_flow</code> - [MWh] Annual flow in energy units (always positive, the sign of inflow defines in/out). Constant or period.</li> <li><code>existing</code> - [MWh] Existing storage capacity (requires <code>has_storage</code>). Constant.</li> <li><code>invest_cost</code> - [CUR/kWh] Investment cost for new storage capacity. Constant or period.</li> <li><code>salvage_value</code> - [CUR/kWh] Salvage value of the storage. Constant or period.</li> <li><code>lifetime</code> - [years] Life time of the storage unit represented by the node. Constant or period.</li> <li><code>interest_rate</code> - [unitless, e.g. 0.05 means 5%] Interest rate for investments. Constant or period.</li> <li><code>invest_max_total</code> - [MWh] Maximum storage investment over all solves. Constant.</li> <li><code>invest_max_period</code> - [MWh] Maximum storage investment for each period. Period.</li> <li><code>invest_min_total</code> - [MWh] Minimum storage investment over all solves. Constant.</li> <li><code>invest_min_period</code> - [MWh] Minimum storage investment for each period. Period.</li> <li><code>fixed_cost</code> - [CUR/kWh] Annual fixed cost for storage. Constant or period.</li> <li><code>penalty_up</code> - [CUR/MWh] Penalty cost for decreasing consumption in the node with a slack variable. Constant or time. Default value is 10 000, but this can be changed from the database.</li> <li><code>penalty_down</code> - [CUR/MWh] Penalty cost for increasing consumption in the node with a slack variable. Constant or time. Default value is 10 000, but this can be changed from the database.</li> <li><code>virtual_unitsize</code> - [MWh] Size of a single storage unit - used for integer investments (lumped investments). If not given, assumed from the existing storage capacity.</li> <li><code>self_discharge_loss</code> - [e.g. 0.01 means 1% every hour] Loss of stored energy over time. Constant or time.</li> <li><code>availablity</code> - [e.g. 0.9 means 90%] Fraction of capacity available for storage. Constant or time.</li> </ul>"},{"location":"reference/#using-nodes-as-storages","title":"Using nodes as storages","text":"<p>FlexTool manages storages through nodes. A regular node maintains an energy/material balance between all inputs and outputs (<code>has_balance</code> set to yes). A storage node includes an additional state variable, which means that the node can also use charging and discharging of the storage while maintaining the energy balance. A storage node is created by setting <code>has_storage</code> to yes and by adding storage capacity using the <code>existing</code> parameter and/or by letting the model invest in storage capacity (<code>invest_method</code>, <code>invest_cost</code>, <code>invest_max_period</code> and <code>invest_max_total</code> parameters).</p> <p>Since FlexTool allows different temporal structures (multi-periods, rolling optimization, etc.) there needs to be ways to define how the storages behave when the model timeline is not fully consequtive. By default, storages are forced to match start level to the end level within timeblocks. This is an acceptable setting for small storages that do not carry meaningful amounts of energy between longer time periods in the model.</p> <p>There are three methods associated with storage start and end values: <code>storage_binding_method</code>, <code>storage_start_end_method</code> and <code>storage_solve_horizon_method</code>. </p> <ul> <li>The most simple one of these is the <code>storage_start_end_method</code> and it overrides the other methods, since it forces the start and/or the end state of the storage to a predefined value based on the proportional parameters <code>storage_state_start</code> and <code>storage_state_end</code> (proportional means that the parameter needs to be set between 0-1 and will be scaled by the storage capacity in the model). These two parameters affect only the first and the last timesteps of the entire model (even when the model has more than one solve).</li> <li><code>storage_binding_method</code> states how the storage should behave over discontinuities in the model timeline. Model timeline can have jumps for three different reasons: timeblocks, periods, and solves. If <code>storage_binding_method</code> is bind_within_timeblock, then the storage has to match the state of the storage between the beginning and the end of each timeblock. In effect, storage_state_at_start_of_timeblock equals storage_state_at_end_of_timeblock plus charging minus discharging minus self_discharge_loss at the last timestep. Similarly, bind_within_period will force the start and end between periods, but it will treat the jumps between timeblocks as continuous from the storage perspective (the storage will continue from where it was at the end of the previous timeblock). bind_within_solve does effectively the same when there are multiple periods within one solve. bind_within_model (NOT IMPLEMENTED 19.3.2023) will extend the continuity to multiple solves and force the end state of the storage at the end of the last solve to match the beginning state of the storage at the start of the first solve. Finally, bind_forward_only will force continuity in the storage state over the whole model without forcing the end state to match the beginning state.</li> <li><code>storage_solve_horizon_method</code> is meant for models that roll forward between solves and have an overlapping temporal window between those solves (e.g. a model with 36 hour horizon rolls forward 24 hours at each solve - those 12 last hours will be overwritten by the next solve). In these cases, the end state of the storage will be replaced by the next solve, but it can be valuable to have some guidance for the end level of storage, since it will affect storage behaviour. There are three methods: free is the default and will simply let the model choose where the storage state ends (usually the storage will be emptied, since it would have no monetary value). use_reference_value will use the value set by <code>storage_state_reference_value</code> to force the end state in each solve to match the reference value. use_reference_price will give monetary value for the storage content at the end of the solve horizon set by the <code>storage_state_reference_price</code> parameter - the model is free to choose how much it stores at the end of horizon based on this monetary value.</li> </ul> <p>-Method hierarchy:</p> <ol> <li><code>storage_start_end_method</code></li> <li><code>storage_binding_method</code></li> <li><code>storage_solve_horizon_method</code></li> </ol> <p>-Meaning:</p> <ul> <li>The <code>storage_binding_method</code> is ignored (exeption bind_forward_only), if <code>storage_start_end_method</code> has the value fix_start_end,</li> <li>The <code>storage_solve_horizon_method</code> use_reference_value is ignored, if other storage state methods are used. Only exeptions are fix_start or bind_forward_only</li> </ul> <p>-Nested Parameters:</p> <ul> <li><code>storage_nested_fix_method</code>: Set this storage as a long term storage, which end state is passed to the lower level solves as a target. Fix_price requires <code>storage_state_reference_price</code></li> </ul>"},{"location":"reference/#units","title":"Units","text":"<p>Units convert energy (or matter) from one form to another (e.g. open cycle gas turbine), but the can also have multiple inputs and/or outputs (e.g. combined heat and power plant). The input nodes are defined with the relationship <code>unit--inputNode</code> while the output nodes are defined through the relationship <code>unit--outputNode</code>.</p>"},{"location":"reference/#defining-how-the-unit-functions","title":"Defining how the unit functions","text":"<ul> <li><code>is_active</code> to state the alternative where the unit becomes active</li> <li>'conversion_method' to define the way unit converts inputs to outputs </li> <li><code>startup_method</code> - Choice of startup method. 'Linear' startup means that the unit can start partially (anything between 0 and full capacity) but will face startup cost as well as minimum load limit based on the capacity started up. 'Binary' startup means that the unit is either off or fully on, but it is computationally more demanding than linearized startups.</li> <li><code>minimum_time_method</code> - Not functional yet. Choice between minimum up- and downtimes (, min_downtime, min_uptime, both)."},{"location":"reference/#main-data-items-for-units","title":"Main data items for units","text":"<ul> <li>Capacity: <code>existing</code> (and the investment and retirement parameters below)</li> <li>Technical: <code>efficiency</code>, <code>min_load</code>, <code>efficiency_at_min_load</code>, <code>min_uptime</code>, <code>min_downtime</code><ul> <li><code>min_load</code> - [0-1] Minimum load of the unit. Applies only if the unit has an online variable. With linear startups, it is the share of capacity started up. Constant or time.</li> </ul> </li> <li><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for flows from/to the unit. For online units, the online variable is multiplied by the availability. Constant or time.</li> <li>Economic: <code>startup_cost</code>, <code>fixed_cost</code> (fuel cost comes through the use of fuel commodities and other variable costs are defined for flows between unit and node, see below)</li> </ul>"},{"location":"reference/#investment-parameters-for-capacity-expansion","title":"Investment parameters for capacity expansion","text":"<ul> <li><code>invest_method</code> - Choice of investment method: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>lifetime_method</code> to choose how the investments behave after unit runs out of lifetime. Automatic reinvestment (reinvest_automatic - default) causes the model to keep the capacity until the end of model horizon and applies the annualized investment cost until the end of model horizon without further choice by the model. Choice of reinvestment (reinvest_choice) removes the capacity at the end of the lifetime and the model needs to decide how much new capacity is to be built. If there is a need to remove the possibility to invest after lifetime, then the investment limits can be used.</li> <li><code>invest_cost</code> - [CUR/kW] Investment cost for new capacity. Constant or period.</li> <li><code>salvage_value</code> - [CUR/kW] Salvage value of the unit capacity. Constant or period.</li> <li><code>lifetime</code> - [years] Lifetime of the unit. Constant or period.</li> <li><code>interest_rate</code> - [unitless, e.g. 0.05 means 5%] Interest rate for investments. Constant or period.</li> <li><code>invest_max_total</code> - [MW] Maximum capacity investment over all solves. Constant.</li> <li><code>invest_max_period</code> - [MW] Maximum capacity investment for each period. Period.</li> <li><code>invest_min_total</code> - [MW] Maximum capacity investment over all solves. Constant.</li> <li><code>invest_min_period</code> - [MW] Maximum capacity investment for each period. Period.</li> <li><code>retire_cost</code> - [CUR/kW] Retirement cost for new capacity. Constant or period.</li> <li><code>retire_max_total</code> - [MW] Maximum capacity retirement over all solves. Constant.</li> <li><code>retire_max_period</code> - [MW] Maximum capacity retirement for each period. Period.</li> <li><code>retire_min_total</code> - [MW] Minimum capacity retirement over all solves. Constant.</li> <li><code>retire_min_period</code> - [MW] Minimum capacity retirement for each period. Period.</li> <li><code>fixed_cost</code> - [CUR/kW] Annual fixed cost for capacity. Constant or period. </li> <li><code>virtual_unitsize</code> - [MWh] Size of a single unit - used for integer investments (lumped investments). If not given, assumed from the existing capacity.</li> </ul>"},{"location":"reference/#discount-calculations","title":"Discount calculations","text":"<p>Each asset that can be invested in should have <code>invest_cost</code>, <code>lifetime</code> and <code>interest_rate</code> parameters set and could have an optional <code>fixed_cost</code>. These are used to calculate the annuity of the investment. Annuity is used to annualize the investment cost, since FlexTool scales all costs (operational, investment and fixed) to annual level in order to make them comparable. Annuity is calculated as follows:</p> <p><code>invest_cost</code> * <code>interest_rate</code> / { 1 - [ 1 / ( 1 + <code>interest_rate</code> ) ] ^ <code>lifetime</code> } + <code>fixed_cost</code></p> <p>The next step is to consider discounting - future is valued less than the present. There is a model-wide assumption for the <code>discount_rate</code>. By default it is 0.05 (i.e. 5%), but it can be changed through the <code>discount_rate</code> parameter set for the flexTool <code>model</code> object. Discount factor for every period in the model is calculated from the <code>discount_rate</code> using the <code>years_represented</code> parameter of each <code>solve</code>, which how many years the period represents. Values for <code>years_represented</code> are used to calculate how many <code>years_from_solve_start</code> each year is. The formula is:</p> <p>[ 1 / ( 1 + <code>discount_rate</code> ) ] ^ <code>years_from_solve_start</code></p> <p>Operational costs are also discounted using the same <code>discount_rate</code>. However, with operational costs it is assumed that they take place on average at the middle of the year whereas investment costs are assumed to take place at the beginning of the year (they are available for the whole year). These can be tweaked with the <code>discount_offset_investments</code> and <code>discount_offset_operations</code> parameters (given in years). Please note that given this formulation, <code>invest_cost</code> should be the overnight built cost (as is typical in energy system modelling, the model does not assume any construction time - the financing costs of the construction period need to be included in your cost assumptions).</p> <p>The model has a model horizon based on the <code>years_represented</code> parameters. The model will not include discounted investment annuities after the model horizon (in other words, the investments are 'returned' at the end of the model horizon). Naturally also operational costs are included only until the end of the model horizon. </p> <p>Finally, the retirements work similar to investments using the same <code>discount_rate</code> and <code>interest_rate</code> parameters but with <code>salvage_value</code> as the benefit from retiring the unit.</p>"},{"location":"reference/#relationship-of-a-unit-to-a-node-and-determination-of-the-type-of-relationship","title":"Relationship of a unit to a node and determination of the type of relationship","text":"<ul> <li>If the unit\u2019s outputs are flowing into the node, the node acts as output for the unit.</li> <li>If the unit\u2019s inputs are flowing out of the node (into the unit), the node acts as input for the unit.</li> <li>Not all units necessary have both an input and an output node. E.g. VRE generators have only output nodes and their generation is driven by profiles</li> </ul>"},{"location":"reference/#properties-of-unit-inputnode-and-unit-outputnode-relationships","title":"Properties of unit--inputNode and unit--outputNode relationships","text":"<ul> <li><code>is_non_synchronous</code> - Chooses whether the unit is synchronously connected to this node.</li> <li><code>coefficient</code> - [factor] Coefficient to scale the output from a unit to a particular node. Can be used e.g. to change unit of measurement or to remove the flow by using zero as the coefficient (the flow variable can still be used in user constraints). Constant.</li> <li><code>other_operational_cost</code> - [CUR/MWh] Other operational variable costs for energy flows. Constant or time. </li> <li><code>inertia_constant</code> - [MWs/MW] Inertia constant for a synchronously connected unit to this node. Constant.</li> <li><code>ramp_method</code> - Choice of ramp method. 'ramp_limit' poses a limit on the speed of ramp. 'ramp_cost' poses a cost on ramping the flow (NOT FUNCTIONAL AS OF 19.3.2023).</li> <li><code>ramp_cost</code> - [CUR/MW] Cost of ramping the unit. Constant.</li> <li><code>ramp_speed_up</code> - [per unit / minute] Maximum ramp up speed. Constant.</li> <li><code>ramp_speed_down</code> - [per unit / minute] Maximum ramp down speed. Constant.</li> </ul>"},{"location":"reference/#units-constrained-by-profiles","title":"Units constrained by profiles","text":"<p>Some generators (e.g. VRE) are not converting energy from one node to the other. Instead, their generation is determined (or limited) by a specific generation profile set by a <code>profile</code> object with a <code>profile_method</code>, thats state whether the profile forces an upper_limit, lower_limit or equality. Finally <code>profile</code> object is given a <code>profile</code> time series (or it can also be a constant). One needs to use <code>node__profile</code>, <code>unit__node__profile</code> or <code>connection__profile</code> to apply the profile to specific energy flow (or storage state in the case of <code>node__profile</code>).</p>"},{"location":"reference/#connections","title":"Connections","text":"<p>Connections can transfer energy between two nodes. Parameters for the connection are defined in the <code>connection</code> object, but the two <code>nodes</code> it connects are defined by establishing a relationship between <code>connection--leftNode--rightNode</code>.</p>"},{"location":"reference/#defining-how-the-connection-functions","title":"Defining how the connection functions","text":"<ul> <li><code>is_active</code> to state the alternative where the connection becomes active</li> <li><code>transfer_method</code> to define the way the connection transfers energy between the nodes</li> <li><code>startup_method</code> where linear startup means that the unit can start partially (anything between 0 and full capacity) but will face startup cost as well as minimum load limit based on the capacity started up. binary startup means that the unit is either off or fully on, but it is computationally more demanding than linearized startups.</li> <li><code>invest_method</code> to define investment and retirement limits: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>lifetime_method</code> to choose how the investments behave after unit runs out of lifetime. Automatic reinvestment (reinvest_automatic - default) causes the model to keep the capacity until the end of model horizon and applies the annualized investment cost until the end of model horizon without further choice by the model. Choice of reinvestment (reinvest_choice) removes the capacity at the end of the lifetime and the model needs to decide how much new capacity is to be built. If there is a need to remove the possibility to invest after lifetime, then the investment limits can be used.</li> </ul>"},{"location":"reference/#main-data-items-for-connections","title":"Main data items for connections","text":"<ul> <li><code>existing</code> - [MW] Existing capacity. Constant.</li> <li><code>efficiency</code> - [factor, typically between 0-1] Efficiency of a connection. Constant or time.</li> <li><code>constraint_capacity_coefficient</code> - A map of coefficients (Index: constraint name, value: coefficient) to represent the participation of the connection capacity in user-defined constraints.  [(invest - divest variable) x coefficient] will be added to the left side of the constraint equation. Invest and divest variables are not multiplied by unitsize.</li> <li><code>other_operational_cost</code> - [CUR/MWh] Other operational variable cost for trasferring over the connection. Constant or time.</li> <li><code>fixed_cost</code> - [CUR/kW] Annual fixed cost. Constant or period.</li> <li><code>invest_cost</code> - [CUR/kW] Investment cost for new 'virtual' capacity. Constant or period.</li> <li><code>interest_rate</code> - [e.g. 0.05 equals 5%] Interest rate for investments. Constant or period.</li> <li><code>lifetime</code> - [years] Used to calculate annuity together with interest rate. Constant or period.</li> <li>other investment parameters: <code>invest_max_total</code>, <code>invest_max_period</code>, <code>invest_min_total</code>, <code>invest_min_period</code>, <code>salvage_value</code></li> <li><code>is_DC</code> - A flag whether the connection is DC (the flow will not be counted as synchronous if there is a non_synchronous_limit). Default false.</li> <li><code>virtual_unitsize</code> - [MW] Size of single connection - used for integer (lumped) investments.</li> <li><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for connection flows. Constant or time.</li> </ul>"},{"location":"reference/#investment-parameters-for-connections","title":"Investment parameters for connections","text":"<p>These are the same as for units, see here</p>"},{"location":"reference/#commodities","title":"Commodities","text":"<p>Some <code>nodes</code> can act as a source or a sink of commodities instead of forcing a balance between inputs and outputs. To make that happen, commodities must have a <code>price</code> and be connected to those <code>nodes</code> that serve (or buy) that particular <code>commodity</code> at the given <code>price</code>. In other words, <code>commodity</code> is separate from <code>node</code> so that the user can use the same <code>commodity</code> properties for multiple nodes. Commodities can also have a <code>co2_content</code>. The <code>commodity</code> and its <code>nodes</code> are connected by establishin a new relationship between the <code>commodity</code> and each of its <code>nodes</code> (e.g. coal--coal_market).</p> <ul> <li><code>price</code> - [CUR/MWh or other unit] Price of the commodity. Constant or period.</li> <li><code>co2_content</code> - [CO2 ton per MWh] Constant.</li> </ul> <p></p>"},{"location":"reference/#groups","title":"Groups","text":"<p>Groups are used to make constraints that apply to a group of nodes, units and/or connections. A group is defined by creating a group object and then creating a relationship between the group and its members. The membership relationship classes are <code>group__node</code>, <code>group__unit</code>, <code>group__connection</code>, <code>group__unit__node</code>, <code>group__connection__node</code> and <code>reserve__upDown__group</code>. The choice of group members depends on what the group is trying to achieve. For instance a group that limits investments could have a set of <code>units</code> included in the group.</p>"},{"location":"reference/#capacity-limits-for-nodes-units-and-connections","title":"Capacity limits for nodes, units and connections","text":"<ul> <li><code>invest_method</code> - the choice of method how to limit or force investments in capacity [MW or MWh] of the group members</li> <li><code>invest_max_total</code> - [MW or MWh] Maximum investment to the virtual capacity of a group of units or to the storage capacity of a group of nodes. Total over all solves.</li> <li><code>invest_max_period</code> - [MW or MWh] Maximum investment per period to the virtual capacity of a group of units or to the storage capacity of a group of nodes.</li> <li><code>invest_min_total</code> - [MW or MWh] Minimum investment to the virtual capacity of a group of units or to the storage capacity of a group of nodes. Total over all solves. </li> <li><code>invest_min_period</code> - [MW or MWh] Minimum investment per period to the virtual capacity of a group of units or to the storage capacity of a group of nodes.</li> </ul>"},{"location":"reference/#cumulative-and-instant-flow-limits-for-unit__nodes-and-connection__nodes","title":"Cumulative and instant flow limits for <code>unit__node</code>s and <code>connection__node</code>s","text":"<ul> <li><code>max_cumulative_flow</code> - [MW] Limits the maximum cumulative flow for a group of connection_nodes and/or unit_nodes. It needs to be expressed as average flow, since the limit is multiplied by the model duration to get the cumulative limit (e.g. by 8760 if a single year is modelled). Applied for each solve. Constant or period.</li> <li><code>min_cumulative_flow</code> - [MW] Limits the minimum cumulative flow for a group of connection_nodes and/or unit_nodes. It needs to be expressed as average flow, since the limit is multiplied by the model duration to get the cumulative limit (e.g. by 8760 if a single year is modelled). Applied for each solve. Constant or period.</li> <li><code>max_instant_flow</code> - [MW] Maximum instantenous flow for the aggregated flow of all group members. Constant or period.</li> <li><code>min_instant_flow</code> - [MW] Minimum instantenous flow for the aggregated flow of all group members. Constant or period.</li> </ul>"},{"location":"reference/#limits-for-nodes","title":"Limits for nodes","text":"<ul> <li><code>has_inertia</code> - A flag whether the group of nodes has an inertia constraint active.</li> <li><code>inertia_limit</code> - [MWs] Minimum for synchronous inertia in the group of nodes. Constant or period.</li> <li><code>penalty_inertia</code> - [CUR/MWs] Penalty for violating the inertia constraint. Constant or period.</li> <li><code>has_non_synchronous</code> - A flag whether the group of nodes has the non-synchronous share constraint active.</li> <li><code>non_synchronous_limit</code> - [share, e.g. 0.8 means 80%] The maximum share of non-synchronous generation in the node group. Constant or period.</li> <li><code>penalty_non_synchronous</code> - [CUR/MWh] Penalty for violating the non synchronous constraint. Constant or period.</li> <li><code>has_capacity_margin</code> - A flag whether the group of nodes has a capacity margin constraint in the investment mode.</li> <li><code>capacity_margin</code> - [MW] How much capacity a node group is required to have in addition to the peak net load in the investment time series. Used only by the investment mode. Constant or period.</li> <li><code>penalty_capacity_margin</code> - [CUR/MWh] Penalty for violating the capacity margin constraint. Constant or period.</li> <li><code>share_loss_of_load</code> - Force the upward slack of the nodes in this group to be equal or inflow (demand) weighted</li> </ul>"},{"location":"reference/#co2-costs-and-limits","title":"CO2 costs and limits","text":"<ul> <li><code>co2_method</code> - Choice of the CO2 method or a combination of methods: no_method, price, period, total, price_period, price_total, period_total, price_period_total.</li> <li><code>co2_price</code> [CUR/ton] CO2 price for a group of nodes. Constant or period.</li> <li><code>co2_max_period</code> [tCO2] Annualized maximum limit for emitted CO2 in each period.</li> <li><code>co2_max_total</code> [tCO2] Maximum limit for emitted CO2 in the whole solve.</li> </ul>"},{"location":"reference/#stochastics","title":"Stochastics","text":"<ul> <li><code>include_stochastics</code> Flag to choose if stochastic timeseries are to be used for the units/nodes/connections of this group </li> </ul>"},{"location":"reference/#controlling-outputs","title":"Controlling outputs","text":"<p>Some results are output for groups of nodes. This means that instead of getting output for each node separately, nodes can be grouped and the aggregated results can be examined. For example it can be helpful to group all electricity nodes and show their aggregated output.</p> <ul> <li><code>output_results</code> - A flag to output aggregated results for the group members.</li> <li><code>output_node_flows</code> - A flag to create a timewise result of the flows in and out of the group of nodes</li> <li><code>output_aggregate_flows</code> - A flag that to sum the process (group_unit_node / group_process_node) flows of this group in the result table created by <code>output_node_flows</code> to different group of nodes (group_node)</li> </ul> <p>Some of the outputs are optional. They can be removed to speed up the post-processing of results. The user can enable/disable them by changing parameters of the the <code>model</code> entity:</p> <ul> <li><code>output_node_balance_t</code>: Default: yes. Produces detailed inflows and outflows for all the nodes for all timesteps. Mainly useful to diagnose what is wrong with the model. </li> <li><code>output_connection__node__node_flow_t</code>: Default: yes. The flows between the nodes for each timestep.</li> <li><code>output_unit__node_flow_t</code>: Default, yes. The flows from units to the nodes for each timestep.</li> <li><code>output_ramp_envelope</code>: Default, no. Includes seven parameters that form the ramp room envelope. How much there is additional ramping capability in a given node. (Parameter node_ramp_t)</li> <li><code>output_connection_flow_separate</code>: Default, no. Produces the connection flows separately for both directions.</li> <li><code>output_unit__node_ramp_t</code>: Default, no. Produces the ramps of individual units for all timesteps.</li> </ul> <p>Additionally a model level option to exclude all node, connection and unit level outputs and only leave group and model level results. This will significantly increase the speed of importing data to the result database.</p> <ul> <li>model: <code>exclude_entity_outputs</code>: Default, no. Excludes results on node, unit and connection level, but preserves group level results</li> </ul> <p>A further option is to output everything from the model horizon. This changes the behaviour of a rolling model, since it would otherwise output only the realized part of the model horizon. This option will also output all variables from the stochastic branches when the model uses those. This option is useful for debugging and constructing stochastic/rolling model. Outputting the unrealized part of the model horizon will include unrealized costs in the cost calculations, so costs will be too high and this option should not be used for the final results.</p> <ul> <li>model: <code>output_horizon</code>: Default, no. Produces outputs for the model horizon after <code>rolling_solve_jump</code>.</li> </ul>"},{"location":"reference/#reserves","title":"Reserves","text":"<p>The user defines reserve categories through <code>reserve</code> object. Reserves are reservations of capacity (either upward or downward) and that capacity will not therefore be available for other use (flowing energy or commodities). There are three different ways how a reserve requirement can be calculated: timeseries, large_failure and dynamic. </p> <ul> <li>Timeseries requires that the user provides a pre-defined time series for the amount of reserve to be procured in each time step. </li> <li>Large_failure requires that the user defines the energy flows that could be the largest failure in the system. The highest possible failure (flow multiplied by <code>large_failure_ratio</code>) in each timestep will then set the reserve requirement for that timestep. </li> <li>Dynamic means that there is a requirement based on user chosen energy flows - each participating flow is multipled by <code>increase_reserve_ratio</code> and then summed to form the reserve requirement. This can be useful for covering variability within timesteps. Also demand variability can be included through <code>increase_reserve_ratio</code> parameter in <code>reserve__upDown__group</code> relationship.</li> </ul> <p>When the same reserve category (e.g. primary upward) has more than one of these (timeseries, large_failure and dynamic) in use, then the largest requirement will apply for that timestep. If they are separated into different reserves, then they need to be fulfilled separately.</p> <p>Reserve requirement is defined for groups of nodes. This means that multiple nodes can have a common reserve requirement (but it is also possible to make a group with only one node). One node can be in multiple groups and therefore subject to multiple overlapping reserve requirements. Only units can generate reserve, but connections can move reserve from one node to another (therefore, there is no impact if the nodes are in the same reserve group, but it can be useful to import reserve from outside the group).</p>"},{"location":"reference/#reserve-groups","title":"Reserve groups","text":"<p>For <code>reserve__upDown__group</code> relationships:</p> <ul> <li><code>reserve_method</code> - Choice of reserve method (timeseries, large_failure, dynamic or their combination).</li> <li><code>reservation</code> - [MWh] Amount of reserve required. Constant or time.</li> <li><code>reserve_penalty</code> - [\u20ac/MWh] Penalty cost for not fulfilling the reserve requirement.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve is increased by the sum of demands from the group members multiplied by this ratio. Constant.</li> </ul>"},{"location":"reference/#reserve-provision-by-units","title":"Reserve provision by units","text":"<p>For <code>reserve__upDown__unit__node</code> relationships:</p> <ul> <li><code>is_active</code> - Can the unit provide this reserve. Empty indicates not allowed. Use 'yes' to indicate true.</li> <li><code>max_share</code> - [factor] Maximum ratio for the transfer of reserve from the unit to the node. Constant.</li> <li><code>reliability</code> - [factor] The share of the reservation that is counted to reserves (sometimes reserve sources are not fully trusted). Constant.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve requirement is increased by the flow between the unit and the node multiplied by this ratio. Constant.</li> <li><code>large_failure_ratio</code> - [factor] Each unit using the N-1 failure method will have a separate constraint to require sufficient reserve to cover a failure of the unit generation (multiplied by this ratio). Constant.</li> </ul>"},{"location":"reference/#reserve-transfer-by-connections","title":"Reserve transfer by connections","text":"<p>For <code>reserve__upDown__connection__node</code> relationships:</p> <ul> <li><code>is_active</code> - Can the unit provide this reserve. Empty indicates not allowed. Use 'yes' to indicate true.</li> <li><code>max_share</code> - [factor] Maximum ratio for the transfer of reserve to this node. Constant.</li> <li><code>reliability</code> - [factor] The share of the reservation that is counted to reserves (sometimes reserve sources are not fully trusted). Constant.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve is increased by generation from this unit multiplied this ratio. Constant.</li> <li><code>large_failure_ratio</code> - [factor] Each connection using the N-1 failure method will have a separate constraint to require sufficient reserve to cover a failure of the connection (multiplied by this ratio). Constant.</li> </ul>"},{"location":"reference/#additional-objects-for-further-functionality","title":"Additional objects for further functionality","text":"<ul> <li><code>constraint</code>: to create user defined constraints between flow, state, and capacity variables (for nodes, units and connections)</li> </ul>"},{"location":"results/","title":"Results","text":"<p>FlexTool outputs results typical to a planning model or a scheduling model, but it also tries to highlight potential flexibility issues in the system. The outputs from the latest run are initially CSV files and can befound in the folder 'output'. File 'summary_solve.csv' can give a quick overview of potential issues in the solve - it is a diagnostic file. The other files are all numerical results and will be imported to a Spine database by the FlexTool workflow.</p> <ul> <li>Costs</li> <li>Prices</li> <li>Energy flows</li> <li>Energy balance in nodes</li> <li>Group results</li> <li>Capacity and investment results</li> <li>CO2 emissions</li> <li>Reserves</li> <li>Inertia and non-synchronous generation</li> <li>Ramps</li> <li>Slack and penalty values</li> </ul>"},{"location":"results/#costs","title":"Costs","text":"<ul> <li><code>model</code> object <code>cost_annualized</code> parameter - M[CUR] (millions of user chosen currency) includes annualized total cost as well as annualized costs divided into </li> <li>unit investment/retirement - M[CUR] cost of investing in unit capacity or benefits from salvaging unit capacity</li> <li>connection investment/retirement - M[CUR] cost of investing in connection capacity or benefits from salvaging connection capacity</li> <li>storage investment/retirement - M[CUR] cost of investing in storage capacity or benefits from salvaging storage capacity</li> <li>commodity - M[CUR] cost of unit using commodity inputs or benefit of selling commodities (negative value)</li> <li>CO2 - M[CUR] cost of CO2 emissions caused by unit using commodities with CO2 content</li> <li>variable cost - M[CUR] other variable operation and maintenance costs</li> <li>starts - M[CUR] start up costs</li> <li>upward penalty - M[CUR] cost of involuntary demand reduction</li> <li>downward penalty - M[CUR] cost of involuntary demand increase</li> <li>inertia penalty - M[CUR] cost of not meeting the inertia constraint</li> <li>non-synchronous penalty - M[CUR] cost of not meeting the non-synchronous constraint</li> <li>capacity margin penalty - M[CUR] cost of not meeting the capacity margin constraint</li> <li>upward reserve penalty - M[CUR] cost of not meeting the upward reserve constraint</li> <li>downward reserve penalty - M[CUR] cost of not meeting the downward reserve constraint</li> <li><code>model</code> object <code>cost_t</code> parameter - M[CUR] similar as above but costs given for each timestep (no investment/retirement costs)</li> <li><code>model</code> object <code>cost_discounted_solve</code> paramater - M[CUR] Costs for the solve considering discounting and years presented (scaled to all years presented). Divided like in <code>cost_annualized</code></li> <li><code>model</code> object <code>cost_discounted_total</code> parameter - M[CUR] Total costs for all the solves considering discounting and years presented (scaled to all years presented). Divided like in <code>cost_annualized</code></li> </ul>"},{"location":"results/#prices","title":"Prices","text":"<ul> <li><code>node</code> object <code>price_t</code> parameter - [CUR/MWh] each node that maintains an energy balance provides a price time series based on the marginal value of the balance constraint</li> </ul>"},{"location":"results/#energy-flows","title":"Energy flows","text":"<ul> <li><code>unit__node</code> relationship <code>flow_annualized</code> parameter - [MWh] cumulative flow from the node (if node is input) or to the node (if node is output) annualized. Annualization scales the sum to correspond with full year time series.</li> <li><code>unit__node</code> relationship <code>flow_t</code> parameter - [MW] flow from the node (if node is input) or to the node (if node is output)</li> <li><code>connection__node__node</code> relationship <code>flow_annualized</code> parameter - [MWh] cumulative flow through the connection (left to right is positive) annualized</li> <li><code>connection__node__node</code> relationship <code>flow_t</code> parameter - [MW] flow through the connection (left to right is positive)</li> </ul>"},{"location":"results/#optional-output-output_connetion_flows_separate","title":"Optional output: output_connetion_flows_separate","text":"<ul> <li><code>connection__node__node</code> relationship <code>flow_to_first_node_annualized</code> parameter - [MWh] annualized cumulative flow through the connection only to the left (first) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_second_node_annualized</code> parameter - [MWh] annualized cumulative flow through the connection only to the right (second) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_first_node_t</code> parameter - [MW] flow through the connection to the left (first) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_second_node_t</code> parameter - [MW] flow through the connection to the right (second) node.</li> </ul>"},{"location":"results/#capacity-factors","title":"Capacity factors","text":"<ul> <li><code>unit__node</code> relationship <code>cf</code> parameter - [per unit] average capacity factor of the flow, i.e. the utilization rate of the flow from/to the unit. Average of flow [MWh/h] divided by capacity [MW] of the input or output to the unit.</li> <li><code>connection</code> relationship <code>cf</code> parameter - [per unit] average capacity factor of the flow, i.e. the utilization rate of the connection where flows in both directions are considered as utilization. Average of the absolute flow [MWh/h] divided by the capacity of the connection.</li> </ul>"},{"location":"results/#energy-balance-in-nodes","title":"Energy balance in nodes","text":"<ul> <li><code>node</code> object <code>balance</code> parameter - [MWh] cumulative inputs (positive) and outputs (negative) to the node from all the possible sources (from_units, from_connection, to_units, to_connections, state change over the period, self discharge during the period, upward slack for involuntary demand reduction and downward slack for involuntary demand increase)</li> <li><code>node</code> object <code>balance_t</code> parameter - [MW] same as above, but for each timestep</li> <li><code>node</code> object <code>state_t</code> parameter - [MWh] storage state of the node in each timestep</li> </ul>"},{"location":"results/#unit-online-and-startup","title":"Unit online and startup","text":"<ul> <li><code>unit</code> object <code>online_average</code> parameter - [count] average online status of the unit (average number of units online during the period)</li> <li><code>unit</code> object <code>online_t</code> parameter - [count] online status of the unit (number of units online in each timestep)</li> <li><code>unit</code> object <code>startup_cumulative</code> parameter - [count] cumulative number of unit startups during the period</li> </ul>"},{"location":"results/#unit-curtailment","title":"Unit curtailment","text":"<ul> <li><code>unit</code> object <code>curtailment_share</code> parameter - [0-1] Share of curtailed production from potential production for periods</li> <li><code>unit</code> object <code>curtailment_t</code> parameter - [MW] curtailed flow to the node</li> </ul>"},{"location":"results/#group-results","title":"Group results","text":"<ul> <li><code>group</code> object <code>indicator</code> parameter - gives a set of results for all <code>node</code> members of the <code>group</code></li> <li>sum of annualized inflows - [MWh] sum of <code>inflow</code> to the node which has been annualized (scaled to correspond to a year of timesteps)</li> <li>VRE share - [0-1] how much the flows from VRE sources (inputs using  'upper limit' profile) are of the inflow</li> <li>curtailed VRE share - [0-1] how much the unused flows from VRE sources would have been of the inflow</li> <li>upward slack share - [0-1] upward slack in relation to the inflow</li> <li>downward slack share - [0-1] downward slack in relation to the inflow</li> <li><code>group</code> object <code>flow_annualized</code> parameter - [MWh] produces grouped and annualized flow results of the <code>node</code> members of the <code>group</code></li> <li><code>group</code> object <code>flow_t</code> parameter - [MW] produces grouped flow results to the <code>node</code> members of the <code>group</code></li> <li><code>group</code> object <code>sum_flow_annualized</code> parameter [MWh] Annualized sum of flows in the group (members from group__connection__node and group__unit__node). Annualization scales the sum to correspond with full year time series.</li> <li><code>group</code> object <code>sum_flow_t</code> parameter [MW] Sum of flows in the group (members from group__connection__node and group__unit__node).</li> <li><code>group</code> object <code>VRE_share_t</code> parameter - [0-1]  how much the flows from VRE sources (inputs using  'upper limit' profile) are of the inflow for each timestep</li> </ul>"},{"location":"results/#capacity-and-investment-results","title":"Capacity and investment results","text":"<ul> <li><code>unit</code>, <code>connection</code> and <code>node</code> objects <code>capacity</code> parameter - [MW or MWh] include the following parameters</li> <li>existing - [MW or MWh] capacity that was assumed to exist in the beginning of the solve</li> <li>invested - [MW or MWh] capacity the model decided to invest for the given period</li> <li>retired - [MW or MWh] capacity the model decided to retire in the beginning of the given period</li> <li>total - [MW or MWh] sum of existing, invested and retired capacities</li> <li><code>unit</code>, <code>connection</code> and <code>node</code> objects <code>invest_marginal</code> parameter - [CUR/MW or MWh] marginal cost to invest in one more MW or MWh of capacity (zero value means that the model has invested in optimal amount; negative value means that if the model would be able to invest more, it could reduce total cost by the stated amount per MW or MWh; positive value means the cost is higher than the benefit by the stated amount per MW or MWh)</li> <li><code>group</code> parameter <code>slack_capacity_margin</code> - [MW or MWh] use of slack variable and the associated penalty cost to meet the capacity margin requirement in the period</li> <li><code>group</code> parameter <code>slack_capacity_margin</code> - use of slack variable and the associated penalty cost to meet the capacity margin requirement in the period</li> </ul>"},{"location":"results/#co2-emissions","title":"CO2 emissions","text":"<ul> <li><code>group</code> object <code>CO2_annualized</code> parameter - [Mt] how many million tons of CO2 annualized the units and connections in this group have generated (by using commodity with CO2 content) or removed.</li> <li><code>unit</code> object <code>CO2_annualized</code> parameter - [Mt] how many million tons of CO2 annualized the unit has generated (by using commodity with CO2 content) or removed</li> </ul>"},{"location":"results/#reserves","title":"Reserves","text":"<ul> <li><code>unit__reserve__upDown__node</code> relationship <code>reservation_t</code> parameter - [MW] how much upward or downward reserve particular unit was providing to a particular node in given timestep</li> <li><code>unit__reserve__upDown__node</code> relationship <code>reservation_average</code> parameter - [MW] how much upward or downward reserve particular unit was providing to a particular node in average during the period</li> <li><code>group__reserve__upDown</code> relationship <code>slack_reserve_t</code> parameter - [MW] use of slack variable and the associated penalty cost to fulfill the upward or downward reserve requirement in each timestep</li> <li><code>group__reserve__upDown</code> relationship <code>slack_reserve</code> parameter - [MW] cumulative use of slack variable and the associated penalty cost to fulfill the upward or downward reserve requirement during the period</li> </ul>"},{"location":"results/#inertia-and-non-synchronous-generation","title":"Inertia and non-synchronous generation","text":"<ul> <li><code>group</code> object <code>inertia_t</code> parameter - [MWs] the amount of inertia (MWs) in the group of nodes in each timestep</li> <li><code>group</code> object <code>slack_inertia_t</code> parameter - [MWs] use of slack variable and the associated penalty cost to fulfill the inertia requirement in each timestep</li> <li><code>group</code> object <code>slack_nonsync_t</code> parameter - [MWh] use of slack variable and the associated penalty cost to fulfill the non-synchronous share maximum share constraint in each timestep </li> </ul>"},{"location":"results/#ramps","title":"Ramps","text":"<ul> <li><code>node</code> object <code>ramp_t</code> parameter - includes seven parameters that form the ramp room envelope (how much there is additional room to ramp in a give node)</li> <li>ramp - [MW] the actual ramp in the node from previous timestep to this timestep</li> <li>units_up - [MW] additional room for upward ramps from non-VRE units connected to the node</li> <li>VRE_up - [MW] adds upward ramp room from VRE units on top of the ramp room from non-VRE units</li> <li>connections_up - [MW] adds upward ramp room from connections on top of the previous ramp rooms (does not consider whether the connected node has ramp room, but is simply the available capacity in the connection)</li> <li>units_down - [MW] additional room for downward ramps from non-VRE units connected to the node </li> <li>VRE_down - [MW] adds downward ramp room from VRE units on top of the ramp room from non-VRE units</li> <li>connections_down - [MW] adds downward ramp room from connections on top of the previous ramp rooms (does not consider whether the connected node has ramp room, but is simply the available capacity in the connection)</li> <li><code>unit__node</code> relationship <code>ramp_t</code> parameter - [MW] shows ramping of particular input or output flow between a unit and a node for each time step</li> </ul>"},{"location":"results/#slack-and-penalty-values","title":"Slack and penalty values","text":"<p>Slack and penalty values are listed in various places above (costs, energy balance, reserves, inertia and non-sychronous generation).</p>"},{"location":"spine_database/","title":"Data structure in Spine databases","text":"<p>Spine databases use Entity-Attribute-Value with Classes and Relationships (EAV-CR). Entity classes define the categories of data. These can be one-dimensional object classes (e.g. <code>node</code> or <code>unit</code>) or multi-dimensional relationship classes formed from the object classes (e.g. <code>unit__node</code>). Spine Toolbox user can define these classes to suit their modelling needs. For FlexTool the entity classes have been pre-defined. Instead, FlexTool user needs to add the entity instances: objects and relationships that define the particular network structure to be modelled (e.g. coal_plant <code>unit</code> or west <code>node</code>). Furthermore, each entity class (object or relationship) can hold only parameters that have been defined for that particular class. Again, FlexTool user does not need to add the parameter types - the user should just add needed parameter values for the entities the user has created.</p> <p></p>"},{"location":"spine_database/#database-editor-in-brief","title":"Database editor in brief","text":"<p>Spine Toolbox database editor can be used to modify data and to build scenarios.  The figure below shows an example where parameter data from two <code>alternatives</code>  have been selected for display (in the data table). The object tree on the left  selects two <code>nodes</code> ('coal_market' and 'west') as well as one <code>unit</code> ('coal_plant').  Consequently, one can use both whole classes and individual entities (members of the classes) as data filters. The results of this filter are visualized in the graph on top. The mouse pointer is showing a relationship  entity that connects the 'coal_plant' and its output <code>node</code> 'west'. The relationship  entity is defined in a relationship tree, which is not visible here.</p> <p>The <code>scenario</code> tree (on the right, below the <code>alternative</code> tree) shows that  the 'coal' <code>scenario</code> is formed by taking all data from the 'init' <code>alternative</code>  and then all data from the 'coal' <code>alternative</code>. If there would be same parameter  defined for both <code>scenarios</code>, then the latter <code>alternative</code> would overwrite  the first <code>alternative</code>.</p> <p>Whenever data is modified, the data is staged in separate database tables (although not directly visible to user). The changes will be applied only once the user <code>commits</code> the changes and leaves a commit message to indicate what has been done. The <code>commit</code> can be done with ctrl-enter or from the database editor menu (triple bar at top-right).</p> <p>The database editor menu has options for how to display the data: table view, different pivot views and a graph view. It also contains a tool to delete data (<code>purge</code>) and decrease database size by removing unused allocations (<code>vacuum</code>). You can also bring back dock windows that have been closed by the user. <code>History</code> will show the history of data changes based on the commits made by the user.</p> <p></p> <p>More on Spine Database editor in https://spine-toolbox.readthedocs.io/en/latest/spine_db_editor/index.html.</p>"},{"location":"spine_toolbox/","title":"IRENA FlexTool workflow shortly explained","text":"<p>IRENA FlexTool uses Spine Toolbox as a workflow and data manager. Open IRENA FlexTool with Spine Toolbox (Open project..., navigate to the IRENA FlexTool and choose Ok). In other words, the IRENA FlexTool repository contains a Spine Toolbox project (in '.spinetoolbox' folder). A regular user is supposed to only change data in the Input_data and Results data stores as well as to choose scenarios to be executed in the arrows leaving these data stores. It is also possible to create your own workflow from the components provided in the '.spinetoolbox/specifications' folder. First, create a new project (in a new, separate, folder) and then, using the '+ From file...' button in the Spine Toolbox toolbar, add the workflow components you want. In this way, you are free to modify the workflow without affecting the git-controlled workflow from the IRENA FlexTool repository (that is modified by the developers). Please note, that the new project will then be in a different folder than the tool specifications, which will remain in the IRENA FlexTool repository folder and can be updated through git.</p> <p>If you are using the IRENA FlexTool browser-interface, then you will not directly see the Spine Toolbox workflow, but the FlexTool web-server will be executing parts of the workflow in the background as you develop and run the model.</p> <p></p> <p>The panel on the right shows the different <code>scenarios</code> that are available in the database.  The user can choose which scenarios will be processed by the workflow (until item Results,  which combines the results into one database). Spine Toolbox can execute scenarios in parallel  (as long as using 'work directories' is defined in FlexTool item).</p> <p>Input data workflow item points to a sqlite file that needs to have IRENA FlexTool data format  (that uses Spine Toolbox database definition). The template file has the right format and contains empty object classes corresponding to FlexTool data structure as well as parameters available  in each object class. Double clicking the Input data workflow item will open the database editor.  Just selecting the Input data workflow item allows one to change the file (make a copy of the  existing Input_data.sqlite using the file system of your OS and point to the copy).</p> <p>Init workflow item points to a sqlite file with predefined data that showcases IRENA FlexTool  functionality. Some of the scenarios from there are used in the user guide. Initialize  copies the contents of the Init database to the Input data database. The scenario filter in the arrow after the Init database can be used to choose what data will be copied.</p> <p>Export_to_csv workflow item is a Spine Toolbox exporter that has been set to write csv files that IRENA FlexTool model code will read.</p> <p>FlexTool workflow item contains a Python script that calls FlexTool model code for each solve  and passes data between these solves. FlexTool model is written in MathProg and it calls HiGHS  solver by default to solve the model. The outputs are csv files.</p> <p>Import_results is a Spine Toolbox importer that takes the output csv files and writes them  in the Results database.</p> <p>Excel_input_data and Import_from_Excel allow users to use Excel as an interface for the input data.  They are optional parts of the workflow.</p> <p>To_Excel worfklow item will export most scenario results to a simple Excel file. One way to utilize  this is by creating another Excel file that draws figures from the result Excel file that is then updated by the workflow.</p> <p>The browser interface of FlexTool also runs part of this same workflow  (Export_to_csv --&gt; FlexTool --&gt; Import_results). The server takes a copy of the workflow (inside the user_projects)  folder and uses Spine Toolbox to execute the scenarios.</p> <p>More instructions for Spine Toolbox in Toolbox User Guide.</p>"},{"location":"spine_toolbox/#data-structure-in-spine-databases","title":"Data structure in Spine databases","text":"<p>Spine databases use Entity-Attribute-Value with Classes and Relationships (EAV-CR). Entity classes define the categories of data. These can be one-dimensional object classes (e.g. <code>node</code> or <code>unit</code>) or multi-dimensional relationship classes formed from the object classes (e.g. <code>unit__node</code>). Spine Toolbox user can define these classes to suit their modelling needs. For FlexTool the entity classes have been pre-defined. Instead, FlexTool user needs to add the entity instances: objects and relationships that define the particular network structure to be modelled (e.g. coal_plant <code>unit</code> or west <code>node</code>). Furthermore, each entity class (object or relationship) can hold only parameters that have been defined for that particular class. Again, FlexTool user does not need to add the parameter types - the user should just add needed parameter values for the entities the user has created.</p> <p></p>"},{"location":"spine_toolbox/#database-editor-in-brief","title":"Database editor in brief","text":"<p>Spine Toolbox database editor can be used to modify data and to build scenarios.  The figure below shows an example where parameter data from two <code>alternatives</code>  have been selected for display (in the data table). The object tree on the left  selects two <code>nodes</code> ('coal_market' and 'west') as well as one <code>unit</code> ('coal_plant').  Consequently, one can use both whole classes and individual entities (members of the classes) as data filters. The results of this filter are visualized in the graph on top. The mouse pointer is showing a relationship  entity that connects the 'coal_plant' and its output <code>node</code> 'west'. The relationship  entity is defined in a relationship tree, which is not visible here.</p> <p>The <code>scenario</code> tree (on the right, below the <code>alternative</code> tree) shows that  the 'coal' <code>scenario</code> is formed by taking all data from the 'init' <code>alternative</code>  and then all data from the 'coal' <code>alternative</code>. If there would be same parameter  defined for both <code>scenarios</code>, then the latter <code>alternative</code> would overwrite  the first <code>alternative</code>.</p> <p>Whenever data is modified, the data is staged in separate database tables (although not directly visible to user). The changes will be applied only once the user <code>commits</code> the changes and leaves a commit message to indicate what has been done. The <code>commit</code> can be done with ctrl-enter or from the database editor menu (triple bar at top-right).</p> <p>The database editor menu has options for how to display the data: table view, different pivot views and a graph view. It also contains a tool to delete data (<code>purge</code>) and decrease database size by removing unused allocations (<code>vacuum</code>). You can also bring back dock windows that have been closed by the user. <code>History</code> will show the history of data changes based on the commits made by the user.</p> <p></p> <p>More on Spine Database editor in Database Editor User Guide.</p>"},{"location":"tutorial/","title":"IRENA FlexTool tutorial","text":"<p>The instructions for installing IRENA FlexTool are at Interface overview.</p> <p>This user guide will build a small system step-by-step. It assumes you will be using Spine Toolbox as the front-end. If you are using the IRENA FlexTool web-interface, the instructions still apply, but the example figures in this tutorial will not be as helpful. IRENA FlexTool concepts are explained in more depth at Model Parameters.  Video tutorial for Building a small test system can be watched here.</p> <p>This tutorial can be used in couple of different ways - the best way depends on your familiarity with energy system modelling. </p> <p>First, all users who are not familiar with the way FlexTool manages data using Spine Toolbox functionalities, should read the page on Spine Toolbox workflow</p> <p>If you are new to energy system modelling, it is probably best to try to build the test system yourself while following the tutorial. This will take time and you will have to look up many data items from the Init database, but it will also force you to learn the concepts. You can also copy-paste data from the Init database to the Input data database when writing the data becomes too tedious. Before you start, it can be a good idea to to check the Essential objects for defining a power/energy system from the beginning of the FlexTool reference page to get an initial understanding of the concepts that will then grow as you learn more. </p> <p>If you have experience in using other types of energy system models - or perhaps older versions of FlexTool - it can be sufficient to follow the tutorial while also browsing the Init database using the database editor. Finding the entity classes, entities, and parameter values in the actual database will assist in the learning process. The concept reference page can also be useful.</p> <p>Finally, if you are a really experienced modeller, it can be enough to check the reference section starting from Essential objects for defining a power/energy system. </p>"},{"location":"tutorial/#building-a-small-test-system","title":"Building a small test system","text":"<p>The system contains three demand nodes, connections between them, a coal plant and a wind plant to provide the energy to the time varying demand. The system is run over a 48 hour timeline. </p> <p></p> <p>The small system to be built is also directly available in the FlexTool repository (Init SQLite database) and can be opened with the Spine Toolbox database editor. The default workflow for IRENA FlexTool executes the scenarios from the Input data database (and not from the Init SQLite database). The Input data database is empty by default. Therefore, if you want to use directly the contents of the Init database (instead of building the small system step-by-step), you need to copy them to the Input data database before running the scenarios in this tutorial. To copy the data, you need to execute the Initialize workflow item: select the item, press Execute selection from the toolbar.</p> <p>Remark: in case you had already populated the Input data database, you need to delete the data before importing from Init SQLite database. This can be done with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge.</p> <ul> <li>Building a small test system</li> <li>1st step - a node with no units</li> <li>2nd step - add a coal unit</li> <li>3rd step - add a wind power plant</li> <li>4th step - add a network</li> <li>More functionality</li> </ul>"},{"location":"tutorial/#choosing-the-database","title":"Choosing the database","text":"<p>You should have the FlexTool project open in the Spine Toolbox. For this tutorial a database time_settings_only.sqlite is provided in the Flextool folder. As the name suggests, it includes the basic time settings needed for running the tool. If you want to know how it is done or how to make your own time settings go to How-to-create-basic-time-settings. How to -section includes simple examples on specific parts of the system. You can explore it after the tutorial.</p> <p>First make a copy of the database and name it tutorial.sqlite. (In the future a new project should be started by copying time_settings_only.sqlite or the empty database input_data_template.sqlite. Use copy and rename, not directly! Otherwise the progress might be lost when updating the tool, as these databases are part of the repository). Then choose it to be the Input_data: </p>"},{"location":"tutorial/#1st-step-a-node-with-no-units","title":"1st step - a node with no units","text":"<p>Open the Input data database by double-clicking it in the Spine Toolbox workflow.</p> <p>The test system is built using <code>alternatives</code>. Alternative is a subset of the system than one can include to a <code>scenario</code> that is optimized by Flextool. For example when adding a wind plant, all the objects and relationships related to only the wind plant should be under their own alternative, so that the wind plant can be included or excluded form the <code>scenario</code> seamlessly.</p> <ul> <li>Each step will add a new <code>alternative</code>, and the data it contains, on top of the previous ones. </li> <li>The first <code>alternative</code> will be called west to hold the data for the first <code>node</code> in the model.</li> <li>The alternative is added in the 'Alternative tree' widget of the 'Spine Database Editor', see figure below.</li> </ul> <p></p> <p>Next step is to add an object for the first <code>node</code> that will be called west. </p> <ul> <li>Right-click on the <code>node</code> object class in the object tree to select 'Add objects'. </li> <li>Use the dialog to add the west <code>node</code> and click ok. See the figures below.</li> <li>Later other objects will need to be added in the same manner - as well as relationships between objects.</li> </ul> <p> </p> <p>Then, add parameter data to the newly minted west <code>node</code>: west node represents the demand in a part of the system.</p> <ul> <li>First add an <code>inflow</code> parameter with negative values to indicate negative inflow, i.e. demand. The <code>inflow</code> timeseries are given as a map-type parameter where the first column contains the names of the timesteps and the second column contains the inflow parameter value for that timestep. This is tedious to do by hand, so you can also copy-paste this from the init database.</li> <li>There are no electricity generating units and the demand cannot be met by ordinary means. The model will therefore use the upward slack variable and accept the <code>penalty_up</code> cost associated with it. This represents the cost of not fulfilling the demand. Also downward <code>penalty_down</code> is defined although the model is not using it at this stage. Here values of 9000 and 8000 are used respectively. By default the model uses the value 10 000 for these. Therefore, it is not mandatory to set them, but sometimes these values need to be changed, so understanding how they work is nessesary.</li> <li>Penalties and slack variables are tools of linear optimization. They ensure that the problem is feasable at all timesteps even when the in-out-balance of the nodes is violated. If no real penalty values are known, one should just use large enough numbers, so that the system won't prefer penalty to energy production. In the results, you can see at which timesteps the penalties are used.</li> <li>The parameter <code>has_balance</code> is related to this and should be set to yes. It forces the node to have a balance on inflow and outflow. If the demand is not fulfilled, balance is forced by the slack variable that will \"create\" the energy with the penalty associated with it. </li> <li>The west <code>node</code> needs to have a parameter called <code>is_active</code> with value yes. This chooses the west <code>node</code> and all its parameters to be sent to the model. </li> <li>All parameters here should be part of the west <code>alternative</code> (column alternative_name) - they will be used whenever a <code>scenario</code> includes the west <code>alternative</code>. </li> </ul> <p></p> <p>The new objects and parameters have now been staged. Even though it looks like they are in the database, they really are not - they need to be committed first. This can be done from the menu of the Database Editor (there is a commit command) or by pressing ctrl-enter. One should write an informative commit message about the changes that have been made. All commits, and the data they have affected, can be seen later from the history menu item.</p>"},{"location":"tutorial/#interlude-creating-a-scenario-and-running-the-model","title":"Interlude - creating a scenario and running the model","text":"<p>Even though the model is very simple and will not do anything interesting, it can be executed. It is first necessary to create the scenario to be executed. Scenarios are created from <code>alternatives</code> in the Scenario tree widget of the Database Editor. In the figure below, a <code>scenario</code> called Test-scenario is created that should contain <code>alternatives</code> west, init and init_2day-test in order to have both a node and a model structure included in the model. The new <code>scenario</code> must also be committed, before it can be used. A new scenario should be added after each step in the tutorial process. </p> <p></p> <p>Note that the order of the alternatives matters if there are conflicts between the alternatives. The alternatives lower down override the alternatives higher up on the list. In this example the init alternative has a full-year timeblock, but because the init_2day-test is lower in the scenario tree, the tool uses its <code>model</code>-flextool: solves parameter which points to the solve to be included in the model (2day-dispatch) and only it will be solved.</p> <p>Same logic will apply if you would add a parameter <code>inflow</code> with a value -100 to the west node in the alternative <code>init</code>. The model would use that instead of the previously set timeseries, because the <code>init</code> alternative is lower down in the alternative list of the scenario.</p> <p>Once the scenario has been committed to the database, it becomes available in the Spine Toolbox workflow. One can select scenarios to be executed from the arrow that leaves the Input data database. At this point, there will be only the Test-scenario available and should be selected. There is also a tool filter with FlexTool3 pre-selected. This selection needs to be present when running scenarios (it is used to filter the <code>is_active</code> entities into the scenario).</p> <p></p> <p>Next, we want to run three tools: Export_to_CSV (that will make input files suitable for FlexTool), FlexTool3 (which is a Python script that calls the FlexTool model generator for each solve) and Import_results (which will take output files from FlexTool and drop their contents to the Results database with a particular <code>alternative</code> name). First, select the three tools (select with left click while ctrl is pressed or draw an area with ctrl pressed, see figure below). Then, press Execute selection from the menu bar. The three items should be executed and if all goes well, then green check marks appear on each of the tool once it has finished. You can explore the outputs of each item by selecting the item and looking at the Console widget window.</p> <p> </p> <p>It is now possible to explore model results for the Test-scenario using either the Results database or the Excel file that can be exported by executing the To_Excel exporter tool. When doing that, no scenarios should be selected so that the tool will create one Excel file with data from all the alternatives that are in the results database (which will make more sense once there are more scenario results). The generated Excel file can be found by selecting the To_Excel tool and clicking on the folder icon on top-right of the Link properties widget window.</p> <p>By running the <code>Open_summary</code> tool, a quick summary csv file will open. This supports only runs with one scenario.</p>"},{"location":"tutorial/#2nd-step-add-a-coal-unit","title":"2nd step - add a coal unit","text":"<p>In the second step, a coal unit is added. </p> <ul> <li>The first thing is to add a new <code>alternative</code> coal so that all new data added in this step will become part of the coal <code>alternative</code>.</li> <li> <p>Then one needs to add the objects:</p> </li> <li> <p><code>unit</code> coal_plant</p> </li> <li><code>node</code> coal_market </li> <li> <p><code>commodity</code> coal</p> </li> <li> <p>And relationships:</p> </li> <li> <p><code>unit__inputNode</code> coal_plant, coal_market to indicate that the coal_plant is using inputs from the coal_market</p> </li> <li><code>unit__outputNode</code> coal_plant, west to indicate that the coal_plant will output electricity to the west node</li> <li> <p><code>commodity__node</code> coal, coal_market</p> </li> <li> <p>coal_plant needs the following parameters (all set for the coal alternative): </p> </li> <li> <p><code>efficiency</code> (e.g. 0.4 for 40% efficiency)</p> </li> <li><code>existing</code> to indicate the existing capacity in the coal_plant (e.g. 500 MW)</li> <li> <p><code>is_active</code> set to yes to include the coal_plant in the model</p> </li> <li> <p>coal <code>commodity</code> needs just one parameter for <code>price</code> (e.g. 20 \u20ac/MWh of fuel)</p> </li> <li>coal_market <code>node</code> needs to have <code>is_active</code> set to yes </li> <li>All these new parameters should be now part of the coal <code>alternative</code>. </li> </ul> <p></p> <p>To see how the results change due to the coal power plant, make a new scenario coal that has the <code>alternatives</code> init, init_2day-test, west and coal. Run the Export_to_CSV, FlexTool3 and Import_results to get the results to the Results database. If you start to get too many result <code>alternatives</code> in the Results database (e.g. if you happen to run the same scenario multiple times), you can delete old ones by removing the unwanted <code>alternatives</code> (right-click on the <code>alternative</code>) and then committing the database.</p>"},{"location":"tutorial/#interlude-visualizing-the-system-in-a-graph","title":"Interlude - visualizing the system in a graph","text":"<p>In Spine Toolbox, it is possible to visualize your system in a graph, which will show all objects, and the relationships between them. To open this visualization mode, open the Input data database. In the top right corner, click on the menu. Select Graph in the View section. You may visualize all objects by selecting root in the Object tree, or choose specifically the objects you want to display by selecting them in the Object tree (maintain ctrl to select multiple objects).</p> <p> </p>"},{"location":"tutorial/#3rd-step-add-a-wind-power-plant","title":"3rd step - add a wind power plant","text":"<p>Next, a wind power plant is added.</p> <ul> <li>Add a new <code>alternative</code> wind</li> <li> <p>Add objects:</p> </li> <li> <p><code>unit</code> wind_plant</p> </li> <li> <p><code>profile</code> wind_profile since wind_plant does not require a commodity, but instead uses a profile to limit the generation to the available wind.</p> </li> <li> <p>Add relationships:</p> </li> <li> <p><code>unit__node__profile</code> wind_plant, west, wind_profile</p> </li> <li> <p><code>unit__outputNode</code> wind_plant, west</p> </li> <li> <p>wind_plant needs the following parameters (all set for the wind alternative):</p> </li> <li> <p><code>conversion_method</code> to choose a method for the conversion process (in this case constant_efficiency)</p> </li> <li><code>efficiency</code> for wind_plant should be set to 1.</li> <li><code>existing</code> capacity can be set to 1000 MW</li> <li> <p><code>is_active</code> set to yes to include the wind_plant in the model</p> </li> <li> <p>wind_profile needs the the parameter <code>profile</code> with a map of values where each time step gets the maximum available capacity factor for that time step (see figure). Again, you can copy this from the init database.</p> </li> <li>wind_plant, west, wind_profile relationship needs a parameter <code>profile_method</code> with the choice upper_limit selected. This means that the wind_plant must generate at or below its capacity factor.</li> </ul> <p>You can now create a new scenario wind,  that has the <code>alternatives</code> init, west, coal and wind. Remember to commit, execute and have a look at the results (there should be no more penalty values used, since the coal and wind plant can together meet the demand in all hours).</p> <p></p>"},{"location":"tutorial/#4th-step-add-a-network","title":"4th step - add a network","text":"<p>A network <code>alternative</code> introduces </p> <ul> <li>two new <code>nodes</code> (east and north) </li> <li>three new <code>connections</code> between <code>nodes</code> (east_north, west_east and west_north). </li> </ul> <p>The new nodes are kept simple: </p> <ul> <li>they have a <code>is_active</code> parameter set to yes</li> <li>they have a <code>has_balance</code> parameter set to yes (to force the node to maintain an energy balance)</li> <li>they have a constant negative <code>inflow</code> (i.e. demand)</li> <li>penalty values for violating their energy balance</li> </ul> <p>The three connections have the following parameters:</p> <ul> <li>they have a <code>is_active</code> parameter set to yes</li> <li>they have a <code>existing</code> parameter to indicate the existing interconnection capacity between the nodes</li> <li>they have a <code>efficiency</code> parameter  (e.g. 0.9 for 90% efficiency).</li> </ul> <p>It is also necessary to create the relationships <code>connection__node__node</code> for east_north | east | north, west_north | west | north and west_east | west | east.</p> <p>The north <code>node</code> has the lowest upward penalty, so the model will prefer to use that whenever the coal and wind units cannot meet all the demand. Sometimes the <code>existing</code> capacity of the new <code>connections</code> will not be sufficient to carry all the needed power, since both generators are producing to the west <code>node</code>. Commit, execute and explore.</p> <p></p>"},{"location":"tutorial/#more-functionality","title":"More functionality","text":"<p>Now you have learned how to create a small model. Remember that you can change which database is used as the Input_data by clicking the tool icon. You can make a copy of the Results database if you want to keep them. The database can also be purged from previous results with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge. Purging by itself will not reduce the file size, you will have to <code>Vacuum</code> it to do this.</p> <p>More instructions on how to create individual parts of the model can be found in the How to section.</p> <p>You can also look and play with the ready scenarios from the init database. Purge Input_data and Initialize it to copy the init database to it. Purging is done the same way as above: This can be done with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge. Then select the initialize tool and run it to copy the init.sqlite to the input_data.sqlite.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>IRENA FlexTool is an energy systems optimisation model developed for power and energy systems with high shares of wind and solar power. It can be used to find cost-effective sources of flexibility across the energy system to mitigate the increasing variability arising from the power systems. It can perform multi-year capacity expansion as well as unit commitment and economic dispatch in a user-defined sequence of solves. The aim has been to make it fast to learn and easy to use while including lot of functionality especially in the time scales relevant for investment planning and operational scheduling of energy systems.</p>"},{"location":"#documentation-structure","title":"Documentation structure","text":"<ul> <li>You can find the installation instructions for IRENA FlexTool using Spine Toolbox as its interface (recommended in most cases): Install with Toolbox</li> <li>Follow video tutorial for installation with Spine Toolbox here: Link to YouTube</li> <li> <p>You can also use IRENA FlexTool with a web browser, but you will need to install a web server first: Install with web server</p> </li> <li> <p>If using FlexTool with Spine Toolbox, learn how the Spine Toolbox workflow functions: Spine Toolbox workflow.</p> </li> <li> <p>If using FlexTool with a web-browser, read how it works: Browser interface</p> </li> <li> <p>The tutorial is recommended for the new users of FlexTool: Tutorial</p> </li> <li>How-to section has examples on how to add specific features to a model: How to</li> <li>More advanced users can find the model parameter descriptions useful: Model parameters</li> <li>Finally, result parameters are documented here: Model results</li> </ul>"},{"location":"#monthly-user-support-telcos","title":"Monthly user support telcos","text":"<p>The monthly user support telco is held on the last Monday of each month at 12-13 UTC (skipping December and July). (Notice that time is according to UTC and in places where day-light saving time is applied, the time of the meeting may change between winter/summer) Each 1 h session starts with a ~15 min presentation on simple IRENA FlexTool demos or tutorials, followed by 45 min Q&amp;A session</p> <p>Teams link</p> <p>Please contact nelli.putkonen@vtt.fi for an Outlook calendar invitation</p>"},{"location":"#background-for-the-flextool-modelling-approach","title":"Background for the FlexTool modelling approach","text":"<p>The theory slides below give some background how FlexTool is formulated. There are also examples that show some ways how FlexTool can be used (including examples from other similar models). The slides were made for training in the OASES project (funded by LEAP-RE, project no: 963530, co-funding from European Commission and national funding agencies). The files can also be found in the folder docs/theory_slides.</p> <p>1: Energy planning and types of modelling approaches</p> <p>2: Modelling tools process and IRENA Flextool approach</p> <p>3: IRENA Flextool in practice</p> <p>4: Examples of studies done with IRENA Flextool approach</p>"},{"location":"browser_interface/","title":"Browser interface in brief","text":"<p>The browser interface connects to an instance of FlexTool web interface.  It can show and edit the same data as the Spine Toolbox. The workflow is not directly visible,  but it is executed in the background when models are run.</p> <p>The main page shows the projects available for the user.</p> <p></p> <p>The front page for the data editor shows all the data classes that can be shown and edited.  Different data classes can be opened to separate browser tabs for convenience.</p> <p></p> <p>Parameter data can be shown and edited once the user chooses an object and an alternative.</p> <p></p> <p>On the 'Run' page, the user can select and execute scenarios.</p> <p></p> <p>Finally, the results page shows the model outputs taken from the result database.  The results database can also be opened with Spine Toolbox for more control  over the shown data as well as export capabilities.</p> <p></p>"},{"location":"how_to/","title":"How-to","text":"<p>How-to section contains examples on how to include common energy system components in your model. The examples assume that you have sufficient understanding of FlexTool basics (e.g. by doing the tutorial). Each example will either include an example database file that is located in the 'how to examples databases' folder or the example is included in the init.sqlite as a scenario. If the example is in its own database, you can switch to that database by selecting the 'input' data store in the workflow and then changing the database by clicking the folder icon next to the current database file path in the 'Data store properties' widget. Navigate to the 'how to example databases' folder and choose the appropriate database.</p> <p>This section is divided into two parts: </p> <p>Building parts of the model:</p> <ul> <li>How to create basic temporal structures for your model</li> <li>How to create a PV, wind or run-of-river hydro power plant</li> <li>How to connect nodes in the same energy network</li> <li>How to set the demand in a node</li> <li>How to add a storage unit (battery)</li> <li>How to make investments (storage/unit)</li> <li>How to create combined heat and power (CHP)</li> <li>How to create a hydro reservoir</li> <li>How to create a hydro pump storage</li> <li>How to add a reserve</li> <li>How to add a minimum load, start-up and ramp</li> <li>How to add CO2 emissions, costs and limits</li> <li>How to create a non-synchronous limit</li> <li>How to see the VRE curtailment and VRE share results for a node</li> </ul> <p>Setting different solves:</p> <ul> <li>How to run solves in a sequence (investment + dispatch)</li> <li>How to create a multi-year model</li> <li>How to use a rolling window for a dispatch model</li> <li>How to use Nested Rolling window solves (investments and long-term storage)</li> <li>How to use stochastics (representing uncertainty)</li> </ul> <p>General:</p> <ul> <li>How to use CPLEX as the solver</li> <li>How to create aggregate outputs</li> <li>How to enable/disable outputs</li> <li>How to make the Flextool run faster</li> </ul>"},{"location":"how_to/#how-to-create-basic-temporal-structures-for-your-model","title":"How to create basic temporal structures for your model","text":"<p>(time_settings_only.sqlite)</p> <p>FlexTool allows to build models for different kinds of purposes and has therefore a flexible temporal structure, which requires some learning at first. To get you started, this how-to creates three different timelines: a full year, a 48h timeline and a timeline with five one-week periods to represent a full year. To be able to choose which of these are used in a given scenario, three alternatives are created: init, init_2day-test, init_5week-invest. </p> <p>The names of these alternatives hint at the intended use of each timeline. Even when you are building a large model with a long timeline, it is better to use a short 48 hour timeline for testing purposes when building the model. Using five one-week periods, i.e. \"a representative periods\", in an investment model is a method to reduce the model size and consequently solve time. More about that in How to run solves in a sequence (investment + dispatch)</p> <p></p> <p>To define a temporal structure for a model instance, you need to create the following objects and relationships:</p> <ul> <li><code>timeline</code> object called y2020 with a map-type parameter <code>timestep_duration</code> that defines the timeline the time series data in the model will need to use. It contains, in the first column, the name of each timestep (e.g. t0001 or 2022-01-01-01) and, in the second column, the length of the timestep in hours (e.g. 1.0). The timestep names here must match the timestep names in other time series like <code>inflow</code> or <code>profile</code>. Here all of the three options use the same full year timeline i.e. timesteps from t0001 to t8760 with a step size of one hour.</li> <li><code>timeblockset</code> objects called full-year, 2day and 5week. Each of them need a map-type parameter <code>block_duration</code> to define a time block using a timestep name to indicate where the timeblock starts and a number to define the duration of the timeblock in timesteps: (t0001, 8760) for the full-year and (t4001 and 48.0) for the 48h. The timeline is larger than the 48 hours, but this way the solver uses 48 hours specified. The 5week needs five starting points t2521, t4538, t5041, t7057 and t8233 with all having the length of 168.0</li> <li><code>timeblockset</code> needs to be connected to the timeline. This is done by adding the <code>timeblockset__timeline</code> relationships (full-year| y2020), (2day| y2020), (5weeks| y2020). From the <code>relationship tree</code> right-click on the <code>timeblockset__timeline</code> relationship class to 'Add relationships...'.</li> <li> <p><code>solve</code> objects called full-year-dispatch, 2day-dispatch and 5week-invest. In addition, they need the following parameters:</p> </li> <li> <p>a map-type parameter <code>period_timeblockSet</code> to define the timeblockset to be used by each period. Here each of the three use their <code>timeblockSet</code> to describe the same period p2020. The first column of the map has the period: p2020 and the second column the <code>timeblockSet</code>: full-year, 2day or 5week</p> </li> <li>an array-type parameter <code>realized_periods</code> to define the periods that are realised from the <code>solve</code> named by the object (the first column of an array is an index number starting with 0, the second column contains the period to be realized in the results: p2020 for all the solves here)</li> <li> <p>a parameter <code>solve_mode</code>, to be set to single_solve in these examples</p> </li> <li> <p>Finally, a <code>model</code> object will define the solves to be included in a one model instance. They are defined in the array parameter <code>solves</code>. For these examples, the model name is flextool and for each <code>solve</code> the name of the <code>solve</code> should be given in the <code>solves</code> array (distinguished by the alternative): full-year-dispatch, 2day-dispatch or 5week-invest.</p> </li> </ul> <p>Be careful when choosing datatypes! Maps need to be maps not arrays. (In the future, an update is coming to toolbox to ensure compliance.) </p> <p></p>"},{"location":"how_to/#how-to-create-a-pv-wind-or-run-of-river-hydro-power-plant","title":"How to create a PV, wind or run-of-river hydro power plant","text":"<p>(init.sqlite scenario: wind) init - west - wind</p> <p>These three power plant types don't use any commodities (i.e. fuels), but are instead dependant on a timeseries profile. To create these plants one needs an output node, an unit and a profile.</p> <p>The unit only needs parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: [The maximum capacity of the plant]  Additionally these parameters should be at their default values:</li> <li><code>conversion_method</code>: constant_efficiency</li> <li><code>efficiency</code>: 1</li> </ul> <p>The <code>profile</code> object only has one parameter: <code>profile</code>. It is a timeseries map which tells what fraction of the capacity the plant can produce at each timestep.</p> <p>The relationships </p> <ul> <li><code>unit__outputnode</code>: (plant|output node) and </li> <li><code>unit__node__profile</code>: (plant|output node|profile) need to be both created.</li> </ul> <p>The <code>unit__node__profile</code> relationship needs a parameter <code>profile_method</code> that has three options: <code>upper_limit</code>, <code>lower_limit</code> and <code>exact</code>. It states how the profile is considered. In most cases the <code>upper_limit</code> option should be used as it allows the plant to curtail the production if there is more supply than demand. Otherwise the output node might have to use <code>downward_penalty</code> to spill energy.</p> <p>The same profile can be used for multiple <code>unit__outputnode</code>s (and that is why the profile is not a unit parameter but its own entity).</p> <p></p>"},{"location":"how_to/#how-to-connect-nodes-in-the-same-energy-network","title":"How to connect nodes in the same energy network","text":"<p>(connections.sqlite)</p> <p>Typically nodes are used to maintain an energy balance and therefore they are used to represent a location with demand or a storage. The nodes can pass energy to each other through a connection entity. This is often an electricity connection but it can be any form of energy (or matter)  moving between two nodes. To create a connection one needs:</p> <ul> <li>two <code>nodes</code> </li> <li><code>connection</code></li> <li>relationship <code>connection__node__node</code> to tie these three together.</li> </ul> <p>The connection needs the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: The maximum capacity of the connection [MW]. Applies to both directions.</li> <li><code>efficiency</code>: represents the losses in transferring the energy. Same in both directions.</li> </ul> <p>Optional parameters:</p> <ul> <li><code>is_DC</code>: yes, flag if the connection is counted as non-synchronous for the possible non-synchronous limit. If <code>is_DC</code> (direct current) is yes, then the connection is non-synchronous. More at: How-to create a non-synchronous limit</li> <li><code>transfer_method</code>: Four options: regular (default), exact, variable_cost_only, no_losses_no_variable_cost. </li> </ul> <p>In most cases regular should be used. The downside of it is that it allows the flows to both directions at the same time, but the model does this only in specific circumstances when its beneficial to leak energy through the connection losses. For example, if connection capacity is 500 and efficiency 0.8, both nodes can send 500, but recive only 400 reducing the incoming energy by 100 in both nodes without any cost. Typically the model does not want to produce extra energy as it usually has costs, but it can happen if there is a cost to curtailing energy generation from a free source or if a unit is forced to generate at some level ('e.g. using <code>profile_method</code>: 'equal'). If <code>non-synchronous</code> constraint is used with a node using this connection, use exact instead as regular connections can circumvent this limit.</p> <p>Exact method does not allow flow in both directions at the same time, but it requires a binary variable, which will be computationally heavier (especially if the model would otherwise be fully linear). </p> <p>Variable_cost_only can be used when there are no losses associated with the flow. It allows costs related to the flow, but if losses are to be included, it should not be used.</p> <p>The no_losses_no_variable_cost can be used when the connection has no losses and no variable costs accociated with the flow. It is computationally the most efficient method, as it uses only one variable for the flow (the variable becomes negative for the other direction, but this can work only when there are no losses or variable costs). It also prevents simultanoues flow to both directions.</p> <p>The results of connections can be seen from the node_balance table. However, these are the results from all the connections connected to the node. If you want to have the results from an individual connection or specified connections, you can create a group of connection_nodes (<code>group_connection_node</code>) with a parameter <code>output_results</code> set to yes. This will produce sum_flow` results from the connection to the node. </p> <p>The example database shows a connection between a two node system where the other node has a wind power plant and the other node has a coal power plant. </p> <p></p>"},{"location":"how_to/#how-to-set-the-demand-in-a-node","title":"How to set the demand in a node","text":"<p>(demand.sqlite)</p> <p>The demand in a node is set with the inflow parameter. When the node is consuming energy or matter, the values should be negative and when the node is supplying energy (or matter) the values should be positive. The inflow parameter accepts two types of data:</p> <ul> <li>Constant</li> <li>Timeseries map</li> </ul> <p>If the model is using multiple periods, then the same timeseries profile is used for every period. However, the inflow can be scaled for different periods with the <code>inflow_method</code> parameter: - <code>scale_to_annual_flow</code>: This will multiply the demand with a constant to make the summed inflow to match the <code>annual_flow</code>. This requires the node parameter <code>annual_flow</code> that is a map of periods containing the annual flow for each period. The sum of inflows is divided by the period's share of the year (hours in period /8760) before scaling (so that the annual energy demand/supply matches the <code>annual_flow</code> no matter what parts of the year are used to represent the full year).  - <code>scale_in_proportion</code>: calculates a scaling factor by dividing <code>annual_flow</code> with the sum of time series inflow (after it has been annualized using <code>timeline_duration_in_years</code>). This does not force the demand/supply to match annual flow in case the representative periods are not representing the full year, but the time series will still be scaled to capture the proportional change in the <code>annual_flow</code> parameter.  - <code>scale_to_annual_and_peak_flow</code>: The inflow scaled so that the peak is at the given <code>peak_flow</code> and the inflow sums to annual flow of the period. This is done by the following equation:</p> <pre><code>new_inflow = (peak/peak_old)*(1+c)*old_inflow-peak*c\n\nwhere c = \n[(peak/peak_old)*(8760/hours_in_period)*sum(old_inflow) - annual_flow] \n/ [peak*8760 - (peak/peak_old)*(8760/hours_in_period)*sum(old_inflow)]\n</code></pre> <p>Examples of all these options are shown in the demand.sqlite.</p> <p></p>"},{"location":"how_to/#how-to-add-a-storage-unit-battery","title":"How to add a storage unit (battery)","text":"<p>(init.sqlite, scenario: wind_battery) init - west - wind - battery</p> <p>In the Init SQLite database, there is a <code>scenario</code> wind_battery. In the example, the wind_plant alone is not able to meet the load in all conditions, but the battery will help it to improve the situation.</p> <p>In FlexTool, only <code>nodes</code> can have storage. <code>Nodes</code> can therefore be demand nodes, storage nodes or both. To make a storage node one the required parameters are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>existing</code>: The maximum storage size of battery as the potential energy [MWh]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: a large number to prefer not creating energy from nowhere</li> </ul> <p>Additional parameters:</p> <ul> <li><code>self_discharge_loss</code> The fraction of energy loss in each hour.</li> </ul> <p>Storage states can be tied to a value. For this three methods are introduced:</p> <ul> <li><code>storage_start_end_method</code>: Fixes start and/or end state of the storage to a chosen value. This is for the start and the end of the whole model timeline (not for individual solves in case the model is rolling forward).<ul> <li><code>storage_state_start</code> and <code>storage_state_end</code> set these values.</li> </ul> </li> <li><code>storage_bind_method</code>: Forces the start and end values to be the same for the chosen  time interval (timeblock, period or solve)</li> <li><code>storage_solve_horizon_method</code>: Fixes the state of the storage at the end of the solve horizon or sets a price for the stored energy at the end of the solve horizon<ul> <li><code>storage_state_reference_value</code> and <code>storage_state_reference_price</code> set these values</li> </ul> </li> </ul> <p>Having multiple storage methods can create infeasible problems. This is why some of the combinations shouldn't (and cannot) be used at the same time. If multiple methods are used, some of them might be ignored by the method hierarchy. More information can be found from Model Parameters: Using nodes as storages. </p> <p>Battery also needs charging and discharging capabilities. These could be presented either with a <code>connection</code> or by having a charging <code>unit</code> and a discharging <code>unit</code>. In here, we are using a <code>connection</code> called battery_inverter. Please note that the <code>efficiency</code> parameter of the <code>connection</code> applies to both directions, so the round-trip <code>efficiency</code> will be <code>efficiency</code> squared.</p> <p>The <code>transfer_method</code> can be used by all types of connections, but in this case it is best to choose regular, which tries to avoid simultaneous charging and discharing, but can still do it when the model needs to dissipate energy. exact method would prevent that, but it would require integer variables and make the storage computationally much more expensive. Model leakage will be reported in the results (forthcoming).</p> <p>The required paremeters of the connection are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>existing</code>: The capacity of energy transsmission [MW]</li> <li><code>transfer_method</code>: (see above)</li> </ul> <p>Additional parameters:</p> <ul> <li><code>efficiency</code>: by default 1</li> </ul> <p>Finally <code>connection_node_node</code> relationship is needed between inverter, the battery and the demand node (west). </p> <p></p>"},{"location":"how_to/#how-to-make-investments-storageunit","title":"How to make investments (storage/unit)","text":"<p>(init.sqlite scenario: wind_battery_invest) init - west - wind - battery - battery_invest</p> <p>Here we will use the previous battery scenario to represent the investment options in the tool.</p> <p>The solve will invest only if it has an array of <code>invest_periods</code> set, telling the periods where it is allowed to make investment decisions. In a multi solve investment model (rolling investments) it can be useful to separately set <code>invest_realized_periods</code> so that the investment results get reported only from the chosen periods from each solve (in order to avoid overlapping reporting of investment decisions that are replaced by  investment decisions in later solves). Furthermore, <code>realized_periods</code> will define the solves and periods from which the dispatch results are output into results.</p> <p>First, the investment parameters need to be included both for the battery_inverter and battery objects:</p> <ul> <li> <p><code>invest_method</code> - the modeller has options to limit the investment and retirement. Options are not_allowed, invest, retire or invest and retire. These have the sub options of no limit invest_no_limit, limit the amount per period: invest_period, limit the total amount invested invest_total or limit both the total investment and the investment per period invest_period_total. </p> </li> <li> <p>If the investment is limited, it requires the corresponding maximum/minimum investment (power [MW] or energy [MWh]) to the virtual capacity. This can be set to individual entities or groups of entities:</p> <ul> <li><code>invest_max_total</code></li> <li><code>invest_max_period</code></li> <li><code>invest_min_total</code></li> <li><code>invest_min_period</code></li> <li><code>retire_max_total</code></li> <li><code>retire_max_period</code></li> <li><code>retire_min_total</code></li> <li><code>retire_min_period</code></li> </ul> </li> <li> <p><code>invest_cost</code> - overnight investment cost new capacity [currency/kW] for the battery_inverter and [currency/kWh] for the battery. Other one can be left empty or zero, since they will be tied together in the next phase. Here we will assume a fixed relation between kW and kWh for this battery technology, but for example flow batteries could have separate investments for storage and charging capacities.</p> </li> <li><code>interest_rate</code> - an interest rate [e.g. 0.05 means 5%] for the technology that is sufficient to cover capital costs. The chosen interest rate should reflect the assumption that in the model economic lifetime equals the technical lifetime.</li> <li><code>lifetime</code> - technical lifetime of the technology to calculate investment annuity (together with the interest rate)</li> </ul> <p>Additional parameters:</p> <ul> <li><code>lifetime_method</code>: Model can either be forced to reinvest when the lifetime ends <code>reinvest_automatic</code> or have a choice <code>reinvest_choice</code></li> <li><code>salvage_value</code>: Sets the extra value that can be gained for retiring [CUR/kW]</li> <li><code>fixed_cost</code>: Annual cost for capacity [CUR/kW]</li> </ul> <p>In many cases some of the investment decisions are tied to each other. Here the battery capacity and the connection capacity of the battery_inverter will be tied as they are simultaneously limited by the choice of the battery technology to be invested in. To model this, a new constraint needs to be created that ties together the storage capacity of the battery and the charging/discharging capacity of the battery_inverter. A new <code>constraint</code> object battery_tie_kW_kWh is created and it is given parameters <code>constant</code>, <code>is_active</code> and <code>sense</code>. Constant could be left out, since it is zero, but <code>is_active</code> must be defined in order to include the constraint in the battery_invest <code>alternative</code>. The <code>sense</code> of the constraint must be equal to enforce the kw/kWh relation.</p> <p>Both battery_inverter and battery need a coefficient to tell the model how they relate to each other. The equation has the capacity variables on the left side of the equation and the constant on the right side.</p> <pre><code>sum_i(`constraint_capacity_coefficient` * `invested_capacity`) = `constant` \n      where i is any unit, connection or node that is part of the constraint\n</code></pre> <p>When the <code>constraint_capacity_coefficient</code> for battery is set at 1 and for the battery_inverter at -8, then the equation will force battery_inverter <code>capacity</code> to be 8 times smaller than the battery <code>capacity</code>. The negative term can be arranged to the right side of the equation, which yields:</p> <p><code>1 x *battery* = 8 x *battery_inverter*, which can be true only if *battery_inverter* is 1/8 of *battery*</code></p> <p><code>constraint_capacity_coefficient</code> is not a parameter with a single value, but a map type parameter (index: constraint name, value: coefficient). It allows the object to participate in multiple constraints.</p> <p>Finally, FlexTool can actually mix three different types of constraint coefficients: <code>constraint_capacity_coefficient</code>, <code>constraint_state_coefficient</code> and <code>constraint_flow_coefficient</code> allowing the user to create custom constraints between any types of objects in the model for the main variables in the model (flow, state as well as invest and divest). So, the equation above is in full form:</p> <pre><code>  + sum_i [constraint_capacity_coefficient(i) * invested_capacity]\n           where i contains [node, unit, connection] belonging to the constraint\n  + sum_j [constraint_flow_coefficient(j) * capacity]\n           where j contains [unit--node, connection--node] belonging to the constraint\n  + sum_k [constraint_state_coefficient(k) * capacity] \n           where k contains [node] belonging to the constraint\n  = \n  constant\n\n  where 'capacity' is existing capacity plus invested capacity\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-combined-heat-and-power-chp","title":"How to create combined heat and power (CHP)","text":"<p>(init.sqlite scenario: coal_chp) init - west - coal_chp - heat</p> <p>First, a new heat <code>node</code> is added with the necessary parameters. The <code>nodes</code> can be used for energy form of energy or matter, so the heat demand node does not differ from the electricity demand node. </p> <p>The required parameters are:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>inflow</code>: Map for the heat demand (negative) [MW]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: a large number to prefer not creating energy from nowhere</li> </ul> <p>The heating systems tend to have some level of storage capability, so one could also add storage parameters to the node as well, but here they are not used.</p> <p>Then the coal_chp <code>unit</code> is made with a high <code>efficiency</code> parameter, since CHP units convert fuel energy to power and heat at high overall rates. In FlexTool, <code>efficiency</code> is a property of the unit - it demarcates at what rate the sum of inputs is converted to the sum of outputs. However, without any additional constraints, the <code>unit</code> is free to choose in what proportion to use inputs and in what proportion to use outputs. In units with only one input and output, this freedom does not exist, but in here, the coal_chp needs to be constrained as otherwise the unit could produce only electricity and no heat at 90% efficiency, which is not feasible. </p> <p>This CHP plant is an another example where the user defined <code>constraint</code> (see the last equation in the previous example) is used to achieve the desired behaviour. In a backpressure CHP, heat and power outputs are fixed - increase one of them, and you must also increase the other. In an extraction CHP plant the relation is more complicated - there is an allowed operating area between heat and power. Both can be represented in FlexTool, but here a backpressure example is given. An extraction plant would require two or more greater_than and/or lesser_than <code>constraints</code> to define an operating area.</p> <p>Electricity and heat outputs are fixed by adding a new <code>constraint</code> coal_chp_fix where the heat and power co-efficients are fixed. You need to create the two relationships <code>unit__outputNode</code>, for coal_chp--heat and coal_chp--west. As can be seen in the bottom part of the figure below, the <code>constraint_flow_coefficient</code> parameter for the coal_chp--heat and coal_chp--west is set as a map value where the <code>constraint</code> name matches with the coal_chp_fix <code>constraint</code> object name. The values are set so that the constraint equation forces the heat output to be twice as large as the electricity output.</p> <p>Create constraint  coal_chp_fix object with parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>Create <code>unit_outputNode</code> (coal_chp|heat):</p> <ul> <li><code>constraint_flow_coefficient</code> : coal_chp_fix, -0.5</li> </ul> <p>Create <code>unit_outputNode</code> (coal_chp|west):</p> <ul> <li><code>constraint_flow_coefficient</code> : coal_chp_fix, 2</li> </ul> <p>Again, the negative value can be turned positive by arranging it to the right side of the equality, creating this:</p> <pre><code>1 x *electricity* = 0.5 x *heat*, which is true only if *heat* is 2 x *electricity*\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-a-hydro-reservoir","title":"How to create a hydro reservoir","text":"<p>hydro_reservoir.sq</p>"},{"location":"how_to/#simple-hydro-reseroir","title":"Simple hydro reseroir","text":"<p>(scenario: hydro)</p> <p>The objective is to create a hydro power plant with a reservoir and connect it to a demand node.</p> <p>Hydro reservoir power plant requires three components:</p> <ul> <li>Reservoir <code>node</code></li> <li>Hydro <code>unit</code></li> <li>Output <code>node</code></li> </ul> <p>It can be useful to create a new alternative for these components to be able to include and exclude them from the scenarios.</p> <p>The reservoir is made with a node as only nodes can have storage in FlexTool. The incoming water can be represented by the inflow parameter. It can be a constant or a time variant. </p> <p>There are two ways to handle the water to electricity coefficient. In this example we store the water as volume and convert it to electricity in the unit.  This option is better when modelling river systems with multiple reservoirs. Note that in the results, the state of the reservoir is then as volume. For the other option of converting the volume to potential energy in the reservoir, look at the start of the 'How to create a hydro pump storage'.</p> <p>In this implementation of reservoir hydro power, there is an option to spill water from the storage so that it does not run through the plant. The simplest way of allowing spilling is setting the downward penalty of the node to 0. This way the energy can disappear from the storage without a cost. The quantity of spilled water can be seen from the results as the 'downward slack' of the node.</p> <p>The required parameters of the reservoir node are (node_c and node_t sheets if using Excel input data):</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>inflow</code>: Mapping of the incoming water as volume [m^3/h]</li> <li><code>existing</code>: The maximum size of the reservoir [m^3]</li> <li><code>penalty_up</code>: a larger number than with the demand node to not allow creating extra water if not enough electricity is being created</li> <li><code>penalty_down</code>: 0 or a large number (spilling or not)</li> <li>a <code>storage_method</code> to set the behaviour on how the storage levels should be managed - for short duration storages bind_within_timeblock may be best and for seasonal storages it could be best to use bind_within_solve. If historical storage level time series are available, it can be beneficial to use fix_start in the <code>storage_start_end_method</code> together with <code>storage_solve_horizon_method</code> use_reference_value, which will pick the storage level at the end of each solve from the time series provided as a reference (storage_state_reference_value).</li> </ul> <p>The <code>unit</code> is connected to the reservoir <code>node</code> and the output <code>node</code> demand_node (unit_c and unit_node_c in excel):</p> <ul> <li>The <code>efficiency</code> of the plant is the coefficient of transfering an unit of volume to an unit of electricity (using piecewise linear efficiency is naturally possible), here we use 0.57. </li> <li>Set <code>existing</code> capacity [MW]</li> <li><code>is_active</code>: yes </li> <li>Create relations <code>unit__inputNode</code>: hydro_plant|reservoir and <code>unit__outputNode</code>: hydro_plant|demand_node.</li> </ul> <p></p>"},{"location":"how_to/#river-system-with-multiple-reservoirs","title":"River system with multiple reservoirs","text":"<p>(scenario: hydro_with_downriver_spill_unit) (scenario: river_system)</p> <p>In this example, we create a hydro system with multiple reseroirs and downriver water demand. Here the water in the reservoir is represented as volume and the conversion to electricity is done in the units.</p> <p>The reservoir and demand node are the same as above. The <code>penalty_down</code> of the reservoir now needs to be the other than 0 as the spilled water needs to flow to the downriver node</p> <p>Let's start with the downriver demand. </p> <p>The downriver node represents the requirement to pass a minimum amount of water through the plant to not dry out the river. The downriver node needs:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>inflow</code>: Minimum requirement of water flow as the potential power (Map or constant)[m^3/h]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: 0, this makes the requirement to be at least the amount of water as the demand, not the equal to it</li> </ul> <p>The hydro plant unit now also needs the relation <code>unit_outputNode</code>: hydro_plant|downriver . </p> <p>The hydro plant now needs to both pass the water to downriver and the electricity to the demand node. Also, it needs to handle the water to electricity transformation as the reservoir now has volume not energy. The user needs to get the water to electricity coefficient ie. how much energy does one unit of volume create when passing the unit in this example the coefficient is 0.57. As the unit creates both the water and the electricity, the efficiency now is the sum of the two. </p> <ul> <li><code>efficiency</code>: 1 + coefficient</li> </ul> <p>Now the unit creates enough stuff to output, but the model can still choose how it will distribute it between the two output nodes. We still need to fix the ratio of output flows. This is done with an user constraint. Here we call this constraint hydro_split. The constraint needs parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0</li> </ul> <p>As we are fixing the output flows, the we need to add the flows with their coefficients to this constraint. This is done with the unit_outputNode parameter <code>constraint_flow_coefficient</code>:</p> <ul> <li><code>unit_outputNode</code>(hydro_plant|downriver): <code>constraint_flow_coefficient</code>: Map (hydro_split| 0.57)  </li> <li><code>unit_outputNode</code>(hydro_plant|demand_node): <code>constraint_flow_coefficient</code>: Map (hydro_split| -1)</li> </ul> <p>These create the constraint: </p> <pre><code>-flow_to_demand_node + 0.57 flow_to_downriver = 0\n</code></pre> <p>The capacity of an unit limits both outputs. Here the flow to downriver is larger than to the demand node. The capacity of the unit should be the electrical capacity divided by the water to electricity coefficient. With the electrical capacity of 500MW and water to elecricity coefficient of 0.57 the capacity of the unit becomes 878. Now at full power, 878 units of water flow to downriver and 500MW of electricity flow to the demand node.</p> <p>To add a spill option to the reservoir we need to create another unit. This is because just making extra water disappear with the <code>penalty_down</code>: 0, will not transfer this water to the downriver node to fulfil its needs.  This spill unit has the relations: - <code>unit_inputNode</code> (spill_unit|reservoir) - <code>unit_outputNode</code> (spill_unit|downriver)</p> <p>And parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>efficiency</code>: 1</li> <li><code>existing</code>: A large enough number to not be a limit</li> </ul> <p></p> <p>The database also includes an example of a river system with two additional reservoirs and plants. Both of them flow to the reservoir already made in this how to. These two are created the exact same way as above, but with just different values and the relation <code>unit_outputNode</code>: (hydro_plant_2| reservoir) and <code>unit_outputNode</code>: (hydro_plant_3| reservoir).</p> <p>In principle you can create as large river systems as you want, but each reservoir adds extra computational burden. Think about the possibility to combine the reservoirs and plants in the system and what information you lose with this approximation.</p> <p></p>"},{"location":"how_to/#how-to-create-a-hydro-pump-storage","title":"How to create a hydro pump storage","text":"<p>(hydro_with_pump.sqlite)</p> <p>For a hydro pump storage one needs the following components:</p> <ul> <li>Demand <code>node</code> </li> <li>hydro_plant <code>unit</code> with </li> <li>storage <code>node</code>, </li> <li>hydro_pump <code>unit</code> with </li> <li>pump storage <code>node</code> </li> <li>a source for external energy (pumped storage plant will lose energy due to charging losses). Wind power plant will be used as a source for external energy.</li> </ul> <p>There are two ways to handle the water to electricity coefficient. Here, we convert the reservoir capacity and inflow to potential energy.  The unit of the inflow should be the power that can be created from the quantity of the incoming water at maximum efficiency [MW]. In the same way, the existing storage capacity should be the maximum amount of stored energy that the reservoir can hold [MWh]. In this implementation of reservoir hydro power, there is an option to spill water (energy) from the storage so that it does not run through the plant. The simplest way of allowing spilling is setting the downward penalty of the node to 0. This way the energy can disappear from the storage without a cost. The quantity of spilled energy can be seen from the results as the 'downward slack' of the node.</p> <p>The required parameters of the reservoir node are (node_c and node_t sheets if using Excel input data):</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>inflow</code>: Mapping of the incoming water as the potential power [MW]</li> <li><code>existing</code>: The maximum size of the reservoir as the potential energy [MWh]</li> <li><code>penalty_up</code>: a large number to prefer not creating energy from nowhere</li> <li><code>penalty_down</code>: 0 or a large number (spilling or not)</li> <li>a <code>storage_method</code> to set the behaviour on how the storage levels should be managed - for short duration storages bind_within_timeblock may be best and for seasonal storages it could be best to use bind_within_solve. If historical storage level time series are available, it can be beneficial to use fix_start in the <code>storage_start_end_method</code> together with <code>storage_solve_horizon_method</code> use_reference_value, which will pick the storage level at the end of each solve from the time series provided as a reference (storage_state_reference_value).</li> </ul> <p>The <code>unit</code> is connected to the reservoir <code>node</code> and the output <code>node</code> nodeA (unit_c and unit_node_c in excel):</p> <ul> <li>The <code>efficiency</code> of the unit can be set to 1 as the inflow time series are directly expressed in MWh (using piecewise linear efficiency is naturally possible).</li> <li>Set <code>existing</code> capacity [MW]</li> <li><code>is_active</code>: yes </li> <li>Create relations <code>unit__inputNode</code>: hydro_plant|reservoir and <code>unit__outputNode</code>: hydro_plant|nodeA.</li> </ul> <p></p> <p>Next create the pump_storage. This is the downstream storage from the hydro plant. Again it should have the parameters as the reservoir:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>has_balance</code>: yes</li> <li><code>has_storage</code>: yes</li> <li><code>existing</code>: The maximum size of the storage [MWh]. Note that this really represents the mass of the water and it should be converted as the potential of the energy of the reservoir-plant system. So that 1 liter of water has the same energy in both storages.</li> <li><code>penalty_up</code>: a large number to avoid creating energy from nowhere</li> <li><code>penalty_down</code>: 0 </li> </ul> <p>In this example database, we have both a closed system and a river system. The difference is that in the closed system the inflow is zero in both reservoir and pump_storage. In river system we have the incoming water for the reservoir as in the reservoir example. In the downstream pump storage, we implement an outflow as the negative inflow representing the minimum amount of water that has to flow out of the system at each timestep to not dry out the river. The <code>penalty_down</code> is set as 0 to allow it let more water go when it needs to, otherwise the storages will keep filling up if the incoming water is larger than the minimum outgoing water.</p> <p>The storage level fixes should be the same in both storages (reservoir and pump storage). Here:</p> <ul> <li><code>fix_start_end_method</code>: fix_start</li> <li><code>storage_state_start</code>: 0.5</li> <li><code>bind_storage_method</code>: bind_with_timeblock</li> </ul> <p>This sets the starting storage levels to be 50%. The binding will also constrain the state of the storage at the end of of each timeblock to be the same as in the beginning of the timeblock.</p> <p>Then create the pump unit. It only needs three parameters:</p> <ul> <li><code>efficiency</code> = 1, The real efficiency of the pump is set elsewhere, so use 1.0 here. </li> <li><code>existing</code>: The wanted capacity</li> <li><code>is_active</code>: yes </li> </ul> <p>Set the relationships as follows:</p> <ul> <li><code>unit_outputNode</code> for (hydro_plant | nodeA), (hydro_plant | pump_storage ), (hydro_pump | reservoir)</li> <li><code>unit_inputNode</code> for (hydro_plant | reservoir), (hydro_pump | pump_storage), (hydro_pump | nodeA)</li> </ul> <p>Your system should look something like:</p> <p></p> <p>Next comes the tricky part of preserving the water and energy as both are represented as generic energy in the model. This is done by setting extra coefficents and constraints to the flows. First the hydro_plant needs to both create the energy for the demand node and pass the mass to the pump_storage. This is done by doubling the efficiency in this example to 2 and setting a extra constraint to force the output flows to both the demand node and the storage to be the same. </p> <p>For the hydro plant:</p> <ul> <li><code>Efficiency</code>:  2 </li> </ul> <p>Create a new constraint (here plant_storage_nodeA_split) and add the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>And for the <code>unit_outputNodes</code>:</p> <ul> <li>(hydro_plant | nodeA) <code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , 1</li> <li>(hydro_plant | pump_storage) <code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , -1</li> <li>Meaning: </li> </ul> <pre><code>flow to nodeA - flow to pump_storage = 0\n</code></pre> <p>As for the pump storage, we will have to make sure that the same amount of water leaves the pump_storage and enters the reservoir. Also it still should use electricity from the demand node without increasing the amount of water that is moving from storage to another.  First to prevent the energy from the demand node from increasing the water flow, add a coefficient to the flow between the demand node and the pump.</p> <p><code>unit_inputNode</code> (hydro_pump|nodeA): - <code>Coefficient</code>: 0 (Default is 1) </p> <p>This prevents the water amount from increasing as:</p> <pre><code>unit_output_flow = coeff1 * unit_input_flow1 + coeff2 * unit_input_flow2.\n</code></pre> <p>We still have to make the unit to consume electricity even though it does not affect the unit output directly. This is done by setting a new constraint to tie the flows to the pump unit from pump storage and the nodeA. Add a constraint (here pump_storage_nodeA_fix) the with the parameters:</p> <ul> <li><code>is_active</code>: yes</li> <li><code>sense</code>: equal</li> <li><code>constant</code>: 0.0</li> </ul> <p>And setting parameters for <code>unit_inputNode</code>:</p> <ul> <li>(hydro_pump | nodeA) <code>constraint_flow_coefficient</code> Map: pump_storage_nodeA_fix , 2</li> <li>(hydro_pump | pump_storage) <code>constraint_flow_coefficient</code> Map: pump_storage_nodeA_fix , -1</li> </ul> <pre><code>2 * flow_from_nodeA - flow_from_pump_storage = 0\n</code></pre> <p>Note that here the (<code>constraint_flow_coefficient</code> Map: plant_storage_nodeA_split , 2) actually sets the efficiency of the pump.  This means that here only half of the electricity used by the pump can be recovered when that amount of water is used by the hydro_plant. (Two units of energy are used to move 1 unit of water_energy) The <code>constraint_flow_coefficient</code> for pump_input should therefore be (1/efficiency)</p> <p> </p>"},{"location":"how_to/#how-to-add-a-reserve","title":"How to add a reserve","text":"<p>(init.sqlite: scenario network_coal_wind_reserve)</p> <p>In FlexTool, reserves are defined for a group of nodes. If there is a need to have a reserve requirement for a single node, it needs its own group. Therefore, when creating a reserve, the first step is to add a new <code>group</code> (e.g. electricity) with all member nodes (e.g. west, east and north) using the <code>group__node</code> relationship class. Then, a new reserve categories can be added (e.g. primary) to the <code>reserve</code> object class.  Finally, make sure there are up and down objects in the `UpDown' object class. These are hard-coded names in FlexTool and need to be used when creating reserves.</p> <p>Next, the reserve requirement will be defined. A relationship between in the <code>reserve__upDown__group</code> class (e.g. primary--up--electricity) allows to define the reserve parameters <code>reserve_method</code>, <code>reservation</code> (i.e. the amount of reserve) and <code>penalty_reserve</code> (i.e. the penalty cost in case of lack of reserve). For example, a constant of 10 MW could be used. Even though the name of the <code>reserve_method</code> is timeseries_only, it can also accept a constant value - it's an exogenous reserve requirement whereas the other two reserve methods are endogenous. Dynamic reserve method calculates the reserve requirement from generation and loads according to user defined factors (<code>increase_reserve_ratio</code>). Largest failure method will force enough reserve to cope with a failure of the chosen unit and connection flows.</p> <p>Parameters from the <code>reserve__upDown__unit__node</code> class should be used to define how different units can contribute to different reserves. Parameter <code>max_share</code> says how large share of the total capacity of the timestep (existing * efficiency * (profile)) of the unit can contribute to this reserve category (e.g. coal_plant may be limited by ramp constraint to provide only 1% of its capacity to an upward primary reserve.) Meanwhile, parameter <code>reliability</code> affects what portion of the reserved capacity actually contributes to the reserve (e.g. wind_plant may contribute only 80% of its generation to reserve due to uncertainty).</p> <p></p>"},{"location":"how_to/#how-to-add-a-minimum-load-start-up-and-ramp","title":"How to add a minimum load, start-up and ramp","text":"<p>(ramp_and_start_up.sqlite)</p> <p>Some plants cannot vary their output freely, but have some cost and limits associated with it. In this example we will add the minimum load behaviour to a coal_plant <code>unit</code> and add the cost and limits for starting up and ramping the plant respectively.</p> <p>Minimum load requires that the unit must have an online variable in addition to flow variables and therefore a <code>startup_method</code> needs to be defined and an optional <code>startup_cost</code> can be given. The <code>startup_cost</code> is added to the total cost every time the unit is required to start-up. Here we use a value 1000 (Currency/MW started up).</p> <p>The options for the <code>startup_method</code> are no_startup, linear and binary. binary would require an integer variable so linear is chosen. However, this means that the unit can startup partially. The minimum online will still apply, but it is the minimum of the online capacity in any given moment (flow &gt;= min_load x capacity x online), where 0 &lt;= online &lt;= 1.</p> <p>The online variable also allows to change the efficiency of the plant between the minimum and full loads. A unit with a part-load efficiency will obey the following equation:</p> <pre><code>  + sum_i[ input(i) * input_coefficient(i) ]\n  =\n  + sum_o[ output(o) * output_coefficient(o) ] * slope\n  + online * section\n\nwhere   slope = 1 / efficiency - section\n  and section = 1 / efficiency \n                - ( 1 / efficiency - min_load / efficiency_at_min_load) / ( 1 - min_load )\n</code></pre> <p>By default, <code>input_coefficient</code> and <code>output_coefficient</code> are 1, but if there is a need to tweak their relative contributions, these coefficients allow to do so (e.g. a coal plant might have lower efficiency when using lignite than when using brown coal).</p> <p>The input is required at different ouput levels is shown in the figure below, when Capacity = 100, Efficiency = 0.8, Minimum load = 0.6 and Efficiency at minimum load = 0.5.</p> <p></p> <p>Next we will add ramp limits. With the ramping limits, the user can force the change of a flow from a unit to be below a certain value each timestep. The ramping is an attribute of the flow. Therefore it does not require the minimum load behaviour and its parameters are added to the <code>unit_outputNode</code> relationship:</p> <ul> <li><code>ramp_method</code>: ramp_cost, ramp_limit or both. Only ramp limit is currently implemented (August 2023).</li> <li><code>ramp_speed_up</code>: Limit on how fast the plant can ramp up. (fraction of unit / min) ie. Value 0.01 allows the change of 60% of capacity per hour. </li> <li><code>ramp_speed_down</code>: Limit on how fast the plant can ramp down. (fraction of unit / min) ie. Value 0.01 allows the change of 60% of capacity per hour.</li> <li><code>ramp_cost</code>: NOT YET IMPLEMENTED. The cost of ramping the capacity. [CUR/MW] </li> </ul> <p></p>"},{"location":"how_to/#how-to-add-co2-emissions-costs-and-limits","title":"How to add CO2 emissions, costs and limits","text":"<p>(init.sqlite scenario: coal_co2 ) init - west - coal - co2_price - co2_limit</p> <p>Carbon dioxide emissions are added to FlexTool by associating relevant <code>commodities</code> (e.g. coal) with a <code>co2_content</code> parameter (CO2 content (tons per MWh) of energy contained in the fuel).  The other CO2 parameters are handeled through a group of nodes (Here coal_price or coal_limit <code>groups</code>). Therefore one needs to create a group and add all the nodes that supply these commodities (eg. coal_market) to a group with a <code>group_node</code> relationship. (Here the relationship co2_price--coal_market) To set a price one needs to create set the co2_method parameter to price (constant) and create the <code>co2_price</code> parameter with the desired value. This price is added to the price of the commodity. </p> <p>Alternatively one can set a limit on the co2 used by setting the <code>co2_method</code> parameter to period or total and setting the <code>co2_max_period</code> (periodic map [tCO2]) parameter or <code>co2_max_total</code> (constant [tCO2]) parameter. </p> <p>There methods can be combined by setting the <code>co2_method</code> to price_period, price_total, period_total or price_period_total.</p> <p></p>"},{"location":"how_to/#how-to-create-a-non-synchronous-limit","title":"How to create a non-synchronous limit","text":"<p>(non_sync_and_curtailment.sqlite) (scenario: non_sync)</p> <p>Non-synchronous limit is a property of a <code>group</code> of nodes. It states that the non-synchronous flow to the group of nodes cannot exceed a set share of the input flows at any timestep. To demonstrate this, we have set a system with a coal plant, a wind plant and a single demand node. However, it can be done to a group of nodes with unlimited number of plants or connections connected. So, one can limit the non-synchronous share of individual nodes or of the whole system. The flows between the nodes of the group are excluded.</p> <p>The non-synchronous limit is set to a <code>group</code> of nodes with one or multiple members. Note: These are set to the group with <code>group_node</code> relationship, not with <code>group_node_unit</code> relationship!</p> <p>Create a group (here nodeA_group) and set a <code>group_node</code> relationship (nodeA_group |nodeA). Then add parameters:</p> <ul> <li><code>has_non_synchronous</code>: yes</li> <li><code>non_synchronous_limit</code>: 0.5</li> <li><code>penalty_non_synchronous</code>: 4000</li> </ul> <p>This forces the non-sync flow to be at max 50% of the incoming flow to the nodeA.  The penalty should be always set as in some cases there is no other way to keep the constraint feasible (and it will be difficult to find the reason why the model does not solve). The existence of the non-synchronous penalty in your results indicates that this constraint has been violated and you should investigate the reason for this in your system. If the <code>penalty_non_synchronous</code> is lower than the <code>upward_penalty</code> of the demand <code>node</code>, the system will prefer breaking the non-sync constraint instead of the <code>node</code> balance equation. In other words, it will not curtail the production of <code>profile</code> plants if the demand is not satisfied even though it will break the non-synchronous penalty. If it is higher, the curtailment will take place instead.</p> <p>When having a connection to a storage from a node with this constraint, the best practice is to add this storage node to the group as well. This excludes the flows to and from the storage in the calculation of the non-synchronous ratio. However, if you want to have these flows in the calculation, you have two options depending on if you want the flow to be synchronous or not. If it is non-synchronous, just set the connection parameter <code>is_DC</code>: yes. If it is synchronous (e.g., some flywheels), an issue arises with the reqular connection as it now can reduce the ratio with equal simultaneous flow in both directions. To prevent the simultaneous flow to both directions you need to set the <code>transfer_method</code>: exact. This will increase the solving time significantly as it will use integer variables (so, better to add the storage node to the node group with a non-synchronous limit).</p> <p>Then set which plants and connections are considered non-synchronous by adding parameters:</p> <p><code>unit_outputNode</code>: - <code>is_non_synchronous</code>: yes </p> <p><code>Connection_node_node</code>: - <code>is_DC</code>: yes </p> <p>Here the (wind_plant|nodeA) relation has the <code>is_non_synchronous</code> parameter and battery connection <code>is_DC</code> parameter.</p> <p>A connection with <code>transfer_method</code>: no_losses_no_variables between a node included in a group with a non-synchronous limit and a node outside of the group is not allowed. The flow in this kind of a connection is presented with a single variable, which would not function correctly with the non-synchronous limit constraints (there is a non-linearity at zero that requires two variables). </p> <p>If you want to see the individual flows in the results you can create separate <code>groups</code> for the flows and add <code>group_unit_node</code> relations to it. To produce the flow results, the groups need the parameter.</p> <ul> <li><code>output_results</code>: yes </li> </ul> <p>Here we have coal_flow <code>group</code> with <code>group_unit_node</code> relation coal_flow|coal_plant|nodeA and wind_flow <code>group</code> with <code>group_unit_node</code> relation wind_flow|wind_plant|nodeA.</p> <p></p>"},{"location":"how_to/#how-to-see-the-vre-curtailment-and-vre-share-results-for-a-node","title":"How to see the VRE curtailment and VRE share results for a node","text":"<p>(non_sync_and_curtailment.sqlite) (scenario: curtailment)</p> <p>When the system has profile-units with the <code>profile_method</code>: upper_limit, the model can curtail the unit's flow to avoid penalties.</p> <p>The curtailment could take place for several reasons:</p> <ul> <li>the supply is higher than the demand and the energy cannot be stored or transferred (further)</li> <li>non-synchronous limit</li> <li>extra flow constraints have been set</li> <li>other unit specific constraint affecting how VRE units or other units are forced to behave (ramp, start-up ...)</li> </ul> <p>To see the curtailment results you need to add a <code>group</code> of nodes (<code>group_node</code> not <code>group_unit_node</code> !) with one or more members. The group then needs the parameter:</p> <ul> <li><code>output_results</code>: yes</li> </ul> <p>This produces the <code>group</code>: indicator result to the Results database and group_summary table to the excel.</p> <p>These changes were done to the previous non-sync example database. </p> <p>Note: The results are the share of curtailment in relation to the inflow (demand) so it can exceed 100% as seen in the figure.</p> <p></p> <p></p>"},{"location":"how_to/#how-to-run-solves-in-a-sequence-investment-dispatch","title":"How to run solves in a sequence (investment + dispatch)","text":"<p>(init.sqlite scenario: 5weeks_invest_fullYear_dispatch_coal_wind)</p> <p>In this example, investment decisions are made using a five week sample of a year and then the dispatch is solved with the full year timeline using these investments. </p> <p>To do this you need two solves:</p> <ul> <li>Investment solve </li> <li>Dispatch solve</li> </ul> <p>Both solves should solve the same periods using different <code>timeblockSet</code> to represent these periods. This example has only one period p2020 describing a year. The investment solve uses a representative sample <code>timeblockSet</code> 5weeks to do the investment decisions. These are then passed to the dispatch solve that uses complete timeline fullYear.</p> <p>Investment solve requires the parameters:</p> <ul> <li><code>Invest_periods</code>: Array of periods where investments can be made</li> <li><code>realised_invest_periods</code>: Array of periods that are output for investment decisions</li> <li><code>period_timeblockSet</code>: Uses the 5weeks as the timeblock </li> </ul> <p>Note that the <code>realized_invest_periods</code> is used instead of <code>realized_periods</code>, because we want the investment solve to only output investments. Additionally some of the units, connections or storages will need investment parameters (<code>invest_cost</code>, <code>lifetime</code>...) see How to make investments (storage/unit)</p> <p>The dispatch solve requires the parameters:</p> <ul> <li><code>realized_periods</code>: Array of output periods</li> <li><code>period_timeblockSet</code>: Uses the fullYear as the timeblock</li> </ul> <p>The sequence of solves is defined by the <code>model</code> parameter <code>solves</code>. Here it is an array where the first item is an investment_solve 5weeks_only_invest and the second is the dispatch solve y2020_fullYear_dispatch. This is enough for the model to know to pass the investment decisions of the period to the period of the same name in the second solve.</p> <p>Note that the picture has two <code>model</code>: solves parameters defined one for each alternative. Only the parameter from the 5weeks_only_invest is used as the lower alternatives in the scenario tree override the values from the higher alternatives and only one model can be run.</p> <p></p>"},{"location":"how_to/#how-to-create-a-multi-year-model","title":"How to create a multi-year model","text":"<p>A multi-year model is constructed from multiple periods, each presenting one year. In the example case, each year is otherwise the same, but the demand is increasing in the west <code>node</code>. This means that all periods can use the same timeblockset 5weeks from the same timeline y2020, but one can also make separate timelines for each year, if data is available for this. The <code>inflow</code> time series are scaled to match the value in <code>annual_flow</code> that is mapped for each period. The model is using the <code>inflow_method</code> scale_to_annual in order to achieve this (default is use_original that would not perform scaling). There should also be a <code>discount_rate</code> parameter set for the <code>model</code> object flexTool if something else than the model default of 5% (0.05 value) is to be used.</p> <p></p> <p>A multi-year model could be solved at one go (multi_year_one_solve) or by rolling through several solves (multi-year) where each solve has a foresight horizon and a realisation horizon. Next we will go through both options.</p>"},{"location":"how_to/#multi-year-with-one-solve","title":"Multi year with one solve","text":"<p>(init.sqlite scenario: multi_year_one_solve)</p> <p>In this example, one solve is used for all the four periods. All the four periods need to be added to the solve arrays <code>invest_periods</code> and <code>realized_periods</code>. Here the same timeblock is used for all the four periods, so only difference between them is the increasing inflow set above. The parameters that need to be added to the <code>solve</code> object:</p> <ul> <li><code>years_represented</code> parameter is used by the model to calculate the discounting factors for the periods in the model (often future years). It should state the number of years each period will be representing. For example, a period for 2025 could represent the years 2025-2029 if its <code>years_represented</code> is set to 5. Any investments would be taking place at the start of 2025 and discounted to the beginning of 2025, but the operational costs would accrue from each year in 2025-2029 each with a different discounting factor (decreasing based on the interest rate).</li> <li><code>invest_periods</code> the periods in which the model is allowed to make investments.</li> <li><code>realized_periods</code> the periods that will be realized in this solve (outputs dispatch results for these periods).</li> <li><code>period_timeblockset</code> defines the set of representative 'periods' (timeblocks in FlexTool) to be used in each FlexTool <code>period</code>.</li> </ul> <p></p>"},{"location":"how_to/#multi-year-with-rolling-solves","title":"Multi year with rolling solves","text":"<p>(init.sqlite scenario: multi_year)</p> <p>If the solving time gets too big, there is an option to split the timeline into overlapping parts and solve them separately. This shortens the solving time as it increases exponentially as the model grows. Therefore, collection of smaller solves is faster. The drawback is that the accuracy will be affected if there are dependencies with a larger time interval than the split size. </p> <p>When dealing with investments the splitting only works if the different periods are similar, in most cases complete years. If the first solve is really windy, it would invest too much on wind which wouldn't produce enough energy in later solves and then it would need to invest again to something else. It can also be challenging to consider lifetimes. If the option of retiring is allowed, it might retire something that is needed for later solves. In this example, the periods are complete years and the only difference between periods is increased demand.</p> <p>The model rolls through several solves and therefore, the <code>model</code> object flexTool has four values in the <code>solves</code> array. Each value represents one solve and it's position in the sequence of solves. The next figure illustrates the realization (blue) and foresight horizons (grey). The first solve will solve both the year 2020 and year 2025, but it will only output the year 2020. The next will solve both 2025 and 2030 but only output 2025.</p> <p></p> <p>Next figure shows the values needed to define one solve (out of the four solves in the example). Each of these need to be repeated for each solve in the model.</p> <ul> <li><code>years_represented</code> parameter is used by the model to calculate the discounting factors for the periods in the model (often future years). It should state the number of years each period will be representing. For example, a period for 2025 could represent the years 2025-2029 if its <code>years_represented</code> is set to 5. Any investments would be taking place at the start of 2025 and discounted to the beginning of 2025, but the operational costs would accrue from each year in 2025-2029 each with a different discounting factor (decreasing based on the interest rate).</li> <li><code>invest_periods</code> the periods in which the model is allowed to make investments. To be given for each solve.</li> <li><code>realized_periods</code> the periods that will be realized in this solve (outputs dispatch results for these periods). To be given for each solve.</li> <li><code>invest_realized_periods</code> parameter states the periods that will realize the investment decisions. If not stated, it will use <code>realized_periods</code>.</li> <li><code>period_timeblockset</code> defines the set of representative 'periods' (timeblocks in FlexTool) to be used in each FlexTool <code>period</code>.</li> </ul> <p>Note the the <code>solve_mode</code>: rolling_window is not used! This is not for investment runs (without nesting) as it rolls freely, and investments should only be made at the start of the period. This example is called 'manual rolling' later when those are discussed.</p> <p>In the init.sqlite, the solve objects have solver parameters: <code>highs_method</code>, <code>highs_parallel</code> and <code>highs_presolve</code>. They only affect the speed and not the results, but usually the default values are good enough and the user should only change them if they understand how the solvers work.</p> <p></p>"},{"location":"how_to/#how-to-use-a-rolling-window-for-a-dispatch-model","title":"How to use a rolling window for a dispatch model","text":"<p>A rolling window can be used for example when a dispatch model gets too big to be solved on one go. It splits the problem into multiple consecutive smaller problems.</p> <p>The rolling window solve splits the time dimension into overlapping parts and solves each one of them separately but in a sequence (and can therefore pass state information from the previous solve to the next one). For example, instead of a solving the full year in one go, you can split the year into six four-month long solves where each solve outputs only the first two months. The solves would therefore include the months:</p> <ul> <li>Roll: Solve months -&gt; Output months</li> <li>1: [1,2,3,4] -&gt; [1,2]</li> <li>2: [3,4,5,6] -&gt; [3,4]</li> <li>3: [5,6,7,8] -&gt; [5,6]</li> <li>4: [7,8,9,10] -&gt; [7,8]</li> <li>5: [9,10,11,12] -&gt;[9,10]</li> <li>6: [11,12] -&gt; [11,12]</li> </ul> <p></p> <p>The rolling solve could be setup also manually as described in the 'How to run a multi year model' - just using shorter periods. </p> <p>However, this would be tedious if there are many solves. In a rolling window model, the user can set the <code>rolling_jump</code> and <code>rolling_horizon</code> parameters, which are expressed in hours. </p> <ul> <li> <p><code>rolling_horizon</code>: sets the length of the whole solve, in hours. In previous example 4 months (2880 hours). Horizon allows the model to see bit further in the future to improve the decision making for the period that will be output.</p> </li> <li> <p><code>rolling_jump</code>: sets the interval for the length of each 'jump' the model takes forward in reach roll. It is then both the interval of roll starting points and the length of the output for each roll. The <code>rolling_jump</code> must be smaller than the <code>rolling_horizon</code>. In the previous example the <code>rolling_jump</code> would be 2 months (1440 hours).</p> </li> </ul> <p>In addition, the user can set the duration for how long the model will roll:</p> <ul> <li><code>rolling_duration</code>: Optional (hours), the length of combined rolls. In the example, it could be set to 8640 hours which would divide evenly, or 8760 hours which means that the last roll will be shorter than the others. It is nicer to use <code>rolling_jump</code> that is divisable with the <code>rolling_duration</code> to keep rolls even. If <code>rolling_duration</code> is not set, it defaults to rolling through the whole timeline.</li> </ul> <p>When using rolling window solve, you are solving the model with less information. Therefore, the results will be less optimal since the model will not have the full information at once. It is therefore important to know how this could affect the results and what things to consider when implementing a rolling window model. It will have an impact on time dependant parts of the model: for example, storages or cumulative flow constraints. If the model can see only a few months to the future, it can't see how much energy needs to be stored after that. </p> <p>Investments should not be used with this free rolling solve (<code>solve_mode</code>: rolling_window) as investments should only be done at the start of the periods. Both the long-term storage and the investments can be taken into account with nested rolling solves that have a separate how-to.</p> <p>Short term storages also are operated less optimally in a rolling window model. There is a positive side to this as well, since perfect foresight linear optimization models are 'too optimal'. They don't reflect the forecast errors present in real life. So, a rolling window model might operate a bit more realistically than a single_solve model. A single_solve model can consider things happening far in the future when setting the storage level at present, even though in reality that information is not available. So, the total cost of a rolling_window model should always be higher than the total cost from a complete single_solve model that has perfect information.</p> <p>To set a dispatch rolling window model you need to set the object <code>solve</code> parameters:</p> <ul> <li><code>solve_mode</code>: rolling_window</li> <li><code>rolling_jump</code>: Hours, the desired length of the solve interval</li> <li><code>rolling_horizon</code>: Hours, the desired length of each roll solve</li> <li><code>rolling_duration</code>: (Optional) Hours, the length of the combined outputs. If not set, the whole timeline is used.</li> </ul> <p>Considerations on the rolling times:</p> <ul> <li>The <code>rolling_jump</code> and <code>rolling_horizon</code> must be large enough to make the model faster. If too small intervals are used, the creation of solves and moving data from solve to another might take too much time.</li> <li>If you are not using 1-hour timesteps, preferably use multiples of the timestep you are using as the <code>rolling_jump</code> and <code>rolling_horizon</code>. The steps included in each solve are calculated by summing the step durations until they are larger or equal to the hours given. So, if multiples are not used, the rolls might not be exactly the same size.</li> <li>The model can roll over timeblock and period jumps, which might cause some issues if storage constraints are used. Using timeblock length or its multiples is therefore recommended. For example, the <code>rolling_jump</code> could be a half of a timeblock and the <code>rolling_horizon</code> whole timeblock or <code>rolling_jump</code> a timeblock and <code>rolling_horizon</code> three timeblocks. Of course, when running e.g. a full year dispatch, there is only one timeblock of 8760 hours, which makes the choices more simple.</li> </ul> <p>Considerations on storage parameters:</p> <ul> <li><code>storage_solve_horizon_method</code> use_reference_value or use_reference_price are the preferred means to bind storage values. They can be used together with the <code>storage_state_start_end_method</code>: start, which would then set the initial storage state. These methods bind either the storage value or the storage price at the end of horizon (not the end of jump). This allows the storage to use the part of the horizon that is not output to improve the behaviour of the storage in the part that is output (as defined by <code>rolling_horizon</code> and <code>rolling_jump</code>). </li> <li><code>bind_within_timeblock</code> does not work correctly if the rolls don't include whole timeblocks. Instead, it will bind the first step of the roll (whatever it is) to the end of the timeblock. Do not use in nested solves if you are not using whole timeblocks or its multiples as <code>rolling_jump</code></li> <li>the same applies to the <code>bind_within_period</code> (but in relation to periods - do not use this unless you are <code>rolling_jump</code> is as long as a period or its multiples).</li> <li><code>storage_start_end_method</code> can be used to set the first timestep of the first roll and/or the last timestep of the last roll (in conjunction with <code>storage_state_start</code> and <code>storage_state_end</code>).</li> <li><code>bind_within_solve</code> binds the start state to the end state of each roll not the start and end of the whole model timeline. Use with caution (and probably best not to use together with <code>storage_solve_horizon_method</code> use_reference_value).</li> </ul>"},{"location":"how_to/#how-to-use-nested-rolling-window-solves-investments-and-long-term-storage","title":"How to use Nested Rolling window solves (investments and long-term storage)","text":"<p>The basic rolling solve can have problems in dealing with long term storage and with investments. If the model only sees a few weeks to the future, it really can't see how much energy should be stored in long term storages. Problems with investments can also be serious: If the first roll is really windy, the model would overinvest in wind power that is not profitable in the later rolls. Similarly, if the model is allowed to retire capacity, it might retire something that is actually needed in the later rolls. </p> <p>Nested solve sequences can first solve the investments and long-term storage levels and pass them to the dispatch solve. Both storage solve and dispatch solve can be rolling solves. The dispatch solves can then send the end storage values to the investment and long-term storage solves as start values to reduce the error of these solves.</p> <p>When to use nested solves?</p> <ul> <li>Dispatch model is taking too long to solve, but simple rolling window solve would not represent the long-term storages correctly. (Nesting without the investment solve)</li> <li>Investment model takes too long to solve, even with manual rolling How to create a multi-year model. With nesting you can have smaller rolls for dispatch solve than the investment solve. (Nesting without the storage solve)</li> <li>Investment model takes too long and you have long term storages to consider. (Three level nesting, graph below)</li> </ul> <p></p> <p>However, the obvious issue is that investment and storage solves cannot be solved using the old complete solve as it wouldn't make the solve time any shorter. Therefore, we need to decrease the information for investment and storage solves as well. There are a few options for this:</p> <ol> <li>Use lower resolution (longer timesteps). This can work quite well for a long-term storage.</li> <li>Use representative periods from the full timeline when performing investments. There is a large body of literature and methods on how to pick the representative weeks.</li> <li>Split the investment timeline (myopic investments) by manually creating a solve sequence for the investment solves like in: How to create a multi-year model section. This can be combined with the first or second option. </li> </ol> <p>Each of these have their pros and cons:</p> <ul> <li>Using the lower resolution can speed-up the model considerably, but it also means that everything that happens faster than the new timestep duration will be lost as the timestep varying parameters are averaged or summed for the new timestep. For example, consider a model with investment options to solar and storage. If the step duration is changed to 24 hours, the model won't invest in enough storage to mitigate the diurnal variation in PV. When these investments are then passed to the dispatch solve, the invested portfolio will have trouble meeting the demand.</li> <li>Using the sample can be effective if the sample is chosen well, but all the needs that are not in these samples are not included. The speed is heavily dependent on the number and size of those samples.</li> <li>Splitting the investment timeline for multi-year models can be seen as a relatively realistic approach, since investment decisions would have a lot of uncertainty in the longer time frame anyway.</li> </ul> <p>The investment decisions with less information are always less optimal than with complete solves. Therefore, when they are passed to the dispatch solve, it will in some cases cause penalties in the results when the invested portfolio is not sufficient to meet the demand at all times.</p> <p>The long term storage solve can be implemented using a lower resolution solve. The storage state values from the storage solves will be used to fix the storage value (or price) at the end of each dispatch solve. This means that on the last step of the roll (or the period), the storage quantity (or price) will have to match the quantity (or price) in the storage solve. The <code>rolling_jump</code> and <code>rolling_horizon</code> in the storage solve have to be longer than in the dispatch solve. You can set which storages are included as \"long term storages\" whose value will be transferred to the dispatch solve.</p> <p>To create a nested solve sequence, you need two or three <code>solve</code> objects. Either the investment solve or the storage solve can be left out. When using nested solve sequence, the sequence is not set with the <code>model</code>: <code>solves</code> parameter. Only the topmost solve is put there. Instead, the nested levels are set by the <code>solve</code> parameter <code>contains_solve</code>: solve_name. The investment solve is always on the top followed by the storage solve and dispatch solve:</p> <ul> <li>investment_solve <code>solve</code> parameter <code>contains_solve</code>: storage_solve_name </li> <li>storage_solve <code>solve</code> parameter <code>contains_solve</code>: dispatch_solve_name</li> </ul> <p>To create a storage solve:</p> <ul> <li><code>solve</code> parameter <code>fix_storage_period</code>: Array of periods where the storage values are fixed in the lower solve. Should be the same as <code>realized_periods</code> for the dispatch solve.</li> <li><code>node</code> parameter <code>storage_nested_fix_method</code>: fix_quantity or fix_price, includes this storage to be fixed. fix_price requires storage_state_reference_price to be set.</li> </ul> <p>To create an investment_solve:</p> <ul> <li><code>solve</code> parameter <code>invest_periods</code>: Array of periods where the model can invest.</li> <li><code>solve</code> parameter <code>realized_invest_periods</code>: Array of periods where the model will realize investment decisions to the lower solves and results.</li> <li><code>solve</code> parameter <code>realized_periods</code>: Should not be used in this solve! You don't want the dispatch results from this solve, but from the dispatch solve.</li> </ul> <p>In addition, the rolling dispatch solve should be created as in the How to use rolling window solve for dispatch. To set a dispatch rolling window model you need to set the object <code>solve</code> parameters:</p> <ul> <li><code>solve_mode</code>: rolling_window</li> <li><code>rolling_jump</code>: Hours, the desired length of the solve interval</li> <li><code>rolling_horizon</code>: Hours, the desired length of each roll solve</li> <li><code>rolling_duration</code>: (Optional) Hours, the length of the combined outputs. If not set, the whole timeline is used.</li> <li><code>realized_periods</code>: Array of periods that are realized</li> </ul> <p>The other model parameters apply to all of the solves. Therefore, the considerations of the storage value binding that were discussed in the How to use a rolling window for a dispatch model should be taken into account here as well.</p> <ul> <li>Storage levels can be fixed with <code>storage_solve_horizon_method</code>: use_reference_value or use_reference_price, these will fix the end of each horizon not each jump.</li> <li><code>storage_start_end_method</code> fixes the starts and/or ends of each solve level, meaning the first step of the first roll and the last step of the last roll.</li> <li>In most cases the <code>bind_storage_method</code> should be left as bind_forward_only</li> <li>Do not use <code>bind_within_timeblock</code> if you are not using full timeblock or its multiples as the <code>rolling_jump</code> in the dispatch model, otherwise you might cause an infeasible problem. </li> <li>Do not use <code>bind_within_period</code> if you are not using full periods or its multiples as the <code>rolling_jump</code> in the dispatch model, otherwise you might cause an infeasible problem. </li> <li>Do not use <code>bind_within_solve</code></li> </ul> <p>The recommended storage parameters with nested solves are: - <code>storage_start_end_method</code>: fix_start - <code>storage_solve_horizon_method</code>: fix_quantity - <code>storage_state_start</code> and <code>storage_state_reference_value</code>: use the same value</p> <p>This way the start and end states of the system are the same. Each end of the horizon (not the output) has that value as well, which keeps the model from emptying the storages at the end of the roll. In the dispatch solve, the fixed storage value from the storage solve overrides the horizon end value if a conflict exist. </p> <p>How to create the three lower information solve types for investment and storage solves discussed above?</p> <p>To create a lower resolution (longer timesteps) solve:</p> <ul> <li>Make a new <code>timeblockSet</code>, but use the same <code>timeline</code> and <code>block_duration</code> for it as with the high resolution solve</li> <li>Set <code>timeblockSet</code> parameter <code>new_stepduration</code>: Hours</li> <li>In the <code>solve</code> use this new <code>timeblockSet</code> in the <code>period_timeblockSet</code></li> </ul> <p>The model will create a new timeline for this solve with the <code>new_stepduration</code>. All the timestep map data like <code>inflow</code> or <code>profile</code> will be either summed or averaged for the new timeline. Again, the <code>new_stepduration</code> should be multiple of the old step duration. If the <code>block_duration</code> is not a multiple of the <code>new_stepduration</code> the last timestep will be shorter than the rest. </p> <p>Note that if the last timestep of the dispatch horizon is not in the storage solve timeline, it will use the last available timestep to fix the storage. This can happen at the end of the timeline when the dispatch solve with a lower step size can fit an extra step after the last time step of the storage solve. Other reason might be that both dispatch and storage solves are aggregated with the <code>new_stepduration</code>. In that case, it is usually best to use values for the <code>new_stepduration</code> that are dividable.  </p> <p>To create a sample solve with representative periods:</p> <p>The tutorial contains an example of representaive periods under alternative 5weeks where the year is represented with five sample weeks. It is done with the <code>timeblockSet</code> parameter <code>block_duration</code> where instead of choosing the whole timeline by setting the first timestep and the duration of whole timeline, you choose multiple starting points with smaller durations. The example for the 5weeks is below.</p> <p></p> <p>To create an investment solve sequence, you have two options:</p> <ul> <li>Create manually a series of solves and set the <code>invest_periods</code> and <code>realized_invest_periods</code> individually for the solves. How to create a multi-year model has an example of this with the difference that here you use <code>realized_invest_periods</code> instead of <code>realized_periods</code> and that each of the higher level solves requires the <code>contains_solve</code> parameter. </li> </ul> <p>If you have many splits, this option can get tedious and prone to mistakes.</p> <p>The other option is to use only one investment <code>solve</code> object:</p> <ul> <li>The <code>invest_periods</code> and <code>realized_invest_periods</code> should then be set with a 2D map where the first column tells the solve (you don't have to create separate <code>solve</code> objects for these) and the second column tells the period. To get a 2D map, choose the parameter type as Map and then right click the table and choose Insert column after/before. The value column does not matter. The model will generate these solves, with the periods given. Note that the solve names should match in both 2D-maps.  </li> </ul> <p>You can use the same lower level solve with each the investment solves as the lower level solves will exclude the periods that are not included in either of the upper level realized periods: <code>realized_invest_periods</code> or <code>fix_storage_periods</code>. So, the lower level solve should have all the periods that it is used for in any the solves.</p> <p></p> <p>Note that the results of a nested rolling solve run are not fully optimal, because the information in the model is decreased. This is the price you pay for the speed. Therefore, the results should not be taken as they are, instead it is important to know how to interpret the results: What phenomena are missing? How will they affect the results? Where should extra investments go to satisfy the demand (there is a possibility to use the <code>capacity_margin</code> method to force extra investments)?</p> <p>In the init.sqlite there are four example scenarios related to this:</p> <ul> <li>multi_fullYear_battery: The four period full year single solve, with coal, wind, battery storage with unlimited investment possibilities. Running this is still possible but takes a few minutes. This is here as a reference for the nested solves.</li> <li>multi_fullYear_battery_nested_24h_invest_one_solve: This has the nested structure and the investment solve is done with 24h timesteps and storage solve 6h timesteps.</li> <li>multi_fullYear_battery_nested_sample_invest_one_solve: This has the investment solve as 5weeks sample but all the four periods are included in the same investment solve. Nested structure with 6h storage solve timesteps.</li> <li>multi_fullYear_battery_nested_multi_invest: This has split the investment to four solves with each having two period 5weeks sample period horizon. Nested structure with 6h storage solve timesteps.</li> </ul> <p>The 24h timestep is clearly too long as it invests too little for storage and coal. A large upward penalty ensues.</p> <p>The sample one solve invest also invests too little, as the largest demand-supply ratio weeks are not in the five week sample. However, the investments are spread more accurately.</p> <p>The split sample investment run produces in this case similar results as the one solve sample run. This is not always the case! Here the only difference between the periods was linearly increased demand.  </p>"},{"location":"how_to/#how-to-use-stochastics-representing-uncertainty","title":"How to use stochastics (representing uncertainty)","text":"<p>(stochastics.sqlite)</p> <p>Stochastics are used to represent the uncertainty of the future in the decision making. The main idea of it is to connect multiple scenarios (branches) of the future to the realized timeline. The model then optimizes the system to get the minimize the total cost all the branches (weighted by their probability). Only the  realized timeline, shared between all branches, will be output. </p> <p>For the stochastics to have an effect on the results, the system needs parameters that change between the stochastic branches. These could be e.g. wind power generation or fuel prices. The model will then have separate variables in every branch for all the decision the model can take ((e.g. invesment, storage state, online, flow). As a consequence, the realization phase will also be dependent on the things that happen in the stochastic branches - weighted by the probablity given to each branch. </p> <p></p> <p>In this example, we show three ways to use stochastics: Single solve, rolling horizon and multiperiod single solve. They all share the same test system that includes: </p> <ul> <li>A demand node </li> <li>Coal, gas and wind power plants </li> <li>Hydro power plant with a reservoir and a downriver nodes</li> </ul> <p>The demand and the downriver nodes have a constant negative inflow. Therefore, the hydro plant capacity is partly in use at all times. The varying timeseries are the wind profile and the water inflow the reservoir. The coal commodity is more expensive than the gas, so the system will try to use the reservoir water to minimize the usage of coal. This will be affected by the forecast of the wind and the forecast of the water inflow. These are the stochastic timeseries in these examples. </p> <p>You can have stochastics in multiple timeseries in the same solve, but these will have to share the branches. This means that for example if you have two wind plants with two different stochastic wind profiles with three branches (upper, mid and lower estimates) you need to think if it is best to use only three branches and put both of the upper estimates to the same 'upper' branch or should you use combinatorics to make nine branches. However, note that the tool will not do the combinatorics for you and the solving time will be heavily affected by extra branches. Consequently, the usual practice is to present all the stochastics using just e.g. three branches and consider the correlations between the stochastic parameters in the pre-processing of the input data.</p> <p>Notes about the storage options with stochastics:</p> <ul> <li> <p>The best options to use are:</p> </li> <li> <p><code>Storage_state_start_end_method</code>: fix_start or fix_start_end (and the their values)</p> </li> <li> <p><code>storage_solve_horizon_method</code>: fix_value or fix_price (and their values)</p> </li> <li> <p>Do not use any of the <code>storage_binding_methods</code>, they do not work correctly with stochastics (there is no unambigious end state that could circle back to the first time step). </p> </li> </ul> <p></p>"},{"location":"how_to/#single-solve-stochastics","title":"Single solve stochastics","text":"<p>(stochastics.sqlite scenario: 2_day_stochastic_dispatch)</p> <p>In this scenario, 24 hours are realized with an uncertain forecast for the next day. The timeblock length is therefore 48 hours and the branching will happen at the timestep t0025.  To set up a stochastic solve, we need three things: The stochastic branch information, the stochastic timeseries and choosing which parts of the model use stochastic timeseries.</p> <p>The information about the branches are set with the solve parameter <code>stochastic_branches</code>. This is a 4 dimensional map. (Edit -&gt; choose map -&gt; right click -&gt; add columns). The columns are: period, branch, analysis_time (starting time of the branch), realized (yes/no) and the value is the weight of the branch. Each starting time, including the first timestep, should have one and only one realized branch. This realized branch is used for the non-stochastic parts of the model with a stochastic timeseries. In this example we have three branches: mid, upper and lower representing the three wind forecasts. The weight will influence the relative weight of each branch in the objective function (model costs). The weights are normalized, so that the total weight is always one in each timestep.</p> <p>The stochastic wind timeseries are set with the same profile parameter <code>profile</code> but with a three dimensional map instead of the regular one dimesional map. The tool recognizes a stochastic timeseries from the dimensions of the data. The three dimensions are: branch, analysis_time and time. Here the realized part of the model (t0001-t0024) uses also the branch 'mid', which is one of the forecast branches as well. In the stochastic part, 'mid' is also set to be 'realized'. It is not actually realized (since the stochastic part is not realized), but it helps the model to choose which branch to use when there is no stochastic data available.</p> <p>The parts of the model that will use stochastic data is chosen with a group parameter <code>include_stochastics</code>. The units, nodes and connections that are added to this group use stochastic timeseries connected to them (if available). Here we add the unit wind_plant to this group. There is a possiblity that to have two wind plants with the same profile, but use the stochastics on only one of them. The other would then use only the realized branch.</p> <p>An option exists to output the stochastic horizons for debugging your system. This is done with the model parameter <code>output_horizon</code>. It will cause errors in the calculation of the cost in each solve (the costs of the unrealized branches will be included) so turn it off when you want the final results.</p> <p>If you change the weights of the stochastic branches, you should see the results change.</p> <p></p>"},{"location":"how_to/#rolling-horizon-stochastics","title":"Rolling horizon stochastics","text":"<p>(stochastics.sqlite scenario: 1_week_rolling_wind)</p> <p>In this scenario we extend the previous timeline to one week and roll through it one day at a time with additional three day stochastic horizon:</p> <p>solve: <code>rolling_solve_jump</code> = 24 and <code>rolling_solve_horizon</code> = 96. </p> <p>The stochastic data should be given so that it can serve the rolling structure: <code>rolling_solve_jump</code> dictates the duration of the initial non-stochastic part of the model horizon. This period needs only data for the 'realized' branch. The stochastic branches will begin only after that and need data only after <code>rolling_solve_jump</code> has been reached. So, for every 'analysis_time' there needs to be a time series in each stochastic branch that extends to the end of horizon (as defined by <code>rolling_solve_horizon</code>). The branches continue to the end of the horizon without branching again.</p> <p>For the solve parameter <code>stochastic_branches</code> this means analysis times (t0001, t0025, t0049, t0073, t0097, t0121 and t0145). t0001 is there only to tell which branch is the realized one.</p> <p>Otherwise there is no difference to the previous example.</p> <p>Realized scenario should not typically be used as a forecast branch in a stochastic model. However, this would happen, if the realized branch has weight other than zero. So, to avoid this, its weight should be set to zero but its realized status to \"yes\". Then the values from the realized scenario are not included in the forecast branches, but they are used in the realized part of the timeline. This happens because the weight of the realized part of the timeline is always forced to be one (even though its weight has been set to zero).</p> <p></p> <p></p>"},{"location":"how_to/#multi-periodic-stochastics","title":"Multi periodic stochastics","text":"<p>(stochastics.sqlite scenario: 2_year_stochastic_invest)</p> <p>Here we solve investment run with one realized year and other year as the stochastic horizon. When using stochastics on multiple periods, they should not use the same timeblock as the stocastics are set for a timestep not (period, timestep). This means that the same value would be used for all the periods with this timestep. Instead use consecutive timeblocks from the same timeline. Here the first timeblock has timesteps t0001-t8760 and the second timeblock has the timesteps t8761-t17520.</p> <p>The <code>stochastic_branches</code> has one branching spot at the first timestep of the period2. This example uses the water inflow of the reservoir as the stochastic timeseries. If you run this scenario, you can see that it takes some time. When planning the stochastic data to be used, you should take into account that it will increase the solving time of the model significantly.</p> <p></p>"},{"location":"how_to/#how-to-use-cplex-as-the-solver","title":"How to use CPLEX as the solver","text":"<p>Using CPLEX requires that you have installed the software, have a licence for it and have added it to PATH or to the environment where you are using the FlexTool, so that the tool can find the solver.</p> <p>CPLEX is used when the solve parameter solver is set to 'cplex'. The tool passes the built optimization model to the CPLEX solver and converts the solution file to a filetype suitable for CPLEX. The solver will produce two additional files to the work directory: 'cplex.log' and 'flexModel3_cplex.sol'. The former is the logfile of the solver and the latter contains the solution in the CPLEX format.</p> <p>The tool uses Interactive Optimizer to pass the problem to the solver. The default command used:</p> <pre><code>cplex -c 'read flexModel3.mps' 'opt' 'write flexModel3_cplex.sol' 'quit'\n</code></pre> <p>Additional parameters:</p> <ul> <li><code>solver_precommand</code> creates a text in front of the cplex call. This is useful when dealing with floating licences. The command allows to call the licence server to reserve the licence for the duration of the cplex program with a command line argument.</li> <li><code>solver_arguments</code> is an array containing additional CPLEX solver commands</li> </ul> <p>With these parameters, the command line call is:</p> <pre><code>'solver_precommand' cplex -c 'read flexModel3.mps' 'solver_command1' 'solver_command2' ... 'solver_command_last' 'opt' 'write flexModel3_cplex.sol' 'quit'\n</code></pre> <p></p>"},{"location":"how_to/#how-to-create-aggregate-outputs","title":"How to create aggregate outputs","text":"<p>It is often desirable to output results that focus on particular aspects of the model. For example, it can be useful to output all flows going in and out of all electricity nodes without the corresponding flows for other energy carriers (e.g. fuels used to produce the electricity). And if the model is large, some of those flows could be aggregated (summed). </p> <p>The first aspect, choosing a group of nodes for which to output results for, is achieved by:</p> <ul> <li>creating or re-using a <code>group</code> (e.g. electricity)</li> <li>set the group's parameter output_node_flows to yes</li> <li>assigning all the relevant nodes to the group (using <code>group__node</code>, e.g. electricity__west)</li> </ul> <p>The second aspect, aggregating flows into one, is achieved by:</p> <ul> <li>creating or re-using a <code>group</code> (e.g. all_VRE)</li> <li>set the group's parameter output_aggregate_flows to yes</li> <li>assigning all flows that should be part of the group (using <code>group__unit__node</code> or <code>group__connection__node</code>, e.g. all_VRE__wind1__west)</li> </ul> <p>All flows that are part of a group that has output_aggregate_flows set to yes will then be output only as part of the aggregate in the <code>group</code> flow_t. In all other outputs, they will remain independent.</p> <p>\"How to database\" (aggregate_output.sqlite) aggregates results for the nodeA and nodeB. Both of the nodes have a wind power plant and nodeA has a coal power plant. The demand is divided to the electricity, heat and irrigiation needs. This means that,  besides an internal demand (inflow), both nodes output to the heat node while nodeA also outputs to the irrigation node. Additionally the nodes are connected to each other and the node_country_y1. The nodeA is connected to the node_country_x1 and nodeB is connected to the node_country_x2. </p> <p>For the sake of the example, we are only interested in the nodeA and nodeB. Therefore, <code>group</code> focus_nodes is created and the nodes are added to it with <code>group__node</code> relationships. To simplify the results, the flows from the two wind plants are aggregated as one. Same applies to the heat pumps. This is done by creating the <code>group</code>s wind_aggregated and heat_aggregated. The flows are added to the group with the <code>group_unit_node</code> relationship. </p> <p>Note that here the <code>node</code> has to be either nodeA or nodeB, not the heat node! E.g. the nodes from the wind_aggregated <code>group_unit_node</code> are tied to the nodes from the focus_nodes <code>group_node</code> only when they share same nodes (e.g. wind_aggregated__wind_plant_1__nodeA and focus_nodes__nodeA have nodeA in common). The <code>group_unit_node</code> can include other flows but only the ones that are have a node that is inside the focus_nodes group are included in the result table under the focus_nodes group.</p> <p>Connections are simplified by creating groups connections_country_x and connections_country_y and adding the relevant connections with <code>group_connection_node</code> relationship. Again the <code>node</code> has to be either nodeA or nodeB to be included in the results.</p> <p></p> <p>The focus_nodes group needs the parameter <code>output_node_flows</code>: yes and the unit and connection groups need the parameter <code>output_aggregate_flows</code>: yes. </p> <p></p> <p>The resulting table has the flows to the focus_nodes group from units and connections. Additionally, the internal losses of the group are calculated. These are the flows between the nodes of the group and the storage losses. Here the losses come from the connection between nodeA and nodeB. Additionally the possible slacks to balance the nodes are included.</p> <p></p>"},{"location":"how_to/#how-to-enabledisable-outputs","title":"How to enable/disable outputs","text":"<p>Some of the outputs are optional. Some of these optional outputs are output by default while some are not (see below). Removing outputs speeds up the post-processing of results. The user can enable/disable them by changing the following parameters of the <code>model</code> entity:</p> <ul> <li><code>output_node_balance_t</code>: Default: yes. Produces detailed inflows and outflows for all the nodes for all timesteps. Mainly useful to diagnose what is wrong with the model. </li> <li><code>output_connection__node__node_flow_t</code>: Default: yes. The flows between the nodes for each timestep.</li> <li><code>output_unit__node_flow_t</code>: Default, yes. The flows from units to the nodes for each timestep.</li> <li><code>output_ramp_envelope</code>: Default, no. Includes seven parameters that form the ramp room envelope. Shows the actual ramp as well as different levels of available ramping  capability in a given node - for both directions, upward and downward. The first level includes ramproom in all the units, except VRE. The second level adds ramping room in VRE units (typically only downward, unless they have been curtailed. Finally, the last level adds potential ramping capability in the connections, which reflects only the ramproom in the connections themselves - the units/nodes behind the connection may or may not have capability to provide that ramp. (Parameter node_ramp_t)</li> <li><code>output_connection_flow_separate</code>: Default, no. Produces the connection flows separately for both directions.</li> <li><code>output_unit__node_ramp_t</code>: Default, no. Produces the ramps of individual units for all timesteps.</li> <li><code>output_horizon</code>: Outputs the timesteps of the horizon outside the realized timesteps. Useful when constructing a stochastic model.</li> </ul> <p></p>"},{"location":"how_to/#how-to-make-the-flextool-run-faster","title":"How to make the Flextool run faster","text":"<p>The list below contains potential ways to decrease the run-time of FlexTool models.</p> <p>External changes (results will remain the same):</p> <ul> <li>Keep both the input database and Flextool on the same drive. If the database is on a different drive, it can slow the process. Avoid network drives.</li> <li>Try to ensure that there is sufficient memory available by closing other programs that use lot of memory. Linear optimization problems can require lot of memory.</li> <li>Use as fast computer as available. Both faster processors and more processors can decrease computation time.</li> </ul> <p>Model changes (results will remain the same):</p> <ul> <li>Disable outputs that you don't need. This will speed up the result processing. See: How to enable/disable outputs</li> <li>When using HiGHS solver: in your solve's parameters, you can set highs_presolve = on, and highs_parallel = on to speed up the optimisation. However, it can be better to turn HiGHS parallel off when executing multiple scnearios in parallel.</li> <li>Especially with MIP problems, considering using a commercial solver like CPLEX (license required). See: How to use CPLEX as the solver</li> </ul> <p>Model changes (results will be affected):</p> <ul> <li>Get rid of integer variables. Mixed integer programming can increase the solving time manyfold compared to the linear version especially if commercial solver is not available. MIP parameters are:</li> <li><code>transfer_method</code>: exact, change to reqular</li> <li><code>startup_method</code>: binary, change to linear</li> </ul> <p>Model changes (potentially large changes to the results --&gt; need to understand how the particular analysis will be affected):</p> <ul> <li>Use representative periods for investment decisions. See: How to create a multi-year model</li> <li>Split the timeline into parts. The solving time increases exponentially with the model size. Multiple smaller solves can be faster. Splitting is best done with Rolling window solve and Nested rolling solve. See: How to use a rolling window for a dispatch model, How to use Nested Rolling window solves (investments and long-term storage)</li> <li>Aggregate data. Technological: Combine power plants that are using the same technology. Spatial: Combine nodes. Temporal: Use longer timesteps.</li> </ul>"},{"location":"install_toolbox/","title":"Installing IRENA FlexTool - SpineToolbox","text":""},{"location":"install_toolbox/#installing-spine-toolbox-and-irena-flextool-on-a-local-computer","title":"Installing Spine Toolbox and IRENA FlexTool on a local computer","text":"<p>Follow video tutorial for installation here: Link to YouTube.</p> <ul> <li>Install Miniconda (or Anaconda)  [Can be ignored if already installed]</li> <li>Start Anaconda prompt</li> <li>Create new Python environment [Also possible to use existing, up-to-date, Spine Toolbox environment]</li> </ul> <pre><code>conda create -n flextool python=3.8\n</code></pre> <ul> <li>Activate the environment</li> </ul> <pre><code>conda activate flextool\n</code></pre> <ul> <li>Install Git to the environment [Also possible to use existing Git installation]</li> </ul> <pre><code>conda install git\n</code></pre> <ul> <li><code>cd</code> to a directory into which both FlexTool and Spine Toolbox will make their own folders</li> <li>Clone the FlexTool Git repository</li> </ul> <pre><code>git clone https://github.com/irena-flextool/flextool\n</code></pre> <p>Install Spine Toolbox [Can be skipped if using existing Toolbox environment]</p> <ul> <li>Clone the Toolbox repository</li> </ul> <pre><code>git clone https://github.com/Spine-project/Spine-Toolbox.git\n</code></pre> <ul> <li>cd to the freshly created folder</li> </ul> <pre><code>cd Spine-Toolbox\n</code></pre> <ul> <li>Make sure Pip is up-to-date</li> </ul> <pre><code>python -m pip install --upgrade pip\n</code></pre> <ul> <li>Install packages required by Toolbox</li> </ul> <pre><code>python -m pip install -r requirements.txt\n</code></pre> <p>In case of problems when installing Spine Toolbox, more instructions are available at: https://github.com/Spine-project/Spine-Toolbox#installation</p> <p>Generate databases from templates:</p> <ul> <li><code>cd</code> back to the flextool repository folder. Most likely:</li> </ul> <pre><code>cd ../flextool\n</code></pre> <ul> <li>Run update_flextool.py script. This will generate the Input_data.sqlite and Results.sqlite from their templates. These are not directly in the repository to avoid future overwrites. Update_flextool.py can also be used later when one wants to update the tool.  </li> </ul> <pre><code>python update_flextool.py\n</code></pre>"},{"location":"install_toolbox/#starting-irena-flextool-in-spine-toolbox","title":"Starting IRENA FlexTool in Spine Toolbox","text":"<ol> <li>Open a conda prompt.</li> <li> <p>Activate the environment</p> <p><code>conda activate flextool</code></p> </li> <li> <p>Launch Spine Toolbox</p> <p><code>python -m spinetoolbox</code></p> </li> <li> <p>Open FlexTool3 project in Spine Toolbox (Choose the flextool folder from File &gt; Open project dialog)</p> </li> </ol>"},{"location":"install_toolbox/#updating-irena-flextool","title":"Updating IRENA FlexTool","text":""},{"location":"install_toolbox/#updates-for-version-314-or-later","title":"Updates for version 3.1.4 or later:","text":"<ul> <li>Start anaconda/miniconda prompt</li> <li><code>conda activate flextool</code> (or whatever is your conda environment name for IRENA FlexTool)</li> </ul> <p>If using Spine Toolbox, start by updating Spine Toolbox:</p> <ul> <li>cd to the repository folder Spine-Toolbox, where you cloned it.  For example <code>cd C:\\Users\\YourUser\\Documents\\Spine-Toolbox</code></li> <li><code>git pull</code></li> <li><code>python -m pip install -U -r requirements.txt</code></li> <li>cd back to FlexTool directory, where you cloned it.  For example <code>cd C:\\Users\\YourUser\\Documents\\flextool</code></li> </ul> <p>Update IRENA FlexTool:</p> <ul> <li>cd to the FlexTool directory</li> <li><code>python update_flextool.py</code></li> <li>This will pull the new version of the tool as well as migrating the input databases to the new version without destroying the data. Making a backup copy of the input data is still a good practice. The input_data_template.sqlite should not be used directly but by making a copy of it. <ul> <li>The updated databases are: <ul> <li>The database chosen as the input data in the tool!!!</li> <li>init.sqlite</li> <li>input_data_template.sqlite</li> <li>time_settings_only.sqlite</li> <li>how to example databases</li> </ul> </li> </ul> </li> <li>If the git complains about merge conflicts, it is probably due to you modifying the template files. Use <code>git restore .</code>  and <code>git pull</code>. This will restore ALL the files downloaded from the repository to their original states. Then repeat <code>python update_flextool.py</code></li> <li> <p>The Results.sqlite will only get additive changes, as we do not want to destroy your data. This causes old parameter definitions to linger in the database. You can remove them by replacing the database with a copy of the Results_template.sqlite that is kept up to date.</p> </li> <li> <p>One can also migrate other input databases to the new version by calling:</p> <ul> <li><code>python migrate_database.py *absolute_path_to_database*</code> or</li> <li><code>python migrate_database.py database_name.sqlite</code> if in the main flextool folder</li> </ul> </li> </ul>"},{"location":"install_toolbox/#old-version-release-313-or-earlier","title":"Old version (release 3.1.3 or earlier):","text":"<p>Update of IRENA FlexTool to the latest version is done as follows:</p> <ul> <li>Start anaconda prompt</li> <li><code>conda activate flextool</code> (or whatever is your conda environment name for IRENA FlexTool)</li> <li>cd to the FlexTool directory</li> <li><code>git restore .</code> (THIS WILL DELETE YOUR LOCAL CHANGES TO THE FILES IN THE WORKFLOW. This will be improved in the future. Currently you can work around this by making your own input files (Excel or SQLite) and pointing the workflow items (Excel_input_data or Input_Data) to your own files instead of the input_data.sqlite or FlexTool_import_template.xlsx.) </li> <li><code>git pull</code> Then do the update_flextool discribed above to migrate the databases:</li> <li><code>python update_flextool.py</code></li> </ul>"},{"location":"install_web_interface/","title":"Installing IRENA FlexTool - Web interface","text":""},{"location":"install_web_interface/#installing-irena-flextool-with-a-web-server","title":"Installing IRENA FlexTool with a web server","text":"<p>Installation instructions are in the FlexTool web server repository: here. The browser interface is shown here.</p>"},{"location":"interface_overview/","title":"Overview of the interfaces to Flextool","text":"<ul> <li>Install a front-end: Install Spine Toolbox and run IRENA FlexTool as a Spine Toolbox project. This gives you the graphical user interface of Spine Toolbox. https://github.com/Spine-project/Spine-Toolbox. The interface and instructions to it are shown Toolbox interface</li> <li>Use a browser: IRENA FlexTool can be accessed with a web browser if you have an account for an IRENA FlexTool server. However, no public servers are available at the moment. The browser interface is introduced here.</li> <li>Local server: It is possible to setup a local server and then use a browser to access that server. See https://github.com/irena-flextool/flextool-web-interface</li> </ul>"},{"location":"reference/","title":"Main entities to define a power/energy system","text":"<p>Elemental entities (one dimensional):</p> <ul> <li><code>node</code>: maintain a balance between generation, consumption, transfers and storage state changes (nodes can also represent storages)</li> <li><code>unit</code>: power plants or other conversion devices that take one or more inputs and turn them into one or more outputs</li> <li><code>connection</code>: transmission lines or other transfer connections between nodes</li> <li><code>commodity</code>: fuels or other commodities that are either purchased or sold at a price outside of the model scope</li> <li><code>profile</code>: timeseries that can be used to constraint the behaviour of units, connections or storages</li> <li><code>reserve</code>: reserve categories to withhold capacity to cope with issues outside of model scope</li> </ul> <p>Entities with two or more dimensions:</p> <ul> <li><code>unit__inputNode</code> and <code>unit__outputNode</code>: defines the inputs, outputs and their properties for the conversion units</li> <li><code>connection__node__node</code>: defines which nodes a connection will connect</li> <li><code>unit__node__profile</code> and <code>connection__profile</code>: defines a profile limit (upper, lower or fixed) for an energy flow</li> <li><code>node__profile</code>: defines a profile limit (upper, lower, or fixed) for the storage state of the node</li> <li><code>commodity__node</code>: defines if a node is a source or sink for a commodity</li> <li><code>reserve__upDown__unit__node</code> and <code>reserve__upDown__connection__node</code>: reserve capacity from a source to the target node</li> </ul> <p>See below for more detailed explanations.</p> <p></p>"},{"location":"reference/#how-to-define-the-temporal-properties-of-the-model","title":"How to define the temporal properties of the model","text":""},{"location":"reference/#timesteps-and-periods","title":"Timesteps and periods","text":"<p>FlexTool has two different kinds of time varying parameters. The first one represents a regular timeline based on timesteps. The duration of each timestep can be defined by the user. There can be multiple timelines in the database - the user needs to define which timeline to use (and what parts of the timeline should be used, as will be explained later). The timestep names in the timeline are defined by the user - they can be abstract like 't0001' or follow a datetime format of choice. However, the timestep names between different timelines must remain unique (usually there should be only one timeline in a database and therefore no issues).</p> <p>The second time varying dimension is <code>period</code>, which is typically used to depict assumptions about the future. One model can include multiple <code>solves</code> that the model will solve in sequence (to allow multi-stage modelling). Each solve can include multiple <code>periods</code> (so that the user can change parameter values for different parts of the future).</p> <p>A parameter of particular type can be either constant/time-varying or constant/period-based. For example <code>inflow</code> is either a constant or time-varying, but it cannot be period-based.</p>"},{"location":"reference/#timeblocksets","title":"Timeblocksets","text":"<p>Timeblocks pick one or more sections from the <code>timeline</code> to form a <code>timeblockset</code>. Each timeblock defines a start and a duration. The aim of timeblocksets is to allow the modeller to create models with representative periods often used in the investment planning.</p>"},{"location":"reference/#definitions","title":"Definitions","text":"<ul> <li> <p><code>model</code>: model defines the sequence of solves to be performed (e.g. first an investment solve and then a dispatch solve)</p> </li> <li> <p>solves: sequence of solves in the model represented with an array of solve names.</p> </li> <li>discount_offset_investment: [years] Offset from the period (often year) start to the first payment of the investment cost annuity.</li> <li> <p>discount_offset_operations: [years] Offset from the period (often year) start to the payment of operational costs.</p> </li> <li> <p><code>solve</code>: each solve is built from an array of periods (e.g. one period for 2025 and another for 2030). Periods use timeblocksets to connect with a timeline.</p> </li> <li> <p>period_timeblockset: map of periods with associated timeblocks that will be included in the solve. Index: period name, value: timeblockSet name.</p> </li> <li>realized_periods: these are the periods the model will 'realize' - i.e., what periods will be reported in the results from this solve</li> <li>realized_invest_periods Array of the periods that will realize the investment decisions. If this is not defined when the invest_periods exist, the realized_periods are used to realize the invests as well</li> <li>invest_periods: array of periods where investements are allowed in this solve (applies only to objects that can be invested in)</li> <li>years_represented: Map to indicate how many years the period represents before the next period in the solve. Used for discounting. Can be below one (multiple periods in one year). Index: period, value: years.</li> <li>solver: choice of a solver ('highs'(default), 'glpsol', 'cplex' (requires a licence))</li> <li>highs_method: HiGHS solver method ('simplex' or 'ipm' which is interior point method). Should use 'choose' for MIP models, since 'simplex' and 'ipm' will not work.</li> <li>highs_parallel: HiGHS parallelises single solves or not ('on' or 'off'). It can be better to turn HiGHS parallel off when executing multiple scnearios in parallel.</li> <li>highs_presolve: HiGHS uses presolve ('on') or not ('off'). Can have a large impact on solution time when solves are large. </li> <li>solve_mode: a single solve or a set of rolling optimisation windows solved in a sequence </li> <li> <p>Rolling window parameters:</p> <ul> <li>rolling_solve_jump: Hours, (Required if rolling_window solve). Interval between the start points of the rolls. Also the output interval. This should be smaller than the horizon</li> <li>rolling_solve_horizon: Hours, (Required if rolling_window solve). The length of the horizon of the roll. How long into the future the roll sees. For an individual roll, horizon is the solve length and jump is the output length.</li> <li>rolling_duration: Hours, (Optional). Duration of rolling, if not stated, assumed to be the whole timeline of the solve</li> </ul> </li> <li> <p>Nested solve sequence parameters:</p> <ul> <li>contains_solve: Array of solves that are run with after this solve using the realized data of this solve. Read 'How to use Nested Rolling window solves (investments and long term storage)'</li> <li>fix_storage_periods: Array of periods where the last storage value of the long term storage node is passed to the contained solve as a target. (Defined using the node parameter <code>storage_nested_fix_method</code>)</li> </ul> </li> <li> <p>Stochastic parameters:</p> <ul> <li>stochastic_branches: 4D-map to set up the stochastic branches, their weights and to choose which of them are realized. See 'How to use stochastics' for more information.</li> </ul> </li> <li> <p>For commercial solvers:</p> <ul> <li>solver_precommand the commandline text in front of the call for the commercial (CPLEX) solver. For a possibility of reserving a floating licence for the duration of the solve</li> <li>solver_arguments Array of additional commands passed to the commercial solver. Made for setting optimization parameters.</li> </ul> </li> <li> <p><code>timeblockset</code>: timeblocksets are sets of timeblocks with a start (from timeline) and a duration (number of time steps)</p> </li> <li> <p>block_duration a map with index timestep_name that starts the timeblock and value that defines the duration of the block (how many timesteps)</p> </li> <li> <p>new_stepduration: Hours. Creates a new <code>timeline</code> from the old for this <code>timeblockSet</code> with this timestep duration. The new timeline will sum or average the other timeseries data like <code>profile</code> and <code>inflow</code> for the new timesteps. </p> </li> <li> <p><code>timeline</code>: continuous timeline with a user-defined duration for each timestep. Timelines are used by time series data.</p> </li> <li> <p>timestep_duration: a map with timestep_name as an index and duration as a value.</p> </li> <li> <p>timeline_duration_in_years Total duration of the timeline in years. Used to relate operational part of the model with the annualized part of the model.</p> </li> <li> <p><code>timeblockset__timeline</code>: defines which timeline object particular timeblockset is using.</p> </li> </ul>"},{"location":"reference/#nodes","title":"Nodes","text":""},{"location":"reference/#defining-how-the-node-functions","title":"Defining how the node functions","text":"<p>These parameters will define how the node will behave and use the data it is given (available choices are marked in italics):</p> <ul> <li><code>name</code> - unique name identifier (case sensitive)</li> <li><code>is_active</code> - is the model/node/unit active in a specific scenario: yes (if not defined, then not active)</li> <li><code>has_balance</code> - does the node maintain a balance for inputs and outputs: yes (if not defined, then balance is not maintained)</li> <li><code>has_storage</code> - does the node represent a storage and therefore have a state: yes (if not defined, then no storage)</li> <li><code>invest_method</code> - Choice of investment method: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>inflow_method</code> - choice how to treat inflow time series<ul> <li>use_original - does not scale the original time series (no value defaults here)</li> <li>no_inflow - ignores any inserted inflow time series</li> <li>scale_to_annual_flow - will scale the time series to match the <code>annual_flow</code> so that the sum of inflow is multiplied by 8760/<code>hours_in_solve</code></li> <li>scale_in_proprotion - calculates a scaling factor by dividing <code>annual_flow</code> with the sum of time series inflow (after it has been annualized using <code>timeline_duration_in_years</code>)</li> <li>scale_to_annual_and_peak_flow - scales the time series to match the 'annual_flow' target while transforming the time series to match the highest load with the 'peak_inflow'</li> </ul> </li> </ul> <p></p>"},{"location":"reference/#data-for-nodes","title":"Data for nodes","text":"<p>Input data is set with the following parameters:</p> <ul> <li><code>inflow</code> - [MWh] Inflow into the node (negative is outflow). Constant or time series.</li> <li><code>annual_flow</code> - [MWh] Annual flow in energy units (always positive, the sign of inflow defines in/out). Constant or period.</li> <li><code>existing</code> - [MWh] Existing storage capacity (requires <code>has_storage</code>). Constant.</li> <li><code>invest_cost</code> - [CUR/kWh] Investment cost for new storage capacity. Constant or period.</li> <li><code>salvage_value</code> - [CUR/kWh] Salvage value of the storage. Constant or period.</li> <li><code>lifetime</code> - [years] Life time of the storage unit represented by the node. Constant or period.</li> <li><code>interest_rate</code> - [unitless, e.g. 0.05 means 5%] Interest rate for investments. Constant or period.</li> <li><code>invest_max_total</code> - [MWh] Maximum storage investment over all solves. Constant.</li> <li><code>invest_max_period</code> - [MWh] Maximum storage investment for each period. Period.</li> <li><code>invest_min_total</code> - [MWh] Minimum storage investment over all solves. Constant.</li> <li><code>invest_min_period</code> - [MWh] Minimum storage investment for each period. Period.</li> <li><code>fixed_cost</code> - [CUR/kWh] Annual fixed cost for storage. Constant or period.</li> <li><code>penalty_up</code> - [CUR/MWh] Penalty cost for decreasing consumption in the node with a slack variable. Constant or time. Default value is 10 000, but this can be changed from the database.</li> <li><code>penalty_down</code> - [CUR/MWh] Penalty cost for increasing consumption in the node with a slack variable. Constant or time. Default value is 10 000, but this can be changed from the database.</li> <li><code>virtual_unitsize</code> - [MWh] Size of a single storage unit - used for integer investments (lumped investments). If not given, assumed from the existing storage capacity.</li> <li><code>self_discharge_loss</code> - [e.g. 0.01 means 1% every hour] Loss of stored energy over time. Constant or time.</li> <li><code>availablity</code> - [e.g. 0.9 means 90%] Fraction of capacity available for storage. Constant or time.</li> </ul>"},{"location":"reference/#using-nodes-as-storages","title":"Using nodes as storages","text":"<p>FlexTool manages storages through nodes. A regular node maintains an energy/material balance between all inputs and outputs (<code>has_balance</code> set to yes). A storage node includes an additional state variable, which means that the node can also use charging and discharging of the storage while maintaining the energy balance. A storage node is created by setting <code>has_storage</code> to yes and by adding storage capacity using the <code>existing</code> parameter and/or by letting the model invest in storage capacity (<code>invest_method</code>, <code>invest_cost</code>, <code>invest_max_period</code> and <code>invest_max_total</code> parameters).</p> <p>Since FlexTool allows different temporal structures (multi-periods, rolling optimization, etc.) there needs to be ways to define how the storages behave when the model timeline is not fully consequtive. By default, storages are forced to match start level to the end level within timeblocks. This is an acceptable setting for small storages that do not carry meaningful amounts of energy between longer time periods in the model.</p> <p>There are three methods associated with storage start and end values: <code>storage_binding_method</code>, <code>storage_start_end_method</code> and <code>storage_solve_horizon_method</code>. </p> <ul> <li>The most simple one of these is the <code>storage_start_end_method</code> and it overrides the other methods, since it forces the start and/or the end state of the storage to a predefined value based on the proportional parameters <code>storage_state_start</code> and <code>storage_state_end</code> (proportional means that the parameter needs to be set between 0-1 and will be scaled by the storage capacity in the model). These two parameters affect only the first and the last timesteps of the entire model (even when the model has more than one solve).</li> <li><code>storage_binding_method</code> states how the storage should behave over discontinuities in the model timeline. Model timeline can have jumps for three different reasons: timeblocks, periods, and solves. If <code>storage_binding_method</code> is bind_within_timeblock, then the storage has to match the state of the storage between the beginning and the end of each timeblock. In effect, storage_state_at_start_of_timeblock equals storage_state_at_end_of_timeblock plus charging minus discharging minus self_discharge_loss at the last timestep. Similarly, bind_within_period will force the start and end between periods, but it will treat the jumps between timeblocks as continuous from the storage perspective (the storage will continue from where it was at the end of the previous timeblock). bind_within_solve does effectively the same when there are multiple periods within one solve. bind_within_model (NOT IMPLEMENTED 19.3.2023) will extend the continuity to multiple solves and force the end state of the storage at the end of the last solve to match the beginning state of the storage at the start of the first solve. Finally, bind_forward_only will force continuity in the storage state over the whole model without forcing the end state to match the beginning state.</li> <li><code>storage_solve_horizon_method</code> is meant for models that roll forward between solves and have an overlapping temporal window between those solves (e.g. a model with 36 hour horizon rolls forward 24 hours at each solve - those 12 last hours will be overwritten by the next solve). In these cases, the end state of the storage will be replaced by the next solve, but it can be valuable to have some guidance for the end level of storage, since it will affect storage behaviour. There are three methods: free is the default and will simply let the model choose where the storage state ends (usually the storage will be emptied, since it would have no monetary value). use_reference_value will use the value set by <code>storage_state_reference_value</code> to force the end state in each solve to match the reference value. use_reference_price will give monetary value for the storage content at the end of the solve horizon set by the <code>storage_state_reference_price</code> parameter - the model is free to choose how much it stores at the end of horizon based on this monetary value.</li> </ul> <p>-Method hierarchy:</p> <ol> <li><code>storage_start_end_method</code></li> <li><code>storage_binding_method</code></li> <li><code>storage_solve_horizon_method</code></li> </ol> <p>-Meaning:</p> <ul> <li>The <code>storage_binding_method</code> is ignored (exeption bind_forward_only), if <code>storage_start_end_method</code> has the value fix_start_end,</li> <li>The <code>storage_solve_horizon_method</code> use_reference_value is ignored, if other storage state methods are used. Only exeptions are fix_start or bind_forward_only</li> </ul> <p>-Nested Parameters:</p> <ul> <li><code>storage_nested_fix_method</code>: Set this storage as a long term storage, which end state is passed to the lower level solves as a target. Fix_price requires <code>storage_state_reference_price</code></li> </ul>"},{"location":"reference/#units","title":"Units","text":"<p>Units convert energy (or matter) from one form to another (e.g. open cycle gas turbine), but the can also have multiple inputs and/or outputs (e.g. combined heat and power plant). The input nodes are defined with the relationship <code>unit--inputNode</code> while the output nodes are defined through the relationship <code>unit--outputNode</code>.</p>"},{"location":"reference/#defining-how-the-unit-functions","title":"Defining how the unit functions","text":"<ul> <li><code>is_active</code> to state the alternative where the unit becomes active</li> <li>'conversion_method' to define the way unit converts inputs to outputs </li> <li><code>startup_method</code> - Choice of startup method. 'Linear' startup means that the unit can start partially (anything between 0 and full capacity) but will face startup cost as well as minimum load limit based on the capacity started up. 'Binary' startup means that the unit is either off or fully on, but it is computationally more demanding than linearized startups.</li> <li><code>minimum_time_method</code> - Not functional yet. Choice between minimum up- and downtimes (, min_downtime, min_uptime, both)."},{"location":"reference/#main-data-items-for-units","title":"Main data items for units","text":"<ul> <li>Capacity: <code>existing</code> (and the investment and retirement parameters below)</li> <li> <p>Technical: <code>efficiency</code>, <code>min_load</code>, <code>efficiency_at_min_load</code>, <code>min_uptime</code>, <code>min_downtime</code></p> <ul> <li> <p><code>min_load</code> - [0-1] Minimum load of the unit. Applies only if the unit has an online variable. With linear startups, it is the share of capacity started up. Constant or time. Calculated for all timesteps: </p> </li> <li> <p>the sum of output flows &gt;= minimum_load * capacity</p> </li> </ul> </li> <li> <p><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for flows from/to the unit. For online units, the online variable is multiplied by the availability. Constant or time.</p> </li> <li>Economic: <code>startup_cost</code>, <code>fixed_cost</code> (fuel cost comes through the use of fuel commodities and other variable costs are defined for flows between unit and node, see below)</li> </ul>"},{"location":"reference/#investment-parameters-for-capacity-expansion","title":"Investment parameters for capacity expansion","text":"<ul> <li><code>invest_method</code> - Choice of investment method: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>lifetime_method</code> to choose how the investments behave after unit runs out of lifetime. Automatic reinvestment (reinvest_automatic - default) causes the model to keep the capacity until the end of model horizon and applies the annualized investment cost until the end of model horizon without further choice by the model. Choice of reinvestment (reinvest_choice) removes the capacity at the end of the lifetime and the model needs to decide how much new capacity is to be built. If there is a need to remove the possibility to invest after lifetime, then the investment limits can be used.</li> <li><code>invest_cost</code> - [CUR/kW] Investment cost for new capacity. Constant or period.</li> <li><code>salvage_value</code> - [CUR/kW] Salvage value of the unit capacity. Constant or period.</li> <li><code>lifetime</code> - [years] Lifetime of the unit. Constant or period.</li> <li><code>interest_rate</code> - [unitless, e.g. 0.05 means 5%] Interest rate for investments. Constant or period.</li> <li><code>invest_max_total</code> - [MW] Maximum capacity investment over all solves. Constant.</li> <li><code>invest_max_period</code> - [MW] Maximum capacity investment for each period. Period.</li> <li><code>invest_min_total</code> - [MW] Minimum capacity investment over all solves. Constant.</li> <li><code>invest_min_period</code> - [MW] Minimum capacity investment for each period. Period.</li> <li><code>retire_cost</code> - [CUR/kW] Retirement cost for new capacity. Constant or period.</li> <li><code>retire_max_total</code> - [MW] Maximum capacity retirement over all solves. Constant.</li> <li><code>retire_max_period</code> - [MW] Maximum capacity retirement for each period. Period.</li> <li><code>retire_min_total</code> - [MW] Minimum capacity retirement over all solves. Constant.</li> <li><code>retire_min_period</code> - [MW] Minimum capacity retirement for each period. Period.</li> <li><code>fixed_cost</code> - [CUR/kW] Annual fixed cost for capacity. Constant or period. </li> <li><code>virtual_unitsize</code> - [MWh] Size of a single unit - used for integer investments (lumped investments). If not given, assumed from the existing capacity.</li> </ul>"},{"location":"reference/#discount-calculations","title":"Discount calculations","text":"<p>Each asset that can be invested in should have <code>invest_cost</code>, <code>lifetime</code> and <code>interest_rate</code> parameters set and could have an optional <code>fixed_cost</code>. These are used to calculate the annuity of the investment. Annuity is used to annualize the investment cost, since FlexTool scales all costs (operational, investment and fixed) to annual level in order to make them comparable. Annuity is calculated as follows:</p> <p><code>invest_cost</code> * <code>interest_rate</code> / { 1 - [ 1 / ( 1 + <code>interest_rate</code> ) ] ^ <code>lifetime</code> } + <code>fixed_cost</code></p> <p>The next step is to consider discounting - future is valued less than the present. There is a model-wide assumption for the <code>discount_rate</code>. By default it is 0.05 (i.e. 5%), but it can be changed through the <code>discount_rate</code> parameter set for the flexTool <code>model</code> object. Discount factor for every period in the model is calculated from the <code>discount_rate</code> using the <code>years_represented</code> parameter of each <code>solve</code>, which how many years the period represents. Values for <code>years_represented</code> are used to calculate how many <code>years_from_solve_start</code> each year is. The formula is:</p> <p>[ 1 / ( 1 + <code>discount_rate</code> ) ] ^ <code>years_from_solve_start</code></p> <p>Operational costs are also discounted using the same <code>discount_rate</code>. However, with operational costs it is assumed that they take place on average at the middle of the year whereas investment costs are assumed to take place at the beginning of the year (they are available for the whole year). These can be tweaked with the <code>discount_offset_investments</code> and <code>discount_offset_operations</code> parameters (given in years). Please note that given this formulation, <code>invest_cost</code> should be the overnight built cost (as is typical in energy system modelling, the model does not assume any construction time - the financing costs of the construction period need to be included in your cost assumptions).</p> <p>The model has a model horizon based on the <code>years_represented</code> parameters. The model will not include discounted investment annuities after the model horizon (in other words, the investments are 'returned' at the end of the model horizon). Naturally also operational costs are included only until the end of the model horizon. </p> <p>Finally, the retirements work similar to investments using the same <code>discount_rate</code> and <code>interest_rate</code> parameters but with <code>salvage_value</code> as the benefit from retiring the unit.</p>"},{"location":"reference/#relationship-of-a-unit-to-a-node-and-determination-of-the-type-of-relationship","title":"Relationship of a unit to a node and determination of the type of relationship","text":"<ul> <li>If the unit\u2019s outputs are flowing into the node, the node acts as output for the unit.</li> <li>If the unit\u2019s inputs are flowing out of the node (into the unit), the node acts as input for the unit.</li> <li>Not all units necessary have both an input and an output node. E.g. VRE generators have only output nodes and their generation is driven by profiles</li> </ul>"},{"location":"reference/#properties-of-unit-inputnode-and-unit-outputnode-relationships","title":"Properties of unit--inputNode and unit--outputNode relationships","text":"<ul> <li><code>is_non_synchronous</code> - Chooses whether the unit is synchronously connected to this node.</li> <li><code>coefficient</code> - [factor] Coefficient to scale the output from a unit to a particular node or the input from a node. Can be used e.g. to change unit of measurement or to remove the flow by using zero as the coefficient (the flow variable can still be used in user constraints). Note that in the case of unit--outputNode the <code>coefficient</code> affects after the capacity and the other unit constraints. Constant.</li> <li><code>other_operational_cost</code> - [CUR/MWh] Other operational variable costs for energy flows. Constant or time. </li> <li><code>inertia_constant</code> - [MWs/MW] Inertia constant for a synchronously connected unit to this node. Constant.</li> <li><code>ramp_method</code> - Choice of ramp method. 'ramp_limit' poses a limit on the speed of ramp. 'ramp_cost' poses a cost on ramping the flow (NOT FUNCTIONAL AS OF 19.3.2023).</li> <li><code>ramp_cost</code> - [CUR/MW] Cost of ramping the unit. Constant.</li> <li><code>ramp_speed_up</code> - [per unit / minute] Maximum ramp up speed. Constant.</li> <li><code>ramp_speed_down</code> - [per unit / minute] Maximum ramp down speed. Constant.</li> </ul>"},{"location":"reference/#units-constrained-by-profiles","title":"Units constrained by profiles","text":"<p>Some generators (e.g. VRE) are not converting energy from one node to the other. Instead, their generation is determined (or limited) by a specific generation profile set by a <code>profile</code> object with a <code>profile_method</code>, thats state whether the profile forces an upper_limit, lower_limit or equality. Finally <code>profile</code> object is given a <code>profile</code> time series (or it can also be a constant). One needs to use <code>node__profile</code>, <code>unit__node__profile</code> or <code>connection__profile</code> to apply the profile to specific energy flow (or storage state in the case of <code>node__profile</code>).</p>"},{"location":"reference/#connections","title":"Connections","text":"<p>Connections can transfer energy between two nodes. Parameters for the connection are defined in the <code>connection</code> object, but the two <code>nodes</code> it connects are defined by establishing a relationship between <code>connection--leftNode--rightNode</code>.</p>"},{"location":"reference/#defining-how-the-connection-functions","title":"Defining how the connection functions","text":"<ul> <li><code>is_active</code> to state the alternative where the connection becomes active</li> <li><code>transfer_method</code> to define the way the connection transfers energy between the nodes</li> <li><code>startup_method</code> where linear startup means that the unit can start partially (anything between 0 and full capacity) but will face startup cost as well as minimum load limit based on the capacity started up. binary startup means that the unit is either off or fully on, but it is computationally more demanding than linearized startups.</li> <li><code>invest_method</code> to define investment and retirement limits: either not_allowed or then a combination of <ul> <li>invest and/or retire </li> <li>investment limits for each period and/or for all periods (total) or no_limit </li> </ul> </li> <li><code>lifetime_method</code> to choose how the investments behave after unit runs out of lifetime. Automatic reinvestment (reinvest_automatic - default) causes the model to keep the capacity until the end of model horizon and applies the annualized investment cost until the end of model horizon without further choice by the model. Choice of reinvestment (reinvest_choice) removes the capacity at the end of the lifetime and the model needs to decide how much new capacity is to be built. If there is a need to remove the possibility to invest after lifetime, then the investment limits can be used.</li> </ul>"},{"location":"reference/#main-data-items-for-connections","title":"Main data items for connections","text":"<ul> <li><code>existing</code> - [MW] Existing capacity. Constant.</li> <li><code>efficiency</code> - [factor, typically between 0-1] Efficiency of a connection. Constant or time.</li> <li><code>constraint_capacity_coefficient</code> - A map of coefficients (Index: constraint name, value: coefficient) to represent the participation of the connection capacity in user-defined constraints.  [(invest - divest variable) x coefficient] will be added to the left side of the constraint equation. Invest and divest variables are not multiplied by unitsize.</li> <li><code>other_operational_cost</code> - [CUR/MWh] Other operational variable cost for trasferring over the connection. Constant or time.</li> <li><code>fixed_cost</code> - [CUR/kW] Annual fixed cost. Constant or period.</li> <li><code>invest_cost</code> - [CUR/kW] Investment cost for new 'virtual' capacity. Constant or period.</li> <li><code>interest_rate</code> - [e.g. 0.05 equals 5%] Interest rate for investments. Constant or period.</li> <li><code>lifetime</code> - [years] Used to calculate annuity together with interest rate. Constant or period.</li> <li>other investment parameters: <code>invest_max_total</code>, <code>invest_max_period</code>, <code>invest_min_total</code>, <code>invest_min_period</code>, <code>salvage_value</code></li> <li><code>is_DC</code> - A flag whether the connection is DC (the flow will not be counted as synchronous if there is a non_synchronous_limit). Default false.</li> <li><code>virtual_unitsize</code> - [MW] Size of single connection - used for integer (lumped) investments.</li> <li><code>availability</code> - [e.g. 0.9 means 90%] Fraction of capacity available for connection flows. Constant or time.</li> </ul>"},{"location":"reference/#investment-parameters-for-connections","title":"Investment parameters for connections","text":"<p>These are the same as for units, see here</p>"},{"location":"reference/#commodities","title":"Commodities","text":"<p>Some <code>nodes</code> can act as a source or a sink of commodities instead of forcing a balance between inputs and outputs. To make that happen, commodities must have a <code>price</code> and be connected to those <code>nodes</code> that serve (or buy) that particular <code>commodity</code> at the given <code>price</code>. In other words, <code>commodity</code> is separate from <code>node</code> so that the user can use the same <code>commodity</code> properties for multiple nodes. Commodities can also have a <code>co2_content</code>. The <code>commodity</code> and its <code>nodes</code> are connected by establishin a new relationship between the <code>commodity</code> and each of its <code>nodes</code> (e.g. coal--coal_market).</p> <ul> <li><code>price</code> - [CUR/MWh or other unit] Price of the commodity. Constant or period.</li> <li><code>co2_content</code> - [CO2 ton per MWh] Constant.</li> </ul> <p></p>"},{"location":"reference/#groups","title":"Groups","text":"<p>Groups are used to make constraints that apply to a group of nodes, units and/or connections. A group is defined by creating a group object and then creating a relationship between the group and its members. The membership relationship classes are <code>group__node</code>, <code>group__unit</code>, <code>group__connection</code>, <code>group__unit__node</code>, <code>group__connection__node</code> and <code>reserve__upDown__group</code>. The choice of group members depends on what the group is trying to achieve. For instance a group that limits investments could have a set of <code>units</code> included in the group.</p>"},{"location":"reference/#capacity-limits-for-nodes-units-and-connections","title":"Capacity limits for nodes, units and connections","text":"<ul> <li><code>invest_method</code> - the choice of method how to limit or force investments in capacity [MW or MWh] of the group members</li> <li><code>invest_max_total</code> - [MW or MWh] Maximum investment to the virtual capacity of a group of units or to the storage capacity of a group of nodes. Total over all solves.</li> <li><code>invest_max_period</code> - [MW or MWh] Maximum investment per period to the virtual capacity of a group of units or to the storage capacity of a group of nodes.</li> <li><code>invest_min_total</code> - [MW or MWh] Minimum investment to the virtual capacity of a group of units or to the storage capacity of a group of nodes. Total over all solves. </li> <li><code>invest_min_period</code> - [MW or MWh] Minimum investment per period to the virtual capacity of a group of units or to the storage capacity of a group of nodes.</li> </ul>"},{"location":"reference/#cumulative-and-instant-flow-limits-for-unit__nodes-and-connection__nodes","title":"Cumulative and instant flow limits for <code>unit__node</code>s and <code>connection__node</code>s","text":"<ul> <li><code>max_cumulative_flow</code> - [MW] Limits the maximum cumulative flow for a group of connection_nodes and/or unit_nodes. It needs to be expressed as average flow, since the limit is multiplied by the model duration to get the cumulative limit (e.g. by 8760 if a single year is modelled). Applied for each solve. Constant or period.</li> <li><code>min_cumulative_flow</code> - [MW] Limits the minimum cumulative flow for a group of connection_nodes and/or unit_nodes. It needs to be expressed as average flow, since the limit is multiplied by the model duration to get the cumulative limit (e.g. by 8760 if a single year is modelled). Applied for each solve. Constant or period.</li> <li><code>max_instant_flow</code> - [MW] Maximum instantenous flow for the aggregated flow of all group members. Constant or period.</li> <li><code>min_instant_flow</code> - [MW] Minimum instantenous flow for the aggregated flow of all group members. Constant or period.</li> </ul>"},{"location":"reference/#limits-for-nodes","title":"Limits for nodes","text":"<ul> <li><code>has_inertia</code> - A flag whether the group of nodes has an inertia constraint active.</li> <li><code>inertia_limit</code> - [MWs] Minimum for synchronous inertia in the group of nodes. Constant or period.</li> <li><code>penalty_inertia</code> - [CUR/MWs] Penalty for violating the inertia constraint. Constant or period.</li> <li><code>has_non_synchronous</code> - A flag whether the group of nodes has the non-synchronous share constraint active.</li> <li><code>non_synchronous_limit</code> - [share, e.g. 0.8 means 80%] The maximum share of non-synchronous generation in the node group. Constant or period.</li> <li><code>penalty_non_synchronous</code> - [CUR/MWh] Penalty for violating the non synchronous constraint. Constant or period.</li> <li><code>has_capacity_margin</code> - A flag whether the group of nodes has a capacity margin constraint in the investment mode.</li> <li><code>capacity_margin</code> - [MW] How much capacity a node group is required to have in addition to the peak net load in the investment time series. Used only by the investment mode. Constant or period.</li> <li><code>penalty_capacity_margin</code> - [CUR/MWh] Penalty for violating the capacity margin constraint. Constant or period.</li> <li><code>share_loss_of_load</code> - Force the upward slack of the nodes in this group to be equal or inflow (demand) weighted</li> </ul>"},{"location":"reference/#co2-costs-and-limits","title":"CO2 costs and limits","text":"<ul> <li><code>co2_method</code> - Choice of the CO2 method or a combination of methods: no_method, price, period, total, price_period, price_total, period_total, price_period_total.</li> <li><code>co2_price</code> [CUR/ton] CO2 price for a group of nodes. Constant or period.</li> <li><code>co2_max_period</code> [tCO2] Annualized maximum limit for emitted CO2 in each period.</li> <li><code>co2_max_total</code> [tCO2] Maximum limit for emitted CO2 in the whole solve.</li> </ul>"},{"location":"reference/#stochastics","title":"Stochastics","text":"<ul> <li><code>include_stochastics</code> Flag to choose if stochastic timeseries are to be used for the units/nodes/connections of this group </li> </ul>"},{"location":"reference/#controlling-outputs","title":"Controlling outputs","text":"<p>Some results are output for groups of nodes. This means that instead of getting output for each node separately, nodes can be grouped and the aggregated results can be examined. For example it can be helpful to group all electricity nodes and show their aggregated output.</p> <ul> <li><code>output_results</code> - A flag to output aggregated results for the group members.</li> <li><code>output_node_flows</code> - A flag to create a timewise result of the flows in and out of the group of nodes</li> <li><code>output_aggregate_flows</code> - A flag that to sum the process (group_unit_node / group_process_node) flows of this group in the result table created by <code>output_node_flows</code> to different group of nodes (group_node)</li> </ul> <p>Some of the outputs are optional. They can be removed to speed up the post-processing of results. The user can enable/disable them by changing parameters of the the <code>model</code> entity:</p> <ul> <li><code>output_node_balance_t</code>: Default: yes. Produces detailed inflows and outflows for all the nodes for all timesteps. Mainly useful to diagnose what is wrong with the model. </li> <li><code>output_connection__node__node_flow_t</code>: Default: yes. The flows between the nodes for each timestep.</li> <li><code>output_unit__node_flow_t</code>: Default, yes. The flows from units to the nodes for each timestep.</li> <li><code>output_ramp_envelope</code>: Default, no. Includes seven parameters that form the ramp room envelope. How much there is additional ramping capability in a given node. (Parameter node_ramp_t)</li> <li><code>output_connection_flow_separate</code>: Default, no. Produces the connection flows separately for both directions.</li> <li><code>output_unit__node_ramp_t</code>: Default, no. Produces the ramps of individual units for all timesteps.</li> </ul> <p>Additionally a model level option to exclude all node, connection and unit level outputs and only leave group and model level results. This will significantly increase the speed of importing data to the result database.</p> <ul> <li>model: <code>exclude_entity_outputs</code>: Default, no. Excludes results on node, unit and connection level, but preserves group level results</li> </ul> <p>A further option is to output everything from the model horizon. This changes the behaviour of a rolling model, since it would otherwise output only the realized part of the model horizon. This option will also output all variables from the stochastic branches when the model uses those. This option is useful for debugging and constructing stochastic/rolling model. Outputting the unrealized part of the model horizon will include unrealized costs in the cost calculations, so costs will be too high and this option should not be used for the final results.</p> <ul> <li>model: <code>output_horizon</code>: Default, no. Produces outputs for the model horizon after <code>rolling_solve_jump</code>.</li> </ul>"},{"location":"reference/#reserves","title":"Reserves","text":"<p>The user defines reserve categories through <code>reserve</code> object. Reserves are reservations of capacity (either upward or downward) and that capacity will not therefore be available for other use (flowing energy or commodities). There are three different ways how a reserve requirement can be calculated: timeseries, large_failure and dynamic. </p> <ul> <li>Timeseries requires that the user provides a pre-defined time series for the amount of reserve to be procured in each time step. </li> <li>Large_failure requires that the user defines the energy flows that could be the largest failure in the system. The highest possible failure (flow multiplied by <code>large_failure_ratio</code>) in each timestep will then set the reserve requirement for that timestep. </li> <li>Dynamic means that there is a requirement based on user chosen energy flows - each participating flow is multipled by <code>increase_reserve_ratio</code> and then summed to form the reserve requirement. This can be useful for covering variability within timesteps. Also demand variability can be included through <code>increase_reserve_ratio</code> parameter in <code>reserve__upDown__group</code> relationship.</li> </ul> <p>When the same reserve category (e.g. primary upward) has more than one of these (timeseries, large_failure and dynamic) in use, then the largest requirement will apply for that timestep. If they are separated into different reserves, then they need to be fulfilled separately.</p> <p>Reserve requirement is defined for groups of nodes. This means that multiple nodes can have a common reserve requirement (but it is also possible to make a group with only one node). One node can be in multiple groups and therefore subject to multiple overlapping reserve requirements. Only units can generate reserve, but connections can move reserve from one node to another (therefore, there is no impact if the nodes are in the same reserve group, but it can be useful to import reserve from outside the group).</p>"},{"location":"reference/#reserve-groups","title":"Reserve groups","text":"<p>For <code>reserve__upDown__group</code> relationships:</p> <ul> <li><code>reserve_method</code> - Choice of reserve method (timeseries, large_failure, dynamic or their combination).</li> <li><code>reservation</code> - [MWh] Amount of reserve required. Constant or time.</li> <li><code>reserve_penalty</code> - [\u20ac/MWh] Penalty cost for not fulfilling the reserve requirement.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve is increased by the sum of demands from the group members multiplied by this ratio. Constant.</li> </ul>"},{"location":"reference/#reserve-provision-by-units","title":"Reserve provision by units","text":"<p>For <code>reserve__upDown__unit__node</code> relationships:</p> <ul> <li><code>is_active</code> - Can the unit provide this reserve. Empty indicates not allowed. Use 'yes' to indicate true.</li> <li><code>max_share</code> - [factor] Maximum ratio for the transfer of reserve from the unit to the node. Constant.</li> <li><code>reliability</code> - [factor] The share of the reservation that is counted to reserves (sometimes reserve sources are not fully trusted). Constant.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve requirement is increased by the flow between the unit and the node multiplied by this ratio. Constant.</li> <li><code>large_failure_ratio</code> - [factor] Each unit using the N-1 failure method will have a separate constraint to require sufficient reserve to cover a failure of the unit generation (multiplied by this ratio). Constant.</li> </ul>"},{"location":"reference/#reserve-transfer-by-connections","title":"Reserve transfer by connections","text":"<p>For <code>reserve__upDown__connection__node</code> relationships:</p> <ul> <li><code>is_active</code> - Can the unit provide this reserve. Empty indicates not allowed. Use 'yes' to indicate true.</li> <li><code>max_share</code> - [factor] Maximum ratio for the transfer of reserve to this node. Constant.</li> <li><code>reliability</code> - [factor] The share of the reservation that is counted to reserves (sometimes reserve sources are not fully trusted). Constant.</li> <li><code>increase_reserve_ratio</code> - [factor] The reserve is increased by generation from this unit multiplied this ratio. Constant.</li> <li><code>large_failure_ratio</code> - [factor] Each connection using the N-1 failure method will have a separate constraint to require sufficient reserve to cover a failure of the connection (multiplied by this ratio). Constant.</li> </ul>"},{"location":"reference/#additional-objects-for-further-functionality","title":"Additional objects for further functionality","text":"<ul> <li><code>constraint</code>: to create user defined constraints between flow, state, and capacity variables (for nodes, units and connections)</li> </ul>"},{"location":"results/","title":"Results","text":"<p>FlexTool outputs results typical to a planning model or a scheduling model, but it also tries to highlight potential flexibility issues in the system. The outputs from the latest run are initially CSV files and can befound in the folder 'output'. File 'summary_solve.csv' can give a quick overview of potential issues in the solve - it is a diagnostic file. The other files are all numerical results and will be imported to a Spine database by the FlexTool workflow.</p> <ul> <li>Costs</li> <li>Prices</li> <li>Energy flows</li> <li>Energy balance in nodes</li> <li>Group results</li> <li>Capacity and investment results</li> <li>CO2 emissions</li> <li>Reserves</li> <li>Inertia and non-synchronous generation</li> <li>Ramps</li> <li>Slack and penalty values</li> </ul>"},{"location":"results/#costs","title":"Costs","text":"<ul> <li><code>model</code> object <code>cost_annualized</code> parameter - M[CUR] (millions of user chosen currency) includes annualized total cost as well as annualized costs divided into </li> <li>unit investment/retirement - M[CUR] cost of investing in unit capacity or benefits from salvaging unit capacity</li> <li>connection investment/retirement - M[CUR] cost of investing in connection capacity or benefits from salvaging connection capacity</li> <li>storage investment/retirement - M[CUR] cost of investing in storage capacity or benefits from salvaging storage capacity</li> <li>commodity - M[CUR] cost of unit using commodity inputs or benefit of selling commodities (negative value)</li> <li>CO2 - M[CUR] cost of CO2 emissions caused by unit using commodities with CO2 content</li> <li>variable cost - M[CUR] other variable operation and maintenance costs</li> <li>starts - M[CUR] start up costs</li> <li>upward penalty - M[CUR] cost of involuntary demand reduction</li> <li>downward penalty - M[CUR] cost of involuntary demand increase</li> <li>inertia penalty - M[CUR] cost of not meeting the inertia constraint</li> <li>non-synchronous penalty - M[CUR] cost of not meeting the non-synchronous constraint</li> <li>capacity margin penalty - M[CUR] cost of not meeting the capacity margin constraint</li> <li>upward reserve penalty - M[CUR] cost of not meeting the upward reserve constraint</li> <li>downward reserve penalty - M[CUR] cost of not meeting the downward reserve constraint</li> <li><code>model</code> object <code>cost_t</code> parameter - M[CUR] similar as above but costs given for each timestep (no investment/retirement costs)</li> <li><code>model</code> object <code>cost_discounted_solve</code> paramater - M[CUR] Costs for the solve considering discounting and years presented (scaled to all years presented). Divided like in <code>cost_annualized</code></li> <li><code>model</code> object <code>cost_discounted_total</code> parameter - M[CUR] Total costs for all the solves considering discounting and years presented (scaled to all years presented). Divided like in <code>cost_annualized</code></li> </ul>"},{"location":"results/#prices","title":"Prices","text":"<ul> <li><code>node</code> object <code>price_t</code> parameter - [CUR/MWh] each node that maintains an energy balance provides a price time series based on the marginal value of the balance constraint</li> </ul>"},{"location":"results/#energy-flows","title":"Energy flows","text":"<ul> <li><code>unit__node</code> relationship <code>flow_annualized</code> parameter - [MWh] cumulative flow from the node (if node is input) or to the node (if node is output) annualized. Annualization scales the sum to correspond with full year time series.</li> <li><code>unit__node</code> relationship <code>flow_t</code> parameter - [MW] flow from the node (if node is input) or to the node (if node is output)</li> <li><code>connection__node__node</code> relationship <code>flow_annualized</code> parameter - [MWh] cumulative flow through the connection (left to right is positive) annualized</li> <li><code>connection__node__node</code> relationship <code>flow_t</code> parameter - [MW] flow through the connection (left to right is positive)</li> </ul>"},{"location":"results/#optional-output-output_connetion_flows_separate","title":"Optional output: output_connetion_flows_separate","text":"<ul> <li><code>connection__node__node</code> relationship <code>flow_to_first_node_annualized</code> parameter - [MWh] annualized cumulative flow through the connection only to the left (first) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_second_node_annualized</code> parameter - [MWh] annualized cumulative flow through the connection only to the right (second) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_first_node_t</code> parameter - [MW] flow through the connection to the left (first) node.</li> <li><code>connection__node__node</code> relationship <code>flow_to_second_node_t</code> parameter - [MW] flow through the connection to the right (second) node.</li> </ul>"},{"location":"results/#capacity-factors","title":"Capacity factors","text":"<ul> <li><code>unit__node</code> relationship <code>cf</code> parameter - [per unit] average capacity factor of the flow, i.e. the utilization rate of the flow from/to the unit. Average of flow [MWh/h] divided by capacity [MW] of the input or output to the unit.</li> <li><code>connection</code> relationship <code>cf</code> parameter - [per unit] average capacity factor of the flow, i.e. the utilization rate of the connection where flows in both directions are considered as utilization. Average of the absolute flow [MWh/h] divided by the capacity of the connection.</li> </ul>"},{"location":"results/#energy-balance-in-nodes","title":"Energy balance in nodes","text":"<ul> <li><code>node</code> object <code>balance</code> parameter - [MWh] cumulative inputs (positive) and outputs (negative) to the node from all the possible sources (from_units, from_connection, to_units, to_connections, state change over the period, self discharge during the period, upward slack for involuntary demand reduction and downward slack for involuntary demand increase)</li> <li><code>node</code> object <code>balance_t</code> parameter - [MW] same as above, but for each timestep</li> <li><code>node</code> object <code>state_t</code> parameter - [MWh] storage state of the node in each timestep</li> </ul>"},{"location":"results/#unit-online-and-startup","title":"Unit online and startup","text":"<ul> <li><code>unit</code> object <code>online_average</code> parameter - [count] average online status of the unit (average number of units online during the period)</li> <li><code>unit</code> object <code>online_t</code> parameter - [count] online status of the unit (number of units online in each timestep)</li> <li><code>unit</code> object <code>startup_cumulative</code> parameter - [count] cumulative number of unit startups during the period</li> </ul>"},{"location":"results/#unit-curtailment","title":"Unit curtailment","text":"<ul> <li><code>unit</code> object <code>curtailment_share</code> parameter - [0-1] Share of curtailed production from potential production for periods</li> <li><code>unit</code> object <code>curtailment_t</code> parameter - [MW] curtailed flow to the node</li> </ul>"},{"location":"results/#group-results","title":"Group results","text":"<ul> <li><code>group</code> object <code>indicator</code> parameter - gives a set of results for all <code>node</code> members of the <code>group</code></li> <li>sum of annualized inflows - [MWh] sum of <code>inflow</code> to the node which has been annualized (scaled to correspond to a year of timesteps)</li> <li>VRE share - [0-1] how much the flows from VRE sources (inputs using  'upper limit' profile) are of the inflow</li> <li>curtailed VRE share - [0-1] how much the unused flows from VRE sources would have been of the inflow</li> <li>upward slack share - [0-1] upward slack in relation to the inflow</li> <li>downward slack share - [0-1] downward slack in relation to the inflow</li> <li><code>group</code> object <code>flow_annualized</code> parameter - [MWh] produces grouped and annualized flow results of the <code>node</code> members of the <code>group</code></li> <li><code>group</code> object <code>flow_t</code> parameter - [MW] produces grouped flow results to the <code>node</code> members of the <code>group</code></li> <li><code>group</code> object <code>sum_flow_annualized</code> parameter [MWh] Annualized sum of flows in the group (members from group__connection__node and group__unit__node). Annualization scales the sum to correspond with full year time series.</li> <li><code>group</code> object <code>sum_flow_t</code> parameter [MW] Sum of flows in the group (members from group__connection__node and group__unit__node).</li> <li><code>group</code> object <code>VRE_share_t</code> parameter - [0-1]  how much the flows from VRE sources (inputs using  'upper limit' profile) are of the inflow for each timestep</li> </ul>"},{"location":"results/#capacity-and-investment-results","title":"Capacity and investment results","text":"<ul> <li><code>unit</code>, <code>connection</code> and <code>node</code> objects <code>capacity</code> parameter - [MW or MWh] include the following parameters</li> <li>existing - [MW or MWh] capacity that was assumed to exist in the beginning of the solve</li> <li>invested - [MW or MWh] capacity the model decided to invest for the given period</li> <li>retired - [MW or MWh] capacity the model decided to retire in the beginning of the given period</li> <li>total - [MW or MWh] sum of existing, invested and retired capacities</li> <li><code>unit</code>, <code>connection</code> and <code>node</code> objects <code>invest_marginal</code> parameter - [CUR/MW or MWh] marginal cost to invest in one more MW or MWh of capacity (zero value means that the model has invested in optimal amount; negative value means that if the model would be able to invest more, it could reduce total cost by the stated amount per MW or MWh; positive value means the cost is higher than the benefit by the stated amount per MW or MWh)</li> <li><code>group</code> parameter <code>slack_capacity_margin</code> - [MW or MWh] use of slack variable and the associated penalty cost to meet the capacity margin requirement in the period</li> <li><code>group</code> parameter <code>slack_capacity_margin</code> - use of slack variable and the associated penalty cost to meet the capacity margin requirement in the period</li> </ul>"},{"location":"results/#co2-emissions","title":"CO2 emissions","text":"<ul> <li><code>group</code> object <code>CO2_annualized</code> parameter - [Mt] how many million tons of CO2 annualized the units and connections in this group have generated (by using commodity with CO2 content) or removed.</li> <li><code>unit</code> object <code>CO2_annualized</code> parameter - [Mt] how many million tons of CO2 annualized the unit has generated (by using commodity with CO2 content) or removed</li> </ul>"},{"location":"results/#reserves","title":"Reserves","text":"<ul> <li><code>unit__reserve__upDown__node</code> relationship <code>reservation_t</code> parameter - [MW] how much upward or downward reserve particular unit was providing to a particular node in given timestep</li> <li><code>unit__reserve__upDown__node</code> relationship <code>reservation_average</code> parameter - [MW] how much upward or downward reserve particular unit was providing to a particular node in average during the period</li> <li><code>group__reserve__upDown</code> relationship <code>slack_reserve_t</code> parameter - [MW] use of slack variable and the associated penalty cost to fulfill the upward or downward reserve requirement in each timestep</li> <li><code>group__reserve__upDown</code> relationship <code>slack_reserve</code> parameter - [MW] cumulative use of slack variable and the associated penalty cost to fulfill the upward or downward reserve requirement during the period</li> </ul>"},{"location":"results/#inertia-and-non-synchronous-generation","title":"Inertia and non-synchronous generation","text":"<ul> <li><code>group</code> object <code>inertia_t</code> parameter - [MWs] the amount of inertia (MWs) in the group of nodes in each timestep</li> <li><code>group</code> object <code>inertia_largest_flow_t</code> parameter - [MW] The largest individual flow coming into the group of nodes that has_inertia</li> <li><code>group</code> object <code>inertia_unit_node_t</code> parameter - [MW] the amount of inertia between units and the nodes of the group</li> <li><code>group</code> object <code>slack_inertia_t</code> parameter - [MWs] use of slack variable and the associated penalty cost to fulfill the inertia requirement in each timestep</li> <li><code>group</code> object <code>slack_nonsync_t</code> parameter - [MWh] use of slack variable and the associated penalty cost to fulfill the non-synchronous share maximum share constraint in each timestep </li> </ul>"},{"location":"results/#ramps","title":"Ramps","text":"<ul> <li><code>node</code> object <code>ramp_t</code> parameter - includes seven parameters that form the ramp room envelope (how much there is additional room to ramp in a give node)</li> <li>ramp - [MW] the actual ramp in the node from previous timestep to this timestep</li> <li>units_up - [MW] additional room for upward ramps from non-VRE units connected to the node</li> <li>VRE_up - [MW] adds upward ramp room from VRE units on top of the ramp room from non-VRE units</li> <li>connections_up - [MW] adds upward ramp room from connections on top of the previous ramp rooms (does not consider whether the connected node has ramp room, but is simply the available capacity in the connection)</li> <li>units_down - [MW] additional room for downward ramps from non-VRE units connected to the node </li> <li>VRE_down - [MW] adds downward ramp room from VRE units on top of the ramp room from non-VRE units</li> <li>connections_down - [MW] adds downward ramp room from connections on top of the previous ramp rooms (does not consider whether the connected node has ramp room, but is simply the available capacity in the connection)</li> <li><code>unit__node</code> relationship <code>ramp_t</code> parameter - [MW] shows ramping of particular input or output flow between a unit and a node for each time step</li> </ul>"},{"location":"results/#slack-and-penalty-values","title":"Slack and penalty values","text":"<p>Slack and penalty values are listed in various places above (costs, energy balance, reserves, inertia and non-sychronous generation).</p>"},{"location":"spine_database/","title":"Data structure in Spine databases","text":"<p>Spine databases use Entity-Attribute-Value with Classes and Relationships (EAV-CR). Entity classes define the categories of data. These can be one-dimensional object classes (e.g. <code>node</code> or <code>unit</code>) or multi-dimensional relationship classes formed from the object classes (e.g. <code>unit__node</code>). Spine Toolbox user can define these classes to suit their modelling needs. For FlexTool the entity classes have been pre-defined. Instead, FlexTool user needs to add the entity instances: objects and relationships that define the particular network structure to be modelled (e.g. coal_plant <code>unit</code> or west <code>node</code>). Furthermore, each entity class (object or relationship) can hold only parameters that have been defined for that particular class. Again, FlexTool user does not need to add the parameter types - the user should just add needed parameter values for the entities the user has created.</p> <p></p>"},{"location":"spine_database/#database-editor-in-brief","title":"Database editor in brief","text":"<p>Spine Toolbox database editor can be used to modify data and to build scenarios.  The figure below shows an example where parameter data from two <code>alternatives</code>  have been selected for display (in the data table). The object tree on the left  selects two <code>nodes</code> ('coal_market' and 'west') as well as one <code>unit</code> ('coal_plant').  Consequently, one can use both whole classes and individual entities (members of the classes) as data filters. The results of this filter are visualized in the graph on top. The mouse pointer is showing a relationship  entity that connects the 'coal_plant' and its output <code>node</code> 'west'. The relationship  entity is defined in a relationship tree, which is not visible here.</p> <p>The <code>scenario</code> tree (on the right, below the <code>alternative</code> tree) shows that  the 'coal' <code>scenario</code> is formed by taking all data from the 'init' <code>alternative</code>  and then all data from the 'coal' <code>alternative</code>. If there would be same parameter  defined for both <code>scenarios</code>, then the latter <code>alternative</code> would overwrite  the first <code>alternative</code>.</p> <p>Whenever data is modified, the data is staged in separate database tables (although not directly visible to user). The changes will be applied only once the user <code>commits</code> the changes and leaves a commit message to indicate what has been done. The <code>commit</code> can be done with ctrl-enter or from the database editor menu (triple bar at top-right).</p> <p>The database editor menu has options for how to display the data: table view, different pivot views and a graph view. It also contains a tool to delete data (<code>purge</code>) and decrease database size by removing unused allocations (<code>vacuum</code>). You can also bring back dock windows that have been closed by the user. <code>History</code> will show the history of data changes based on the commits made by the user.</p> <p></p> <p>More on Spine Database editor in https://spine-toolbox.readthedocs.io/en/latest/spine_db_editor/index.html.</p>"},{"location":"spine_toolbox/","title":"IRENA FlexTool workflow shortly explained","text":"<p>IRENA FlexTool uses Spine Toolbox as a workflow and data manager. Open IRENA FlexTool with Spine Toolbox (Open project..., navigate to the IRENA FlexTool and choose Ok). In other words, the IRENA FlexTool repository contains a Spine Toolbox project (in '.spinetoolbox' folder). A regular user is supposed to only change data in the Input_data and Results data stores as well as to choose scenarios to be executed in the arrows leaving these data stores. It is also possible to create your own workflow from the components provided in the '.spinetoolbox/specifications' folder. First, create a new project (in a new, separate, folder) and then, using the '+ From file...' button in the Spine Toolbox toolbar, add the workflow components you want. In this way, you are free to modify the workflow without affecting the git-controlled workflow from the IRENA FlexTool repository (that is modified by the developers). Please note, that the new project will then be in a different folder than the tool specifications, which will remain in the IRENA FlexTool repository folder and can be updated through git.</p> <p>If you are using the IRENA FlexTool browser-interface, then you will not directly see the Spine Toolbox workflow, but the FlexTool web-server will be executing parts of the workflow in the background as you develop and run the model.</p> <p></p> <p>The panel on the right shows the different <code>scenarios</code> that are available in the database.  The user can choose which scenarios will be processed by the workflow (until item Results,  which combines the results into one database). Spine Toolbox can execute scenarios in parallel  (as long as using 'work directories' is defined in FlexTool item).</p> <p>Input data workflow item points to a sqlite file that needs to have IRENA FlexTool data format  (that uses Spine Toolbox database definition). The template file has the right format and contains empty object classes corresponding to FlexTool data structure as well as parameters available  in each object class. Double clicking the Input data workflow item will open the database editor.  Just selecting the Input data workflow item allows one to change the file (make a copy of the  existing Input_data.sqlite using the file system of your OS and point to the copy).</p> <p>Init workflow item points to a sqlite file with predefined data that showcases IRENA FlexTool  functionality. Some of the scenarios from there are used in the user guide. Initialize  copies the contents of the Init database to the Input data database. The scenario filter in the arrow after the Init database can be used to choose what data will be copied.</p> <p>Export_to_csv workflow item is a Spine Toolbox exporter that has been set to write csv files that IRENA FlexTool model code will read.</p> <p>FlexTool workflow item contains a Python script that calls FlexTool model code for each solve  and passes data between these solves. FlexTool model is written in MathProg and it calls HiGHS  solver by default to solve the model. The outputs are csv files.</p> <p>Import_results is a Spine Toolbox importer that takes the output csv files and writes them  in the Results database.</p> <p>Excel_input_data and Import_from_Excel allow users to use Excel as an interface for the input data.  They are optional parts of the workflow.</p> <p>To_Excel worfklow item will export most scenario results to a simple Excel file. One way to utilize  this is by creating another Excel file that draws figures from the result Excel file that is then updated by the workflow.</p> <p>The browser interface of FlexTool also runs part of this same workflow  (Export_to_csv --&gt; FlexTool --&gt; Import_results). The server takes a copy of the workflow (inside the user_projects)  folder and uses Spine Toolbox to execute the scenarios.</p> <p>More instructions for Spine Toolbox in Toolbox User Guide.</p>"},{"location":"spine_toolbox/#data-structure-in-spine-databases","title":"Data structure in Spine databases","text":"<p>Spine databases use Entity-Attribute-Value with Classes and Relationships (EAV-CR). Entity classes define the categories of data. These can be one-dimensional object classes (e.g. <code>node</code> or <code>unit</code>) or multi-dimensional relationship classes formed from the object classes (e.g. <code>unit__node</code>). Spine Toolbox user can define these classes to suit their modelling needs. For FlexTool the entity classes have been pre-defined. Instead, FlexTool user needs to add the entity instances: objects and relationships that define the particular network structure to be modelled (e.g. coal_plant <code>unit</code> or west <code>node</code>). Furthermore, each entity class (object or relationship) can hold only parameters that have been defined for that particular class. Again, FlexTool user does not need to add the parameter types - the user should just add needed parameter values for the entities the user has created.</p> <p></p>"},{"location":"spine_toolbox/#database-editor-in-brief","title":"Database editor in brief","text":"<p>Spine Toolbox database editor can be used to modify data and to build scenarios.  The figure below shows an example where parameter data from two <code>alternatives</code>  have been selected for display (in the data table). The object tree on the left  selects two <code>nodes</code> ('coal_market' and 'west') as well as one <code>unit</code> ('coal_plant').  Consequently, one can use both whole classes and individual entities (members of the classes) as data filters. The results of this filter are visualized in the graph on top. The mouse pointer is showing a relationship  entity that connects the 'coal_plant' and its output <code>node</code> 'west'. The relationship  entity is defined in a relationship tree, which is not visible here.</p> <p>The <code>scenario</code> tree (on the right, below the <code>alternative</code> tree) shows that  the 'coal' <code>scenario</code> is formed by taking all data from the 'init' <code>alternative</code>  and then all data from the 'coal' <code>alternative</code>. If there would be same parameter  defined for both <code>scenarios</code>, then the latter <code>alternative</code> would overwrite  the first <code>alternative</code>.</p> <p>Whenever data is modified, the data is staged in separate database tables (although not directly visible to user). The changes will be applied only once the user <code>commits</code> the changes and leaves a commit message to indicate what has been done. The <code>commit</code> can be done with ctrl-enter or from the database editor menu (triple bar at top-right).</p> <p>The database editor menu has options for how to display the data: table view, different pivot views and a graph view. It also contains a tool to delete data (<code>purge</code>) and decrease database size by removing unused allocations (<code>vacuum</code>). You can also bring back dock windows that have been closed by the user. <code>History</code> will show the history of data changes based on the commits made by the user.</p> <p></p> <p>More on Spine Database editor in Database Editor User Guide.</p>"},{"location":"tutorial/","title":"IRENA FlexTool tutorial","text":"<p>The instructions for installing IRENA FlexTool are at Interface overview.</p> <p>This user guide will build a small system step-by-step. It assumes you will be using Spine Toolbox as the front-end. If you are using the IRENA FlexTool web-interface, the instructions still apply, but the example figures in this tutorial will not be as helpful. IRENA FlexTool concepts are explained in more depth at Model Parameters.  Video tutorial for Building a small test system can be watched here.</p> <p>This tutorial can be used in couple of different ways - the best way depends on your familiarity with energy system modelling. </p> <p>First, all users who are not familiar with the way FlexTool manages data using Spine Toolbox functionalities, should read the page on Spine Toolbox workflow</p> <p>If you are new to energy system modelling, it is probably best to try to build the test system yourself while following the tutorial. This will take time and you will have to look up many data items from the Init database, but it will also force you to learn the concepts. You can also copy-paste data from the Init database to the Input data database when writing the data becomes too tedious. Before you start, it can be a good idea to to check the Essential objects for defining a power/energy system from the beginning of the FlexTool reference page to get an initial understanding of the concepts that will then grow as you learn more. </p> <p>If you have experience in using other types of energy system models - or perhaps older versions of FlexTool - it can be sufficient to follow the tutorial while also browsing the Init database using the database editor. Finding the entity classes, entities, and parameter values in the actual database will assist in the learning process. The concept reference page can also be useful.</p> <p>Finally, if you are a really experienced modeller, it can be enough to check the reference section starting from Essential objects for defining a power/energy system. </p>"},{"location":"tutorial/#building-a-small-test-system","title":"Building a small test system","text":"<p>The system contains three demand nodes, connections between them, a coal plant and a wind plant to provide the energy to the time varying demand. The system is run over a 48 hour timeline. </p> <p></p> <p>The small system to be built is also directly available in the FlexTool repository (Init SQLite database) and can be opened with the Spine Toolbox database editor. The default workflow for IRENA FlexTool executes the scenarios from the Input data database (and not from the Init SQLite database). The Input data database is empty by default. Therefore, if you want to use directly the contents of the Init database (instead of building the small system step-by-step), you need to copy them to the Input data database before running the scenarios in this tutorial. To copy the data, you need to execute the Initialize workflow item: select the item, press Execute selection from the toolbar.</p> <p>Remark: in case you had already populated the Input data database, you need to delete the data before importing from Init SQLite database. This can be done with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge.</p> <ul> <li>Building a small test system</li> <li>1st step - a node with no units</li> <li>2nd step - add a coal unit</li> <li>3rd step - add a wind power plant</li> <li>4th step - add a network</li> <li>More functionality</li> </ul>"},{"location":"tutorial/#choosing-the-database","title":"Choosing the database","text":"<p>You should have the FlexTool project open in the Spine Toolbox. For this tutorial a database time_settings_only.sqlite is provided in the Flextool folder. As the name suggests, it includes the basic time settings needed for running the tool. If you want to know how it is done or how to make your own time settings go to How-to-create-basic-time-settings. How to -section includes simple examples on specific parts of the system. You can explore it after the tutorial.</p> <p>First make a copy of the database and name it tutorial.sqlite. (In the future a new project should be started by copying time_settings_only.sqlite or the empty database input_data_template.sqlite. Use copy and rename, not directly! Otherwise the progress might be lost when updating the tool, as these databases are part of the repository). Then choose it to be the Input_data: </p>"},{"location":"tutorial/#1st-step-a-node-with-no-units","title":"1st step - a node with no units","text":"<p>Open the Input data database by double-clicking it in the Spine Toolbox workflow.</p> <p>The test system is built using <code>alternatives</code>. Alternative is a subset of the system than one can include to a <code>scenario</code> that is optimized by Flextool. For example when adding a wind plant, all the objects and relationships related to only the wind plant should be under their own alternative, so that the wind plant can be included or excluded form the <code>scenario</code> seamlessly.</p> <ul> <li>Each step will add a new <code>alternative</code>, and the data it contains, on top of the previous ones. </li> <li>The first <code>alternative</code> will be called west to hold the data for the first <code>node</code> in the model.</li> <li>The alternative is added in the 'Alternative tree' widget of the 'Spine Database Editor', see figure below.</li> </ul> <p></p> <p>Next step is to add an object for the first <code>node</code> that will be called west. </p> <ul> <li>Right-click on the <code>node</code> object class in the object tree to select 'Add objects'. </li> <li>Use the dialog to add the west <code>node</code> and click ok. See the figures below.</li> <li>Later other objects will need to be added in the same manner - as well as relationships between objects.</li> </ul> <p> </p> <p>Then, add parameter data to the newly minted west <code>node</code>: west node represents the demand in a part of the system.</p> <ul> <li>First add an <code>inflow</code> parameter with negative values to indicate negative inflow, i.e. demand. The <code>inflow</code> timeseries are given as a map-type parameter where the first column contains the names of the timesteps and the second column contains the inflow parameter value for that timestep. This is tedious to do by hand, so you can also copy-paste this from the init database.</li> <li>There are no electricity generating units and the demand cannot be met by ordinary means. The model will therefore use the upward slack variable and accept the <code>penalty_up</code> cost associated with it. This represents the cost of not fulfilling the demand. Also downward <code>penalty_down</code> is defined although the model is not using it at this stage. Here values of 9000 and 8000 are used respectively. By default the model uses the value 10 000 for these. Therefore, it is not mandatory to set them, but sometimes these values need to be changed, so understanding how they work is nessesary.</li> <li>Penalties and slack variables are tools of linear optimization. They ensure that the problem is feasable at all timesteps even when the in-out-balance of the nodes is violated. If no real penalty values are known, one should just use large enough numbers, so that the system won't prefer penalty to energy production. In the results, you can see at which timesteps the penalties are used.</li> <li>The parameter <code>has_balance</code> is related to this and should be set to yes. It forces the node to have a balance on inflow and outflow. If the demand is not fulfilled, balance is forced by the slack variable that will \"create\" the energy with the penalty associated with it. </li> <li>The west <code>node</code> needs to have a parameter called <code>is_active</code> with value yes. This chooses the west <code>node</code> and all its parameters to be sent to the model. </li> <li>All parameters here should be part of the west <code>alternative</code> (column alternative_name) - they will be used whenever a <code>scenario</code> includes the west <code>alternative</code>. </li> </ul> <p></p> <p>The new objects and parameters have now been staged. Even though it looks like they are in the database, they really are not - they need to be committed first. This can be done from the menu of the Database Editor (there is a commit command) or by pressing ctrl-enter. One should write an informative commit message about the changes that have been made. All commits, and the data they have affected, can be seen later from the history menu item.</p>"},{"location":"tutorial/#interlude-creating-a-scenario-and-running-the-model","title":"Interlude - creating a scenario and running the model","text":"<p>Even though the model is very simple and will not do anything interesting, it can be executed. It is first necessary to create the scenario to be executed. Scenarios are created from <code>alternatives</code> in the Scenario tree widget of the Database Editor. In the figure below, a <code>scenario</code> called Test-scenario is created that should contain <code>alternatives</code> west, init and init_2day-test in order to have both a node and a model structure included in the model. The new <code>scenario</code> must also be committed, before it can be used. A new scenario should be added after each step in the tutorial process. </p> <p></p> <p>Note that the order of the alternatives matters if there are conflicts between the alternatives. The alternatives lower down override the alternatives higher up on the list. In this example the init alternative has a full-year timeblock, but because the init_2day-test is lower in the scenario tree, the tool uses its <code>model</code>-flextool: solves parameter which points to the solve to be included in the model (2day-dispatch) and only it will be solved.</p> <p>Same logic will apply if you would add a parameter <code>inflow</code> with a value -100 to the west node in the alternative <code>init</code>. The model would use that instead of the previously set timeseries, because the <code>init</code> alternative is lower down in the alternative list of the scenario.</p> <p>Once the scenario has been committed to the database, it becomes available in the Spine Toolbox workflow. One can select scenarios to be executed from the arrow that leaves the Input data database. At this point, there will be only the Test-scenario available and should be selected. There is also a tool filter with FlexTool3 pre-selected. This selection needs to be present when running scenarios (it is used to filter the <code>is_active</code> entities into the scenario).</p> <p></p> <p>Next, we want to run three tools: Export_to_CSV (that will make input files suitable for FlexTool), FlexTool3 (which is a Python script that calls the FlexTool model generator for each solve) and Import_results (which will take output files from FlexTool and drop their contents to the Results database with a particular <code>alternative</code> name). First, select the three tools (select with left click while ctrl is pressed or draw an area with ctrl pressed, see figure below). Then, press Execute selection from the menu bar. The three items should be executed and if all goes well, then green check marks appear on each of the tool once it has finished. You can explore the outputs of each item by selecting the item and looking at the Console widget window.</p> <p> </p> <p>It is now possible to explore model results for the Test-scenario using either the Results database or the Excel file that can be exported by executing the To_Excel exporter tool. When doing that, no scenarios should be selected so that the tool will create one Excel file with data from all the alternatives that are in the results database (which will make more sense once there are more scenario results). The generated Excel file can be found by selecting the To_Excel tool and clicking on the folder icon on top-right of the Link properties widget window.</p> <p>By running the <code>Open_summary</code> tool, a quick summary csv file will open. This supports only runs with one scenario.</p>"},{"location":"tutorial/#2nd-step-add-a-coal-unit","title":"2nd step - add a coal unit","text":"<p>In the second step, a coal unit is added. </p> <ul> <li>The first thing is to add a new <code>alternative</code> coal so that all new data added in this step will become part of the coal <code>alternative</code>.</li> <li> <p>Then one needs to add the objects:</p> </li> <li> <p><code>unit</code> coal_plant</p> </li> <li><code>node</code> coal_market </li> <li> <p><code>commodity</code> coal</p> </li> <li> <p>And relationships:</p> </li> <li> <p><code>unit__inputNode</code> coal_plant, coal_market to indicate that the coal_plant is using inputs from the coal_market</p> </li> <li><code>unit__outputNode</code> coal_plant, west to indicate that the coal_plant will output electricity to the west node</li> <li> <p><code>commodity__node</code> coal, coal_market</p> </li> <li> <p>coal_plant needs the following parameters (all set for the coal alternative): </p> </li> <li> <p><code>efficiency</code> (e.g. 0.4 for 40% efficiency)</p> </li> <li><code>existing</code> to indicate the existing capacity in the coal_plant (e.g. 500 MW)</li> <li> <p><code>is_active</code> set to yes to include the coal_plant in the model</p> </li> <li> <p>coal <code>commodity</code> needs just one parameter for <code>price</code> (e.g. 20 \u20ac/MWh of fuel)</p> </li> <li>coal_market <code>node</code> needs to have <code>is_active</code> set to yes </li> <li>All these new parameters should be now part of the coal <code>alternative</code>. </li> </ul> <p></p> <p>To see how the results change due to the coal power plant, make a new scenario coal that has the <code>alternatives</code> init, init_2day-test, west and coal. Run the Export_to_CSV, FlexTool3 and Import_results to get the results to the Results database. If you start to get too many result <code>alternatives</code> in the Results database (e.g. if you happen to run the same scenario multiple times), you can delete old ones by removing the unwanted <code>alternatives</code> (right-click on the <code>alternative</code>) and then committing the database.</p>"},{"location":"tutorial/#interlude-visualizing-the-system-in-a-graph","title":"Interlude - visualizing the system in a graph","text":"<p>In Spine Toolbox, it is possible to visualize your system in a graph, which will show all objects, and the relationships between them. To open this visualization mode, open the Input data database. In the top right corner, click on the menu. Select Graph in the View section. You may visualize all objects by selecting root in the Object tree, or choose specifically the objects you want to display by selecting them in the Object tree (maintain ctrl to select multiple objects).</p> <p> </p>"},{"location":"tutorial/#3rd-step-add-a-wind-power-plant","title":"3rd step - add a wind power plant","text":"<p>Next, a wind power plant is added.</p> <ul> <li>Add a new <code>alternative</code> wind</li> <li> <p>Add objects:</p> </li> <li> <p><code>unit</code> wind_plant</p> </li> <li> <p><code>profile</code> wind_profile since wind_plant does not require a commodity, but instead uses a profile to limit the generation to the available wind.</p> </li> <li> <p>Add relationships:</p> </li> <li> <p><code>unit__node__profile</code> wind_plant, west, wind_profile</p> </li> <li> <p><code>unit__outputNode</code> wind_plant, west</p> </li> <li> <p>wind_plant needs the following parameters (all set for the wind alternative):</p> </li> <li> <p><code>conversion_method</code> to choose a method for the conversion process (in this case constant_efficiency)</p> </li> <li><code>efficiency</code> for wind_plant should be set to 1.</li> <li><code>existing</code> capacity can be set to 1000 MW</li> <li> <p><code>is_active</code> set to yes to include the wind_plant in the model</p> </li> <li> <p>wind_profile needs the the parameter <code>profile</code> with a map of values where each time step gets the maximum available capacity factor for that time step (see figure). Again, you can copy this from the init database.</p> </li> <li>wind_plant, west, wind_profile relationship needs a parameter <code>profile_method</code> with the choice upper_limit selected. This means that the wind_plant must generate at or below its capacity factor.</li> </ul> <p>You can now create a new scenario wind,  that has the <code>alternatives</code> init, west, coal and wind. Remember to commit, execute and have a look at the results (there should be no more penalty values used, since the coal and wind plant can together meet the demand in all hours).</p> <p></p>"},{"location":"tutorial/#4th-step-add-a-network","title":"4th step - add a network","text":"<p>A network <code>alternative</code> introduces </p> <ul> <li>two new <code>nodes</code> (east and north) </li> <li>three new <code>connections</code> between <code>nodes</code> (east_north, west_east and west_north). </li> </ul> <p>The new nodes are kept simple: </p> <ul> <li>they have a <code>is_active</code> parameter set to yes</li> <li>they have a <code>has_balance</code> parameter set to yes (to force the node to maintain an energy balance)</li> <li>they have a constant negative <code>inflow</code> (i.e. demand)</li> <li>penalty values for violating their energy balance</li> </ul> <p>The three connections have the following parameters:</p> <ul> <li>they have a <code>is_active</code> parameter set to yes</li> <li>they have a <code>existing</code> parameter to indicate the existing interconnection capacity between the nodes</li> <li>they have a <code>efficiency</code> parameter  (e.g. 0.9 for 90% efficiency).</li> </ul> <p>It is also necessary to create the relationships <code>connection__node__node</code> for east_north | east | north, west_north | west | north and west_east | west | east.</p> <p>The north <code>node</code> has the lowest upward penalty, so the model will prefer to use that whenever the coal and wind units cannot meet all the demand. Sometimes the <code>existing</code> capacity of the new <code>connections</code> will not be sufficient to carry all the needed power, since both generators are producing to the west <code>node</code>. Commit, execute and explore.</p> <p></p>"},{"location":"tutorial/#more-functionality","title":"More functionality","text":"<p>Now you have learned how to create a small model. Remember that you can change which database is used as the Input_data by clicking the tool icon. You can make a copy of the Results database if you want to keep them. The database can also be purged from previous results with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge. Purging by itself will not reduce the file size, you will have to <code>Vacuum</code> it to do this.</p> <p>More instructions on how to create individual parts of the model can be found in the How to section.</p> <p>You can also look and play with the ready scenarios from the init database. Purge Input_data and Initialize it to copy the init database to it. Purging is done the same way as above: This can be done with the 'purge' tool from the Database Editor menu: in <code>purge</code>, click on both Select entity and value items, and Select scenario items and then purge. Then select the initialize tool and run it to copy the init.sqlite to the input_data.sqlite.</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index e63d9df97e13290f8244ef5ee8ec194db995647e..4479c0011b119d8e2d959e8c993cff14d63949cb 100755
GIT binary patch
delta 14
Vcmb=g=aBE_;9wE8N}I@04geag1Bw6u

delta 14
Vcmb=g=aBE_;LxuBmpYN78~`E-1l|Au