Global Variables are used in ResSim to allow the user to pass simulation-specific information into ResSim that is not easily managed with observed timeseries.  A good example of this would be a range of flows from the Water Control Manual based on the current  forecast of yearly accumulated inflow volume.  This data is calculated external to the simulation and often has a wider time horizon than the simulation, but impacts the simulation's operations.  The user can enter and store this information in Global Variables that can be used in the rule sets.  This How To shows an example of using the global variables within a scripted rule to allow the user to easily control reservoir operations from the Alternative Editor.  


BACKGROUND.  The example model is from the James River Basin North Dakota, which has Jamestown and Pipestem Dams.  These dams protect the City of Jamestown, ND from flooding and provide flood control for downstream communities and agriculture.  The projects often accumulate large snowpacks which can fill their flood control zones in the spring.  This water is then released throughout the spring and summer.  The combined release rate is determined based on the combined reservoirs' forecasted yearly inflow defined as High, Medium and Low flow years.  The corresponding max combined release rates are then set to 1800 cfs in High, 750 cfs in Medium and 200 cfs in low flow years.  ResSim simulations timewindows are typically set to 2-4 weeks, so a full yearly forecasted inflow cannot be developed from the HMS modeling.  Because of this the High, Medium, or Low flow selection must be passed into the ResSim model based on an external forecast.  Global Variables help pass this forecast information into the ResSim model and also distribute the flow between the two reservoir outflows.  ResSim modeling often occurs while flooding downstream of the projects is ongoing, which can force the reservoirs to hold releases at 0 cfs while downstream flooding subsides.  This model uses Global Variables to enter the number of days dam releases should be held at 0 cfs based on the time needed for downstream flooding to recede.  

This was originally modeled in ResSim using java pop-up boxes that would prompt the user for the necessary inputs like High/Medium/Low flow selection and entering the portion of flows to each project.  This was a workable solution, but required the developer to understand how to create java pop-up boxes and led to a longer and more complex script.  The java pop-up based script required approximately 500 lines of code, where the solution described below provides similar functionality with less than 100 lines of code.  

Step-by-step guide

James_River.zip

  1. Download and open the attached ResSim model.  
  2. Open the simulation "Retest_GVs".  (Suggest zooming in on the reservoirs near the middle of the model)
  3. GLOBAL VARIABLES - The list of Global Variables can be seen/edited in the toolbar "Edit→Global Variables.."  The Global Variable Editor is shown here.
    1. Year_Type- GV contains the High/Med/Low forecast the user will provide.  It is a user selection where High/Med/Low were all added as dropdown options.  The scripted rule will use this user provided information to set the combined release from two projects at the levels described in the background.  High/Med/Low = 1800/750/200 cfs.
    2. JATO_Flow_Percent - GV contains the percentage of the combined flow that will be applied to Jamestown Dam releases.  If a High flow year (1800 cfs) is selected and JATO_Flow_Percent is set to 0.8 then 1440 cfs will be the release target for Jamestown Dam.  The combination of JATO_Flow_Percent and PIST_Flow_Percent should equal 1.
    3. PIST_Flow_Percent - Same as above.
    4. ZeroDaysJATO - Jamestown Dam outflows are often held at 0 cfs for several days at the start of a flood to wait for downstream flooding to dissipate.  This GV stores the number of days to hold releases at 0 cfs before increasing to the Jamestown target flow described above.  
    5. ZeroDaysPIST - Same as above.
  4. SETTING GLOBAL VARIABLES - To modify the Global Variables, open the Alternative Editor.  The Global Variables shows the cells where each GV can be changed.  These values will then be available to use within the resSim rules and scripted rules.   
  5. SCRIPTED RULE USING GVs  - Open the Jamestown Dam "Edit Reservoir Properties" and then open the "SetRelease" Rule.  This shows the python code where the GVs are utilized to make reservoir release decisions.  
    1. The initRuleScript (Lines 23-30) shows where the GVs are written into a special ResSim variable called a 'varPut'.  VarPuts are able to store data from a scripted rule across resSim timesteps.  So here the user has set the varPut "PISTdaysZero" to the GV "ZeroDaysPIST", which can now be used as resSim iterates through the simulation's timesteps.  The initRuleScript only executes once before the first timestep, which stores these GVs into the varPuts.  An example snippet of this code available for copy/paste is shown below.   

      ResSim Scripted Rule Snippet

      def initRuleScript(currentRule, network):
	currentRule.varPut('PISTdaysZero', network.getGlobalVariable("ZeroDaysPIST").getValue()*24)
	# ...
	return Constants.TRUE
      PYTHON

    2. The runRulescript will execute its code for each timestep in the timewindow.  The heart of its code is shown below.  Lines 46-53 first utilizes the ZeroDays varPuts to count down how many timesteps have been set to 0 cfs.  
    3. Lines 60-68 read the Year_Type GV into the code and set the combinedFlow variable based on the GV's value.  The code snippet is available below the screenshot for copy/paste.
    4. Line 70 and 71 set the JATO release to 0 cfs if the ZeroDays count from above has not reached 0. 
    5. If the zero flow period has passed line 77 will us the GVs to determine Jamestown Dam's release.
    6. Line 77 will perform the following multiplication of the GVs "JATO_Flow_Percent" * combinedFlow (see 5c above), which produces the desired outflow for Jamestown Dam.
    7. Line 77 utilizes a state variable to store the calculated flow.  A state variable is similar to a varPut as it allows the user to save information from the current timestep and use it in other parts of the model and in the next timestep.   
      1. This state variable JATOout is then to set a specified release in the rule JATOout.  This rule generally controls the flow from Jamestown Dam.   

        YearType

        	yearType= network.getGlobalVariable("Year_Type").getValue()
	if yearType == "High" or yearType == "HIGH" or yearType == "high":
		combinedFlow = 1800
	elif yearType == "Medium" or yearType == "MEDIUM" or yearType == "medium":
		combinedFlow  = 750
	elif yearType == "Low" or yearType == "LOW" or yearType == "low":
		combinedFlow = 200
	else:
		combinedFlow = 600
        PYTHON
    8. This process is then repeated to test PIST for its zero flow period and also set PIST release in line 82.  The code snippet is available for copy/paste below.   

      Set PIST State Variable to Global Variable Value

      network.getStateVariable("PISTout").setValue(currentRuntimestep, network.getGlobalVariable("PIST_Flow_Percent").getValue()*combinedFlow)
      PYTHON
  6. Run the Compute.  This will produce a combined release from Jamestown Dam and Pipestem Dam of 750 cfs (Med Flow) with 70% going to Jamestown and 30% to Pipestem.  Jamestown will hold at 0 cfs for 1 day while Pipestem holds 0 cfs for two days, all as specified in the Global Variable Editor in Step 4.  
  7. The user can now visualize the results of these GV settings and can now change these values to improve the operation, recompute the simulation and repeat as needed to perfect the forecasted operation.  
  8. Using Script API.  - ResSim script editor provides access to list of functions via the API Tree.  The screenshot below.  Double-clicking an entry in the API will place it on the currently selected line of the script.