Merge pull request #7 from Katetc/master

Changes for the Nag compiler and documentation with Doxygen

.gitignore

@@ -1,3 +1 @@
-/.externalToolBuilders/
-/.project
-/.pydevproject
+html/

doc/CMakeFiles/3.2.3/CMakeSystem.cmake

@@ -0,0 +1,15 @@
+set(CMAKE_HOST_SYSTEM "Linux-3.10.0-123.el7.x86_64")
+set(CMAKE_HOST_SYSTEM_NAME "Linux")
+set(CMAKE_HOST_SYSTEM_VERSION "3.10.0-123.el7.x86_64")
+set(CMAKE_HOST_SYSTEM_PROCESSOR "x86_64")
+
+
+
+set(CMAKE_SYSTEM "Linux-3.10.0-123.el7.x86_64")
+set(CMAKE_SYSTEM_NAME "Linux")
+set(CMAKE_SYSTEM_VERSION "3.10.0-123.el7.x86_64")
+set(CMAKE_SYSTEM_PROCESSOR "x86_64")
+
+set(CMAKE_CROSSCOMPILING "FALSE")
+
+set(CMAKE_SYSTEM_LOADED 1)

doc/CMakeFiles/cmake.check_cache

@@ -0,0 +1 @@
+# This file is generated by cmake for dependency checking of the CMakeCache.txt file

doc/source/GettingStarted.txt

@@ -20,35 +20,21 @@
 
 /*! \page intro Introduction 
 
-PIO is a software interface layer designed to encapsolate the
-complexities of parallel IO and make it easier to replace the lower
-level software backend.  It currently supports <a href=http://www.unidata.ucar.edu/software/netcdf/docs/html_guide/index.html#user_guide>
-netcdf </a>  and <a href=http://trac.mcs.anl.gov/projects/parallel-netcdf> pnetcdf </a>.
-
-PIO calls are collective.  A MPI communicator is set in a call to
-\ref PIO_init and all tasks associated with that communicator must
-participate in all subsequent calls to PIO.  An application can make
-multiple calls to \ref PIO_init in order to support multiple MPI communicators.
-
-To use PIO, your program should begin by calling the
-\ref PIO_init function providing the MPI communicator and the
-rank within that communicator of the calling task. This call initializes an
-IO system type structure that will be used in subsequent file and
-decomposition functions.
-
-You can then open a file for reading or writing with a call to \ref
-PIO_createfile or \ref PIO_openfile. In this call you will specify the
-file type: pio_iotype_netcdf, pio_iotype_pnetcdf, 
-pio_iotype_netcdf4c or pio_iotype_netcdf4p; along with the file name 
-and optionally the netcdf mode.
-
-To read or write decomposed data you must first describe the mapping
-between the organization of data in the file and that same data in the
-application space.  This is done in a call to
-\ref PIO_initdecomp. In the simplest call to this function, a
-one dimensional integer array is passed from each task, the values in
-the array represent the offset from the beginning of the array
-on file.   
+PIO is a software interface layer designed to encapsolate the complexities of parallel IO and make it easier to replace the lower level software backend.  It currently supports <a href=http://www.unidata.ucar.edu/software/netcdf/docs/html_guide/index.html#user_guide> netcdf </a>  and <a href=http://trac.mcs.anl.gov/projects/parallel-netcdf> pnetcdf </a>.
+
+Basic description of how to optimize IO in a parallel environment...
+
+PIO calls are collective.  A MPI communicator is set in a call to \ref PIO_init and all tasks associated with that communicator must participate in all subsequent calls to PIO.  An application can make multiple calls to \ref PIO_init in order to support multiple MPI communicators.
+
+Begin by checking out a copy from [gitHub](https://github.com/PARALLELIO/ParallelIO) and installing on your system as per the instructions in the [Installation](@ref install) document. Take a look at examples of PIO usage in both complex and simple test programs in the [Examples](@ref examp) document. Finally, read through the [FAQ](@ref faq) to see if any remaining questions can be answered. 
+
+### Using PIO has three basic steps. ###
+
+1. Your program should call the \ref PIO_init function, and provide the MPI communicator (and the rank within that communicator) of the calling task. This call initializes an IO system type structure that will be used in subsequent file and decomposition functions.
+
+2. You can open a file for reading or writing with a call to \ref PIO_createfile or \ref PIO_openfile. In this call you will specify the file type: pio_iotype_netcdf, pio_iotype_pnetcdf, pio_iotype_netcdf4c or pio_iotype_netcdf4p; along with the file name and optionally the netcdf mode.
+
+3. Finally, you can read or write decomposed data to the output file. You must describe the mapping between the organization of data in the file and that same data in the application space.  This is done in a call to \ref PIO_initdecomp. In the simplest call to this function, a one dimensional integer array is passed from each task, the values in the array represent the offset from the beginning of the array on file. (what happens next?)
 
 
 */

doc/source/Installing.txt

@@ -15,39 +15,130 @@
  *
  */ /*! \page install Installing PIO
 
-<ol>
-<li>Download the code from the following Google code subversion location using either a subversion export:
 
-> svn export http://parallelio.googlecode.com/svn/trunk_tags/pio1_8_12  <<<< need to correct
-</li>
+The PIO code is currently stored on github at <https://github.com/PARALLELIO/ParallelIO>. For questions about downloading or developing this code, consult the [CIME Git Wiki](https://github.com/CESM-Development/cime/wiki/CIME-Git-Workflow) or email <mailto:[email protected]>.
 
-<li>PIO uses <a href="http://www.cmake.org> cmake </a> to configure and build 
+### Dependencies ###
 
-Before running cmake, you will need to know the location of some supporting libraries. 
+PIO can use NetCDF (version 4.3.3+) and/or PnetCDF (version 1.6.0+) for I/O.
+Ideally, the NetCDF version should be built with MPI, which requires that it
+be linked with an MPI-enabled version of HDF5.  Optionally, NetCDF can be 
+built with DAP support, which introduces a dependency on CURL.  Additionally,
+HDF5, itself, introduces dependencies on LIBZ and (optionally) SZIP.
 
-- Set the NETCDF_PATH environment variable to the netcdf install directory.
+### Configuring with CMake ###
 
-- Set the PNETCDF_PATH environment variable to the pnetcdf install directory, This will enable support
-for parallel-netcdf
+To configure the build, PIO requires CMake version 2.8.12+.  The typical
+configuration with CMake can be done as follows:
 
-- Set the CC, FC, MPICC, and MPIFC environment variables to the serial and parallel C and Fortran 90 compiler names.
 
-This should be the minimal set of flags required to build pio.
+    > CC=mpicc FC=mpif90 cmake [-DOPTION1=value1 -DOPTION2=value2 ...] /path/to/pio/source
 
-One additional flag of interest is -PIO_FILESYSTEM_HINTS which can
-be set to gpfs or lustre.  You should only use this flag if you are sure that the
-file system you are using is either gpfs or lustre respectively. If you are unsure, then do not use this flag. </li>
 
-<li>After cmake completes use gmake in the build directory to complete the build.   
+where `mpicc` and `mpif90` are the appropriate MPI-enabled compiler wrappers
+for your system.
 
-> gmake
+The `OPTIONS` section typically should consist of pointers to the install
+locations for various dependencies, assuming these dependencies are not 
+located in *canonical* search locations.  
 
-Note that although the user application only needs to 'use pio'  at least some compilers require that
-all of the module files be located in the install directory. If that is the case, then running
+For each dependency `XXX`, one can specify the location of its 
+installation path with the CMake variable `XXX_PATH`.  If the `C` and
+`Fortran` libraries for the dependency are installed in different locations
+(such as can be done with NetCDF), then you can specify individually
+`XXX_C_PATH` and `XXX_Fortran_PATH`.  Hence, you can specify the locations
+of both NetCDF-C and NetCDF-Fortran, as well as PnetCDF, with the following
+CMake configuration line:
 
-> gmake install 
 
-will move the compiled library and module files to the directory specified by $PREFIX.</li>
-</ol>
+    > CC=mpicc FC=mpif90 cmake -DNetCDF_C_PATH=/path/to/netcdf-c \
+               -DNetCDF_Fortran_PATH=/path/to/netcdf-fortran \
+               -DPnetCDF_PATH=/path/to/pnetcdf \
+               /path/to/pio/source
+
+
+This works for the dependencies: `NetCDF`, `PnetCDF`, `HDF5`, `LIBZ`, `SZIP`.
+
+### Additional CMake Options ###
+
+Additional configuration options can be specified on the command line.
+
+The `PIO_ENABLE_TIMING` option can be set to `ON` or `OFF` to enable or
+disable the use of GPTL timing in the PIO libraries.  This feature requires
+the GPTL C library for the PIO `C` library and the GPTL Fortran library with
+the `perf_mod.mod` and `perf_utils.mod` interface modules.  If these GPTL
+libraries are already installed on the system, the user can point PIO to the
+location of these libraries with the `GPTL_PATH` variable (or, individually,
+`GPTL_C_PATH` and `GPTL_Fortran_Perf_PATH` variables).  However, if these
+GPTL libraries are not installed on the system, and GPTL cannot be found,
+then PIO will build its own internal version of GPTL.  
+
+If PnetCDF is not installed on the system, the user can disable its use by
+setting `-DWITH_PNETCDF=OFF`.  This will disable the search for PnetCDF on the
+system and disable the use of PnetCDF from within PIO.
+
+If the user wishes to disable the PIO tests, then the user can set the
+variable `-DPIO_ENABLE_TESTS=OFF`.  This will entirely disable the CTest 
+testing suite, as well as remove all of the test build targets.
+
+If you wish to install PIO in a safe location for use later with other
+software, you may set the `CMAKE_INSTALL_PREFIX` variable to point to the
+desired install location.
+
+### Building ###
+
+Once you have successfully configured PIO with CMake in a build directory.
+From within the build directory, build PIO with:
+
+
+    > make
+
+
+This will build the `pioc` and `piof` libraries.
+
+
+### Testing ###
+
+If you desire to do testing, and `PIO_ENABLE_TESTS=ON` (which is the default
+setting), you may build the test executables with:
+
+
+    > make tests
+
+
+Once the tests have been built, you may run tests with:
+
+
+    > ctest
+
+
+_If you have not run `make tests` before you run `ctest`, then you will see
+all of the tests fail._
+
+Alternatively, you may build the test executables and then run tests 
+immediately with:
+
+
+    > make check
+
+
+(similar to the typical `make check` Autotools target).
+
+*NOTE:* These tests are designed to run in parallel.
+If you are on one of the supported supercomputing platforms (i.e., NERSC, NWSC, ALCF, 
+etc.), then the `ctest` command will assume that the tests will be run in an appropriately configured and scheduled parallel job.  This can be done by requesting an interactive session from the login nodes and then running `ctest` from within the interactive terminal.  Alternatively, this can be done by running the `ctest` command from a job submission script.  It is important to understand, however, that `ctest` itself will preface all of the test executable commands with the appropriate `mpirun`/`mpiexec`/`runjob`/etc. Hence, you should not further preface the `ctest` command with these MPI launchers.
+
+### Installing ###
+
+Once you have built the PIO libraries, you may install them in the location
+specified by the `CMAKE_INSTALL_PREFIX`.  To do this, simply type:
+
+
+    > make install
+
+
+If the internal GPTL libraries were built (because GPTL could not be found
+and the `PIO_ENABLE_TIMING` variable is set to `ON`), then these libraries
+will be installed with PIO.
 
 */

tests/performance/pioperformance.F90

@@ -101,7 +101,8 @@ program pioperformance
         if(varsize(vs) > 0 ) then
            do nv=1,max_nvars
               if(nvars(nv)>0) then
-                 call pioperformancetest(decompfile(i), piotypes(1:niotypes), mype, npe, rearrangers, niotasks, nframes, nvars(nv), varsize(vs))
+                 call pioperformancetest(decompfile(i), piotypes(1:niotypes), mype, npe, rearrangers, & 
+                                         niotasks, nframes, nvars(nv), varsize(vs))
               endif
            enddo
         endif