# $Id: CHANGES,v 1.13 2007-02-12 20:36:41 gosselin_a Exp $
# $Name: not supported by cvs2svn $
# $Log: not supported by cvs2svn $
# Revision 1.12  2007/02/12 20:13:14  gosselin_a
# Allow deleting CDF attributes using the standard del() function.
# Allow querying dimension length using the standard len() functio.
#
# 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, pycdf-0.6.3b
  Date: 2007-02-11

    New features.

      Ported pycdf to NumPy.

    New functionnalities
      A dataset or variable attribute can now be deleted with the 'del()'
      standard function, eg: 'del(cdfFile.attr)' or 'del(cdfVar.attr)'.
      This is equivalent to obtaining the attribute instance and calling
      the delete() method of this instance, altough simpler.

      Standard function len() can be applied to a dimension instance
      to obtain the dimension length. Equivalent to 'dim.inq_len()',
      altough simplet.

    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(<file>,READ)", 
     one must now write: "CDF(<file>,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.

