Unit of Measurement


This is a collection of ideas and discussions about the inclusion of a Unit of Measurement package in SAGE that have taken place in the last year (half 2008 - half 2009). Hopefully this can helps developers and other people involved to get a clear image of the current situation.

The main sources are:


This is the situation described by the trac ticket at about August 2008. The proposal was to include in SAGE one of the following packages (already existing):


Comments from IPython mailing list: it is supported by ipython, whose physics profile is supposed to be used in conjunction with.


Unum tutorial

   1 ----------------------------------------------------------------------
   2 | Sage Version 3.4.2, Release Date: 2009-05-05                       |
   3 | Type notebook() for the GUI, and license() for information.        |
   4 ----------------------------------------------------------------------
   5 sage: from unum.units import *
   6 sage: distance = 50*M
   7 sage: distance
   8 50.0 [m]
   9 sage: volume = distance ^ 3; volume
  10 125000.0 [m3]
  11 sage: duration = 25*S; duration
  12 25.0 [s]
  13 sage: speed = distance/duration; speed
  14 2.0 [m/s]
  15 sage: mass = 1.5*KG; mass
  16 1.50000000000000 [kg]
  17 sage: kinetic_energy = 0.5*(mass*speed^2); kinetic_energy
  18 3.00000000000000 [kg.m2/s2]

   1 sage: distance = 50*M
   2 sage: distance + 3*KG
   3 ---------------------------------------------------------------------------
   4 DimensionError                            Traceback (most recent call last)
   5 ...
   6 DimensionError: [m] incompatible with [kg]

   1 sage: TON + 500*KG
   2 1.5 [t]
   3 sage: 5e-8*M - 28*ANGSTROM
   4 472.000000000000 [angstrom]
   5 sage: 3*H + 20*MIN + 15*S
   6 3.3375 [h]
   7 sage: H == 60*MIN
   8 True
   9 sage: 10000*S > 3*H + 15*MIN
  10 False

   1 sage: (M).as(ANGSTROM)
   2 ------------------------------------------------------------
   3    File "<ipython console>", line 1
   4      (M).as(ANGSTROM)
   5           ^
   6 SyntaxError: invalid syntax
   8 sage: M.matchUnits(ANGSTROM)
   9 (10000000000.0 [angstrom], 1.0 [angstrom])

   1 sage: from math import cos
   2 sage: cos(180*ARCDEG)
   3 -1.0
   4 sage: sin(180*ARCDEG)
   5 ---------------------------------------------------------------------------
   6 TypeError                                 Traceback (most recent call last)
   7 ...
   8 TypeError: cannot coerce type '<class 'unum.Unum'>' into a SymbolicExpression.
   9 sage: f = 440*HZ
  10 sage: cos(f)
  11 ---------------------------------------------------------------------------
  12 DimensionError                            Traceback (most recent call last)
  13 ...
  14 DimensionError: unit [Hz] unexpected
  15 sage: dt = 0.32*S
  16 sage: cos(2*pi*f*dt)
  17 0.30901699437502272

   1 sage: a = 1*MILE
   2 sage: b = 1*M
   3 sage: a/b
   4 1609.34 []

- Note that the issue of Celsius conversions is not addressed in this version, i.e. Unum assumes that all quantities are relative, in particular, 1°C is considered as equivalent to 1 K, which is not false if we talk about a raise of temperature. Debates are still on-going on possible Unum evolution to cope with absolute temperatures and offsets, to get at last 1°C = 274.15 K. I am afraid that there is no simple solution to this because it is impossible to guess, without further information from the user, when the offset is needed or not.
- I have another idea for further development, which is more technical. It is to remove the unit dictionary stored as Unum's class attributes (which is the cornerstone of the current design !). Currently, the unit symbol strings are used as keys for this dictionary; numerous dictionary lookups may occur at unit normalization or unification. The idea now is that each unum contains direct references to other unums representing its inner units. More precisely, basic units (as meter, second, etc) are, by definition, terminal unums (without references); derived units (as Newton, Joule, etc) have a dictionary with, as keys, unums representing basic/derived units, and, as values, their exponents; finally, any quantity may be derived with the same idea. The big picture at the end is that all quantities, units and conversion rules boils down to a single connected graph where each node is a unum. This redesign should save a lot in time and memory consumption. It requires however to rewrite almost all Unum's methods. I wrote a small prototype to validate the concept, with promising results.

Enthought's Units

Enthought ticket: the Enthought suite provides two units modules (the second one seems to be Physical Quantities from ScientificPython), so the unification has been proposed, but seems still not completed. As a workaround, both the units package have been deprecated in favor of a unification/refactoring. This was happening in July 2008


Quantities tutorial

   1 ----------------------------------------------------------------------
   2 | Sage Version 3.4.2, Release Date: 2009-05-05                       |
   3 | Type notebook() for the GUI, and license() for information.        |
   4 ----------------------------------------------------------------------
   5 sage: import quantities as pq
   6 sage: q = pq.Quantity([1,2,3],'J')
   7 sage: q
   8 array([1, 2, 3], dtype=object)*J
   9 sage: import numpy as np
  10 sage: q = np.array([1,2,3])*pq.J
  11 ---------------------------------------------------------------------------
  12 AttributeError                            Traceback (most recent call last)
  13 ...
  14 AttributeError: 'NotImplementedType' object has no attribute '_dimensionality'

* The workaround to make it work is to provide Python buil-in numerical types:

   1 sage: q = 1*pq.m
   2 ---------------------------------------------------------------------------
   3 TypeError                                 Traceback (most recent call last)
   4 ...
   5 TypeError: unsupported operand parent(s) for '*': 'Integer Ring' and '<class 'quantities.unitquantity.UnitLength'>'
   6 sage: q = 1r*pq.m
   7 sage: q
   8 array(1.0)*m

   1 sage: q.units = pq.ft
   2 sage: print q
   3 3.28083989501 ft

   1 sage: q2 = q.rescale(pq.watt)
   2 ---------------------------------------------------------------------------
   3 ValueError                                Traceback (most recent call last)
   4 ...
   5 ValueError: Unable to convert between units of "ft" and "W"

   1 sage: q = (10r*pq.meter)**2
   2 ---------------------------------------------------------------------------
   3 AssertionError                            Traceback (most recent call last)
   5 /media/LaCie/Software/sage-3.4.2-sage.math-only-x86_64-Linux/<ipython console> in <module>()
   7 /media/LaCie/Software/sage-3.4.2-sage.math-only-x86_64-Linux/local/lib/python2.5/site-packages/quantities-0.5b2-py2.5.egg/quantities/quantity.pyc in __pow__(self, other)
   8     319             raise ValueError('Quantities must be raised to a single power')
   9     320 
  10 --> 321         dims = self._dimensionality**other.min()
  11     322         ret = super(Quantity, self).__pow__(other)
  12     323         ret._dimensionality = dims
  14 /media/LaCie/Software/sage-3.4.2-sage.math-only-x86_64-Linux/local/lib/python2.5/site-packages/quantities-0.5b2-py2.5.egg/quantities/dimensionality.pyc in __pow__(self, other)
  15     132 
  16     133     def __pow__(self, other):
  17 --> 134         assert isinstance(other, (int, float))
  18     135         new = Dimensionality(self)
  19     136         for i in new:
  21 AssertionError: 

   1 sage: q
   2 array(10.0)*m
   3 sage: q2 = q/(1r*pq.ft)
   4 sage: q2
   5 array(10.0)*m/ft
   6 sage: qs = q2.simplified
   7 sage: print qs
   8 32.8083989501 dimensionless

Darren Dale comments

Darren Dale is the developer of Quantities. From the sage-devel discussion:

"Let me explain my background and that of quantities. I am a scientist at the Cornell High Energy Syncrotron Source (CHESS), and have been a developer on the matplotlib project for several years. I have been interested in having a units package for python for a long time. I have considered all the units packages discussed so far in this thread, but did not find one that suited my needs. I make heavy use of numpy arrays for my work, and wanted a numpy subclass that handled physical quantities. It has taken several iterations but I finally found an appropriate abstraction for such a package. Quantities is already in pretty good shape, in large part because it does not try to do too much. I am currently trying to improve Quantities interaction with numpy's builtin functions, however, I have run into some limitations in numpy, mainly in the implementation of ufuncs. If you are interested, please search the numpy archives for my name. I have suggested on that list how things could be improved, but the devs are busy preparing to release numpy-1.3. I will try to engage them again after 1.3 is out.

I have been spending most of my effort on Quantities recently improving the unit tests. This uncovered a few bugs in numpy that have been fixed in time for the 1.3 release. If you run pq.test() with numpy-1.2, you will encounter errors that have been fixed in 1.3.

I would be willing to consider how quantities can be improved so it can be used in the sage environment, but it sounds like there are some existing issues with the interaction of sage types and numpy arrays which need to be worked out first."

The author of this document (Maurizio) made a comment in post #16 of that discussion:

"provided that the system is SI, you should get the result as a multiplier (bigger than one) of the closest classic unit representation
ex: meters -> nm - um - mm - m - km - ecc ecc

x1 = 10cm
x2 = 1m
x1 + x2 = 1.1m

y1 = 1V (Volt)
y2 = 0.5 V
y1 - y2 = 500 mV

z1 = 500 mA [milliAmperes]
k = 3
z1 * k = 1.5 A 

Two optional features could be very important, in my opinion:
1) locking one object unit representation to a certain order of magnitude and/or metric system

x1 = 1 cm
x2 = x1 + 1 m [x2 can inherit the lock property]
x2 = 101 cm
x2 = 39.76 inches
x2 = 1.01 m

PS: locking property could also be specified when instantiating an object

2) changing the standard metric system (imperial / SI / any other) so that by default each value is scaled as previously proposed "

This is Darren Dale's comment about it:

"Dealing with physical quantities can be somewhat thorny, because there are lots of use cases and everybody seems to have their own ideas about how it should behave. Case in point, the proposal in post #16 would keep units the way you like them for scalars, but it would create additional overhead in cases like 1m-0.999999m. In that case, I guess the proposed behavior would be to yield 1um as the result, which means quantities would have to a) determine the appropriate final unit and b) would have to perform additional arithmetic. Quantities is not really designed to handle item a. I've tried to keep the package as simple as possible in order to keep the problem tractable in my limited free time. Item b would be unacceptable to those concerned about speed. Automatically rescaling the result becomes more complicated with arrays, since you would then have to inspect the min, max or mean in order to determine how to rescale the output, and there are plenty of compound operations sqrt(x +y**3/(...)...) where the user would only be interested in rescaling the final result, not the result of each individual step of arithmetic. There are plenty of examples, like operations involving constants for quantum mechanics or astrophysics, where the user wants the result in the units specified by the constants. "

And a very brief technical description after a question:

"Quantities values are all instances of Quantity or a subclass thereof, and Quantity itself is a subclass of ndarray. It sounds like the first step would be to work out this compatibility issue between sage objects and ndarray. Has anyone brought it up at numpy-discussion? "

Additional information

Robert Dodler commented that any Unit of Measurement package should not provide the output expression forced to any chosen measurement system (SI, imperial, ...), because that would prevent the usage of nonstandard combinations (cm/day, liters/km, ...), which occur very often in the US.

He also suggested in a recent discussion in sage-support, to write a new package from scratch. He himself has written the ezunits for Maxima, making extensive use of symbolic computations. This can provide a source of inspiration. That same discussion evidenced that there is some amount of interest about having this feature in SAGE.

Other stuff

As reported by Carl Witty, fergusnoble was working on a units package for SAGE. He joined the discussion, with a couple of comments: his approach was to always keep quantities in SI, doing the necessary conversions when needed (as opposed to what happen in Quantities). fergusnoble agreed to clean up his code and to make a little demo.

Author comments

In the first run, I was very attracted from Quantities being actively developed. So, I tried to install it within SAGE, but I was disappointed from having to deal with different numeric types than the built-in ones. Once discussed this with the developers, I was trying to overcome the problem, but I soon discovered that Quantities was missing a couple of desired features, like dealing with different units of the same physical quantity. I consider this fundamental to a package like this. The author is certainly nice and kind, but he looks pretty busy, so the amount of help in trying to adapt Quantities to my need was too poor.

In the second run, I have rediscovered Unum. From the tutorial it seems to provide the kind of features I'd like to get, so it could be worthwhile to give it a try. I've easily installed it, and it successfully runs in SAGE. Next step is to understand how hard would it be to let the SAGE mathematical functions to accept Unum types. On the other side, it seems that Unum suffers from a simple design, which can cause memory and cpu usage issues. Its author seems to be conscious of the necessity for a refactoring of the code, getting rid of the big amount of dictionaries used. From this point of view, Quantities seems more modern and better designed.






Unit of Measurement (last edited 2009-06-15 10:16:43 by MaurizioGranato)