CGNS 3.3.0
============

INTRODUCTION
===============

This document describes the difference between CGNS 3.2.1 and
CGNS 3.3.0, and contains information on known problems in CGNS 3.3.0.

Links to the CGNS 3.3.0 source code can be found at:

     http://cgns.org/download.html

User documentation for the current release can be found at:

     http://cgns.org/CGNS_docs_current/midlevel/index.html

For more information, see the CGNS home page:

     http://cgns.org


CONTENTS
============

- New Features
- Support for new platforms and languages
- Bug Fixes since CGNS 3.2.1
- Known Problems

New Features
==============

    Configuration:
    ------------------
    * Example build scripts for supercomputer systems can be found in src/SampleScripts 
      of the CGNS source code. They include scripts for building zlib, 
      hdf5 (assuming the user does not already have them installed system wide) 
      and a script for building CGNS. All the scripts use autotools; cmake remains untested.

    * The Fortran compiler environment variable can now be set with "FC", this is the preferred
      method.

    * The Fortran compiler flags can now be set with "FCFLAGS", this is the preferred method.
      If both FFLAGS (which predates FCFLAGS) and FCFLAGS are set then FCFLAGS is ignored. (CGNS-23)

    Library:
    ------------
    * Replaced the hid_t to double (and vice-versa) utilities to_HDF_ID and to_ADF_ID 
      from a type cast to a function which uses memcpy for the conversion. This is needed 
      for the upcomming release of HDF5 1.10 where hid_t was changed from a 32 bit integer 
      to a 64 bit integer. Should be transparent to user.

    * Implemented CPEX0039 : To enable with CGNS_ENABLE_BASE_SCOPE

    * Implemented CPEX0038 : Quadratic Elements for High Order


    Parallel Library:
    ---------------------
    * The default parallel input/output mode was changed from CGP_INDEPENDENT 
      to CGP_COLLECTIVE.

    * A new function was added for passing MPI info to the CGNS library:
      cgp_mpi_info (cgp_mpi_info_f)

    * A new parallel example benchmark program, benchmark_hdf5.c, was added 
      to directory ptests.

    * The cgp_*_read/write_dataset APIs now excepts non-allocated arrays, or NULL, 
      as valid parameters for the datasets. Additionally, the dimensional arrays, 
      rmin and rmax, can also be NULL. If the data array is NULL and the dimensional 
      arrays are not NULL, then the validity of the dimensional arrays, rmin and rmax, 
      is not checked. For collective parallel IO, this is used as a mechanism to 
      indicated that processes with NULL API parameters will not write any data to the file.

    * cgp_queue_set and cgp_queue_flush were depreciated in this release.

    Fortran Library:
    --------------------
    * SUPPORT WAS DROPPED FOR NON-FORTRAN 2003 COMPLIANT COMPILERS.

    * Configure was changed to check if the Fortran compiler is Fortran 2003 compliant.

    * The predefined CGNS constant parameters data types were changed from 
      INTEGER to ENUM, BIND(C) for better C interoperability. The users should use the 
      predefined constants whenever possible and not the numerical value represented by 
      the constants. A variable expecting an enum value returned from a Fortran API should be 
      declared, INTEGER(cgenum_t).

    * INCLUDE "cgslib_h" was changed in favor of using a module, USE CGNS.
      - This allows defining a KIND type for integers instead of 
        the current way of using the preprocessor dependent cgsize_t.

    * The user should be sure to declare the arguments 
      declared int in the C APIs as INTEGER in Fortran. The ONLY 
      Fortran arguments declared as type cgsize_t should be the 
      arguments which are also declared cgsize_t in the C APIs. This 
      is very important when building with option --enable-64bit. The 
      test programs were updated in order to conform to this convention.

    * Assuming the rules in step [enu:int64] were followed, users 
      should not need to use parameter CG_BUILD_64BIT since Fortran's 
      cgsize_t is now guaranteed to match C's cgsize_t. 

    * Fortran programs defining CGNS data types with a default 
      INTEGER size of 8 bytes also then need to compile the CGNS 
      library with the default INTEGER size of 8 bytes. This is 
      independent of whether or not --enable-64bit is being used. For 
      clarification, using --enable-64bit allows for data types (i.e. 
      those declared as cgsize_t) to be able to store values which 
      are too large to be stored as 4 byte integers (i.e. numbers 
      greater than 2,147,483,647). It is not necessary, or advisable 
      (since it waste memory), to have CGNS INTEGER types (types 
      declared int in C) to be 8 bytes; the variables declared as 
      cgsize_t will automatically handle data types that can not be 
      stored as 4 byte integers when --enable-64bit is being used. If 
      the CGNS library was not compiled with a default INTEGER of 8 
      bytes, but the calling program was, then all integers passed to 
      CGNS with C type int should be declared INTEGER(C_INT).   

    * A new Fortran API was added for determining the CGNS data type of a 
      variable which is interoperable with the C data type. 

      Function cg_get_type(var)
         type, INTENT(IN) :: var
         INTEGER(KIND(enumvar)) :: cg_get_type

      An example of using the new function to automatically specify the CGNS 
      type corresponding to the Fortran data type is,

         INTEGER, DIMENSION(1:10) :: Array_i
         CALL cgp_array_write_f("ArrayI",cg_get_type(Array_i(1)),1,INT(nijk(1),cgsize_t),Ai, err)

    * Removed all parallel flush/queue functions (CGNS-9)

    * Removed support of "include cgns_f.h", all examples and tests were updated to reflect these changes (CGNS-34)

    Tools:
    ----------
     - None

Bug Fixes since CGNS 3.2.1 release
==================================

    Configuration:
    ------------------
    * Fixed issue with autotools putting a blank "-l" in "MPILIBS =" when compiling the library
      using mpi.

    * Added a new PGI fortran compiler flag fix issue when  passing to C varags (CGNS-40)

    * CMake find_package was added for HDF5, users should use -D CMAKE_PREFIX_PATH=$HDF_DIR to
      specify a specific version of HDF5.


    Library:
    ------------

    * Generally improved the performance of cgp_open (cgp_open_f).

    * Fixed elemtest.c to compile for SunOS 5.12 (CGNS-29)

    * Fixed parallel issue when not all processors involved in reading/writing (CGNS-51)
    
    * Fixed argument being passed to H5Pget_driver in ADFH.c (CGNS-50)

    * Fixed issue with writing/reading 4D and higher arrays in parallel (CGNS-19) 

    Fortran:
    ------------

    * cgio_link_size_f -- file_len and name_len were changed from cgsize_t to integer to match the C API, CGNS-37.

    * cgio_is_link_f -- cgio_num was changed from type cgsize_t to an integer to match the C API, CGNS-36.

    * cgio_is_supported_f -- ier changed from cgsize_t to integer to match the C API, CGNS-35.

    * Added PGI flag to fix cg_goto_f failing with the PGI compilers on x86_64 platforms, CGNS-40.


    Tools:
    ----------
    * None

Known Problems
================

   * Building CGNS with Fortran enabled is not working on Windows.
   * When building with PGI and gcc compilers it might be necassary to set the
     environment variables:
            FLIBS="-Wl,--no-as-needed -ldl"
            LIBS="-Wl,--no-as-needed -ldl"

Supported Platforms
======================
The following platforms are supported and have been tested for this release.
They are built with the configure process unless specified otherwise.

    Linux 2.6.32-573.3.1.el6      GNU C (gcc), Fortran (gfortran)   compilers:
    #1 SMP x86_64 GNU/Linux          Version 4.4.7 20120313 
    (platypus)                       Version 4.8.4, Version 5.2.0
                                  PGI C, Fortran for 64-bit target on x86-64;
                                      Version 15.7-0
                                  Intel(R) C (icc), C++ (icpc), Fortran (icc)
                                  compilers:
                                     Version 15.0.3.187 Build 20150407
                                  MPICH 3.1.4 compiled with GCC 4.9.3

    Linux 2.6.32-504.8.1.el6.ppc64 gcc (GCC) 4.4.7 20120313 (Red Hat 4.4.7-11)
    #1 SMP ppc64 GNU/Linux         GNU Fortran (GCC) 4.4.7 20120313 (Red Hat 4.4.7-11)
    (ostrich)                      IBM XL C/C++ V13.1
                                   IBM XL Fortran V15.1
                                  

    Linux 3.10.0-229.14.1.el7   GNU C (gcc), Fortran (gfortran)
    #1 SMP x86_64 GNU/Linux       compilers:
    (kituo/moohan)                  Version 4.8.3 20140911 (Red Hat 4.8.3-9)
                                    Version 5.2.0
                                  Intel(R) C (icc), Fortran (icc)
                                  compilers:
                                     Version 15.0.3.187 Build 20150407
                                  MPICH 3.1.4 compiled with GCC 4.9.3

    SunOS 5.11 32- and 64-bit     Sun C 5.12 SunOS_sparc
    (emu)                         Sun Fortran 95 8.6 SunOS_sparc

    Mac OS X Yosemite 10.10.5     Apple clang/clang++ version 6.0 from Xcode 7.0.0
    64-bit                        gfortran GNU Fortran (GCC) 4.9.2
    (osx1010dev/osx1010test)      Intel icc/icpc/ifort version 15.0.3

Tested Configuration Features Summary
=====================================

    In the table below
          y   = tested
          n   = not tested in this release
          x   = not working in this release
          dna = does not apply

Platform                             |  C        | F90/  |  F90     
                                     |  parallel | F2003 |  parallel
-------------------------------------|-----------|-------|----------
SunOS 5.11 32-bit                    |   n      |  y/y       n      
SunOS 5.11 64-bit                    |   n      |  y/y    |  n      
Windows 7                            |   n      |  x/x    |  n      
Windows 7 x64                        |   n      |  x/x    |  n      
Windows 7 Cygwin                     |   n      |   x/x   |  n      
Windows 8.1                          |   n      |  x/x    |  n      
Windows 8.1 x64                      |   n      |  x/x    |  n        
Windows 10                           |   n      |  x/x    |  n      
Windows 10  x64                      |   n      |  x/x    |  n      
Mac OS X Mountain Lion 10.8.5 64-bit |   n      |  y/y    |  n      
Mac OS X Mavericks 10.9.5 64-bit     |   n      |  y/y    |  n     
Mac OS X Yosemeti 10.10.5 64-bit     |   n      |  y/y    |  n     
AIX 6.1 32- and 64-bit               |   n      |  y/n    |  n    
CentOS 6.7 Linux 2.6.32 x86_64 GNU   |   y      |  y/y    |  y    
CentOS 6.7 Linux 2.6.32 x86_64 Intel |   n      |  y/y    |  n    
CentOS 6.7 Linux 2.6.32 x86_64 PGI   |   n      |   y/y   |  n    
CentOS 7.1 Linux 3.10.0 x86_64 GNU   |   y      |  y/y    |  y    
CentOS 7.1 Linux 3.10.0 x86_64 Intel |   n      |  y/y    |  n    
Linux 2.6.32-431.11.2.el6.ppc64      |   n      |  y/n    |  n
