A high-level Parallel I/O Library for structured grid applications
For complete documentation, see our website at http://ncar.github.io/ParallelIO/.
The results of our nightly tests on multiple platforms can be found on our cdash site at http://my.cdash.org/index.php?project=PIO.
PIO can use NetCDF (version 4.3.3+) and/or PnetCDF (version 1.6.0+) for I/O. NetCDF may be built with or without netCDF-4 features. NetCDF is required for PIO, PnetCDF is optional.
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.
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
mpif90 are the appropriate MPI-enabled compiler wrappers
for your system.
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
Fortran libraries for the dependency are installed in different locations
(such as can be done with NetCDF), then you can specify individually
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:
Additional CMake Options
Additional configuration options can be specified on the command line.
PIO_ENABLE_TIMING option can be set to
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
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_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
-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
-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.
Once you have successfully configured PIO with CMake in a build directory. From within the build directory, build PIO with:
This will build the
If you desire to do testing, and
PIO_ENABLE_TESTS=ON (which is the default
setting), you may build the test executables with:
Once the tests have been built, you may run tests with:
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:
(similar to the typical
make check Autotools target).
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
will preface all of the test executable commands with the appropriate
Hence, you should not further preface the
ctest command with these MPI launchers.
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:
If the internal GPTL libraries were built (because GPTL could not be found
PIO_ENABLE_TIMING variable is set to
ON), then these libraries
will be installed with PIO.