Commit 0cd8ee41 authored by Godoy, William F's avatar Godoy, William F
Browse files

More docs changes from Nick's feedback

parent d0dc5a3b
......@@ -15,7 +15,7 @@ This is ADIOS 2: The Adaptable Input/Output (I/O) System, ADIOS 2 is developed a
ADIOS 2 is a framework designed for scientific data I/O to publish and subscribe (put/get) data when and where required.
ADIOS 2 would Transport and Transform your data as groups of self-describing variables and attributes across different media (file, wide-area-network, memory-to-memory, etc.) using a common application programming interface (API) for all transport modes. ADIOS 2 uses range from high-performance supercomputers to personal computers and cloud based applications.
ADIOS2 transports data as groups of self-describing variables and attributes across different media types (such as files, wide-area-networks, and remote direct memory access) using a common application programming interface for all transport modes. ADIOS2 can be used on supercomputers, commercial clouds, and personal computers.
ADIOS 2 focuses on:
......
......@@ -71,7 +71,7 @@ The goal is to provide specific advice and good practices about the use of ADIOS
20. C, Fortran: always call ``adios2_finalize`` for every call to ``adios2_init`` to avoid memory leaks.
21. Reminder: C++, C, Python: Row-Major, while Fortran: Column-Major. ADIOS 2 will handle interoperability between ordering. Remember that :ref:`bpls : Inspecting Data` is always a Row-Major reader.
21. Reminder: C++, C, Python: Row-Major, while Fortran: Column-Major. ADIOS 2 will handle interoperability between ordering. Remember that :ref:`bpls : Inspecting Data` is always a Row-Major reader so Fortran reader need to swap dimensions seen in bpls. bpls: (slow, ...., fast) -> Fortran(fast,...,slow).
22. Fortran API: use the type members (``var%valid``, ``var%name``, etc.) to get extra type information.
......
......@@ -4,7 +4,7 @@ Full APIs
.. note::
Product Application Developers targeting finer-level control for their IO tasks for optimization should use the current full APIs. If you want to use ADIOS2 in simple use cases (*e.g.* reading a file for analysis, interactive Python, or saving some data for a small project) please refer to the :ref:`High-Level APIs` for a flat learning curve.
Application developers who desire fine-grained control of IO tasks should use the Full APIs. In simple cases (e.g. reading a file for analysis, interactive Python, or saving some data for a small project or tests) please refer to the :ref:High-Level APIs.
Currently ADIOS2 support bindings for the following languages and their minimum standards:
......
......@@ -91,7 +91,7 @@ The following section provides a summary of the available functionality for each
Debugging
---------
To help debugging, functionality is provided that creates human-readable representations of adios2 C++11 class instances and enums. To get a string representation, use ``ToString(object)``. You can also directly pass objects to ``ostream``s.
For debugging, ADIOS2 C++11 class instances and enums can be passed directly to ostreams, as well as converted to human-readable strings via the ubiquitous ``ToString(object)`` member variable. You can also directly pass objects to ``ostream``s.
Example:
......
......@@ -7,5 +7,5 @@ Python bindings
Product Application Developers targeting finer-level control for their IO tasks for optimization should use the current full APIs. If you want to use ADIOS2 in simple use cases (*e.g.* reading a file for analysis, interactive Python, or saving some data for a small project) please refer to the :ref:`High-Level APIs` for a flat learning curve.
The full Python APIs follow very closely the full C++11 API interface.
This is Work In Progress.
This section is Work In Progress until we figure out an automated way to pull the docs.
......@@ -2,9 +2,9 @@
High-Level APIs
###############
The current simple APIs are designed for simple and direct tasks in which performance is not a critical aspect. Unlike the :ref:`Full APIs` the simple High-Level APIs only require a single object/handler offering native resemblance to C++ (fstream) and Python (file I/O) native implementations. Thus, offering a nearly-flat learning curve for first-time users.
The high-level APIs are designed for simple tasks for which performance is not critical. Unlike the :ref:`Full APIs`, the high-level APIs only require a single object handler resembling a C++ fstream or a Python file I/O idiom. The high-level APIs are recommended to both first-time and advanced users; the low-level APIs being recommended only when performance testing identifies a bottleneck or when more control is needed.
Typical scenarios for using the simple APIs are:
Typical scenarios for using the simple high-level APIs are:
* Reading a file to perform data analysis with libraries (matplotlib, scipy, etc.)
* Interactive: few calls make interactive usage easier.
......@@ -16,10 +16,6 @@ The main function calls are: ``open`` (or constructor in C++), ``write``, ``read
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::
The simplified APIs are not meant to be used inside applications in which the end user has no access to the IO layer and/or when performance and full functionality are critical, *e.g.* running on a HPC cluster at scale. Use the :ref:`Full APIs` instead
.. note::
The simpified APIs are based on language native file IO interface. Hence ``write`` and ``read`` calls are always synchronized and variables data memory is ready to use immediatley after these calls.
......
......@@ -6,8 +6,8 @@ C++11 High-Level APIs are based on a single object `adios2::fstream`
.. caution::
DO NOT call ``use namespace adios2`` in your C++ code.
Use ``adios2::fstream`` directly to prevent conflicts with ``std::stream``.
DO NOT place ``use namespace adios2`` in your C++ code.
Use ``adios2::fstream`` directly to prevent conflicts with ``std::fstream``.
C++11 Write example
......
......@@ -2,7 +2,7 @@
Python High-Level API
*********************
Python simple bindings follow closely the :ref:`C++ High-Level API`. Just like the full APIs, they rely on numpy and (optionally) on ``mpi4py`` if ADIOS2 is compiled with MPI.
Python simple bindings follow closely Python style directives. Just like the full APIs, they rely on numpy and, optionally, on ``mpi4py``, if the underlying ADIOS2 library is compiled with MPI.
For online examples on MyBinder :
......
......@@ -2,7 +2,7 @@
adios2-config
*************
`adios2-config` is the preferred to use in non-CMake (*e.g.* Makefile builds).
`adios2-config` is provided to aid with non-CMake builds (*e.g.* manually generated Makefile).
Running the `adios2-config` command under `adios2-install-dir/bin/adios2-config` will generate the following usage information:
.. code-block:: bash
......
......@@ -4,7 +4,7 @@ Visualizing Data
.. note::
As of version 2.4.0 this work should be treated as experimental. As it builds on top of the library in third party ecosystems, and doesn't ship with ADIOS 2 source code.
As of version 2.4.0 this work is experimental. As it builds on top of the library in third party ecosystems, and doesn't ship with ADIOS 2 source code.
Certain ADIOS 2 bp files, and in-memory streams in the future), can be recognized by third party products to enable data visualization. The expectation is to keep adding support to the list of products enabling ADIOS 2 for visualization purposes. The goal of this section is to describe the currently cover cases and how to create an ADIOS 2 BP file to accomodate the visualization product requirements.
......
......@@ -2,23 +2,20 @@
Using VTK and Paraview
**********************
ADIOS streams can now be seamlessly integrated into the well-established visualization and analysis `Visualization Toolkit <https://vtk.org/>`_ (VTK) and `Paraview <https://www.paraview.org/>`_ products. Data sets can be described with an additional attribute that conforms to the well known and documented `VTK XML data model formats <https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf>`_ as a high-level descriptors that will allow interpretation of ADIOS 2 variables into a hierarchy understood by the VTK infrastructure. This XML data format is saved in ADIOS as either an attribute, and optionally, as an additional `vtk.xml` file inside a resulting bp data set `file.bp.dir/vtk.xml` from the default engine, see :ref:`BP3 (Default)`.
.. note::
This is work in progress developed inside VTK, not in the ADIOS 2 code base
ADIOS BP files can now be seamlessly integrated into the `Visualization Toolkit <https://vtk.org/>`_ (VTK) and `Paraview <https://www.paraview.org/>`_. Datasets can be described with an additional attribute that conforms to the `VTK XML data model formats <https://vtk.org/wp-content/uploads/2015/04/file-formats.pdf>`_ as high-level descriptors that will allow interpretation of ADIOS 2 variables into a hierarchy understood by the VTK infrastructure. This XML data format is saved in ADIOS as either an attribute, and optionally, as an additional vtk.xml file inside file.bp.dir/vtk.xml from the default engine. For more details, see :ref:`BP3 (Default)`.
Current limitations:
* Only works with MPI builds of VTK and Paraview
* Support only one Block per ADIOS dataset
* Only supports BP Files, streams will be added in the future
* Only supports BP Files, streams are not supported
* Currently working up to 3D (and linearized 1D) variables for scalars and vectors.
* Image Data, vti, is supported with ADIOS2 Global Array Variables only
* Unstructured Grid, vtu, is supported with ADIOS2 Local Arrays Variables only
So far two "VTK File" types are supported:
Two "VTK File" types are supported:
1. Image data (.vti)
2. Unstructured Grid (.vtu)
......@@ -102,7 +99,7 @@ To incorporate the data model in a BP data file, the application has two options
.. tip::
C++11 users should take advantage of the added string literal capabilities in C++11, R''( )", as in the example above.
C++11 users should take advantage C++11 string literals (R"( xml_here )") to simplify escaping characters in the XML.
The resulting bpls output should contain the "vtk.xml" attribute and the variables in the model:
......@@ -219,15 +216,12 @@ Build VTK and Paraview with ADIOS 2 Support
Currently the implementation for ADIOS 2 readers exist in VTK and Paraview branches. We expect this to be part of the VTK and Paraview release cycle with their upcoming releases. Users must build from source and point to these branches until formal merge into their master branches is done.
Paraview and its VTK dependency must be built with the following CMake options:
1. `-DVTK_MODULE_ENABLE_VTK_IOADIOS2=YES`
2. `-DVTK_USE_MPI=ON`
3. `-DPARAVIEW_USE_MPI=ON`
For comprehensive build instructions see the documentation for `VTK <https://vtk.org/>`_ (VTK) and `Paraview <https://www.paraview.org/>`_ , respectively.
We look forward to maintain and expand the current service capabilities developed in VTK and Paraview to support more complex scenarios: e.g. moving mesh, multigrid, real-time streams, as well as enriching the data model capabilities base on VTK XML formats.
For comprehensive build instructions see the documentation for `VTK <https://vtk.org/>`_ (VTK) and `Paraview <https://www.paraview.org/>`_.
......@@ -91,7 +91,7 @@ Follow directions at :ref:`Building on HPC Systems` to setup support for PGI on
How do I enable the Python bindings on Titan?
---------------------------------------------
ADIOS 2 default configuration on Titan is to build the static library. Python bindings require enabling the dynamic libraries and the Cray dynamic environment variable. See :ref:`Building on HPC Systems` and :ref:`Enabling the Python bindings`. For example:
The default ADIOS2 configuration on Titan builds a static library. Python bindings require enabling the dynamic libraries and the Cray dynamic environment variable. See :ref:`Building on HPC Systems` and :ref:`Enabling the Python bindings`. For example:
.. code-block:: bash
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment