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?
  • 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

• 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

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.

[rburghol]

Meeting notes:

• UVNAME - creates a simulation-wide relationship, but the actual numbers can differ by domain that they are applied
  • addr: these are targets from the source quantity that corresponds to UVNAME, that take fractions of the UVNAME value, these addr names MUST already be part of the simulation. Ex: SAMSU, surface applied ammonia, is in the NITR domain of the simulation
  • fractions for multiple addr do NOT have to add up to 1.0
• UVQUAN: this is a localized value, that is, it is derived from a single segment simulation quantity, however the resulting UVQUAN value is globally accessible by the unique name.
  • The variable that is reference by UVQUAN must exist in the code or be defined in the global workspace.
• Special Actions manual.
  • "Global Workspace Variables"
• HSPF Common logic document