class cfunits.Units(units=None, calendar=None, formatted=False, names=False, definition=False, _ut_unit=None)[source]

Bases: object

Utilities for working with physical units.

Store, combine and compare physical units and convert numeric values to different units.

Units are as defined in UNIDATA’s Udunits-2 package, with a few exceptions for greater consistency with the CF conventions namely support for CF calendars and new units definitions.

Modifications to the standard Udunits database

Whilst a standard Udunits-2 database may be used, greater consistency with CF is achieved by using a modified database. The following units are either new to, modified from, or removed from the standard Udunits-2 database (version 2.1.24):

Unit name







New unit



New unit



New unit



New unit




New unit


10 dB

New unit



1e6 m3 s-1

Added symbol


J kg-1

Removed symbol

Plural forms of the new units’ names are allowed, such as practical_salinity_units.

The modified database is in the udunits subdirectory of the etc directory found in the same location as this module.

Accessing units

Units may be set, retrieved and deleted via the units attribute. Its value is a string that can be recognized by UNIDATA’s Udunits-2 package, with the few exceptions given in the CF conventions.

>>> u = Units('m s-1')
>>> u
<Units: m s-1>
>>> v = Units('days since 2004-3-1')
>>> v
<Units: days since 2004-3-1>

Equality and equivalence of units

There are methods for assessing whether two units are equivalent or equal. Two units are equivalent if numeric values in one unit are convertible to numeric values in the other unit (such as kilometres and metres). Two units are equal if they are equivalent and their conversion is a scale factor of 1 and an offset of 0 (such as kilometres and 1000 metres). Note that equivalence and equality are based on internally stored binary representations of the units, rather than their string representations.

>>> u = Units('m/s')
>>> v = Units('m s-1')
>>> w = Units('km.s-1')
>>> x = Units('0.001 kilometer.second-1')
>>> y = Units('gram')
>>> u.equivalent(v), u.equals(v),  u == v
(True, True, True)
>>> u.equivalent(w), u.equals(w)
(True, False)
>>> u.equivalent(x), u.equals(x)
(True, True)
>>> u.equivalent(y), u.equals(y)
(False, False)

Time and reference time units

Time units may be given as durations of time (time units) or as an amount of time since a reference time (reference time units):

>>> v = Units()
>>> v = Units('s')
>>> v = Units('day')
>>> v = Units('days since 1970-01-01')
>>> v = Units('seconds since 1992-10-8 15:15:42.5 -6:00')


It is recommended that the units year and month be used with caution, as explained in the following excerpt from the CF conventions: “The Udunits package defines a year to be exactly 365.242198781 days (the interval between 2 successive passages of the sun through vernal equinox). It is not a calendar year. Udunits includes the following definitions for years: a common_year is 365 days, a leap_year is 366 days, a Julian_year is 365.25 days, and a Gregorian_year is 365.2425 days. For similar reasons the unit month, which is defined to be exactly year/12, should also be used with caution.”


The date given in reference time units is associated with one of the calendars recognized by the CF conventions and may be set with the calendar attribute. However, as in the CF conventions, if the calendar is not set then, for the purposes of calculation and comparison, it defaults to the mixed Gregorian/Julian calendar as defined by Udunits:

>>> u = Units('days since 2000-1-1')
>>> u.calendar
Traceback (most recent call last):
AttributeError: Units has no attribute 'calendar'
>>> v = Units('days since 2000-1-1', 'gregorian')
>>> v.calendar
>>> v.equals(u)

Arithmetic with units

The following operators, operations and assignments are overloaded:

Comparison operators:

==, !=, >, >=, <, <=

Binary arithmetic operations:

+, -, *, /, //, pow(), **, %

Unary arithmetic operations:

-, +

Augmented arithmetic assignments:

+=, -=, *=, /=, //=, **=

The comparison operations return a boolean and all other operations return a new units object or modify the units object in place.

>>> u = Units('m')
>>> u
<Units: m>
>>> v = u * 1000
>>> v
<Units: 1000 m>
>>> u == v
>>> u != v
>>> u **= 2
>>> u
<Units: m2>

It is also possible to create the logarithm of a unit corresponding to the given logarithmic base:

>>> u = Units('seconds')
>>> u.log(10)
<Units: lg(re 1 s)>

Modifying data for equivalent units

Any numpy array or Python numeric type may be modified for equivalent units using the conform static method.

>>> Units.conform(2, Units('km'), Units('m'))
>>> import numpy
>>> a = numpy.arange(5.0)
>>> Units.conform(a, Units('minute'), Units('second'))
array([   0.,   60.,  120.,  180.,  240.])
>>> a
array([0., 1., 2., 3., 4.])

If the inplace keyword is True, then a numpy array is modified in place, without any copying overheads:

>>> Units.conform(
...     a,
...     Units('days since 2000-12-1'),
...     Units('days since 2001-1-1'),
...     inplace=True
... )
array([-31., -30., -29., -28., -27.])
>>> a
array([-31., -30., -29., -28., -27.])

Initialises the Units instance.

units: str or Units, optional

Set the new units from this string.

calendar: str, optional

Set the calendar for reference time units.

formatted: bool, optional

Format the string representation of the units in a standardized manner. See the formatted method.

names: bool, optional

Format the string representation of the units using names instead of symbols. See the formatted method.

definition: bool, optional

Format the string representation of the units using basic units. See the formatted method.

_ut_unit: int, optional

Set the new units from this Udunits binary unit representation. This should be an integer returned by a call to ut_parse function of Udunits. Ignored if units is set.

Units attributes


The calendar for reference time units.


True if the units contain an offset.


True if the units are dimensionless, false otherwise.


True if and only if the units are latitude units.


True if and only if the units are longitude units.


True if the units are pressure units, false otherwise.


True if the units are reference time units, false otherwise.


True if the units are time units, false otherwise.


Whether the units are valid.


The reason that units are considered invalid.


The reference date-time of reference time units.


The units.

Units methods


Conforms values to equivalent values in a compatible unit.


Returns a deep copy.


Tests if units are numerically convertible to equal value.


Tests whether two units are numerically convertible.


Formats the units attribute string in a standardised way.


Returns the logarithmic unit corresponding to a log base.

Units static methods


Conforms values to equivalent values in a compatible unit.