Merge pull request #945 from williamfgc/docs (64398b57) · Commits · Podhorszki, Norbert / ADIOS2

ReadMe.md

+4 −8

Original line number	Diff line number	Diff line
		@@ -19,11 +19,7 @@ ADIOS >= 2.0 is licensed under the Apache License v2.0. See the accompanying
		Copyright.txt for more details.

		## Documentation
		Please find ADIOS2 software documentation for:

		1. [ADIOS2 User Guide at readthedocs](https://adios2-adaptable-io-system-version-2.readthedocs.io)

		2. Local user guide documentation generation [docs/ReadMe.md](docs/ReadMe.md)
		Please find [ADIOS2 User Guide at readthedocs](https://adios2.readthedocs.io)

		## Directory layout
		* cmake - Project specific CMake modules
		@@ -32,8 +28,8 @@ Please find ADIOS2 software documentation for:
		* source - ADIOS2 source
		* adios2 - source directory for the ADIOS2 library to be installed under install-dir/lib/libadios2.
		* utils - source directory for the binary utilities, to be installed under install-dir/bin
		* bindings - public interface language bindings (C++11, C++98, C, Fortran and Python)
		* testing - Tests using gtest
		* bindings - public interface language bindings (C++11, C++98, C, Fortran, Python and Matlab)
		* testing - Tests using [gtest](https://github.com/google/googletest)


		## Getting Started
		@@ -42,7 +38,7 @@ ADIOS2 uses CMake for its build environment. CMake expects projects
		to use "out-of-source" builds, which means keeping a separate build and source
		directory (different from autotools, which usually uses an in-source build).

		The following is a quick step-by-step build guide, find the full CMake-based install documentation [here](http://adios2-adaptable-io-system-version-2.readthedocs.io/en/latest/installation/installation.html)
		The following is a quick step-by-step build guide, find the full CMake-based install documentation [here](http://adios2.readthedocs.io/en/latest/installation/installation.html)

		Step-by-step build guide:

docs/user_guide/source/api_simple/api_simple.rst

+3 −3

Original line number	Diff line number	Diff line
		@@ -2,16 +2,16 @@
		Simple Language Bindings APIs
		#############################

		The current simple APIs are designed for simple and direct tasks in which performance is not a critical aspect. Unlike the :ref:`Full Language Bindings APIs` the simple APIs only require a single object/handler. Thus offering a nearly-flat learning curve.
		The current simple APIs are designed for simple and direct tasks in which performance is not a critical aspect. Unlike the :ref:`Full Language Bindings APIs` the simple APIs only require a single object/handler. Thus offering a nearly-flat learning curve for first-time users.

		Typical scenarios for using the simple APIs are:

		* Reading a file to perform data analysis with libraries (matplotlib, scipy, etc.)
		* Interactive: few calls make interactive usage easier.
		* Saving data to files is small or personal projects
		* Notebooks: e.g. Jupyter
		* Online frameworks: e.g. Jupyter notebooks

		The designed functionality syntax is closely related to the native language IO bindings for formatted text IO e.g. C++ fstream, C FILE*, Fortran and Python file IO. The main function calls are: ``open`` (or constructor in C++), ``write``, ``read`` and ``close`` (or destructor in C++), with the corresponding language native syntax for advancing the step in write mode, and for a "step-by-step" streaming basis in read mode. See each language section for an example.
		The designed functionality syntax is closely related to the native language IO bindings for formatted text IO e.g. C++ fstream, C FILE*, Fortran and Python file IO. The main function calls are: ``open`` (or constructor in C++), ``write``, ``read`` and ``close`` (or destructor in C++). In addition, ADIOS2 borrows the corresponding language native syntax for advancing lines to advance the step in write mode, and for a "step-by-step" streaming basis in read mode. See each language section in this chapter for a write/read example.

		.. warning::

docs/user_guide/source/components/engine.rst

+1 −1

Original line number	Diff line number	Diff line
		@@ -102,7 +102,7 @@ The following example illustrates the basic API usage in write mode for data gen
		.. danger::
		The default behavior of adios2 Put and Get calls IS NOT synchronized, but rather deferred. It's actually the opposite of MPI_Put and more like MPI_rPut.
		Do not assume the data pointer is usable after a Put and Get, before EndStep, Close or the corresponding PerformPuts/PerformGets.
		Be SAFE and use the adios2::Mode::Sync in the 3rd argument.
		Be SAFE and consider using the adios2::Mode::Sync in the 3rd argument. Avoid using TEMPORARIES, r-values, and out-of-scope variables in Deferred mode.


		Available Engines

docs/user_guide/source/components/overview.rst

+25 −6

Original line number	Diff line number	Diff line
		@@ -2,13 +2,32 @@
		Components Overview
		*******************

		The simple way to understand the big picture for the ADIOS2 core components is to map each class to the actual definition of the ADIOS acronym.

		============== =========== ============== ============
		Acronym Word ADaptable Input/Output System
		============== =========== ============== ============
		Component ADIOS IO Engine
		============== =========== ============== ============
		.. note::

		If you are doing simple tasks where performance is a non-critical aspect please go to the :ref:`Simple Language Bindings APIs` section for a quick start. If you are an HPC application developer or you want to use ADIOS2 functionality in full please read this chapter.


		The simple way to understand the big picture for the ADIOS2 unified user interface components is to map each class to the actual definition of the ADIOS acronym.

		+------------+-----------+---------------------------+
		\| Component \| Acronym \| Function \|
		+------------+-----------+---------------------------+
		\| \| \| Set MPI comm domain \|
		\| \| \| \|
		\| ADIOS \| ADaptable \| Set runtime settings \|
		\| \| \| \|
		\| \| \| Own other components \|
		+------------+-----------+---------------------------+
		\| \| \| Set engine \|
		\| \| \| \|
		\| IO \| I/O \| Set variables/attributes \|
		\| \| \| \|
		\| \| \| Set compile-time settings \|
		+------------+-----------+---------------------------+
		\| \| \| Execute heavy IO tasks \|
		\| Engine \| System \| \|
		\| \| \| Manage system resources \|
		+------------+-----------+---------------------------+


		ADIOS2's public APIs are based on the natural choice for each supported language to represent each ADIOS2 components and its interaction with application datatypes. Thus,

docs/user_guide/source/faq/faq.rst

+3 −3

Original line number	Diff line number	Diff line
		@@ -20,7 +20,7 @@ APIs
		Building on Titan
		*****************

		#. :ref:`My application uses PGI on Titan, can I link ADIOS 2?`
		#. :ref:`My application uses PGI compilers on Titan, can I link ADIOS 2?`
		#. :ref:`How do I enable the Python bindings on Titan?`


		@@ -67,8 +67,8 @@ you must use sync mode with adios2_put. Deferred mode will save garbage data sin



		My application uses PGI on Titan, can I link ADIOS 2?
		-----------------------------------------------------
		My application uses PGI compilers on Titan, can I link ADIOS 2?
		---------------------------------------------------------------

		Follow directions at :ref:`Building on High Performance Computing, HPC, Systems` to setup support for PGI on Titan. PGI compilers depend on GNU headers, but they must point to a version greater than gcc 4.8.1 to support C++11 features. The gcc module doesn't need to be loaded, though. Example:

Admin message