Proposal for units support for real entries

[h-krishnan]

At present, real entries returned from the settings API are in SI units but the unit information is not available. There is no ready mechanism to convert the value to other units.
Suppose we define a "RealWithUnits" class:

class RealWithUnits(float):
   ...

The float value is the SI value of the setting, but the class also stores unit information.
Along with the real value, suppose we also return the units via the API.

>>> session.get_settings_service().get_var("setup/boundary-conditions/velocity-inlet/inlet2/vmag/constant")
(10.2, "m/s")

We can wrap the return value with RealWithUnits so that setup.boundary_conditions.velocity_inlet['inlet2'].vmag.constant() will return RealWithUnits(10.2, "m/s"). The __str__() method of this class will return (10.2, 'm/s').
We can support index operators so that users can get the value in desired units:

v = RealWithUnits(10.2, "m/s")
v["cm/s"]  # --> "1020 [cm/s]" ( ReaWithUnits(1020, "cm/s") )

Whenever values are set via RealWithUnits() instead of real, we could convert to SI units and then send to Fluent. We could support special "tuple" assignment:

setup.boundary_conditions.velocity_inlet['inlet2'].vmag.constant = (1.2, "ft/s")

Of course, if no units are specified, SI units are implicitly assumed.

setup.boundary_conditions.velocity_inlet['inlet2'].vmag.constant = 1.2  # m/s

Values returned from Fluent will always be in SI units. But if user creates their own RealWithUnits object and sets a setting with that value, the value will be converted to SI units before sending to Fluent. User's specification of units is not preserved in the case file.

[seanpearsonuk]

@h-krishnan thanks for raising this topic. This looks good.

To instantiate a ReaWithUnits and reliably convert for any quantity type then in certain cases the quantity type is needed. This is the case for temperature versus temperature difference, and rotation based quantities. ReaWithUnits could take an additional optional construction argument to denote this, which would be an enumeration constant from a narrow range of values. To make that work, the API needs to provide that information.

[seanpearsonuk]

@hpohekar you can start to think about this topic soon. Perhaps do some research. We can start it without having the new-style API in place - in fact we can mock that part in some basic testing. For the simple case that only covers the requirements as dicussed above then one could imagine that we could quite easily implement everything ourselves. But what if RealWithUnits were a full value type with operations like * / + - power, then we have to deal with generating correct resultant units as well as validation of inputs for consistency (e.g. adding same dimensions). So I think we should look into using some library from the ecosystem. In that case, you might not need to do much unit testing at all.

[dnwillia-work]

Generally I think this is a great idea. To have units attached to real values would be useful. I think it would be good if the library supported mathematics. eg: you can multiply two instances of RealWithUnits and get a new object with the result and the proper units.

[seanpearsonuk]

Created #678, which references this, and can be tracked on the kanban board.

[seanpearsonuk]

@h-krishnan We are thinking about how compute commands etc should work. Do you already have a fixed idea about this?

Taking report definition as an example, whereas the value is currently a float, i.e., [{<report def name>: <float value>}], it could be an object: [{<report def name>: <real object>}]. This real object could have a method to get the quantity info (just as for API parameters). Whatever we do here should be mirrored by what we do for expressions etc, and should not diverge significantly from the behaviour for real parameters.

@hpohekar

[seanpearsonuk]

@h-krishnan @dnwillia-work @hpohekar @gyeole @mkundu1 @ajain-work @prmukherj

Metadata attributes

units-quantity

In the current version (2023R1) this is currently simply a string in the settings API, e.g., "pressure", where the name is specifically a Fluent name*, which encompasses many things, all with that Fluent-specific naming. For a client to use this information, it needs to know how these names translate to names that it understands, or at least into correct units. For instance, the units code in PyFluent uses names inherited from the Ansys/CFX units library. The names do not match, and inevitably the two sets of quantities are different, such that one-to-one translation of names is impracticable. The internal data structures that map those Fluent names to corresponding SI units can easily be translated to Python, such that any client could at least extract the units from the Fluent name. Alternatively, we could also provide such information directly as attributes via the API (see units and dimensions below).

The current representation of units-quantity as string is seen as too limiting. For instance, the API returns an area-integral of pressure, where the quantity information could be preserved as the product of pressure and area rather than force. The proposed format is {"pressure":1, "area":1} for the present example, and {"pressure": 1} for the first example. The client can use the detailed quantity information not only to select the most appropriate units, but may also propagate that information in subsequent client-side operations (e.g., quantity1 * quantity2), such that appropriate units for those objects could also be computed.

units

In the current version, there is no units attribute. The client code has the responsibility of always computing the units from the units-quantity attribute, but as mentioned above, that might not always be practical. Hence, a units string attribute could be added. The provided units string would be of some specific format, and would also contain some idiosyncrasies. The issues caused by those idiosyncrasies should not be underestimated. For instance C stands for coulomb, but we are using it to stand for degrees celsius. These two facts (the specific format and the wrong use of some symbols) means that any client would have to be careful when using the data in its own code.

dimensions

The safest way to label the data is with its dimensions. The representation could be a fixed-length list/tuple of floats with the meaning of each element clearly documented (shorter lists could be returned, implying a tail of all zeros). Given that it is also documented that all data is SI, this attribute allows suitable units of all data to be robustly computed without having either to deal with arcane quantity names or to parse units strings of specific formats or containing idiosyncratic symbols. The only drawback is in the case that a client wants to recover the "most" appropriate units.

*Q: are we definitely using the Fluent names in the units-quantity attribute?
n.b. the unitQuantity attributes in the data model APIs all use the CFX/"Ansys" names from the units library.

[seanpearsonuk]

Conclusion following internal discussions:

Exposed attributes

• generally, the key attribute is dimensions. This is the easiest to implement without ambiguity. It provides the client opportunity to generate some appropriate units.
• the other attribute to expose is the units quantity which must be consistent with the dimensions, and confers more specific quantity information. It can be either a string or a dictionary(/map/associated list) of string to float. The string must be in CFX naming format. The float value indicates the power to which each quantity is raised.

Implementations

• settings API parameter implementations will provide an attribute to indicate the quantity, which can be either a string or a dictionary/map/associated list of string to float. The string will be in Fluent naming format. The API framework will translate to CFX naming format so that only those will be exposed, and will also generate the dimensions from the quantity information.
• datamodel parameter implementations will provide an attribute to indicate the quantity, which can be either a string or a dictionary/map/associated list of string to float. The string will be in CFX naming format. The actual data structure will probably be a list of list (dict might not be practical in the implementation TBC). The datamodel framework will automatically generate the dimensions attribute from the quantity attribute.

PyFluent API object methods

• PyFluent API objects reflecting real parameters (as well as other real values extracted from the API) with include methods, dimensions() and quantity_map() connected to the above exposed attributes. Where the attributes are unimplemented, the methods will return None.

Representation of dimensions
Two options are a least of floats, and a dictionary; e.g., dimensions of

• mass: either [1] or {'M': 1}
• force: either [1,1,-2] or {'M': 1, 'L': 1, 'T': -2}

The meaning of the list elements follow the existing CFX convention; [1] and [1,1,-2] imply that each respective following element is 0.