specl: UVNAME (parser and code)

[rburghol]

Overview

• Takes a standard special action variable as input (can also take any variable?)
• Specifies 1 to n variables (existing state variable, can also be a special action created name?) to be set as a multiplier of the original source variable.
• Example (see below for UCI entry):
  • A variable named FNO3 is created in a standard special action line for PERLND 1
  • A UVNAME line refers to the FNO3 as it's source data in the varnam column
  • 2 "standard variables" are each to be updated by this action SNO3 and UNO3
  • These standard vars have their value set to the given decimal multiplied by the FNO3 variable:
    • UNO3 = 0.5 * FNO3
    • SNO3 = 0.5 * FNO3
• Question: If multiple PERLND, IMPLND or RCHRES had the same standard ACTION name, would the UVNAME action propagate to all of them with matching destination variables?

Tasks

• [x] Data Model
• [ ] Class handler (turns table data into linked and integrated executable runtime)
• [ ] Parser
• [ ] Executable Code
• [ ] Unit Tests
• [ ] Performance Tests

UCI Structure

From HSPF v12.2 manual

Example UCI

• From: https://deq1.bse.vt.edu/hsp2/land_spec/hwmA51800.uci
• Example UVNAME specifies using 2 variables (specified by the ct column in UCI, corresponds to CNT in hdf5 table)
  • These variables would be stored in hdf5 table as NAME1 |CSUB1 |ADDR1 |FRAC1, and ACTCD1 |VNAME2 |CSUB2 |ADDR2 |FRAC2 (see hdf5 Data Model below).
• Both variables have QUAN operation (specified by column oper in UCI, )

ACTIONS optyp range dc ds yr mo da hr mn d t vari s1 s2 s3 ac value tc ts num <****><-><--><><-><--><-><-><-><-><><> <----><-><-><-><-><--------> <> <-><-> PERLND 1 DY 11984 3 1 12 2 3 FNO3 += 1.917460

...

UVNAMES kwd varnam ct vari s1 s2 s3 frac oper vari s1 s2 s3 frac oper <****> <----><-> <----><-><-><-> <---> <--> <----><-><-><-> <---> <--> UVNAME FNO3 2 SNO3 0.5 QUAN UNO3 0.5 QUAN

### hdf5 Data Model
- hdf5 Path: `/SPEC_ACTIONS/UVNAME/table`
- Example (from **Example UCI** above)
- May need a simpler table, with one line for each target variable, and then the quantity is used in parsing to make sure that all targets get read, but are not needed in the final table?  Then each SPECL can be rendered at runtime as individual equations stemming from the source variable?
   - Function `` in SPECL.py would need to query these by UVNAME

#### Original 1 to many table mimics UCI incompletely
| index|UVNAME |CNT |VNAME1 |CSUB1 |ADDR1 |FRAC1   |ACTCD1 |VNAME2 |CSUB2 |ADDR2 |FRAC2   |ACTCD2 |VNAME3 |CSUB3 |ADDR3 |FRAC3   |ACTCD3 |
|-----:|:------|:------|:------|:--|:--|:----|:----|:----|:----|:----|:----|:----|:----|:----|:----|:----|:----|
|     0|FNO3 |2      | SNO3      |   |   |   | 0.5 | QUAN | UNO3      |   |   |   | 0.5 |  QUAN  |   |   |   |  

#### Possible streamlined many to 1 table
| index|UVNAME |VNAME |CSUB |ADDR |FRAC   |ACTCD |
|-----:|:------|:------|:------|:--|:----|:----|
|     0|FNO3 | SNO3      |  |   | 0.5 | QUAN | 
|     1|FNO3 | UNO3      |  |   | 0.5 | QUAN | 

### Execution Code
- Fortran version [SUBROUTINE PSPACT in 12.2](https://github.com/respec/FORTRAN/blob/cb2cbf8ec09f11eb290b01fe7646295fcfcdbf1a/lib3.0/SRC/HSPF122/Specact.FOR#L2285)