Align variable types with intent used by xarray-simlab

[aufdenkampe]

The current design separates variables into three types based on the use attribute: 'static', 'state', or 'dynamic'. This can lead to substantial confusion.

I much prefer the variable intent as defined by xarray-simlab, where the three options are:

• intent='in' if needed as input to a process, but not modified (read-only)
• intent='inout' if updated by a process (read & write)
• intent='out' if computed by a process (write only)

This is much less ambiguous, and more clearly aligns with modeling language describing inputs and outputs (and variables that are both).

As more background, the term "state variable" means something very specific to chemists, which does not align with the current use of that term by this library. Remember that these are water quality modules, so I would really like to move back toward using that term in a way that doesn't conflict with how it is used by chemists. See:

• State Variables
• State vs Path Variables | ChemTalk
• State vs. Path Functions - Chemistry LibreTexts

This issue started out as a side thread under the following:

• Figure out what to do with volume and surface area #50 (comment)

NOTE: I do not think this change will deeply affect core functionality, although a deeper exploration of impacts will be required. @xaviernogueira explained some potential complications with his #50 (comment)

[aufdenkampe]

In response to @xaviernogueira's #50 (comment), I wrote #50 (comment):

I indeed think that we indeed have in, inout, and out variables, but that they aren't simple translations from your current static, dynamic, and state.

For example, while some input (in) variables are a single scalar (such as the Arrhenius coefficients) , whereas others (such as volume and surface area) are full time-changing grid of values that you get from an external program. The key point is that these values are not changed by anything internal to these models. A chemist would argue that volume and surface area are state variables

Other variables, like Temperature or a nutrient concentration, are read in from an external source, modified by these models, and sent back to the external transport model. These are "state variables" (as defined by a chemist) that would be inout.

Many other "state variables", however, will never be read from an external program, but are completely calculated within these modules. These variables are out whether we write them to a file or not (because of course we could write them to a file). Calling these intermediate values doesn't make sense, because many of them could be important for post-modeling interpretation, even though we aren't going to send them back to the transporter model for advection/diffusion calculations.

[aufdenkampe]

In support of my reasoning, @PeterKlaver emailed me the following comments:

I wanted to add my support for your position. I too am uncomfortable with using “state variable” in a sense that departs from its more formal definition in math and science and modeling. The distinction there (that is, what a state variable is versus a derived variable) is not relevant to the case at hand. Your reference to “intent” strikes me as rather more exactly relevant to the case as I understand it. You may know that in Fortran, subprogram variables can be (and ought to be) declared with an “intent” attribute that can have the values “in”, “out” or “inout”. I think this primarily provides instructions to the compiler, which wouldn’t apply here, but the organizational thinking is the same: is my subprogram allowed to modify these, and what does the calling program do with them on the other side of the interface.

I think you’ve got this covered and I’m interested to find out where it lands. But “static”, “dynamic” and “state” doesn’t work for me. “Static” and “dynamic” are already a binary pair, and two’s company, three’s a crowd (in this case anyway).