Woo-Sun Yang and Chris Ding,
Computational Research Division, 50F-1650
Lawrence Berkeley National Laboratory, Berkeley, CA, 94720-8139

Copyright
---------
ZioLib for Parallel I/O on Distributed Memory Computers is Copyright
(c) 2003, The Regents of the University of California, through Lawrence
Berkeley National Laboratory (subject to receipt of any required
approvals from the U.S. Dept. of Energy).  All rights reserved.

Your use of this software is pursuant to a license agreement, the text
of which is in license.txt.  If the license agreement is not there, or
if you have questions about the license, please contact Berkeley Lab's
Technology Transfer Department at  TTD@lbl.gov referring to "ZioLib
(LBNL Ref CR-1955)"

ZioLib: a Parallel I/O Library
------------------------------
ZioLib facilitates efficient parallel I/O for arrays in a distributed
memory parallel environment.  In case of a write, ZioLib remaps a
distributed field into a "Z"-decomposition (i.e., the decomposition
along the last array dimension) on a subset of MPI processes and from
there launches I/O to a disk file in parallel. In this Z-decomposition,
the data layout of the remapped array on the staging processes' memory
is the same as on disk, thus only block data transfer occurs during
parallel I/O, achieving maximum efficiency.  In case of a read the
reverse steps are followed to have the required distributed array.

Please see for more information about the library at
http://www.nersc.gov/research/SCG/acpi/ZioLib/.

For users manual, see
http://www.nersc.gov/research/SCG/acpi/ZioLib/zio_manual/ or

Woo-Sun Yang and Chris H. Q. Ding, 2003, ZioLib: a Parallel I/O
Library, LBNL Tech Report, LBNL-53521,
(http://www-library.lbl.gov/docs/LBNL/535/21/PDF/LBNL-53521.pdf)

A LaTeX document for the manual can be retrieved from the source files
using ProTeX (that is, 'protex -s zio.F90 zio_data.F90 zio_remap.F90
zio_binary.F90 zio_netcdf77.F90 > zio.tex').  ProTeX is available from
http://polar.gsfc.nasa.gov/software/protex/.


Files
-----
Makefile
Makefile.in
Readme
remapping.ps
zio.h
zio_data.F90
zio_remap.F90
zio_binary.F90
zio_netcdf77.F90
zio.F90

unit_testers/Makefile
unit_testers/nftest1.F90
unit_testers/nftest2.F90
unit_testers/nftest3.F90
unit_testers/nftest4.F90
unit_testers/bintest1.F90
unit_testers/bintest2.F90
unit_testers/bintest3.F90
unit_testers/bintest4.F90

ZioLib codes can be compiled in either fixed or free source form.  The
test codes included are in free source form.

To compile the source codes, type from the ziolib directory

   % gmake all

To create library file libzio.a, type from the ziolib directory

   % gmake library


ZioLib test codes
-----------------
nftest1.F90: NetCDF I/O
             3-D arrays in a 3-D decomposition
             Writing and reading entire fields
             Not changing output index orders
nftest2.F90: NetCDF I/O
             2- and 3-D arrays in a 3-D decomposition
             Writing and reading entire fields
             Changing output index orders
nftest3.F90: NetCDF I/O
             2- and 3-D arrays in a 3-D decomposition
             Writing and reading array sections
             Changing output index orders
nftest4.F90: NetCDF I/O
             2- and 3-D arrays in a 3-D decomposition
             Writing and reading array sections
             Changing output index orders
             Subdomains made of multiple separate rectangular blocks
	     A number of xyz-blocks created, and assigned to MPI
	     processes in either a random or a round-robin fashion

bintest1.F90: Unformatted direct- or sequential-access I/O
              3-D arrays in a 3-D decomposition
              Writing and reading entire fields
              Not changing output index orders
bintest2.F90: Unformatted direct- or sequential-access I/O
              2- and 3-D arrays in a 3-D decomposition
              Writing and reading entire fields
              Changing output index orders
bintest3.F90: Unformatted direct- or sequential-access I/O
              2- and 3-D arrays in a 3-D decomposition
              Writing and reading array sections
              Changing output index orders
bintest4.F90: Unformatted direct- or sequential-access I/O
              2- and 3-D arrays in a 3-D decomposition
              Writing and reading array sections
              Changing output index orders
              Subdomains made of multiple separate rectangular blocks
	      A number of xyz-blocks created, and assigned to MPI
	      processes in either a random or a round-robin fashion

All the test codes write fields to a file, read back and then compare
with the original values. The comparison results (normalized L2 error,
normalized maximum and minimum differences for each field in real*8
precisions) are printed.  For successful I/O those values must be zeros
or around the machine epsilon.

To compile the test codes, type from the ziolib directory

   % gmake tests

You can play with a different problem parameter set by changing grid
size, output index orders, parallel decomposition, and number of I/O
staging processes, etc., which are usually specified near the top of
each test code.
