Document commonly used hydrologic model output variable units

[stcui007]

On a number of occasions in recent time and past, users of ngen have asked about the units of output variables from running ngen. As ngen becomes more freqiently used in the community, there is a need to address this issue in a centralized document. This PR summarizes the comments made in the past and tabulate the output variables used in the commonly used hydrologic models so that users can easily find them. Input variables for these models are also tabulated for reference.

Additions

doc/UNITS_IN_NextGen.md

Removals

Changes

Testing

Visually inspecting the md formatted document.

Screenshots

Notes

Todos

Checklist

• [x ] PR has an informative and human-readable title
• [x ] Changes are limited to a single goal (no scope creep)
• [x ] Code can be automatically merged (no conflicts)
• [x ] Code follows project standards (link if applicable)
• [x ] Passes all existing automated tests
• Any change in functionality is tested
• New functions are documented (with a description, list of inputs, and expected output)
• Placeholder code is flagged / future todos are captured in comments
• Project documentation has been updated (including the "Unreleased" section of the CHANGELOG)
• [x ] Reviewers requested with the Reviewers tool ➡️

Testing checklist (automated report can be put here)

Target Environment support

• Linux

[PhilMiller]

In addition to just documenting typical formulations and their (current) units, would it make sense to add runtime output in some fashion that gives the units for each variable that's being output?

Do we currently have anything in the code to do unit conversion of outputs when there's a mix of formulations in use with disparate units?

[stcui007]

To your first question, it is a bit complicated to do in a general fashion because the output variables will depend on the realization config the users put together based on their interest. If we want to do that, in the long run, it probably have to be done in the function get_output_line_for_timestep. There might be quite a few possibilities to consider.

To your second question, I do see unit conversion functions in the codes. I suspect these are for model engine's internal consistency for updating timesteps in the BMI framework, not for outputing variables in proper units. It is possible these functions might be leveraged for output variable units as it is.

Someone more knowledgeable might want to chime in on this.