Add support and testing for equivalent units

[dustinswales]

Description

Extend the unit-conversion functionality to allow for equivalent units.

Equivalent units can be registered in the supported unit conversion module, just as for unit conversion. New equivalent units need to return '{Var}', instead of '{Var}'*some_conversion

User interface changes?: [ No ]

Fixes:
Addresses #570

Testing

Passes tests for Capgen and Prebuild

[gold2718]

That was quick!
This looks good to me.

[gold2718]

I don't know what this is called in the DSM-5 but I really want a couple of more hash marks here :)
I know where to get some cheap :)

[climbfuji]

This is not going to work with prebuild (at least the way the PR is written now). The unit conversions above return

def erg_cm_minus_2_s_minus_1__to__W_m_minus_2():
    """Convert erg per square centimeter and second to Watt per square meter"""
    return '1.0E-3{kind}*{var}'

in other words, they contain the input variable in the result string. I think you need to make similar changes to the ccpp_prebuild logic (if None then skip the unit conversion altogether), or you may get an error in the Python code, or in the auto-generated Fortran code.

[dustinswales]

Yeah, I didn't add this to prebuild yet.
If we agree on this for Capgen, then I could add it in to Prebuild as part of this PR.

[dustinswales]

@gold2718 Nothing is cheap in Norway, not even hashes from what I hear :)
And now I know what DSM-5 is.
(I will add some more hashes in for prettiness)

[gold2718]

Nothing is cheap in Norway, not even hashes from what I hear :)

That's what a harrytur* is for.

*Harrytur: Norwegian slang for driving to Sweden to buy stuff that's cheaper there.

[climbfuji]

@dustinswales The easiest way (no changes at all in prebuild) would be to return just the input variable in the conversion string ({var}) for equivalent units, not None. If a compiler finds foo=foo in the fortran code, it is very likely going to optimize out that line anyway.

[dustinswales]

@climbfuji Done.
Although I think returning None and skipping writing the equivalence statement is the way to go to skip adding all of "transform infrastructure" to the cap. (not here, but post unification).

When returning Var for equivalent cases, we don't just get a foo=foo added before the scheme, but rather:

foo_local = foo
...
call sub_foo(foo=foo_local)
...
foo=foo_local

[climbfuji]

This is not going to work with prebuild (at least the way the PR is written now). The unit conversions above return

def erg_cm_minus_2_s_minus_1__to__W_m_minus_2():
    """Convert erg per square centimeter and second to Watt per square meter"""
    return '1.0E-3{kind}*{var}'

in other words, they contain the input variable in the result string. I think you need to make similar changes to the ccpp_prebuild logic (if None then skip the unit conversion altogether), or you may get an error in the Python code, or in the auto-generated Fortran code.

[climbfuji]

Just checking, does a unit string of m2 s-1 in the metadata files correspond to m2_s_minus_2 or m_2_s_minus_2 or m_plus_2_s_minus_2?

[dustinswales]

In think you mean m2 s-2 as the metadata string?
But yeah, until these units, we didn't have the case where there is an exponent is in the numerator for a supported conversion.
I feel adding _plus_ is overkill, and adding _ between the base and the exponent may be confusing. But I'm down for whatever is agreed upon.

[climbfuji]

There should be an underscore between the unit and the exponent, but I agree that the additional _plus is not needed.

[dustinswales]

@climbfuji After some sleuthing, I don't know if we should add the underscore here. We would need to extend units_to_string() to find and partition the baseXpositive_exponent piece of the string.
This is not hard, but we don't distinguish the baseXpositive_exponent anywhere else in the metadata (there are "m2" all over the physics, for example), so adding that distinction for the name of an internal procedures name is probably not necessary.