/******************************************************************************
 *
 * 
 *
 * Copyright (C) 2009 
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation under the terms of the GNU General Public License is hereby 
 * granted. No representations are made about the suitability of this software 
 * for any purpose. It is provided "as is" without express or implied warranty.
 * See the GNU General Public License for more details.
 *
 * Documents produced by Doxygen are derivative works derived from the
 * input used in their production; they are not affected by this license.
 *
 */ 

/*! \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 netcdf
(http://www.unidata.com), pnetcdf
(http://trac.mcs.anl.gov/projects/parallel-netcdf) and MPI-IO.

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 PIO 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.  You should also
provide the number of iotasks to be used, the stride or number of
tasks between iotasks, and the number of mpi aggregators to be used.
You may optionally also choose the base IO task. This task will be
used for output of any non-decomposed data.  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, or
pio_iotype_binary, 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 0 based offset from the beginning of the array
on file.   

*/