Finishing Ops Model components

[rburghol]

@COBrogan

LATEST WORK STOP STEPS: respec#197 (comment)

• (9/10-14/2025) Review pandas df only UCI, and Develop base class for native HSPF features, and ops model, and prototype looping. Present to steering committee.
  • Add IOManagerPandas Mayb be deprecated with Tim's code.
  • YES Does a list of objects actually pass by reference?
  • Prototype main loop
    • See: Main Loop to support timestep level integration of processes and respec/HSPsquared#186
    • include stub function for varying time step
    • Do at least 1 example of moving if-then code into functions (if not class + method)
• (10/13/2025) Refactor state to enhance readability and usability
  • Move state into hsp2/state/ folder, alter imports and do PR
  • Make custom jit-able class that contains all of the multitude of state elements develop-state-class: Reorganize Files and create STATE jit class respec/HSPsquared#197
  • Include elements like state_ix, state_paths etc. to reduce the number of arguments to functions.
  • Update HYDR
  • Update SEDTRN
  • Test with om_constant: develop-state-class: Reorganize Files and create STATE jit class respec/HSPsquared#197 (comment)
  • Test with om_Equation : develop-state-class: Reorganize Files and create STATE jit class respec/HSPsquared#197 (comment)
  • Update other Paul has done?
  • Add PR with revised state
  • Also squash bugs in 179, 180, and 181
• (10/20-25/2025) Add single PR with all current prototype components (See the PR roadmap issue Development Plan: Merges into develop-specact (1-2/2024) #80 )
  • Locate draft @njit and parser/handler functions for each existing set of objects
  • Add a branch to house this set of PRs https://github.com/HARPgroup/HSPsquared/tree/develop-om
  • Consider combining into a folder for easier readability
  • Do we need develop-else (or has Tim's changes fixed this)? Develop else respec/HSPsquared#190
  • Consider renaming classes to append "Handler": these have all been done as means of translating json/nested dataframes into objects
  • Start by adding a stub for each object component type we plan to have. Talked to Paul about getting them in via PR, with the understanding that no code gets implemented until a companion testing data set is there.
  • Add single library file for all op model objects
    • Talk to Paul: should we do separate lib file for handlers and executable @njit code?
• (10/27-11/3/2025) Develop Facility model test
  • json includes: test matrix, flowby, equation and broadcast
• (11/10-14/2025) Develop very basic classes for model overall execution (RCHRES, PERLND, IMPLND, COPY, GENER)
  • Classes will enable storing things like UCI parameters, timeseries references, state pointers, and other persistent data between timestep iterations which will improve performance by avoiding reloading each timestep.
  • Prototype classes for ops model components, with one generic class to overcome limit for passing in lists of objects:
    • Leverage inputs to allow custom data model
    • See RQUAL_class work done by Tim/Paul https://github.com/respec/HSPsquared/blob/develop/src/hsp2/hsp2/RQUAL_Class.py
    • Pass the objects to the existing exec scripts that can then choose which function to use to perform step(), to provide custom object handling (until @njit catches up to more flexible object orientation). See develop-hydrclass for examples
    • Base Classe ModelBase: Base njit class for abstracting model execution #110
    • ModelRCHRES + HandlerRCHRES ModelRCHRES #111
      • without ts
      • with ts
    • ModelRQUAL + HandlerRQUAL -- See RQUAL_class work done by Tim/Paul https://github.com/respec/HSPsquared/blob/develop/src/hsp2/hsp2/RQUAL_Class.py
    • ModelPERLND + HandlerPERLND
    • ModelIMPLND + HandlerIMPLND
    • ModelCOPY ? + HandlerCOPY
    • ModelSEDTRN + HandlerSEDTRN
• Revisit test of associative array performance, Dynamic Object Calculation (form and speed) #35
  • Create script directory and prototype testing scripts. See https://github.com/HARPgroup/HSPsquared/blob/develop-hydrclass/src/hsp2/hsp2/classes/model.test.class.py
  • Repeat performance tests for three most recent versions of Python Dynamic Object Calculation (form and speed) #35
  • Overarching questions:
    • (YES) Are class properties faster than class named Dict references? (i.e. is self$volint = self$volt - (self$ks * self$roseff * self$delts) faster than self['state']['volint'] = self['state']['volt'] - (self['state']['ks'] * self['state']['roseff'] * self['state']['delts'])?
    • Can we store state as pandas slices, like if state['RCHRESR001'] contained ['OVOL'], ['IVOL'], ... and then we could at create set self.state = state['/RCHRESR001'] and then maths that we did in the loop would be like `self.state['IVOL'] = X' and that would auto write to
    • Create a testing class with 8 permutations (2 * ts reading/writing, 2* state reading/writing, 2 * execution)
    • is there a difference in speed for executing class methods versus passing class data to an external function?
  • NJIT main loop versus Python main loop revisited
  • consider performance impact of storing main objects such as RCHRES and PERLND in lists keyed according to a string,
  • Create a generic benchmarking script to include in tests
  • Check out codon and potential performance improvements (check njit and non-njit) https://www.usenix.org/publications/loginonline/codon-python-compiler-update
  • Enable generic object support for op models with op_components object holding ops
    • Either with step function that calls hard-wired component step functions based on comp settings
    • Or a separate list of processor objects for each type, and use numeric key to ID which type list to load from at execution time?
    • Could one of these objects contain a reference to the time series array for the given component, like each physical gets an object for it's properties, ie RCHRESR001 can live in an object with references to all its properties?
  • for testing, we can just create a associative array version of the existing step functions in very short order
• IF-THEN special action with dynamic exec list modification
  • Plan & Implement IF-THEN turn on /off
    • Meet with Tim Cera to plan architecture
    • Add prototype handling of enable/disable spec-actions based on remote property value 0/1
  • This will be used for flow dependent AGWRC initial implementation
  • This will also allow subsequently testing of dataMatrix version of the AGWRC variation
• HSP2 main loop considerations Main Loop to support timestep level integration of processes and respec/HSPsquared#186
  • single step HYDR function is priority, just to ensure that our OPS model and single step versions will work seamlessly.
  • timing stuff takes up much space in HSPF code but can be streamlined into a single function? Or maybe a timing function and a ts loader?
  • single step PERLND, IMPLND, and SEDTRN/ADCALC etc functions are lower priority, maybe add stubs
• Testing framework support
  • each function must have test coverage to merge
• Meet with Karin Klein to brief her on our project and get her perspective.

[rburghol]

Runtime object model design:

• A common base class can be used for all standard model components and operational components.
• RCHRES, IMPLND, and PERLND can all be a INDIVIDUAL classrs.
• include references to global state
• Include inputs, decide whether object references or path references will work, and which will function more quickly

[rburghol]

State decisions:

• State currently is a mix of jit-able and non-jit-able components
• model_object_cache is non-jit-able and is passed in via state and is used to order operations prior to entering a jit-ed function
• op_tokens is an om construct that is jit-able, but is not properly associated with state
• Ultimately, we will need a construct to handle om objects, so supporting that construct now in simple Dict form or class form could be desirable.
• options:
  • do order operations before calling intermediate functions and store op_order in state and store op_tokens in state
    • Will later replace state.op_tokens with objects and state.op_order with self.op_order on each main level object like rchres_Model
  • pass state in as is, and separate into state_class in the intermediate functions that call jit-ed code
  • pass state in to main as is, and separate into state_class before the intermediate functions that call jit-ed code, and must add an argument for model_object_cache
  • do order operations before calling intermediate functions and store in om_operations; add om_operations to function arguments,