/****************************************************************************
**  SIONLIB     http://www.fz-juelich.de/jsc/sionlib                       **
*****************************************************************************
**  Copyright (c) 2008-2021                                                **
**  Forschungszentrum Juelich, Juelich Supercomputing Centre               **
**                                                                         **
**  See the file COPYRIGHT in the package base directory for details       **
****************************************************************************/

----------------------------------------------------------------------
SIONlib - Scalable I/O library for parallel access to task-local files
          Version: 2.0.0-rc.3
W. Frings, 2021-02-15

SIONlib is a library for writing and reading data from several thousands
of parallel tasks into/from one or a small number of physical files.
Only the open and close functions are collective while file access can be
performed independently.

SIONlib can be used as a replacement for standard I/O APIs (e.g. POSIX)
that are used to access distinct files from every parallel process.
SIONlib will bundle the data into one or few files in a coordinated
fashion in order to sidestep sequentialising mechanism in the file
system. At the same time, the task-per-file picture is maintained for
the application, every process has access to its logical file only.
File access is performed using SIONlib equivalents to standard C-I/O
functionality (`fwrite` becomes `sion_write`, `fseek` becomes `sion_seek`,
etc.) which have similar semantics as their C counterparts.

Internally, the physical files are sub-divided into sequences of blocks,
which themselves contain one chunk of data belonging to every logical
file. In case the amount to be written to a file is known up front, it can
optionally be specified when opening the file and the sequence of blocks
collapses into a single block with one chunk per task containing all of
its data. If a chunk size cannot be specified ahead of time, a sensible
default is chosen and reads and writes that cross chunk boundaries are
handled transparently by SIONlib.

SIONlib also uses information about the block size of the underlying
file system, because access to the same block from different tasks often
leads to contention.

Both, the estimated chunk size and file system block size are used to
align individual chunks with file system blocks. Ensuring contention-free
access to file system blocks enables efficient parallel writing and reading.

SIONlib provides two different interfaces: one for parallel access
(with implementations for different parallel programming technologies
such as MPI, OpenMP and hybrid MPI+OpenMP) and one for sequential access
which is also used internally by the SIONlib utilities.

Installation:
-------------
 The installation procedure is described in:

	   ./doc/inputs/installation.md

        or https://apps.fz-juelich.de/jsc/sionlib/docu/2.0.0-rc.3/installation.html

SION API:
---------
 The SIONlib interface is described in:

	   ./src/lib/sion.h
	   ./src/lib/sion_common.h
	   ./src/lib/sion_const.h
	   ./src/lib/sion_datatypes.h
	   ./src/lib/sion_debug.h
	   ./src/lib/sion_enums.h
	   ./src/lib/sion_serial.h
	   ./src/lib/sion_version.h.in
           ./src/parlib/sion_generic.h
           ./src/parlib/sion_mpi.h
           ./src/parlib/sion_datatypes_mpi.h
           ./src/parlib/sion_omp.h
           ./src/parlib/sion_ompi.h

        or https://apps.fz-juelich.de/jsc/sionlib/docu/2.0.0-rc.3/


Templates and Examples:
-----------------------
 C-Templates and examples for using SIONlib in serial and parallel codes can be found in:

	   ./examples/*.example
	   ./examples/simple

	   ./doc/inputs/examples.dox

        or https://apps.fz-juelich.de/jsc/sionlib/docu/2.0.0-rc.3/examples.html

File data format:
-----------------
 The internal format of SION-files is described in:

	   ./doc/inputs/fileformat.dox

        or https://apps.fz-juelich.de/jsc/sionlib/docu/2.0.0-rc.3/fileformat.html


Utilities:
----------

 Utilities for managing SION-files and test SIONlib are described in:

	   ./doc/inputs/utilities.dox

        or https://apps.fz-juelich.de/jsc/sionlib/docu/2.0.0-rc.3/util.html


Debugging:
----------

If the sources are compiled with the option -DEBUG debugging can be
switched on by environment variables, for example:

export SION_DEBUG=SION.log
export SION_DEBUG_MASK=1023
export SION_DEBUG_RANK1=0
export SION_DEBUG_RANK2=2

Variables:
        SION_DEBUG            file name prefix, will be appended by task number
        SION_DEBUG_MASK       level of detail:
                                  1 -> sion user function entries and exits
                                  2 -> sion internal function entries and exits
                                  8 -> high frequently called sion user function
                                       entries and exits (sion_feof, sion_ensure_free_space, ...)
                                 16 -> high frequently called sion user function entries
                                       and exits (internal steps)
                                 32 -> high frequently called sion internal function (internal steps)
                                128 -> timings (top level)
                                256 -> timings (low level)
                                512 -> elg lib
                               1024 -> gz lib
                               2048 -> higher frequently called sion internal function (internal steps)
                              The value of SION_DEBUG_MASK can be combination of the values above (logical or)
        SION_DEBUG_RANK1      rank of the first MPI task who should do debugging
        SION_DEBUG_RANK2      rank of a second MPI task who should do debugging


Contact:
--------

The SIONlib developers can be reached via

- the issue tracker: https://gitlab.version.fz-juelich.de/SIONlib/SIONlib/-/issues or
- the mailing list: sionlib_jsc@fz-juelich.de


License:
--------

See the file COPYRIGHT in the package base directory for details
