HSP2 Python Implementation of HSPF SPEC-ACTIONS (withdrawals)

[rburghol]

Development main tracking here. Live issue on $hsp^2$ is: respec#90

• Main code base is /opt/model/HSPsquared
• Our fork of respec is /opt/model/HSP2fork

Overview

This issue is set up to plan and track development for a proposed "SPEC-ACTIONS" module in hsp2. Development has 2 main components:

1. Understand the model representation of Withdrawals. What variables to set, how standard WDM withdrawals work, etc.
2. Provide support for pre-hsp2 uci files that use SPEC-ACTIONS
3. Provide an enhanced "next generation" type implementation for SPEC-ACTIONS
4. Use new form spec-actions to make complex operational withdrawals.
5. Understand how model handles releases from reaches (reservoirs).
6. Use new form spec-actions to make complex operational releases.

Tasks

• Add initial outline in hsp2 repo
• Document location of withdrawal code in HSPF and hsp2 Document location of withdrawal code in HSPF and hsp2 #10
• Examine execution flow in HSP2/HSPF
  • The hsp2 model (and presumably hspf) executes each individual component (RCHRES, PERLAND) completely in isolation before moving downstream to the next component.
    • Is component order dynamic based on linkages? See SCHEMATIC table in uci and code to handle SCHEMATIC for answers.
  • The hsp2 (and hspf) model executes each individual process completely, iterating through all timesteps in isolation before the next process. Process order is hard-wired in the model code.
  • The variables ui and ts contain domain specific, i.e., related only to RCHRES001 if we are iterating through block functions for RCHRES001. Thus, all objects should be declared underneath RCHRES001 in the hdf5 database.
• Scoping Code Tasks -- Function defs, testing a single hard-coded withdrawal, h5 writing
  • See Scoping Code Tasks: #12
• Function naming conventions, arguments and code - propose specl() which calls _specl_() as place for analog. specl(): Proposed function definition for SPEC-ACTIONS  #13
• Prototype ps_cumulative_mgd\wd_cumulative_mgd First test code: equation to calculate ps_cumulative_mgd\wd_cumulative_mgd #14
• Write a parser for basic SPECL (just setting variables till we decide on our final approach) #24
• How to pass more complex aspects/objects in?
  • How could we alter demands in a SPECL object?
    • Passing referenced OUTDGT (and others) into _hydr_() #31
  • In short, there is little reason to try to fit all desired behaviors into the old spec-act format if we can support a complex object based operational model.
  • However, the new model might be best inserted into the model at the same/similar location as spec-actions workflow, in order to take over old functions.
  • At the same time, the new specl objects values should be able to be called via the old notation - in other words, all objects can be declared in specl, then reference json files or python files for runtime loading. All dynamically loaded functions and object classes should accept as input the same params passed to _specl_()
  • Possibly functions created in the new specl object could be exposed to the old notation but that would be a future
• Base classes to implement see Begin coding data model, object classes. #7
• Setting data in ts and ui, pass by reference in python functions Setting data in ts and ui, pass by reference in python functions #19
• Final data model / input and output data sharing
  • Classes Begin coding data model, object classes. #7
  • State data and object class persistence vs. purely-functional Specl and Objects hdf5 data model #20

Reference

• Version 12.2 fortran Special Actions code
  • specact.f/ SPECACT.FOR: subroutines for parsing and executing special actions
    • PSPECL: process the special actions block lib3.0/SRC/HSPF122/Specact.FOR
    • Execute SPEC-ACTIONS: https://github.com/respec/FORTRAN/blob/ae3b77117872a8625b1dc2ab51c0a4b48ddd411b/lib3.0/SRC/HSPF122/Specact.FOR#L4696
  • HSPF: the main executable for HSPF hspf/lib3.2/src/hspf/hspf.f
  • Special actions called: https://github.com/respec/FORTRAN/blob/ae3b77117872a8625b1dc2ab51c0a4b48ddd411b/lib3.0/SRC/HSPF122/HOSUPER.FOR#L290

[rburghol]

Where do special actions get called?

fgrep "call specl" -i hspf/lib3.2/src/hspf/*
hspf/lib3.2/src/hspf/himp.f:          CALL SPECL (OPTYP,LSNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,
hspf/lib3.2/src/hspf/hper.f:          CALL SPECL (OPTYP,LSNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,
hspf/lib3.2/src/hspf/hrch.f:          CALL SPECL (OPTYP,RCHNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,
hspf/lib3.2/src/hspf/hutop.f:          CALL SPECL (OPTYP,COPYNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,
hspf/lib3.2/src/hspf/hutop.f:          CALL SPECL (OPTYP,GENRNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,
hspf/lib3.2/src/hspf/hutop.f:          CALL SPECL (OPTYP,PLTNO,SPAKND,SPOPNO,DATIM,MESSU,SPIVL,

[rburghol]

Find the HYDR routine in the old code base:
fgrep "HYDR" /opt/model/p53/p532c-sova/code/src/* -R|grep -i subroutine

[jdkleiner]

Next Steps (11/9/22):

• Work off of specdev branch
  • verified we're able to install and tests run with no errors
• We know how to modify the ts variables, now we want to be able to modify ts dictionary values without manually resetting ts
• Now we need to know how to modify the state variable (i.e. lowercase outdgt)
  • Look at previous progress made in stashed branches and notes in log here: https://github.com/HARPgroup/HSPsquared/wiki/JK-HSP2-Log#week-of-10322
• Test setting of values inside of SPECL.py
  • Rob may set up an equation function to do this