Skip to content

Commit

Permalink
Merge pull request ESMCI#1403 from NCAR/ejh_docs1
Browse files Browse the repository at this point in the history 
Mostly documentation improvements, plus change to example program...
  • Loading branch information
@edhartnett
edhartnett authored May 1, 2019
2 parents 7d33589 + 59b88bc commit 70518f4
Show file tree
Hide file tree
Showing 8 changed files with 140 additions and 156 deletions.
125 changes: 23 additions & 102 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ cdash site at [http://my.cdash.org/index.php?project=PIO](http://my.cdash.org/in

## Dependencies

PIO can use NetCDF (version 4.3.3+) and/or PnetCDF (version 1.6.0+)
PIO can use NetCDF (version 4.6.1+) and/or PnetCDF (version 1.9.0+)
for I/O. NetCDF may be built with or without netCDF-4 features. NetCDF
is required for PIO, PnetCDF is optional.

Expand All @@ -29,122 +29,43 @@ 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.

## Configuring with CMake
## Building PIO

To configure the build, PIO requires CMake version 2.8.12+. The typical
configuration with CMake can be done as follows:
To build PIO, unpack the distribution tarball and do:

```
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:

CC=mpicc FC=mpif90 ./configure --enable-fortran && make check install
```
make tests
```

Once the tests have been built, you may run tests with:

For a full description of the available options and flags, try:
```
ctest
./configure --help
```

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.
42 changes: 35 additions & 7 deletions doc/source/GettingStarted.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,21 +20,49 @@

/*! \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 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...
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.
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.
Begin by getting and unpacking the most recent release of PIO from
[gitHub](https://github.com/PARALLELIO/ParallelIO/releases) 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.
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.
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?)
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.


*/
2 changes: 1 addition & 1 deletion doc/source/Installing.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
30 changes: 16 additions & 14 deletions doc/source/base.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion doc/source/faq.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
*/
Loading

0 comments on commit 70518f4

Please sign in to comment.