Merge pull request #1054 from williamfgc/docs

.. tip::

   It's recommended to be consistent when using types for portability. If data is defined as a fixed-width integer, define variables in ADIOS2 using a fixed-width type, *e.g.*  for int32_t data use ``DefineVariable<int32_t>``. Mapping to a primitive variable is already handled automatically by the compiler.

   It's recommended to be consistent when using types for portability. If data is defined as a fixed-width integer, define variables in ADIOS2 using a fixed-width type, *e.g.*  for ``int32_t`` data types use ``DefineVariable<int32_t>``. Mapping to a primitive variable is already handled automatically by the compiler.

Variables Shape Types

         adios2::Variable<unsigned int> varNodes = adios2::DefineVariable<unsigned int>("Nodes");

         adios2::Variable<std::string> varFlag = adios2::DefineVariable<std::string>("Nodes flag");

         // ...

         engine.PutDeferred( varNodes, nodes );

         engine.PutDeferred( varFlag, "increased" );

         engine.Put( varNodes, nodes );

         engine.Put( varFlag, "increased" );

         // ...

      }

   .. note::

      Variables of type string are defined just like global single values. In the current adios2 version multidimensional strings are supported through variables of type `char`.

      Variables of type string are defined just like global single values. In the current adios2 version multidimensional strings are supported for fixed size strings through variables of type `char`.

2. **Global Array**: the most common shape used for storing self-describing data used for analysis that lives in several MPI processes. The image below illustrates the definitions of the dimension components in a global array: shape, start, and count.

   .. image:: http://i66.tinypic.com/1zw15xx.png : alt: my-picture2

   Start and Count can be later modified with the ``Variable::SetSelection`` function if it is not a constant dimensions variable.

   .. image:: http://i64.tinypic.com/29px5yx.png : alt: my-picture2

   .. warning::

      The C++ interface doesn't separate the public API from the private implementation (`PIMPL idiom <https://isocpp.org/blog/2018/01/the-pimpl-pattern-what-you-should-know-bartlomiej-filipek>`_). Users must be careful in accessing the m_Shape, m_Start and m_Count public members directly (*e.g.* ``variable.m_Shape`` or ``variable->m_Shape``).

      Be aware of data ordering in your language of choice (Row-Major or Column-Major) as depicted in the above figure. Data decomposition is done by the application based on their requirements, not by adios2.

   Start and Count local dimensions can be later modified with the ``Variable::SetSelection`` function if it is not a constant dimensions variable.

3. **Local Single Value**: single value variables that are local to the MPI process. They are defined by passing the ``adios2::LocalValueDim`` enum as follows:

      adios2::Variable<int> varProcessID =

            io.DefineVariable<int>("ProcessID", {adios2::LocalValueDim})

      //...

      engine.PutDeferred<int>(varProcessID, rank);

      engine.Put<int>(varProcessID, rank);

4. **Local Array**: single array variables that are local to the MPI process. These are more commonly used to write Checkpoint data, that is later read for Restart. Reading, however, needs to be handled differently: each process' array has to be read separately, using SetSelection per rank. The size of each process selection should be discovered by the reading application by inquiring per-block size information of the variable, and allocate memory accordingly.

  .. image:: http://i64.tinypic.com/732neq.png : alt: my-picture3

5. **Joined Array**: in certain circumstances every process has an array that is different only in one dimension. ADIOS2 allows user to present them as a global array by joining the arrays together. For example, if every process has a table with a different number of rows, and one does not want to do a global communication to calculate the offsets in the global table, one can just write the local arrays and let ADIOS2 calculate the offsets at read time (when all sizes are known by any process).

5. **Joined Array (NOT YET SUPPORTED)**: in certain circumstances every process has an array that is different only in one dimension. ADIOS2 allows user to present them as a global array by joining the arrays together. For example, if every process has a table with a different number of rows, and one does not want to do a global communication to calculate the offsets in the global table, one can just write the local arrays and let ADIOS2 calculate the offsets at read time (when all sizes are known by any process).

   .. code-block:: c++

    # 'utilities/utilities.rst',

    'utilities/bpls.rst',

    'engines/dataman.rst',

    'engines/insitu_mpi.rst',

    'engines/hdf5.rst',

    'engines/bp3.rst',

    'engines/sst.rst',

3. **CollectiveMetadata**: turns ON/OFF forming collective metadata during run (used by large scale HPC applications)

4. **Threads**: number of threads provided from the application for buffering, use this for very large variables

4. **Threads**: number of threads provided from the application for buffering, use this for very large variables in data size

5. **InitialBufferSize**: initial memory provided for buffering (minimum is 16Kb)

.. include:: bp3.rst

.. include:: hdf5.rst

.. include:: insitu_mpi.rst

.. include:: dataman.rst

.. include:: sst.rst

**********

InSitu MPI

**********

Coming soon...

 No newline at end of file