specl: UVNAME (parser and code)

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?
- If this is the case (as it seems):
  - Option 1: Define UVNAME separate from all RCHRES/PERLND, and execute the UVNAME tree in each applicable module/domain, before executing domain-specific (i.e. RCHRES_R001,. ...) operations.
    - Or should it execute after?
    - Or execute according to dependency?
  - Option 2: Define a distinct UVNAME as a child of each domain object that they interact with during model parsing and setup, then these can all execute inside their respective dependency hierarchy.

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) 

### Implementation with Operational Model
- Equation object, has 3 main attributes: 
   - "name": "UNO3"
   - "equation": "0.5 * FNO3"
   - "object_class": "Equation"
- Resides in nested hierarchy which determines it's `PERLND`, etc. See below "Example JSON", and compare to below "Original Special Action".

#### Example JSON - Option 2 UVNAME declaration. Must create a unique equation in each RCHRES or PERLND (or other domain) tree for every `UVNAME` defined.

{ "PERLND_P005": { "name": "PERLND_P005", "object_class": "ModelObject", "value": "0", "UNO3": { "name": "UNO3", "object_class": "Equation", "equation": "0.5 FNO3" }, "SNO3": { "name": "SNO3", "object_class": "Equation", "equation": "0.5 FNO3" }, "UNO3": { "name": "UNO3", "object_class": "Equation", "equation": "0.5 * FNO3" } }
}

#### Or, as a globally applied `UVNAME` (non-domain specific), will be loaded by OM code at each domain.

{

"UVNAME": {
    "name": "UVNAME",
    "object_class": "ModelObject",
    "value": "0",
    "UNO3": {
        "name": "UNO3",
        "object_class": "Equation",
        "equation": "0.5 * FNO3"
    },
    "SNO3": {
        "name": "SNO3",
        "object_class": "Equation",
        "equation": "0.5 * FNO3"
    }
}

}


#### Original Special Action `FNO3` partition.

respec / HSPsquared