# $Id: CHANGES,v 1.5 2007/02/12 00:18:37 gosselin_a Exp $ # $Name: $ # $Log: CHANGES,v $ # Revision 1.5 2007/02/12 00:18:37 gosselin_a # Posted new release of the pycdf documentation. # # Revision 1.11 2007/02/11 22:28:51 gosselin_a # Documented changes for release 0.6-3 . # # Revision 1.10 2006/02/15 03:13:58 gosselin_a # Preliminary 0.6.2 release. # New CDFMF class, some new methods and a few bug fixes. # # Revision 1.9 2006/01/09 04:16:26 gosselin_a # Preparing new release 0.6-2 . # # Revision 1.8 2006/01/09 04:12:15 gosselin_a # New method CDF.inq_unlimlen(). # # Revision 1.7 2006/01/03 23:20:04 gosselin_a # A bug was found in the pycdf-0.6-0 release shortly after it # was made public. The new pycdf-0.6-1 release corrects that. # # Revision 1.6 2006/01/02 23:08:51 gosselin_a # Forgot to enter the 0.6-0 rrelease date. # # Revision 1.5 2006/01/02 20:37:56 gosselin_a # New pycdf-0.6-0 release. # # Revision 1.4 2005/08/16 02:39:03 gosselin_a # Addition of new features in preparation of release 0.6-0 . # -Support of CDF2 file format (64 bit file offsets). # Requires netCDF 3.6+. # # Revision 1.3 2005/08/15 02:00:29 gosselin_a # pycdf-0.5-4 bug fix release. See CHANGES file. # # Revision 1.2 2005/07/16 17:01:18 gosselin_a # pycdf-0.5-3 # pycdf classes are now 'new-style' classes (they derive from 'object'). # Updated documentation and admin files. # List of changes to 'pycdf' since the initial release. pycdf-0.6-3 Date: 2007-02-11 New features. Ported pycdf to NumPy. File changes. setup.py New NUMPY case (now default). Thanks to Christian Marquardt (christian@marquardt.sc) for having submitted his patches. Clean up code. pycdf/__init__.py Clean up the package namespace, so that only the wanted references are exposed to the user pycdf/README updated documentation for numpy pycdf/pycdf/pycdf.py Cleaned up documentation. Added documentation for the CDFMF class. Function pycdfArrayPkg() now takes a parameter to return either the name of the array package, or a reference to the array module used by pycdf. pycdf/pycdfext/numpy/ New subdir, used when the 'numpy' array package is used. examples/ Added examples multi.py and compr.py . pycdf-0.6-2 Date: 2006-02-14 New features. New class CDFMF Class CDFMF is a subclass of CDF, and allows joining a sequence of CDF files by concatenating their record variables together. The set of files can then be manipulated as a whole like an ordinary CDF file. Thanks to Robert Hetland for suggesting this nice addition to pycdf. New method CDF.inq_unlimlen() Calling method inq_unlimlen() of a CDF instance returns the current length of the dataset unlimited dimension, or -1 if no unlimited dimension has been defined in the dataset. New method CDFDim.inq_id() Method inq_id() of a dimension instance returns the dimension index number. New method CDFVar.inq_id() Method inq_id() of a variable instance returns the variable index number. Documentation additions New section "Quirks" to document some not so obvious problems with netcdf and pycdf. Thanks to Ralph Gommers for prompting me to start this section with comments about the _FillValue attribute. Bug fixes. Scalar variables were sometimes incorrectly handled, leading to index error exceptions. Thanks to Rob Hetland for stimulating me to find this bug. pycdf-0.6-1 Date: 2006-01-02 New features. -'numarray' support. Many users asked that pycdf could be linked with 'numarray' instead of just 'Numeric'. This is now possible. To compile pycdf against numarray, simply set "USE = NUMARRAY" at top of the 'setup.py' file in the installation root directory. Then run "python setup.py install" as usual. Set "USE = NUMERIC" to configure pycdf for use with Numeric. Note that pycdf can only be compiled against one array package. However, since pycdf just makes use of the 'array' type and since 'numarray' and 'Numeric' are compatible at the array level, a program importing numarray should work with a Numeric-based pycdf installation, and conversely for a program importing Numeric and a numarray-based pycdf installation. Both numarray and Numeric can thus be installed on the host system. Users are asked to report any incompatibility they may find at this level. Thanks to Robert Hetland (hetland@tamu.edu) for his convincing arguments in favor of the numarray package support. -Support of the new CDF2 file format offered by netCDF 3.6.0, allowing bigger file sizes ( > 2GB). CDF2 files are created by setting flag NC.BIT64_OFFSET in the mode argument when calling the CDF() constructor. This flag will be inoperant if an older version of the netCDF library is installed. Thanks to Bjoern Aadlandsvik (bjorn@imr.no) for suggesting support of the CDF2 large file format. -The ellipsis (...) notation is now allowed inside a slicing expression, to denote any number of intervening dimensions either at the start, the end, of the middle of the expression. Only one ellipsis is allowed, otherwise the expression would be ambiguous. Thus, if 'v' is a 4-dimensional array : v[...] whole array (identical to v[:]) v[...,2:] elements at index 2 and above along the last dimension (equivalent to v[:,:,:,2:]) v[-1,...,1] elements at last index along first dimension, and at first index along last dimension (equivalent to v[-1,:,:,1]) v[2:5,...] elements at index 2 to 4 along first dimension (equivalent to v[2:5]) The ellipsis notation allows one to write more generic code, capable of slicing arrays of arbitrary dimensions. It also helps to write cleaner programs. One can argue that v[...] is a cleaner way to designate a whole array than v[:]. Thanks to Kevin Mueller (kjmuelle@atmos.uiuc.edu) for first suggesting that the ellipsis notation be supported by the pycdf package. -The full contents of a Numeric array or a cdf variable can now be assigned to a sliced variable, simply by using its name, without recourse to a "[:]" slicing expression. For ex.: x[:] = y[:] # how we had to write it before x[:] = y # how we can write it now -A cdf variable can now be converted to a string (and thus printed) without having to slice it (with [:] for ex.). Thus : v = cdf.var(...) print v[:] # how we had to write it before print v # how we can now write it -New functions: pycdfVersion() returns the pycdf version string pycdfArrayPkg() returns the name of the array package used to install pycdf -New method CDFVar.isrecord() Calling method 'isrecord()' of a CDFVar intance tells if the variable is a record variable, eg if its 1st dimension is based on the unlimited dimension. Documentation changes -Added a new section "Primer on reading and querying a netcdf file" Thanks to Rob Hetland (hetland@tamu.edu) for suggesting this addition. -Added new section "Array package : Numeric and numarray". -Added new section "Rules governing array assignment". -Augmented section "High level variable access : extended indexing, slicing and ellipsis" to describe the new ellipsis notation. -Augmented section "Working with the unlimited dimension". Bug fixes. -Previous pycdf releases were somewhat careless when dealing with array assignments. This sometimes resulted in non-sensical results and hard to catch bugs. Many users complained about this. This issue has been extensively reworked in release 0.6-0 . Now, when an array (or a slice of an array) is assigned to, pycdf makes sure that the type of right-hand side is one of the following : - a scalar (integer or float) - a sequence (list or tuple) of integers, floats, or sequences thereof - an array (possibly sliced) When an integer or float scalar value is used on the right-hand side (as in "x[4:6,:10:2] = 5), the value is now replicated (broadcasted) over the whole left-hand size. Thus, "x[:2] = 0" zeroes the first two rows of array "x". Thanks to Kevin Mueller (kjmuelle@atmos.uiuc.edu) for submiting a patch to achieve this behavior. When a sequence appears on the right-hand size, it must hold only integer or float scalars, or nested sequences thereof. The total number of scalars in the sequence (ignoring nesting level) must match exactly the number of elements expected on the left-hand side. Thus, if "x" is a 3x3 array and "seq" is a sequence , then the statement "x[:] = seq" is legal only if "seq" enumerates exactly 9 values, eg: x[:] = (1,2,3,4,5,6,7,8,9) # ok, 9 values x[:] = ((1,2,3),(4,5,6),(7,8,9)) # ok, 9 values x[:] = ((1,2,3)[(4,5,6),(7,8,9)]) # ok, 9 values x[:] = [1,2,3,4] # wrong, 5 values missing When an array (possibly sliced) is used as the right-hand size, its shape must exactly match that of the array (possibly sliced) used on the left- hand side. Thus, if "x" is a 4x4 array and "y" is a 6x4 array : x[...] = y # Fails, shape of x is (4,4) and does not match # that of y which is (6,4) x[...] = y[:4] # Works since array 'y' is sliced to a (4,4) shape If the above conditions are not met, a TypeError or ValueError exception is raised. -In the following sequence of statements : cdf = CDF('test-1.nc', ...) ... cdf.close() cdf = CDF('test-2.nc', ...) ... a CDFError exception could be raised related to a 'Not a netCDF id' error. The error resulted from the combination of an explicit call to the close() method, followed by the reuse of the previous CDF instance variable. The python interpreter executed a call to the cdf.__del__() method in order to free its internal data structures, before reassigning it to a new CDF instance. __del__() then tried to close an already closed file, with perverse effects on the internal state of the netcdf library. Thanks to Deahyok Shin (sdhyok@email.unc.edu) and Bjoern Aadlandsvik (bjorn@imr.no) for having reported this problem. -The unlimited dimension was sometimes badly handled when validating a slicing expression. pycdf-0.5-4 August 14 2005 Bug fix release. -Fixed a bad 'raise' statement in CDF.__init()__ method. (thanks: E.Bernsen@phys.uu.nl who reported this bug) -Fixed an infinite loop condition in the CDF.__del__() method when trying to open a non-existent file. (thanks: E.Bernsen@phys.uu.nl who reported this bug) -Fixed bug in CDF.def_var() method : the number of dimensions was not always correctly computed. (thanks: badland@broadpark.no who reported this bug) -Fixed bug in the handling of scalar variables inside methods get() and put(), and slicing expression "v[:]". Added a new section "Working with scalar variables" in the documentation. (thanks: gerry@ucar.edu for reporting this bug) -Fixed a bug with assignments to variables based on an unlimited dimension. Added a new section "Working with the unlimited dimension" in the documentation. (thanks to sdhyok@email.unc.edu for reporting this bug) -Added a new section "Open issues and current limitations" to the documentation. -Added some comments about the '_FillValue' attribute inside the documentation. pycdf-0.5-3 July 16 2005 Interim release. -pycdf classes are now 'new-style' classes (they derive from 'object'). -Updated documentation. pycdf-0.5-2 July 20 2003 -Corrected unfortunate error in the 'setup.py' script. -Forced closing of the dataset when the python object referring to it goes out of scope. -To avoid name clashes with an upcoming 'pyhdf' package, all netCDF constants heve been moved to a new 'NC' class. As a consequence, instead of saying eg:"CDF(,READ)", one must now write: "CDF(,NC.READ). Since this change comes really early in the lifetime of 'pycdf', it is hoped it will not impact too many users. *** EXAMPLES MUST BE DOWNLOADED AFRESH *** -List of names imported by an "from pycdf import *" statement has been substantially cleaned up. pycdf-0.5-1 July 19 2003 -Initial release.