import ctypes import netCDF4 import os import sys from numpy import array as numpy_array from numpy import dtype as numpy_dtype from numpy import empty as numpy_empty from numpy import generic as numpy_generic from numpy import ndarray as numpy_ndarray from numpy import ones as numpy_ones from numpy import reshape as numpy_reshape from numpy import where as numpy_where from numpy import zeros as numpy_zeros from .functions import inspect as cf_inspect # -------------------------------------------------------------------- # Aliases for ctypes # -------------------------------------------------------------------- _sizeof_buffer = 257 _string_buffer = ctypes.create_string_buffer(_sizeof_buffer) _c_char_p = ctypes.c_char_p _c_int = ctypes.c_int _c_uint = ctypes.c_uint _c_float = ctypes.c_float _c_double = ctypes.c_double _c_size_t = ctypes.c_size_t _c_void_p = ctypes.c_void_p _pointer = ctypes.pointer _POINTER = ctypes.POINTER _ctypes_POINTER = {4: _POINTER(_c_float), 8: _POINTER(_c_double)} # -------------------------------------------------------------------- # Load the Udunits-2 library and read the database # -------------------------------------------------------------------- if sys.platform == 'darwin': # This has been tested on Mac OSX 10.5.8 and 10.6.8 _udunits = ctypes.CDLL('libudunits2.0.dylib') else: # Linux _udunits = ctypes.CDLL('libudunits2.so.0') #--- End: if # Suppress "overrides prefixed-unit" messages. This also suppresses # all other error messages - so watch out! # # Messages may be turned back on by calling the module function # udunits_error_messages. # ut_error_message_handler ut_set_error_message_handler( # ut_error_message_handler handler); _ut_set_error_message_handler = _udunits.ut_set_error_message_handler _ut_set_error_message_handler.argtypes = (_c_void_p, ) _ut_set_error_message_handler.restype = _c_void_p _ut_set_error_message_handler(_udunits.ut_ignore) # Read the data base # ut_system* ut_read_xml(const char* path); _ut_read_xml = _udunits.ut_read_xml _ut_read_xml.argtypes = (_c_char_p, ) _ut_read_xml.restype = _c_void_p #print 'units: before _udunits.ut_read_xml(',_unit_database,')' _ut_system = _ut_read_xml(None) #print 'units: after _udunits.ut_read_xml(',_unit_database,')' # Reinstate the reporting of error messages #_ut_set_error_message_handler(_udunits.ut_write_to_stderr) # -------------------------------------------------------------------- # Aliases for the UDUNITS-2 C API. See # http://www.unidata.ucar.edu/software/udunits/udunits-2.2.18/doc/udunits/udunits2lib.html # for documentation. # -------------------------------------------------------------------- # int ut_format(const ut_unit* const unit, char* buf, size_t size, unsigned opts); _ut_format = _udunits.ut_format _ut_format.argtypes = (_c_void_p, _c_char_p, _c_size_t, _c_uint) _ut_format.restype = _c_int # char* ut_trim(char* const string, const ut_encoding encoding); _ut_trim = _udunits.ut_trim _ut_trim.argtypes = (_c_char_p, _c_int) # ut_encoding assumed to be int! _ut_trim.restype = _c_char_p # ut_unit* ut_parse(const ut_system* const system, # const char* const string, const ut_encoding encoding); _ut_parse = _udunits.ut_parse _ut_parse.argtypes = (_c_void_p, _c_char_p, _c_int) # ut_encoding assumed to be int! _ut_parse.restype = _c_void_p # int ut_compare(const ut_unit* const unit1, const ut_unit* const # unit2); _ut_compare = _udunits.ut_compare _ut_compare.argtypes = (_c_void_p, _c_void_p) _ut_compare.restype = _c_int # int ut_are_convertible(const ut_unit* const unit1, const ut_unit* # const unit2); _ut_are_convertible = _udunits.ut_are_convertible _ut_are_convertible.argtypes = (_c_void_p, _c_void_p) _ut_are_convertible.restype = _c_int # cv_converter* ut_get_converter(ut_unit* const from, ut_unit* const # to); _ut_get_converter = _udunits.ut_get_converter _ut_get_converter.argtypes = (_c_void_p, _c_void_p) _ut_get_converter.restype = _c_void_p # ut_unit* ut_divide(const ut_unit* const numer, const ut_unit* const # denom); _ut_divide = _udunits.ut_divide _ut_divide.argtypes = (_c_void_p, _c_void_p) _ut_divide.restype = _c_void_p # ut_unit* ut_offset(const ut_unit* const unit, const double offset); _ut_offset = _udunits.ut_offset _ut_offset.argtypes = (_c_void_p, _c_double) _ut_offset.restype = _c_void_p # ut_unit* ut_raise(const ut_unit* const unit, const int power); _ut_raise = _udunits.ut_raise _ut_raise.argtypes = (_c_void_p, _c_int) _ut_raise.restype = _c_void_p # ut_unit* ut_scale(const double factor, const ut_unit* const unit); _ut_scale = _udunits.ut_scale _ut_scale.argtypes = (_c_double, _c_void_p) _ut_scale.restype = _c_void_p # ut_unit* ut_multiply(const ut_unit* const unit1, const ut_unit* # const unit2); _ut_multiply = _udunits.ut_multiply _ut_multiply.argtypes = (_c_void_p, _c_void_p) _ut_multiply.restype = _c_void_p # ut_unit* ut_log(const double base, const ut_unit* const reference); _ut_log = _udunits.ut_log _ut_log.argtypes = (_c_double, _c_void_p) _ut_log.restype = _c_void_p # ut_unit* ut_root(const ut_unit* const unit, const int root); _ut_root = _udunits.ut_root _ut_root.argtypes = (_c_void_p, _c_int) _ut_root.restype = _c_void_p # void ut_free_system(ut_system* system); _ut_free = _udunits.ut_free _ut_free.argypes = (_c_void_p, ) _ut_free.restype = None # float* cv_convert_floats(const cv_converter* converter, const float* # const in, const size_t count, float* out); _cv_convert_floats = _udunits.cv_convert_floats _cv_convert_floats.argtypes = (_c_void_p, _c_void_p, _c_size_t, _c_void_p) _cv_convert_floats.restype = _c_void_p # double* cv_convert_doubles(const cv_converter* converter, const # double* const in, const size_t count, # double* out); _cv_convert_doubles = _udunits.cv_convert_doubles _cv_convert_doubles.argtypes = (_c_void_p, _c_void_p, _c_size_t, _c_void_p) _cv_convert_doubles.restype = _c_void_p # double cv_convert_double(const cv_converter* converter, const double # value); _cv_convert_double = _udunits.cv_convert_double _cv_convert_double.argtypes = (_c_void_p, _c_double) _cv_convert_double.restype = _c_double # void cv_free(cv_converter* const conv); _cv_free = _udunits.cv_free _cv_free.argtypes = (_c_void_p, ) _cv_free.restype = None _UT_ASCII = 0 _UT_NAMES = 4 _UT_DEFINITION = 8 _cv_convert_array = {4: _cv_convert_floats, 8: _cv_convert_doubles} # Some function definitions necessary for the following # changes to the unit system. _ut_get_unit_by_name = _udunits.ut_get_unit_by_name _ut_get_unit_by_name.argtypes = (_c_void_p, _c_char_p) _ut_get_unit_by_name.restype = _c_void_p _ut_get_status = _udunits.ut_get_status _ut_get_status.restype = _c_int _ut_unmap_symbol_to_unit = _udunits.ut_unmap_symbol_to_unit _ut_unmap_symbol_to_unit.argtypes = (_c_void_p, _c_char_p, _c_int) _ut_unmap_symbol_to_unit.restype = _c_int _ut_map_symbol_to_unit = _udunits.ut_map_symbol_to_unit _ut_map_symbol_to_unit.argtypes = (_c_char_p, _c_int, _c_void_p) _ut_map_symbol_to_unit.restype = _c_int _ut_map_unit_to_symbol = _udunits.ut_map_unit_to_symbol _ut_map_unit_to_symbol.argtypes = (_c_void_p, _c_char_p, _c_int) _ut_map_unit_to_symbol.restype = _c_int _ut_map_name_to_unit = _udunits.ut_map_name_to_unit _ut_map_name_to_unit.argtypes = (_c_char_p, _c_int, _c_void_p) _ut_map_name_to_unit.restype = _c_int _ut_map_unit_to_name = _udunits.ut_map_unit_to_name _ut_map_unit_to_name.argtypes = (_c_void_p, _c_char_p, _c_int) _ut_map_unit_to_name.restype = _c_int _ut_new_base_unit = _udunits.ut_new_base_unit _ut_new_base_unit.argtypes = (_c_void_p, ) _ut_new_base_unit.restype = _c_void_p # Change Sv mapping. Both sievert and sverdrup are just aliases, # so no unit to symbol mapping needs to be changed. # We don't need to remove rem, since it was constructed with # the correct sievert mapping in place; because that mapping # was only an alias, the unit now doesn't depend on the mapping # persisting. assert(0 == _ut_unmap_symbol_to_unit(_ut_system, _c_char_p('Sv'), _UT_ASCII)) assert(0 == _ut_map_symbol_to_unit(_c_char_p('Sv'), _UT_ASCII, _ut_get_unit_by_name(_ut_system, _c_char_p('sverdrup')))) # Add new base unit calendar_year calendar_year_unit = _ut_new_base_unit(_ut_system) assert(0 == _ut_map_symbol_to_unit(_c_char_p('cY'), _UT_ASCII, calendar_year_unit)) assert(0 == _ut_map_unit_to_symbol(calendar_year_unit, _c_char_p('cY'), _UT_ASCII)) assert(0 == _ut_map_name_to_unit(_c_char_p('calendar_year'), _UT_ASCII, calendar_year_unit)) assert(0 == _ut_map_unit_to_name(calendar_year_unit, _c_char_p('calendar_year'), _UT_ASCII)) assert(0 == _ut_map_name_to_unit(_c_char_p('calendar_years'), _UT_ASCII, calendar_year_unit)) # Add various aliases useful for CF. def add_unit_alias(definition, symbol, singular, plural): unit = _ut_parse(_ut_system, _c_char_p(definition), _UT_ASCII) if symbol is not None: assert(0 == _ut_map_symbol_to_unit(_c_char_p(symbol), _UT_ASCII, unit)) if singular is not None: assert(0 == _ut_map_name_to_unit(_c_char_p(singular), _UT_ASCII, unit)) if plural is not None: assert(0 == _ut_map_name_to_unit(_c_char_p(plural), _UT_ASCII, unit)) add_unit_alias("1.e-3", "psu", "practical_salinity_unit", "practical_salinity_units") add_unit_alias("calendar_year/12", "cM", "calendar_month", "calendar_months") add_unit_alias("1", None, "level", "levels") add_unit_alias("1", None, "layer", "layers") add_unit_alias("1", None, "sigma_level", "sigma_levels") add_unit_alias("1", "dB", "decibel", "debicels") add_unit_alias("10 dB", None, "bel", "bels") #_udunits.ut_get_unit_by_name(_udunits.ut_new_base_unit(_ut_system), # _ut_system, 'calendar_year') # -------------------------------------------------------------------- # Create a calendar year unit # -------------------------------------------------------------------- #_udunits.ut_map_name_to_unit('calendar_year', _UT_ASCII, # _udunits.ut_new_base_unit(_ut_system)) # -------------------------------------------------------------------- # Aliases for netCDF4.netcdftime classes # -------------------------------------------------------------------- _netCDF4_netcdftime_utime = netCDF4.netcdftime.utime _datetime = netCDF4.netcdftime.datetime DateFromJulianDay = netCDF4.netcdftime.DateFromJulianDay if netCDF4.__version__ <= '1.1.1': _DateFromNoLeapDay = netCDF4.netcdftime._DateFromNoLeapDay _DateFromAllLeap = netCDF4.netcdftime._DateFromAllLeap _DateFrom360Day = netCDF4.netcdftime._DateFrom360Day elif netCDF4.__version__ <= '1.2.4': _DateFromNoLeapDay = netCDF4.netcdftime.netcdftime._DateFromNoLeapDay _DateFromAllLeap = netCDF4.netcdftime.netcdftime._DateFromAllLeap _DateFrom360Day = netCDF4.netcdftime.netcdftime._DateFrom360Day else: # In 1.2.5 these functions have been moved to pure cython (cdef) # functions, inaccessible from python. pass # -------------------------------------------------------------------- # Aliases for netCDF4.netcdftime functions # -------------------------------------------------------------------- try: _num2date = netCDF4.num2date _date2num = netCDF4.date2num except: _num2date = netCDF4.netcdftime.num2date _date2num = netCDF4.netcdftime.date2num _cached_ut_unit = {} _cached_utime = {} # -------------------------------------------------------------------- # Save some useful units # -------------------------------------------------------------------- # A time ut_unit (equivalent to 'day', 'second', etc.) _day_ut_unit = _ut_parse(_ut_system, _c_char_p('day'), _UT_ASCII) _cached_ut_unit['days'] = _day_ut_unit # A pressure ut_unit (equivalent to 'Pa', 'hPa', etc.) _pressure_ut_unit = _ut_parse(_ut_system, _c_char_p('pascal'), _UT_ASCII) _cached_ut_unit['pascal'] = _pressure_ut_unit # A calendar time ut_unit (equivalent to 'cY', 'cM') _calendartime_ut_unit = _ut_parse(_ut_system, _c_char_p('calendar_year'), _UT_ASCII) _cached_ut_unit['calendar_year'] = _calendartime_ut_unit # A dimensionless unit one (equivalent to '', '1', '2', etc.) #_dimensionless_unit_one = _udunits.ut_get_dimensionless_unit_one(_ut_system) #_cached_ut_unit[''] = _dimensionless_unit_one #_cached_ut_unit['1'] = _dimensionless_unit_one _dimensionless_unit_one = _ut_parse(_ut_system, _c_char_p('1'), _UT_ASCII) _cached_ut_unit[''] = _dimensionless_unit_one _cached_ut_unit['1'] = _dimensionless_unit_one # -------------------------------------------------------------------- # Set the default calendar type according to the CF conventions # -------------------------------------------------------------------- _default_calendar = 'gregorian' _canonical_calendar = {'gregorian' : 'gregorian' , 'standard' : 'gregorian' , 'none' : 'gregorian' , 'proleptic_gregorian': 'proleptic_gregorian', '360_day' : '360_day' , 'noleap' : '365_day' , '365_day' : '365_day' , 'all_leap' : '366_day' , '366_day' : '366_day' , 'julian' : 'julian' , } ## -------------------------------------------------------------------- ## Set month lengths in days for non-leap years (_days_in_month[0,1:]) ## and leap years (_days_in_month[1,1:]) ## -------------------------------------------------------------------- #_days_in_month = numpy_array( # [[-99, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31], # [-99, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]]) # -------------------------------------------------------------------- # Function to control Udunits error messages # -------------------------------------------------------------------- def udunits_error_messages(flag): ''' Control the printing of error messages from Udunits, which are turned off by default. :Parameters: flag : bool Set to True to print Udunits error messages and False to not print Udunits error messages. :Returns: None :Examples: >>> udunits_error_messages(True) >>> udunits_error_messages(False) ''' if flag: _ut_set_error_message_handler(_udunits.ut_write_to_stderr) else: _ut_set_error_message_handler(_udunits.ut_ignore) #--- End: def #def _month_length(year, month, calendar, _days_in_month=_days_in_month): # ''' # #Find month lengths in days for each year/month pairing in the input #numpy arrays 'year' and 'month', both of which must have the same #shape. 'calendar' must be one of the standard CF calendar types. # #:Parameters: # # #''' # shape = month.shape # if calendar in ('standard', 'gregorian'): # leap = numpy_where(year % 4 == 0, 1, 0) # leap = numpy_where((year > 1582) & # (year % 100 == 0) & (year % 400 != 0), # 0, leap) # elif calendar == '360_day': # days_in_month = numpy_empty(shape) # days_in_month.fill(30) # return days_in_month # # elif calendar in ('all_leap', '366_day'): # leap = numpy_zeros(shape) # # elif calendar in ('no_leap', '365_day'): # leap = numpy_ones(shape) # # elif calendar == 'proleptic_gregorian': # leap = numpy_where(year % 4 == 0, 1, 0) # leap = numpy_where((year % 100 == 0) & (year % 400 != 0), # 0, leap) # # days_in_month = numpy_array([_days_in_month[l, m] # for l, m in zip(leap.flat, month.flat)]) # days_in_month.resize(shape) # # return days_in_month ##--- End: def # #def _proper_date(year, month, day, calendar, fix=False, # _days_in_month=_days_in_month): # ''' # #Given equally shaped numpy arrays of 'year', 'month', 'day' adjust #them *in place* to be proper dates. 'calendar' must be one of the #standard CF calendar types. # #Excessive number of months are converted to years but excessive days #are not converted to months nor years. If a day is illegal in the #proper date then a ValueError is raised, unless 'fix' is True, in #which case the day is lowered to the nearest legal date: # # 2000/26/1 -> 2002/3/1 # # 2001/2/31 -> ValueError if 'fix' is False # 2001/2/31 -> 2001/2/28 if 'fix' is True # 2001/2/99 -> 2001/2/28 if 'fix' is True # #:Parameters: # #''' ## y, month = divmod(month, 12) ## year += y # # year += month // 12 # month[...] = month % 12 # # mask = (month == 0) # year[...] = numpy_where(mask, year-1, year) # month[...] = numpy_where(mask, 12, month) # del mask # # days_in_month = _month_length(year, month, calendar, # _days_in_month=_days_in_month) # # if fix: # day[...] = numpy_where(day > days_in_month, days_in_month, day) # elif (day > days_in_month).any(): # raise ValueError("Illegal date(s) in %s calendar" % calendar) # # return year, month, day ##--- End: def # ==================================================================== # # Units object # # ==================================================================== class Units(object): ''' 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 Symbol Definition Status ======================= ====== ============ ============== practical_salinity_unit psu 1e-3 New unit level 1 New unit sigma_level 1 New unit layer 1 New unit decibel dB 1 New unit bel 10 dB New unit sverdrup Sv 1e6 m3 s-1 Added symbol sievert 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 >>> u.units = 'days since 2004-3-1' >>> u **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' .. note:: 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." **Calendar** 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 AttributeError: Can't get 'Units' attribute 'calendar' >>> v = Units('days since 2000-1-1') >>> v.calendar = 'gregorian' >>> v.equals(u) True **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') >>> v = u * 1000 >>> v >>> u == v False >>> u != v True >>> u **= 2 >>> u It is also possible to create the logarithm of a unit corresponding to the given logarithmic base: >>> u = Units('seconds') >>> u.log(10) **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')) 2000.0 >>> 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.]) ''' def __init__(self, units=None, calendar=None, names=None, definition=None, _ut_unit=None): ''' **Initialization** :Parameters: units : str or cf.Units, optional Set the new units from this string. calendar : str, optional Set the calendar for reference time units. format : bool, optional Format the string representation of the units in a standardized manner. See the `format` method. names : bool, optional Format the string representation of the units using names instead of symbols. See the `format` method. definition : bool, optional Format the string representation of the units using basic units. See the `format` 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. ''' if isinstance(units, self.__class__): self.__dict__ = units.__dict__ return if units is not None: units = units.strip() if ' since ' in units: # -------------------------------------------------------- # Set a reference time unit # -------------------------------------------------------- # Set the calendar if calendar is None: _calendar = _default_calendar else: _calendar = _canonical_calendar[calendar.lower()] units_split = units.split(' since ') unit = units_split[0].strip() ut_unit = _cached_ut_unit.get(unit, None) if ut_unit is None: ut_unit = _ut_parse(_ut_system, _c_char_p(unit), _UT_ASCII) if not ut_unit or not _ut_are_convertible(ut_unit, _day_ut_unit): raise ValueError( "Can't set unsupported unit in reference time: '%s'" % value) _cached_ut_unit[unit] = ut_unit #--- End: if utime = _cached_utime.get((_calendar, units), None) if not utime: # Create a new Utime object unit_string = '%s since %s' % (unit, units_split[1].strip()) utime = _cached_utime.get((_calendar, unit_string), None) if utime is None: try: utime = Utime(_calendar, unit_string) except ValueError: # Assume that the value error came from # Utime complaining about the units. In # this case, change the units to something # acceptable to Utime and afterwards # overwrite the Utime.units and # Utime.unit_string attributes with the # correct values. If this assumption was # incorrect, then we'll just end up with # another error, this time untrapped # (possibly due to a wrong calendar). utime = Utime(_calendar, 'days since %s' % units_split[1].strip()) utime.unit_string = unit_string utime.units = unit #--- End: try _cached_utime[(_calendar, unit_string)] = utime #--- End: if _cached_utime[(calendar, units)] = utime #--- End: if self._isreftime = True self._calendar = calendar self._utime = utime else: # ---------------------------------------------------- # Set a unit other than a reference time unit # ---------------------------------------------------- ut_unit = _cached_ut_unit.get(units, None) if ut_unit is None: ut_unit = _ut_parse(_ut_system, _c_char_p(units), _UT_ASCII) if not ut_unit: raise ValueError( "Can't set unsupported unit: %r" % units) _cached_ut_unit[units] = ut_unit #--- End: if self._isreftime = False self._calendar = None self._utime = None #--- End: if self._ut_unit = ut_unit self._units = units if names is not None or definition is not None: self._units = self.formatted(names, definition) return elif calendar: #--------------------------------------------------------- # Calendar is set, but units are not. #--------------------------------------------------------- self._units = None self._ut_unit = None self._isreftime = True self._calendar = calendar self._utime = Utime(_canonical_calendar[calendar.lower()]) return #--- End: if if _ut_unit is not None: #--------------------------------------------------------- # _ut_unit is set #--------------------------------------------------------- self._ut_unit = _ut_unit units = self.formatted(names, definition) _cached_ut_unit[units] = _ut_unit self._units = units self._isreftime = False self._calendar = None self._utime = None return #--- End: if #------------------------------------------------------------- # Nothing has been set #------------------------------------------------------------- self._units = None self._ut_unit = None self._isreftime = False self._calendar = None self._utime = None #--- End: def # def __getstate__(self): # ''' # #Called when pickling. # #:Parameters: # # None # #:Returns: # # out : dict # A dictionary of the instance's attributes # #:Examples: # #>>> u = cf.Units('days since 3-4-5', calendar='gregorian') #>>> u.__getstate__() #{'calendar': 'gregorian', # 'units': 'days since 3-4-5'} # #''' # return dict([(attr, getattr(self, attr)) # for attr in ('calendar', 'units') if hasattr(self, attr)]) # #--- End: def # # def __setstate__(self, odict): # ''' # #Called when unpickling. # #:Parameters: # # odict : dict # The output from the instance's `__getstate__` method. # #:Returns: # # None # #''' # for attr, value in odict.iteritems(): # setattr(self, attr, value) # #--- End: def # def __hash__(self): # ''' #x.__hash__() <==> hash(x) # #''' ## if not self: ## return hash(self.__class__) # # if not self._isreftime: # return hash(('Units', self._ut_unit)) # ## return hash((self._ut_unit, self._rtime._jd0, self._rtime.calendar, ## self._rtime.tzoffset)) # return hash(('Units', # self._ut_unit, self._rtime_jd0, self._rtime_calendar, # self._rtime_tzoffset)) # #--- End: def def __repr__(self): ''' x.__repr__() <==> repr(x) ''' return '' % (self.__class__.__name__, str(self)) #--- End: def def __str__(self): ''' x.__str__() <==> str(x) ''' string = [] if self._units is not None: string.append(self._units) if self._calendar is not None: string.append('calendar=%s' % self._calendar) return ' '.join(string) #--- End: def def __deepcopy__(self, memo): ''' Used if copy.deepcopy is called on the variable. ''' return self #--- End: def def __nonzero__(self): ''' Truth value testing and the built-in operation ``bool`` x.__nonzero__() <==> x!=0 ''' return self._ut_unit is not None #--- End: def def __eq__(self, other): ''' The rich comparison operator ``==`` x.__eq__(y) <==> x==y ''' return self.equals(other) #--- End: def def __ne__(self, other): ''' The rich comparison operator ``!=`` x.__ne__(y) <==> x!=y ''' return not self.equals(other) #--- End: def def __sub__(self, other): ''' The binary arithmetic operation ``-`` x.__sub__(y) <==> x-y ''' if (self._isreftime or (isinstance(other, self.__class__) and other._isreftime)): raise ValueError("Can't do %r - %r" % (self, other)) try: _ut_unit = _ut_offset(self._ut_unit, _c_double(other)) return type(self)(_ut_unit=_ut_unit) except: raise ValueError("Can't do %r - %r" % (self, other)) #--- End: def def __add__(self, other): ''' The binary arithmetic operation ``+`` x.__add__(y) <==> x+y ''' if (self._isreftime or (isinstance(other, self.__class__) and other._isreftime)): raise ValueError("Can't do %r + %r" % (self, other)) try: _ut_unit = _ut_offset(self._ut_unit, _c_double(-other)) return type(self)(_ut_unit=_ut_unit) except: raise ValueError("Can't do %r + %r" % (self, other)) #--- End: def def __mul__(self, other): ''' The binary arithmetic operation ``*`` x.__mul__(y) <==> x*y ''' if isinstance(other, self.__class__): if self._isreftime or other._isreftime: raise ValueError("Can't do %r * %r" % (self, other)) try: ut_unit=_ut_multiply(self._ut_unit, other._ut_unit) except: raise ValueError("Can't do %r * %r" % (self, other)) #--- End: try else: if self._isreftime: raise ValueError("Can't do %r * %r" % (self, other)) try: ut_unit=_ut_scale(_c_double(other), self._ut_unit) except: raise ValueError("Can't do %r * %r" % (self, other)) #--- End: if return type(self)(_ut_unit=ut_unit) #--- End: def def __div__(self, other): ''' x.__div__(y) <==> x/y ''' if isinstance(other, self.__class__): if self._isreftime or other._isreftime: raise ValueError("Can't do %r / %r" % (self, other)) try: ut_unit=_ut_divide(self._ut_unit, other._ut_unit) except: raise ValueError("Can't do %r / %r" % (self, other)) #--- End: try else: if self._isreftime: raise ValueError("Can't do %r / %r" % (self, other)) try: ut_unit=_ut_scale(_c_double(1.0/other), self._ut_unit) except: raise ValueError("Can't do %r / %r" % (self, other)) #--- End: if return type(self)(_ut_unit=ut_unit) #--- End: def def __pow__(self, other, modulo=None): ''' The binary arithmetic operations ``**`` and ``pow`` x.__pow__(y) <==> x**y ''' # ------------------------------------------------------------ # y must be either an integer or the reciprocal of a positive # integer. # ------------------------------------------------------------ if modulo is not None: raise NotImplementedError( "3-argument power not supported for %r" % self.__class__.__name__) if self and not self._isreftime: ut_unit = self._ut_unit try: return type(self)(_ut_unit=_ut_raise(ut_unit, _c_int(other))) except: pass if 0 < other <= 1: # If other is a float and (1/other) is a positive # integer then take the (1/other)-th root. E.g. if # other is 0.125 then we take the 8-th root. try: recip_other = 1/other root = int(recip_other) if recip_other == root: ut_unit = _ut_root(ut_unit, _c_int(root)) if ut_unit is not None: return type(self)(_ut_unit=ut_unit) except: pass else: # If other is a float equal to its integer tehn raise # to the integer part. E.g. if other is 3.0 then we # raise to the power of 3; if other is -2.0 then we # raise to the power of -2 try: root = int(other) if other == root: ut_unit = _ut_raise(ut_unit, _c_int(root)) if ut_unit is not None: return type(self)(_ut_unit=ut_unit) except: pass #--- End: if #--- End: if raise ValueError("Can't do %r ** %r" % (self, other)) #--- End: def def __isub__(self, other): ''' x.__isub__(y) <==> x-=y ''' return self - other #--- End def def __iadd__(self, other): ''' x.__iadd__(y) <==> x+=y ''' return self + other #--- End def def __imul__(self, other): ''' The augmented arithmetic assignment ``*=`` x.__imul__(y) <==> x*=y ''' return self * other #--- End def def __idiv__(self, other): ''' The augmented arithmetic assignment ``/=`` x.__idiv__(y) <==> x/=y ''' return self / other #--- End def def __ipow__(self, other): ''' The augmented arithmetic assignment ``**=`` x.__ipow__(y) <==> x**=y ''' return self ** other #--- End def def __rsub__(self, other): ''' The binary arithmetic operation ``-`` with reflected operands x.__rsub__(y) <==> y-x ''' try: return -self + other except: raise ValueError("Can't do %r - %r" % (other, self)) #--- End def def __radd__(self, other): ''' The binary arithmetic operation ``+`` with reflected operands x.__radd__(y) <==> y+x ''' return self + other #--- End def def __rmul__(self, other): ''' The binary arithmetic operation ``*`` with reflected operands x.__rmul__(y) <==> y*x ''' return self * other #--- End def def __rdiv__(self, other): ''' x.__rdiv__(y) <==> y/x ''' try: return (self ** -1) * other except: raise ValueError("Can't do %r / %r" % (other, self)) #--- End def def __floordiv__(self, other): ''' x.__floordiv__(y) <==> x//y <==> x/y ''' return self / other #--- End def def __ifloordiv__(self, other): ''' x.__ifloordiv__(y) <==> x//=y <==> x/=y ''' return self / other #--- End def def __rfloordiv__(self, other): ''' x.__rfloordiv__(y) <==> y//x <==> y/x ''' try: return (self ** -1) * other except: raise ValueError("Can't do %r // %r" % (other, self)) #--- End def def __truediv__(self, other): ''' x.__truediv__(y) <==> x/y ''' return self / other #--- End def def __itruediv__(self, other): ''' x.__itruediv__(y) <==> x/=y ''' return self / other #--- End def def __rtruediv__(self, other): ''' x.__rtruediv__(y) <==> y/x ''' try: return (self ** -1) * other except: raise ValueError("Can't do %r / %r" % (other, self)) #--- End def def __mod__(self, other): ''' ''' raise ValueError("Can't do %r %% %r" % (self, other)) #--- End def def __neg__(self): ''' The unary arithmetic operation ``-`` x.__neg__() <==> -x ''' return self * -1 #--- End def def __pos__(self): ''' The unary arithmetic operation ``+`` x.__pos__() <==> +x ''' return self #--- End def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def isreftime(self): ''' True if the units are reference time units, False otherwise. Note that time units (such as ``'days'``) are not reference time units. .. seealso:: `isdimensionless`, `islongitude`, `islatitude`, `ispressure`, `istime` :Examples: >>> print Units('days since 2000-12-1 03:00').isreftime True >>> print Units('hours since 2100-1-1', calendar='noleap').isreftime True >>> print Units(calendar='360_day').isreftime True >>> print Units('days').isreftime False >>> print Units('kg').isreftime False >>> print Units().isreftime False ''' return self._isreftime #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def iscalendartime(self): ''' True if the units are reference time units, False otherwise. Note that time units (such as ``'days'``) are not reference time units. .. seealso:: `isdimensionless`, `islongitude`, `islatitude`, `ispressure`, `istime` :Examples: >>> print Units('days since 2000-12-1 03:00').isreftime True >>> print Units('hours since 2100-1-1', calendar='noleap').isreftime True >>> print Units(calendar='360_day').isreftime True >>> print Units('days').isreftime False >>> print Units('kg').isreftime False >>> print Units().isreftime False ''' return bool(_ut_are_convertible(self._ut_unit, _calendartime_ut_unit)) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def isdimensionless(self): ''' True if the units are dimensionless, false otherwise. .. seealso:: `islongitude`, `islatitude`, `ispressure`, `isreftime`, `istime` :Examples: >>> cf.Units('').isdimensionless True >>> cf.Units('1').isdimensionless True >>> cf.Units('100').isdimensionless True >>> cf.Units('m/m').isdimensionless True >>> cf.Units('m km-1').isdimensionless True >>> cf.Units().isdimensionless False >>> cf.Units('m').isdimensionless False >>> cf.Units('m/s').isdimensionless False >>> cf.Units('days since 2000-1-1', calendar='noleap').isdimensionless False ''' return bool(_ut_are_convertible(self._ut_unit, _dimensionless_unit_one)) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def ispressure(self): ''' True if the units are pressure units, false otherwise. .. seealso:: `isdimensionless`, `islongitude`, `islatitude`, `isreftime`, `istime` :Examples: >>> Units('bar').ispressure True >>> Units('hPa').ispressure True >>> print Units('meter^-1-kilogram-second^-2').ispressure True >>> Units('hours since 2100-1-1', calendar='noleap').ispressure False ''' ut_unit = self._ut_unit if ut_unit is None: return False return bool(_ut_are_convertible(ut_unit, _pressure_ut_unit)) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def islatitude(self): ''' True if and only if the units are latitude units. This is the case if and only if the `units` attribute is one of ``'degrees_north'``, ``'degree_north'``, ``'degree_N'``, ``'degrees_N'``, ``'degreeN'``, and ``'degreesN'``. Note that units of ``'degrees'`` are not latitude units. .. seealso:: `isdimensionless`, `islongitude`, `ispressure`, `isreftime`, `istime` :Examples: >>> Units('degrees_north').islatitude True >>> Units('degrees').islatitude False >>> Units('degrees_east').islatitude False >>> Units('kg').islatitude False >>> Units().islatitude False ''' return self._units in ('degrees_north', 'degree_north', 'degree_N', 'degrees_N', 'degreeN', 'degreesN') #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def islongitude(self): ''' True if and only if the units are longitude units. This is the case if and only if the `units` attribute is one of ``'degrees_east'``, ``'degree_east'``, ``'degree_E'``, ``'degrees_E'``, ``'degreeE'``, and ``'degreesE'``. Note that units of ``'degrees'`` are not longitude units. .. seealso:: `isdimensionless`, `islatitude`, `ispressure`, `isreftime`, `istime` :Examples: >>> Units('degrees_east').islongitude True >>> Units('degrees').islongitude False >>> Units('degrees_north').islongitude False >>> Units('kg').islongitude False >>> Units().islongitude False ''' return self._units in ('degrees_east', 'degree_east', 'degree_E', 'degrees_E', 'degreeE', 'degreesE') #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def istime(self): '''True if the units are time units, False otherwise. Note that reference time units (such as ``'days since 2000-12-1'``) are not time units, nor are calendar years and calendar months. .. seealso:: `iscalendartime`, `isdimensionless`, `islongitude`, `islatitude`, `ispressure`, `isreftime` :Examples: >>> Units('days').istime True >>> Units('seconds').istime True >>> Units('kg').istime False >>> Units().istime False >>> Units('hours since 2100-1-1', calendar='noleap').istime False >>> Units(calendar='360_day').istime False >>> Units('calendar_years').istime False >>> Units('calendar_months').istime False ''' if self._isreftime: return False ut_unit = self._ut_unit if ut_unit is None: return False return bool(_ut_are_convertible(ut_unit, _day_ut_unit)) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def reftime(self): ''' The reference date-time of reference time units. .. seealso:: `calendar`, `isreftime`, `units` :Examples: >>> repr(Units('days since 1900-1-1').reftime) >>> str(Units('days since 1900-1-1 03:00').reftime) '1900-01-01 03:00:00' ''' utime = self._utime if utime: origin = utime.origin if origin: return origin #--- End: if raise AttributeError( "{0!r} has no attribute 'reftime'".format(self.__class__.__name__)) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def calendar(self): ''' The calendar for reference time units. May be any string allowed by the calendar CF property. If it is unset then the default CF calendar is assumed when required. .. seealso:: `units` :Examples: >>> Units(calendar='365_day').calendar '365_day' >>> Units('days since 2001-1-1', calendar='noleap').calendar 'noleap' >>> Units('days since 2001-1-1').calendar AttributeError: Units has no attribute 'calendar' ''' value = self._calendar if value is not None: return value raise AttributeError("%s has no attribute 'calendar'" % self.__class__.__name__) #--- End: def # ---------------------------------------------------------------- # Attribute (read only) # ---------------------------------------------------------------- @property def units(self): ''' The units. May be any string allowed by the units CF property. .. seealso:: `calendar` :Examples: >>> Units('kg').units 'kg' >>> Units('seconds').units 'seconds' >>> Units('days since 2000-1-1', calendar='366_day').units 'days since 2000-1-1' ''' value = self._units if value is not None: return value raise AttributeError("'%s' object has no attribute 'units'" % self.__class__.__name__) #--- End: def def equivalent(self, other): ''' Returns True if numeric values in one unit are convertible to numeric values in the other unit. .. seealso:: `~cf.Units.equals` :Parameters: other : Units The other units. :Returns: out : bool True if the units are equivalent, False otherwise. :Examples: >>> u = Units('m') >>> v = Units('km') >>> w = Units('s') >>> u.equivalent(v) True >>> u.equivalent(w) False >>> u = Units('days since 2000-1-1') >>> v = Units('days since 2000-1-1', calendar='366_day') >>> w = Units('seconds since 1978-3-12', calendar='gregorian) >>> u.equivalent(v) False >>> u.equivalent(w) True ''' isreftime1 = self._isreftime isreftime2 = other._isreftime if isreftime1 and isreftime2: # Both units are reference-time units units0 = self._units units1 = other._units if units0 and units1 or (not units0 and not units1): return self._utime.calendar == other._utime.calendar else: return False #--- End: if # Still here? if not self and not other: # Both units are null and therefore equivalent return True if not isreftime1 and not isreftime2: # Both units are not reference-time units return bool(_ut_are_convertible(self._ut_unit, other._ut_unit)) # Still here? Then units are not equivalent. return False #--- End: def def formatted(self, names=None, definition=None): ''' Formats the string stored in the `units` attribute in a standardized manner. The `units` attribute is modified in place and its new value is returned. :Parameters: names : bool, optional Use unit names instead of symbols. definition : bool, optional The formatted string is given in terms of basic-units instead of stopping any expansion at the highest level possible. :Returns: out : str The formatted string. :Examples: >>> u = Units('W') >>> u.units 'W' >>> u.units = u.format(names=True) >>> u.units 'watt' >>> u.units = u.format(definition=True) >>> u.units 'm2.kg.s-3' >>> u.units = u.format(names=True, definition=True) 'meter^2-kilogram-second^-3' >>> u.units = u.format() >>> u.units 'W' >>> u.units='dram' >>> u.format(names=True) '1.848345703125e-06 meter^3' Formatting is also available during object initialization: >>> u = Units('m/s', format=True) >>> u.units 'm.s-1' >>> u = Units('dram', names=True) >>> u.units '1.848345703125e-06 m3' >>> u = Units('W', names=True, definition=True) >>> u.units 'meter^2-kilogram-second^-3' ''' ut_unit = self._ut_unit if ut_unit is None: raise ValueError("Can't format unit %r" % self) opts = _UT_ASCII if names: opts |= _UT_NAMES if definition: opts |= _UT_DEFINITION if _ut_format(ut_unit, _string_buffer, _sizeof_buffer, opts) != -1: return _string_buffer.value raise ValueError("Can't format unit %r" % self) #--- End: def @staticmethod def conform(x, from_units, to_units, inplace=False): ''' Conform values in one unit to equivalent values in another, compatible unit. Returns the conformed values. The values may either be a numpy array or a python numeric type. The returned value is of the same type, except that input integers are converted to floats (see the *inplace* keyword). :Parameters: x : numpy.ndarray or python numeric from_units : Units The original units of `x` to_units : Units The units to which `x` should be conformed to. inplace : bool, optional If True and `x` is a numpy array then change it in place, creating no temporary copies, with one exception: If `x` is of integer type and the conversion is not null, then it will not be changed inplace and the returned conformed array will be of float type. :Returns: out : numpy.ndarray or python numeric The modified numeric values. :Examples: >>> Units.conform(2, Units('km'), Units('m')) 2000.0 >>> 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.]) >>> 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.]) .. warning:: Do not change the calendar of reference time units in the current version. Whilst this is possible, it will almost certainly result in an incorrect interpretation of the data or an error. Allowing the calendar to be changed is under development and will be available soon. ''' if from_units.equals(to_units): if inplace: return x else: return x.copy() #--- End: if if not from_units.equivalent(to_units): raise ValueError("Units are not convertible: %r, %r" % (from_units, to_units)) ut_unit1 = from_units._ut_unit ut_unit2 = to_units._ut_unit if ut_unit1 is None or ut_unit2 is None: raise ValueError("Units are not convertible: %r, %r" % (from_units, to_units)) convert = _ut_compare(ut_unit1, ut_unit2) if from_units._isreftime and to_units._isreftime: # -------------------------------------------------------- # Both units are time-reference units, so calculate the # non-zero offset in units of days. # -------------------------------------------------------- offset = to_units._utime._jd0 - from_units._utime._jd0 else: offset = 0 # ---------------------------------------------------------------- # If the two units are identical then no need to alter the # value, so return it unchanged. # ---------------------------------------------------------------- # if not convert and not offset: # return x if convert: cv_converter = _ut_get_converter(ut_unit1, ut_unit2) if not cv_converter: _cv_free(cv_converter) raise ValueError("Units are not convertible: %r, %r" % (from_units, to_units)) #-- End: if # ---------------------------------------------------------------- # Find out if x is an numpy array or a python number # ---------------------------------------------------------------- if isinstance(x, numpy_generic): # Convert a generic numpy scalar to a 0-d array x = numpy_array(x) if not isinstance(x, numpy_ndarray): x_is_numpy = False else: x_is_numpy = True if not x.flags.contiguous: x = numpy_array(x, order='C') #ARRRGGHH dch # ---------------------------------------------------------------- # Convert an integer numpy array to a float numpy array # ---------------------------------------------------------------- if inplace: if x.dtype.kind is 'i': if x.dtype.char is 'i': y = x.view(dtype='float32') y[...] = x x.dtype = numpy_dtype('float32') elif x.dtype.char is 'l': y = x.view(dtype=float) y[...] = x x.dtype = numpy_dtype(float) else: # At numpy vn1.7 astype has many more keywords ... if x.dtype.kind is 'i': if x.dtype.char is 'i': x = x.astype('float32') elif x.dtype.char is 'l': x = x.astype(float) else: x = x.copy() #--- End: if # ------------------------------------------------------------ # Convert the array to the new units # ------------------------------------------------------------ if convert: if x_is_numpy: # Create a pointer to the array cast to the appropriate # ctypes object itemsize = x.dtype.itemsize pointer = x.ctypes.data_as(_ctypes_POINTER[itemsize]) # print 'U1 ', type(x) # Convert the array in place _cv_convert_array[itemsize](cv_converter, pointer, _c_size_t(x.size), pointer) else: # Create a pointer to the number cast to a ctypes double # object. y = _c_double(x) pointer = ctypes.pointer(y) # Convert the pointer _cv_convert_doubles(cv_converter, pointer, _c_size_t(1), pointer) # Reset the number x = y.value #--- End: if _cv_free(cv_converter) #--- End: if # print 'U', type(x) # ------------------------------------------------------------ # Apply an offset for reference-time units # ------------------------------------------------------------ if offset: # Convert the offset from 'days' to the correct units and # subtract it from x if _ut_compare(_day_ut_unit, ut_unit2): cv_converter = _ut_get_converter(_day_ut_unit, ut_unit2) scale = numpy_array(1.0) pointer = scale.ctypes.data_as(ctypes.POINTER(ctypes.c_double)) _cv_convert_doubles(cv_converter, pointer, _c_size_t(scale.size), pointer) _cv_free(cv_converter) offset *= scale.item() #--- End: if x -= offset #--- End: if # print 'U', type(x) return x #--- End: def def copy(self): ''' Return a deep copy. Equivalent to ``copy.deepcopy(u)``. :Returns: out : The deep copy. :Examples: >>> v = u.copy() ''' return self #--- End: def def dump(self, display=True, prefix=None, omit=()): ''' Return a string containing a description of the units. :Parameters: display : bool, optional If False then return the description as a string. By default the description is printed, i.e. ``u.dump()`` is equivalent to ``print u.dump(display=False)``. :Returns: out : None or str A string containing the description. :Examples: ''' if prefix is None: prefix = self.__class__.__name__ string = [] for attr in self.__dict__: try: string.append("%s.%s = '%s'" % (prefix, attr, getattr(self, attr))) except AttributeError: pass #--- End: for string = '\n'.join(string) if display: print string else: return string #--- End: def def equals(self, other, rtol=None, atol=None): ''' Return True if and only if numeric values in one unit are convertible to numeric values in the other unit and their conversion is a scale factor of 1. .. seealso:: `~cf.Units.equivalent` :Parameters: other : Units The other units. :Returns: out : bool True if the units are equal, False otherwise. :Examples: >>> u = Units('km') >>> v = Units('1000m') >>> w = Units('100000m') >>> u.equals(v) True >>> u.equals(w) False >>> u = Units('m s-1') >>> m = Units('m') >>> s = Units('s') >>> u.equals(m) False >>> u.equals(m/s) True >>> (m/s).equals(u) True Undefined units are considered equal: >>> u = Units() >>> v = Units() >>> u.equals(v) True ''' try: if _ut_compare(self._ut_unit, other._ut_unit): return False except AttributeError: return False isreftime1 = self._isreftime isreftime2 = other._isreftime if not isreftime1 and not isreftime2: # Neither units is reference-time so they're equal return True if isreftime1 and isreftime2: # Both units are reference-time utime0 = self._utime utime1 = other._utime if utime0.calendar != utime1.calendar: return False return utime0.origin_equals(utime1) #--- End: if # One unit is a reference-time and the other is not so they're # not equal return False #--- End: def def inspect(self): ''' Inspect the object for debugging. .. seealso:: `cf.inspect` :Returns: None ''' print cf_inspect(self) #--- End: def def log(self, base): ''' Return the logarithmic unit corresponding to the given logarithmic base. :Parameters: base : int or float The logarithmic base. :Returns: out : Units The logarithmic unit corresponding to the given logarithmic base. :Examples: >>> u = Units('W', names=True) >>> u >>> u.log(10) >>> u.log(2) >>> import math >>> u.log(math.e) >>> u.log(3.5) ''' try: _ut_unit = _ut_log(_c_double(base), self._ut_unit) except TypeError: pass else: if _ut_unit: return type(self)(_ut_unit=_ut_unit) #--- End: try raise ValueError( "Can't take the logarithm to the base %r of %r" % (base, self)) #--- End def #--- End: class # ==================================================================== # # Utime object # # ==================================================================== class Utime(netCDF4.netcdftime.utime): ''' Performs conversions of netCDF time coordinate data to/from datetime objects. This object is (currently) functionally equivalent to a `netCDF4.netcdftime.utime` object. **Attributes** ============== ====================================================== Attribute Description ============== ====================================================== `!_jd0` `!calendar` The calendar used in the time calculation. `!origin` A date/time object for the reference time. `!tzoffset` Time zone offset in minutes. `!unit_string` `!units` ============== ====================================================== ''' def __init__(self, calendar, unit_string=None): ''' **Initialization** :Parameters: calendar : str The calendar used in the time calculations. Must be one of: ``'gregorian'``, ``'360_day'``, ``'365_day'``, ``'366_day'``, ``'julian'``, ``'proleptic_gregorian'``, although this is not checked. unit_string : str, optional A string of the form "time-units since " defining the reference-time units. ''' if unit_string: _netCDF4_netcdftime_utime.__init__(self, unit_string, calendar) else: self.calendar = calendar self._jd0 = None self.origin = None self.tzoffset = None self.unit_string = None self.units = None #--- End: def def __repr__(self): ''' x.__repr__() <==> repr(x) ''' unit_string = self.unit_string if unit_string: x = [unit_string] else: x = [] x.append(self.calendar) return "" % ' '.join(x) #--- End: def def inspect(self): ''' Inspect the object for debugging. .. seealso:: `cf.inspect` :Returns: None ''' print cf_inspect(self) #--- End: def def num2date(self, time_value): '''Return a datetime-like object given a time value. The units of the time value are described by the `!unit_string` and `!calendar` attributes. See `netCDF4.netcdftime.utime.num2date` for details. In addition to `netCDF4.netcdftime.utime.num2date`, this method handles units of months and years as defined by Udunits, ie. 1 year = 365.242198781 days, 1 month = 365.242198781/12 days. ''' units = self.units unit_string = self.unit_string if units in ('month', 'months'): # Convert months to days unit_string = unit_string.replace(units, 'days', 1) time_value = numpy_array(time_value)*365.242198781/12 elif units in ('year', 'years', 'yr'): # Convert years to days unit_string = unit_string.replace(units, 'days', 1) time_value = numpy_array(time_value)*365.242198781 elif units == 'calendar_month': # Convert months to days unit_string = unit_string.replace(units, 'days', 1) time_value = numpy_array(time_value)*365.242198781/12 elif units == 'calendar_year': # Convert months to days unit_string = unit_string.replace(units, 'days', 1) time_value = numpy_array(time_value)*365.242198781/12 u = _netCDF4_netcdftime_utime(unit_string, self.calendar) return u.num2date(time_value) #--- End: def def origin_equals(self, other): ''' ''' if self is other: return True else: return (self._jd0 == other._jd0 and self.calendar == other.calendar and self.tzoffset == other.tzoffset) #--- End: def #--- End: class