Unit of Measurement
Introduction
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:
Overview
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):
PysicalQuantities module form Scientific Python
Unum last updated in 2005
Pyre has a units package. Pyre looks like a Geodynamics framework
Units module from the Enthought suite
Quantities package from Darren Dale. It looks like the most actively developed (news also in 2009)
PhysicalQuantities
Comments from IPython mailing list: it is supported by ipython, whose physics profile is supposed to be used in conjunction with.
Unum
License: GPL
- Author: Pierre Denis
Last update: 2005 - Designed for Python 2.2
- Supported architectures: Linux, Windows, others
It boasts integration with NumPy and some degree of customization.
- Small size (12.7 Kbytes archived, 119.7 Kbytes installed) and self-consistent. Easy installation.
It has been tested to work with basic functionalities in SAGE 3.4.2
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]
Consistency Checking feature which prevents from combining incompatible units.
Unit Conversions feature, allowing to combine in the same expression multiple units of the same dimension (i.e.: meters, and millimeters, and inches), getting a consistent result.
as statement not working, although the matchUnits function used does still work
Integration with mathematical functions working for python standard math
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
Automatic simplification between units of the same physical quantity (in Quantities this is present but not automatic)
A couple of possible issues from Unum Diary about release 4.0 (the last available):
- 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
License: BSD License (revised)
- Author: Darren Dale
Requires: NumPy 1.2
- Born as refactoring and joining of the two Enthought packages.
Actively developed, the target is the inclusion in NumPy 1.3.
- It has been tested in SAGE. It is not natively compatible with SAGE numerical types.
In this discussion from the Enthought mailing list, they claim that: "The units package is very stable, but perhaps lacking in documentation."
- Small size (746 Kbytes) and self-consistent. Easy installation.
- At a first look, the package has a quite complex structure, which may comes from careful investigation of pros and cons and software design of other packages, to provide a well designed system. The code is harder to read for a newbie, which may stand for code coming from an experienced programmer.
Its documentation is already provided in ReST
It has been tested to work with basic functionalities in SAGE 3.4.2: its heavy use of NumPy is representing an obstacle, provided that SAGE still doesn't play completely nicely with NumPy
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
- Modify quantity's unit:
- Dimensional analysis check:
- Seems to have problems with power in SAGE
1 sage: q = (10r*pq.meter)**2
2 ---------------------------------------------------------------------------
3 AssertionError Traceback (most recent call last)
4
5 /media/LaCie/Software/sage-3.4.2-sage.math-only-x86_64-Linux/<ipython console> in <module>()
6
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
13
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:
20
21 AssertionError:
- Per designer's choice doesn't automatically simplify in ambiguous situations
- Supports quantities with uncertainty
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
ex:
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
ex:
x1 = 1 cm
x1.lock('cm')
x2 = x1 + 1 m [x2 can inherit the lock property]
x2 = 101 cm
x2.lock('inches')
x2 = 39.76 inches
x2.unlock()
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.
Threads
http://groups.google.com/group/sage-devel/browse_thread/thread/8791448b7a303ce9/807189c979add549
http://groups.google.com/group/sage-devel/browse_thread/thread/ae18ce618abd66d2/b440d40dd28b8ef2
http://groups.google.com/group/sage-support/browse_thread/thread/842c647087271b71/6b398b1f4309bd2e
etc.