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:
......@@ -226,8 +223,5 @@ Paraview and its VTK dependency must be built with the following CMake options:
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
......
Supports Markdown
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