more doc fixes

README.md

@@ -42,122 +42,31 @@ For a full description of the available options and flags, try:
 ./configure --help
 ```
 
-## Configuring with CMake
-
-To configure the build, PIO requires CMake version 2.8.12+.  The typical
-configuration with CMake can be done as follows:
-
-```
-CC=mpicc FC=mpif90 cmake [-DOPTION1=value1 -DOPTION2=value2 ...] /path/to/pio/source
-```
-
-where `mpicc` and `mpif90` are the appropriate MPI-enabled compiler wrappers
-for your system.
-
-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.  
-
-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:
-
-```
-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:
-
-```
+Note that environment variables CC and FC may need to be set to the
+MPI versions of the C and Fortran compiler. Also CPPFLAGS and LDFLAGS
+may need to be set to indicate the locations of one or more of the
+dependent libraries. (If using MPI compilers, the entire set of
+dependent libraries should be built with the same compilers.) For
+example:
+
+```
+export CC=mpicc
+export FC=mpifort
+export CPPFLAGS='-I/usr/local/netcdf-fortran-4.4.5_c_4.6.3_mpich-3.2/include -I/usr/local/netcdf-c-4.6.3_hdf5-1.10.5/include -I/usr/local/pnetcdf-1.11.0_shared/include'
+export LDFLAGS='-L/usr/local/netcdf-c-4.6.3_hdf5-1.10.5/lib -L/usr/local/pnetcdf-1.11.0_shared/lib'
+./configure --prefix=/usr/local/pio-2.4.2 --enable-fortran
 make check
+make install
 ```
 
-(similar to the typical `make check` Autotools target).
+## Building with CMake
 
-**NOTE:** It is important to note that 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:
+The typical configuration with CMake can be done as follows:
 
 ```
-make install
+CC=mpicc FC=mpif90 cmake [-DOPTION1=value1 -DOPTION2=value2 ...] /path/to/pio/source
 ```
 
-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.
+Full instructions for the cmake build can be found in the installation
+documentation.
+

doc/source/GettingStarted.txt

@@ -27,7 +27,7 @@ href=http://www.unidata.ucar.edu/software/netcdf/docs/html_guide/index.html#user
 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...
+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

doc/source/Installing.txt

@@ -20,7 +20,7 @@ The PIO code is currently stored on github at <https://github.com/PARALLELIO/Par
 
 ### Dependencies ###
 
-PIO can use NetCDF (version 4.3.3+) and/or PnetCDF (version 1.6.1+) for I/O.
+PIO can use NetCDF (version 4.6.1+) and/or PnetCDF (version 1.9.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,

doc/source/base.txt

@@ -16,28 +16,30 @@
  */ 
 /*! 
 
-\mainpage Parallel I/O library (PIO)
+\mainpage Parallel I/O Libraries (PIO)
 
 \author Jim Edwards
 \author John M. Dennis
 \author Mariana Vertenstein
 \author Edward Hartnett
 
-The Parallel I/O (PIO) library has been developed over several years
-to improve the ability of component models of the Community Earth
-System Model (CESM) to perform I/O.  We believe that the interface is
-sufficiently general to be useful to a broader spectrum of
-applications.  The focus of development has been on backend tools that
-use the NetCDF file format.  PIO currently supports NetCDF and PnetCDF
-as backend libraries, both can be linked and used with runtime options
-controlling which is used for a given file.
+The Parallel IO libraries (PIO) are high-level parallel I/O C and
+Fortran libraries for structured grid applications. PIO provides a
+netCDF-like API, and allows users to designate some subset of
+processors to perform IO. Computational code calls netCDF-like
+functions to read and write data, and PIO uses the IO processors to
+perform all necessary IO.
 
-PIO2 represents a significant rewrite of the PIO library and includes
-a C API as well as the original F90 API.  A new decomposition strategy
-has been introduced which gives the user more ability to tune io communications.
+PIO also supports the creation of multiple computation components,
+each containing many processors, and one shared set of IO
+processors. The computational components can perform write operation
+asynchronously, and the IO processors will take care of all storage
+interaction.
 
-This user's guide provides information about the PIO library and examples on how it can be used. 
-Please review the ChangeLog that is included with the distribution for up-to-date release information.
+This user's guide provides information about the PIO library and
+examples on how it can be used. Please watch the PIO GitHub site
+[https://github.com/NCAR/ParallelIO] for announcements and new
+releases.
 
  - \ref intro
  - \ref install

doc/source/faq.txt

@@ -25,7 +25,7 @@
 Note that num_iotasks is the maximum number of IO tasks to use for an IO operation.   The size of the field being read or written along with the tunable blocksize parameter, \ref PIO_set_blocksize, determines the actual number of tasks used for a given IO operation.
 </dd>
 <dt>How do I test if PIO is installed and working correctly? </dt> 
-    <dd>The PIO Library distribution contains a testpio subdirectory with a number of programs to test the PIO library. Please see the \ref examp page for details. </dd>
+    <dd>The PIO Library distribution contains tests for PIO. They are run my 'make check'. The tests use mpiexec to run tests on 4, 8, or 16 processors. </dd>
 
 </dl>
 */

docs/_c_a_mexample.html

@@ -107,7 +107,7 @@ <h1><a class="anchor" id="Init"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/annotated.html

@@ -106,7 +106,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/api.html

@@ -149,7 +149,7 @@ <h2><a class="anchor" id="inqnc"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/contributing_code.html

@@ -94,7 +94,7 @@ <h2>Indentation and Spacing</h2>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/decomp.html

@@ -94,7 +94,7 @@ <h1><a class="anchor" id="SUBSETREARR"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/deprecated.html

@@ -77,7 +77,7 @@
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_105b7c361203833ef447ec1f3c9e0fde.html

@@ -102,7 +102,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_209baab7a174f8da935e472521be6c82.html

@@ -78,7 +78,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_68267d1309a1af8e8297ef4c3efbcdba.html

@@ -75,7 +75,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_6df6542b1223c38c3752260fabab64d0.html

@@ -84,7 +84,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_d28a4824dc47e487b107a5db32ef43c4.html

@@ -75,7 +75,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/dir_fbdd47254eba6596566cfbbd6768a55d.html

@@ -78,7 +78,7 @@
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:19 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:36 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/error.html

@@ -83,7 +83,7 @@
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/examp.html

@@ -87,7 +87,7 @@ <h3>Other Examples</h3>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/example1_8c.html

@@ -475,7 +475,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#aeb75303058f3be9b462de7ba
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/example2_8c.html

@@ -703,7 +703,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#aeb75303058f3be9b462de7ba
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/example_pio_8c.html

@@ -624,7 +624,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a0ddf1224851353fc92bfbff6
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/example_pio_8f90.html

@@ -149,7 +149,7 @@ <h2 class="memtitle"><span class="permalink"><a href="#a8ec2266d83cd6c0b762cbcbc
 </div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

docs/faq.html

@@ -74,14 +74,14 @@
 </ul>
 Note that num_iotasks is the maximum number of IO tasks to use for an IO operation. The size of the field being read or written along with the tunable blocksize parameter, <a class="el" href="group___p_i_o__set__blocksize.html">PIO_set_blocksize</a>, determines the actual number of tasks used for a given IO operation.  </dd>
 <dt>How do I test if PIO is installed and working correctly?  </dt>
-<dd><p class="startdd">The PIO Library distribution contains a testpio subdirectory with a number of programs to test the PIO library. Please see the <a class="el" href="examp.html">Examples</a> page for details. </p>
+<dd><p class="startdd">The PIO Library distribution contains tests for PIO. They are run my 'make check'. The tests use mpiexec to run tests on 4, 8, or 16 processors. </p>
 <p class="enddd"></p>
 </dd>
 </dl>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Fri Apr 19 2019 14:00:17 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Tue Apr 30 2019 10:14:35 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>