SPEC-ACTIONS in hsp2

[rburghol]

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. Provide support for pre-hsp2 uci files that use SPEC-ACTIONS
2. Provide an enhanced "next generation" type implementation for SPEC-ACTIONS

Tasks

• Document legacy Outline legacy SPEC-ACTIONS code operational behavior #98
• Write parser & Develop hdf5 Data Model specactions Parser readUCI & hdf5 Data Model #99
• Support legacy fn in hsp2
  • Identify locations in the hsp2 code where each legacy specl() function should be called.
    • RCHRES
      • specl() should be called at line 267 (or) just before code line that says if irexit >= 0: - see:

        HSPsquared/HSP2/HYDR.py

        Line 267 in f9555f2

        # vols, sas variables and their initializations not needed.

    • COPY, GENER, PLTGEN, IMPLND, PERLND
  • Data passing: See STATE Data Model Data Model for Shared STATE (supports model modularity) RFC #112
• Outline new functionality key questions and architecture:
  • Q: Is execution location for legacy sufficient for new functions?
    • A: n/a as code may ned top be implemented in multiple places and architecture has changed from fortran version
  • Q: Will included blocks of python be able to be executed?
    • A: Yes.
  • Q: Is there a method/function or global array of state variables that are writeable or a protected method for passing values back from SPEC-ACTIONS?
    • A: This is introduced for this version in Data Model for Shared STATE (supports model modularity) RFC #112
  • Develop API/structures for custom code block execution and shared data STATE.
    • Data Model Data Model for Shared STATE (supports model modularity) RFC #112
    • What new "primitives" for variable operation are needed:
      • equations
      • lookups
      • statistical functions (min, max, median).
    • Executable Code blocks Dynamic python code loading for hsp2 runtime customization  #113
    • How to define new objects in UCI
      • For executable python, file reference (see Dynamic python code loading for hsp2 runtime customization  #113 )
      • Complex object definition for SPEC-ACTIONS Develop specact 1 #128
    • How can the code support named/tagged "agents" or "objects" such as individual water consumers that can provide model dynamic data (like withdrawal amounts), and be loggable as individual entities
• Begin prototype coding, submitted via pull requests or issue demos.
  • Submit STATE data model PR State #115
  • Document method for inclusion How to Implement New Module in STATE system #127
  • Implement legacy ACTIONS for HYDR specl: ACTIONS (parser and code) #105
  • Implement advanced operational primitives
  • Final code organization STATE sub-module refactor #126

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

@PaulDudaRESPEC

[PaulDudaRESPEC]

@rburghol , this looks like a great outline for getting started! We look forward to collaborating!

[aufdenkampe]

@rburghol, I second @PaulDudaRESPEC's appreciation for creating this issue!

It's great to see your interest for implementing these Special Action capabilities! Do you and your team have plans to dive in, get started, and/or issue a pull request?

The RESPEC/LimnoTech collaborative team just got another round of funding to continue developing HSP2, but we won't be getting started with that work until September. Addressing SpecialActions is in our scope of work, but we had been thinking of first prioritizing additional code refactoring to move all existing modules to object-oriented class structures (similar to what we did in late 2021 for RQUAL modules). So it would be helpful to better understand your needs to evaluate whether we should tweak priorities.

cc: @ptomasula & @tredder75

[rburghol]

@aufdenkampe thanks! My ambition is to get started asap -- but be smart about the approach to minimize refactoring all over again as your work on SA evolves.

My groups main need is for advanced water supply operational code, mostly on RCHRES. If RCHRES execution is already objectified that will be great. That said, I'll be writing objects, so I should be able to easily adapt to whatever your evolving framework looks like.

Tentative Schedule:

• I am going to go heavy on outlines/checklists for the next week, as well as assembling a dataset for testing. Comments will be appreciated.
• I will post some proposed base classes for water supply system/reservoir related actions based on direct translations of what we currently use for comment by the end of June. If no one has time to comment, no worries, changes is constant and it's open source, I'll be writing code that can adapt to the infrastructure.
• By early July I hope to be prototyping on our local branch/fork.
• I will develop on my groups fork, with a goal for a pull request whenever you all solidify the framework and I can tie things in nicely. Our dev branch: https://github.com/HARPgroup/HSPsquared

I will look at your RQUAL stuff for an inkling about design goals, any links that you can share to point me in the right direction would be awesome. Also, forward on any test datasets that you may have if you have some in mind.

[rburghol]

Hey @aufdenkampe and @PaulDudaRESPEC -- wanted to let you know I have begun working in earnest on the special actions. Started with the parser for the most basic SA, and tracking that progress here #99.

• there is a downloadable test dataset
• a link to my groups repo if anyone wanted to examine the code
• I have identified all the places in the code that need to get work to support parsing
• I have put together a basic parser support for standard actions though the data parsing info is off so I am not getting good info yet.

I won't do a pull request till something is actually working though I am making a good bit of progress, but if anyone wants to take a look that would be awesome since I assume I am making a silly mistake of some sort in the parser CSV def or code.