Some questions on how to use Quantity's as objects

[jeffwright13]

Hello,

I have a use case for Quantiphy that I'm not sure how to handle. I enjoy this library and would like to expand and streamline the way I have been using it. My goal is to minimize the number of times/places where I have to type in something like variable = Quantity(value, unit).

I work with a codebase where the usual way to express physical units in a human-readable form has been to type in string formatters for each print or log statement:

LOG.info(f"Real and reactive power values are P = {real_power:,.0f} Watts, Q = {reactive_power:,.0f} VAr")

The output from this is passable, but not great:

real_power = -63_120_0220_100
reactive_power = 9_455_010
Real and reactive power values are P = -631,200,220,100 Watts, Q = 9,455,010 VAr

So the decimal places are OK and the commas help separate out large quantities, but it's still a bit tedious to read, and I have to do this every place in the code where a log or print statement is used to show a quantity.

As a direct replacement for this, I started invoking Quantity() as a constructor, inline, for each value I wanted to print/log. For example:

LOG.info(f"Real and reactive power values are P = {Quantity(real_power, 'W')}, Q = {Quantity(reactive_power, 'VAr')}")

The output now takes care of the auto-scaling issue:

Real and reactive power values are P = -631.2 GW, Q = 9.455 MVAr

This is straightforward and there don't seem to be any situations where I can't use it. But it's basically the same amount of work as just hand-formatting the strings. The only benefit to using Quantiphy in this case is the auto-scaling.

At some point I discovered that I could define a Quantity at the beginning of some block of code, then access it directly when invoking print or log. For example:

real_power = Quantity(-63_120_0220_100, "W")
reactive_power = Quantity(9_455_010, "VAr")
clock_rate = Quantity(1_544_000, "Hz")
.
.
.
LOG.info(f"Real and reactive power values are P = {real_power}, Q = {reactive_power}")
LOG.info(f"Observed clock rate: {clock_rate}")

Real and reactive power values are P = -631.2 GW, Q = 9.455 MVAr
Observed clock rate: 1.544 MHz

This seems cleaner, less burdensome, easier to review in a PR, and becomes more efficient the more times I reference either variable in a print/log statement. But it doesn't always work. Here are a couple of examples.

Example 1:

Simple arithmetic on aQuantity instance removes its "Quantity-ness.

a = Quantity(1100, "meter")

type(a)
quantiphy.Quantity
a
Quantity('1.1 kmeter')

b = 2 * a

type(b)
float
b
2200.0

Example 2:

I have a test that creates a bunch of dataclass instances representing test input vectors, pushes them onto a queue, then later unpacks them for use in another part of the code. Once the data has been consumed by one iteration of the test, I want to print out the results, which includes the values in the original dataclass, some of which have units that I want to be handled by Quantiphy. I would like to just define my dataclass fields as a Quantity with an assigned unit, and then later on populate their values. Something like this, I guess:

@dataclass
class TestInput:
    enabled: bool
    max: Quantity(0, "s")
    min: Quantity(0, "s")
    test_p: Quantity(0, "Watt")
    test_q: Quantity(0, "VAr")
    clock_rate: Quantity(0, "Hz")

Is this possible? In general, how can I just create Quantities, with or without values, and pass them around as objects, to be manipulated by other code (like in formulas), and then have their values printed/logged correctly with their associated units?

I admit I have not read all the docs, so maybe some of this is in there. Please point me to appropriate sections if I've missed something.

Thanks in advance, Jeff

[KenKundert]

I increasingly find myself subclassing Quantity to support specific and common units. This started when I wanted to print dollar amounts, because the formatting for currency is idiosyncratic. So I would typically define something like this at the top of my code:

    >>> class Dollars(Quantity):
    ...     units = '$'
    ...     form = 'fixed'
    ...     prec = 2
    ...     strip_zeros = False
    ...     show_commas = True

That simplifies printing a dollar amount:

    >>> print(f"Total: {Dollars(total)}")
    $10,000.00

Over time I found myself doing that more and more often. It seems like an approach that might help you. For example, you could create subclasses for types of quantities you encounter often:

    >>> class W(Quantity):
    ...     units = 'W'
    ...     name = 'P'

    >>> class VAr(Quantity):
    ...     units = 'VAr'
    ...     name = 'Q'

    >>> class s(Quantity):
    ...     units = 's'
    ...     name = 'time'

    >>> class Hz(Quantity):
    ...     units = 'Hz'
    ...     name = 'freq'

Then, printing values might look like this:

    >>> real_power = 2.5e9
    >>> reactive_power = 125e6
    >>> clock_rate = 42.6e3

    >>> print(f"Real power: P = {W(real_power)}")
    Real power: P = 2.5 GW

    >>> print(f"Reactive power: Q = {VAr(reactive_power)}")
    Reactive power: Q = 125 MVAr

    >>> print(f"Observed clock rate: {Hz(clock_rate)}")
    Observed clock rate: 42.6 kHz

Or, if you define the quantities up front, you might get this:

    >>> real_power = W(2.5e9)
    >>> reactive_power = VAr(125e6)
    >>> clock_rate = Hz(42.6e3)

    >>> print(f"Real power: {real_power:Q}")
    Real power: P = 2.5 GW

    >>> print(f"Reactive power: {reactive_power:Q}")
    Reactive power: Q = 125 MVAr

    >>> print(f"Observed clock rate: {clock_rate:Q}")
    Observed clock rate: freq = 42.6 kHz

Finally, on your data class question. I am not conversant with dataclasses, but a quick glance at the documentation seems to suggest that you should use the Quantity subclasses rather than the Quantity objects for your type qualifiers. That is not all that helpful because the arguments will only be cast to the specified types if they are not already the desired type, and since Quantity subclasses float, the dataclass will not cast float arguments to the specified quantity. It will cast strings though, which is interesting. Anyway, you can
fix things up in post_init()::

    >>> @dataclass
    ... class TestInput:
    ...     max: s
    ...     min: s
    ...     test_p: W
    ...     test_q: VAr
    ...     clock_rate: Hz = "100 kHz"
    ...     enabled: bool=True
    ...
    ...     def __post_init__(self):
    ...         self.max = s(self.max)
    ...         self.min = s(self.min)
    ...         self.test_p = W(self.test_p)
    ...         self.test_q = VAr(self.test_q)
    ...         self.clock_rate = Hz(self.clock_rate)

    >>> test = TestInput(max=1.2, min=0.34, test_p=2.5e9, test_q=125e6)

    >>> print(f"max = {test.max}")
    max = 1.2 s

    >>> print(f"min = {test.min}")
    min = 0.34 ms

    >>> print(f"test_p = {test.test_p}")
    test_p = 2.5 GW

    >>> print(f"test_q = {test.test_q}")
    test_q = 125 MVAr

    >>> print(f"clock_rate = {test.clock_rate}")
    clock_rate = 100 kHz

Hope that helps,
-Ken

[jeffwright13]

Revisiting the arithmetic issue. Can I use Quantity objects (or subclassed objects) in standard arithmetic or functional calculations?

In [11]: a = Quantity(1100, "meter")

In [12]: type(a)
Out[12]: quantiphy.Quantity

In [13]: 2*a
Out[13]: 2200.0

In [14]: type(2*a)
Out[14]: float

In [7]: import math

In [8]: def something(var: Quantity):
   ...:     return var ** 2 // math.pi

In [9]: something(a)
Out[9]: 385154.0

[KenKundert]

Yes. As I said, they subclass float and so can be used anywhere floats can be used. But be aware that the result of an expression involving Quantities is always a true float, not a quantity, as shown by your examples.

[jeffwright13]

Right - and so is there a way to use Quantify objects in an arithmetic expression so then when I get the result, if I want to print/log it, it will retain units? I know I can always 'cast' it back to a Quantity, but that seems a bit superfluous since I already defined the units on the original object.

[KenKundert]

No. It is a common request, and conceptually it would be possible to provide a collection of overloaded operators to do the job. The reason I don't do that is that

1. I have found very little use for it
2. It is a deep hole (it is surprisingly fragile, often coming up with unsatisfying or incorrect units, and would require a great deal of work and user engagement to make it work as desired).

Let me say a bit more about 1, because it seems counter intuitive to many people. In my experience, and I have long experience with writing numerical programs, you want units and SI scale factors when reading numbers and when writing numbers, but there is little to no benefit to carrying and manipulating units during the intervening calculations. In most programs the input & output values and their units are prescribed. For example, I do a lot of work in circuit simulation, and when simulating a circuit you may compute voltage waveforms as a function of component values, such as resistances, capacitances and inductances. These values are always given in Ohms, Farads, and Henrys and the computations involved to compute the output voltage are very complex. Practically it would make no sense and provide no value to actually compute the units of the output waveforms as a function ot input units because the computations are structured to always produce voltages. You would be doing a lot of extra work to determine what you already knew, that the output is a voltage. In my experience, the value of units on the inputs and output is as a form of documentation and error checking. Once a program has been fully debugged and is working properly, then the errors are always in specifying the inputs and interpreting the outputs. Providing units on the inputs and output reduce the chance of errors.

There is one application that I have found benefits from interactive computation of the units along side the values, and that is if you are writing a calculator. In that case the user can be doing any calculation, the calculator itself has no up-front expectation on the units involved. It would be nice to be able to say 100V * 2A = 200W. I have such a program, but it does not propagate units. One day, if I have the time, I may extend QuantiPhy to support calculation of units, and see just how useful or annoying unit computation is.

[jeffwright13]

That all makes sense, and I agree with your statements. In my situation, I am dealing with energy and power calculations for renewable power plants, so mostly kA, kV, MW, MWh, and MVAr. And like you, all I care about is the values/units going in and coming out.

I can live with the subclass solution, and use those classes inline to make things more consistent and nicer to look at, so no further requests at this time. Thanks very much for taking the time to help!