diff --git a/docs/user_guide/source/api_high/cxx11.rst b/docs/user_guide/source/api_high/cxx11.rst index cb84f866c1..f322bd07e8 100644 --- a/docs/user_guide/source/api_high/cxx11.rst +++ b/docs/user_guide/source/api_high/cxx11.rst @@ -34,7 +34,7 @@ C++11 Write example { if(rank == 0 && step == 0) // global variable { - oStream.write("size", size); + oStream.write("size", size); } // physicalTime double, is optional diff --git a/docs/user_guide/source/components/attribute.rst b/docs/user_guide/source/components/attribute.rst index 7324799ee1..8d6a85e248 100644 --- a/docs/user_guide/source/components/attribute.rst +++ b/docs/user_guide/source/components/attribute.rst @@ -2,7 +2,9 @@ Attribute ********* -Attributes are extra information associated with a particular IO component. They can be thought of a very simplified version of a Variable, but with the goal of adding extra metadata. The most common use is the addition of human-readable information available when producing data (*e.g.* ``"experiment name"``, ``"date and time"``, ``"04,27,2017"``, or a schema). +Attributes are extra information associated with a particular IO component. +They can be thought of as a very simplified ``Variable``, but with the goal of adding extra metadata. +The most common use is the addition of human-readable metadata (*e.g.* ``"experiment name"``, ``"date and time"``, ``"04,27,2017"``, or a schema). Currently, ADIOS2 supports single values and arrays of primitive types (excluding ``complex``) for the template type in the ``IO::DefineAttribute`` and ``IO::InquireAttribute`` function (in C++). @@ -30,4 +32,5 @@ The returned object (``DefineAttribute`` or ``InquireAttribute``) only serves th .. note: - Attributes are not forcibly associated to a particular variable in ADIOS2. Developers are free to create associations through their own naming conventions. + Attributes are not forcibly associated to a particular variable in ADIOS2. + Developers are free to create associations through their own naming conventions. diff --git a/docs/user_guide/source/components/engine.rst b/docs/user_guide/source/components/engine.rst index eb8b58a3c9..d4dfa58c14 100644 --- a/docs/user_guide/source/components/engine.rst +++ b/docs/user_guide/source/components/engine.rst @@ -2,27 +2,35 @@ Engine ****** -The Engine abstraction component serves as the base interface to the actual IO Systems executing the heavy-load tasks performed when Producing and Consuming data. +The Engine abstraction component serves as the base interface to the actual IO systems executing the heavy-load tasks performed when producing and consuming data. -Engine functionality works around two concepts from the application's point-of-view: +Engine functionality works around two concepts: -1. Self-describing variables are published and consumed in "steps" in either "File" random-access (all steps are available) or "Streaming" (steps are available as they are produced in a step-by-step fashion). -2. Self-describing variables are published (Put) and consumed (Get) using a "sync" or "deferred" (lazy evaluation) policy. +1. Variables are published (``Put``) and consumed (``Get``) in "steps" in either "File" random-access (all steps are available) or "Streaming" (steps are available as they are produced in a step-by-step fashion). +2. Variables are published (``Put``) and consumed (``Get``) using a "sync" or "deferred" (lazy evaluation) policy. .. caution:: - The ADIOS 2 "step" is a logical abstraction that means different things depending on the application context. Examples: "time step", "iteration step", "inner loop step", or "interpolation step", "variable section", etc. It only indicates how the variables were passed into ADIOS 2 (e.g. I/O steps) without the user having to index this information on their own. + The ADIOS2 "step" is a logical abstraction that means different things depending on the application context. + Examples: "time step", "iteration step", "inner loop step", or "interpolation step", "variable section", etc. + It only indicates how the variables were passed into ADIOS2 (e.g. I/O steps) without the user having to index this information on their own. .. tip:: - Publishing/Consuming data can be seen as a round-trip in ADIOS 2. Put and Get APIs for write/append and read modes aim to be "symmetric". Hence, reusing similar functions, objects, semantics as much as possible. + Publishing and consuming data can be seen as a round-trip in ADIOS2. + ``Put`` and ``Get`` APIs for write/append and read modes aim to be "symmetric". + Hence, reusing similar functions, objects, semantics as much as possible. The rest of the section explains the important concepts BeginStep --------- - Begin logical step and return the status (via an enum) of the stream to be read/written. In streaming engines BeginStep in where the receiver tries to acquire a new step in the reading process. The full signature allows for a mode and timeout parameters. See :ref:`Supported Engines` for more information on what engine allows. A simplified signature allows each engine to pick reasonable defaults. + Begins a logical step and return the status (via an enum) of the stream to be read/written. + In streaming engines ``BeginStep`` is where the receiver tries to acquire a new step in the reading process. + The full signature allows for a mode and timeout parameters. + See :ref:`Supported Engines` for more information on what engine allows. + A simplified signature allows each engine to pick reasonable defaults. .. code-block:: c++ @@ -41,17 +49,19 @@ EndStep .. tip:: - To write portable code for a step-by-step access across adios2 engines (file and streaming engines) use BeginStep and EndStep. + To write portable code for a step-by-step access across ADIOS2 engines (file and streaming engines) use ``BeginStep`` and ``EndStep``. .. danger:: - Accessing random steps in read mode (e.g. Variable::SetStepSelection in file engines) will create a conflict with BeginStep and EndStep and will throw an exception. In file engines, data is either consumed in a random-access or step-by-step mode, but not both. + Accessing random steps in read mode (e.g. ``Variable::SetStepSelection`` in file engines) will create a conflict with ``BeginStep`` and ``EndStep`` and will throw an exception. + In file engines, data is either consumed in a random-access or step-by-step mode, but not both. Close ----- - Close current engine and underlying transports. Engine object can't be used after this call. + Close current engine and underlying transports. + An ``Engine`` object can't be used after this call. .. tip:: @@ -61,9 +71,10 @@ Close Put: modes and memory contracts ------------------------------- -``Put`` is the generalized abstract function for publishing data in adios2 when an Engine is created using Write, or Append, mode at ``IO::Open``. +``Put`` is the generalized abstract function for publishing data in adios2 when an Engine is created using ``Write`` or ``Append`` mode at ``IO::Open``. -The most common signature is the one that passes a ``Variable`` object for the metadata, a ``const`` piece of contiguous memory for the data, and a mode for either Deferred (data is collected until EndStep/PerformPuts/Close) or Sync (data is reusable immediately). This is the most common use case in applications. +The most common signature is the one that passes a ``Variable`` object for the metadata, a ``const`` piece of contiguous memory for the data, and a mode for either ``Deferred`` (data is collected until EndStep/PerformPuts/Close) or ``Sync`` (data is reusable immediately). +This is the most common use case in applications. 1. Deferred (default) or Sync mode, data is contiguous memory @@ -71,20 +82,24 @@ The most common signature is the one that passes a ``Variable`` object for th void Put(Variable variable, const T* data, const adios2::Mode = adios2::Mode::Deferred); -Optionally, adios2 Engines can provide direct access to its buffer memory using an overload that returns a piece of memory to a variable block, basically a zero-copy. Variable::Span is based on a subset of the upcoming `C++20 std::span `_, which is non-owning and typed contiguous memory piece (it helps to review what std::span is, formerly known as array_view). Spans act as a 1D memory container meant to be filled out by the application. It is safely used as any other STL sequence container, with iterators ``begin()`` and ``end()``, ``operator[]`` and ``at()``, while also providing ``data()`` and ``size()`` functions to manipulate the internal pointer. +Optionally, ADIOS2 Engines can provide direct access to its buffer memory using an overload that returns a piece of memory to a variable block. +``Variable::Span`` is based on a subset of the upcoming `C++20 std::span `_, which is a non-owning reference to a block of contiguous memory. +Spans act as a 1D container meant to be filled out by the application. +It is safely used like any other STL container, providing ``begin()`` and ``end()`` iterators, ``operator[]`` and ``at()``, while also providing ``data()`` and ``size()`` functions to manipulate the internal pointer. -Variable::Span is helpful in situations in which temporaries are needed to create contiguous pieces of memory from non-contiguous pieces (``e.g.`` tables, arrays without ghost-cells), or just to save memory as the returned Variable::Span can be used for computation, thus avoiding an extra copy from user memory into the adios buffer. -Variable::Span combines a hybrid Sync and Deferred mode, in which the initial value and memory allocations are Sync, while data population and metadata collection are done at EndStep/PerformPuts/Close. Memory contracts are explained later in this chapter followed by examples. +``Variable::Span`` is helpful in situations in which temporaries are needed to create contiguous pieces of memory from non-contiguous pieces (``e.g.`` tables, arrays without ghost-cells), or just to save memory as the returned ``Variable::Span`` can be used for computation, thus avoiding an extra copy from user memory into the adios buffer. +``Variable::Span`` combines a hybrid Sync and Deferred mode, in which the initial value and memory allocations are Sync, while data population and metadata collection are done at EndStep/PerformPuts/Close. +Memory contracts are explained later in this chapter followed by examples. -The following Variable::Span signatures are available: +The following ``Variable::Span`` signatures are available: -2. Return a span setting a default T() value into a default buffer +2. Return a span setting a default ``T()`` value into a default buffer .. code-block:: c++ Variable::Span Put(Variable variable); -3. Return a span setting an initial fill value into a certain buffer. If span is not returned then the fillValue is fixed for that block. +3. Return a span setting an initial fill value into a certain buffer. If span is not returned then the ``fillValue`` is fixed for that block. .. code-block:: c++ @@ -93,7 +108,8 @@ The following Variable::Span signatures are available: .. warning:: - As of version 2.4.0 only the default BP3 engine using the C++11 bindings supports ``Variable::Span`` Put signatures. We plan to support this feature and add this to streaming Engines. + As of version 2.4.0 only the default BP3 engine using the C++11 bindings supports ``Variable::Span`` Put signatures. + We plan to support this feature and add this to streaming Engines. In summary, the following are the current Put signatures for publishing data in ADIOS 2: diff --git a/docs/user_guide/source/components/io.rst b/docs/user_guide/source/components/io.rst index dcbe4825c1..3eb389f4a3 100644 --- a/docs/user_guide/source/components/io.rst +++ b/docs/user_guide/source/components/io.rst @@ -55,7 +55,7 @@ If ``SetEngine`` is not called, then the ``BPFile`` engine is used. void adios2::IO::SetEngine( const std::string engineType ); /** Example */ - bpIO.SetEngine("BPFileWriter"); + bpIO.SetEngine("BPFile"); Each ``Engine`` allows the user to fine tune execution of buffering and output tasks via parameters passed to the ``IO`` object. These parameters are then propagated to the ``Engine``. @@ -163,7 +163,8 @@ Keep in mind that Attributes apply to all Engines created by the ``IO`` object a const size_t elements); In situations in which a variable and attribute has been previously defined: -1) a variable/attribute reference goes out of scope, or 2) when reading from an incoming stream, IO can inquire the current variables and attributes and return a pointer acting as reference. If the inquired variable/attribute is not found, then ``nullptr`` is returned. +1) a variable/attribute reference goes out of scope, or 2) when reading from an incoming stream, IO can inquire the current variables and attributes and return a pointer acting as reference. +If the inquired variable/attribute is not found, then the overloaded ``bool()`` operator of returns ``false``. .. code-block:: c++ @@ -172,7 +173,7 @@ In situations in which a variable and attribute has been previously defined: adios2::Attribute InquireAttribute(const std::string &name) noexcept; /** Example */ - adios2::Variable varPressure = io.InquireVariable("pressure"); + adios2::Variable varPressure = io.InquireVariable("pressure"); if( varPressure ) // it exists { ... @@ -180,7 +181,7 @@ In situations in which a variable and attribute has been previously defined: .. note:: - ``InquireVariable`` returns a pointer so that ``nullptr`` can indicate invalid states (e.g. variables haven't arrived in a stream, weren't previously defined, or weren't written in a file). + ``adios2::Variable`` overloads ``operator bool()`` so that we can check for invalid states (e.g. variables haven't arrived in a stream, weren't previously defined, or weren't written in a file). .. caution:: diff --git a/docs/user_guide/source/components/operator.rst b/docs/user_guide/source/components/operator.rst index f9be356022..1c3bcb8dbf 100644 --- a/docs/user_guide/source/components/operator.rst +++ b/docs/user_guide/source/components/operator.rst @@ -2,7 +2,8 @@ Operator ******** -The Operator abstraction allows ADIOS2 to act upon the user application data, either from a ``adios2::Variable`` or a set of Variables in an ``adios2::IO`` object. Current supported operations are: +The Operator abstraction allows ADIOS2 to act upon the user application data, either from a ``adios2::Variable`` or a set of Variables in an ``adios2::IO`` object. +Current supported operations are: 1. Data compression/decompression, lossy and lossless. 2. Callback functions (C++11 bindings only) supported by specific engines @@ -11,4 +12,5 @@ ADIOS2 enables the use of third-party libraries to execute these tasks. .. warning:: - Make sure your ADIOS2 library installation used for writing and reading was linked with a compatible version of a third-party dependency when working with operators. ADIOS2 will issue an exception if an operator library dependency is missing. + Make sure your ADIOS2 library installation used for writing and reading was linked with a compatible version of a third-party dependency when working with operators. + ADIOS2 will issue an exception if an operator library dependency is missing. diff --git a/docs/user_guide/source/components/overview.rst b/docs/user_guide/source/components/overview.rst index da1af1ca52..c6a28b46b2 100644 --- a/docs/user_guide/source/components/overview.rst +++ b/docs/user_guide/source/components/overview.rst @@ -4,7 +4,8 @@ Components Overview .. note:: - If you are doing simple tasks where performance is a non-critical aspect please go to the :ref:`High-Level 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. + If you are doing simple tasks where performance is a non-critical aspect please go to the :ref:`High-Level 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. diff --git a/docs/user_guide/source/components/runtime.rst b/docs/user_guide/source/components/runtime.rst index 2e66899a0d..d79398f976 100644 --- a/docs/user_guide/source/components/runtime.rst +++ b/docs/user_guide/source/components/runtime.rst @@ -6,7 +6,8 @@ ADIOS2 supports passing an optional runtime configuration file to the :ref:`ADIO This file contains key-value pairs equivalent to the compile time ``IO::SetParameters`` (``adios2_set_parameter`` in C, Fortran), and ``IO::AddTransport`` (``adios2_set_transport_parameter`` in C, Fortran). -Each Engine and Operator must provide a set of available parameters as described in the :ref:`Supported Engines` section. Up to version v2.6.0 only XML is supported, v2.6.0 and beyond support XML as well as YAML. +Each ``Engine`` and ``Operator`` must provide a set of available parameters as described in the :ref:`Supported Engines` section. +Up to version v2.6.0 only XML is supported, v2.6.0 and beyond support XML as well as YAML. .. warning:: @@ -50,7 +51,10 @@ XML YAML ---- -Starting with v2.6.0, ADIOS supports YAML configuration files. The syntax follows strict use of the YAML node keywords mapping to the ADIOS2 components hierarchy. If a keyword is unknown ADIOS2 simply ignores it. For an example file refer to `adios2 config file example in our repo. `_ +Starting with v2.6.0, ADIOS supports YAML configuration files. +The syntax follows strict use of the YAML node keywords mapping to the ADIOS2 components hierarchy. +If a keyword is unknown ADIOS2 simply ignores it. +For an example file refer to `adios2 config file example in our repo. `_ .. code-block:: yaml @@ -100,4 +104,3 @@ Starting with v2.6.0, ADIOS supports YAML configuration files. The syntax follow .. tip:: Run a YAML validator or use a YAML editor to make sure the provided file is YAML compatible. - diff --git a/docs/user_guide/source/components/variable.rst b/docs/user_guide/source/components/variable.rst index 16711bf62f..5a4b4b77e3 100644 --- a/docs/user_guide/source/components/variable.rst +++ b/docs/user_guide/source/components/variable.rst @@ -56,22 +56,21 @@ In C++, acceptable types ``T`` in ``Variable`` along with their preferred fix Shapes --------------------- -.. note:: - As of beta release version 2.2.0 local variable reads are not supported, yet. This is work in progress. Please use global arrays and values as a workaround. - -ADIOS2 is designed *out-of-the-box* for MPI applications. -Thus different application data shape types must be covered depending on their scope within a particular MPI communicator. -The shape type is defined at creation from the IO object by providing the dimensions: shape, start, count in the ``IO::DeclareVariable`` template function. -The supported Variables by shape types can be classified as: +ADIOS2 is designed for MPI applications. +Thus different application data shapes must be supported depending on their scope within a particular MPI communicator. +The shape is defined at creation from the ``IO`` object by providing the dimensions: shape, start, count in the ``IO::DeclareVariable`` template function. +The supported shapes are described below. -1. **Global Single Value**: only a name is required for their definition. These variables are helpful for storing global information, preferably managed by only one MPI process, that may or may not change over steps: *e.g.* total number of particles, collective norm, number of nodes/cells, etc. +1. **Global Single Value**: +Only a name is required for their definition. +These variables are helpful for storing global information, preferably managed by only one MPI process, that may or may not change over steps: *e.g.* total number of particles, collective norm, number of nodes/cells, etc. .. code-block:: c++ if( rank == 0 ) { - adios2::Variable varNodes = adios2::DefineVariable("Nodes"); + adios2::Variable varNodes = adios2::DefineVariable("Nodes"); adios2::Variable varFlag = adios2::DefineVariable("Nodes flag"); // ... engine.Put( varNodes, nodes ); @@ -81,52 +80,46 @@ The supported Variables by shape types can be classified as: .. note:: - 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``. + 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. +2. **Global Array**: +The most common shape used for storing data 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:: https://i.imgur.com/MKwNe5e.png .. warning:: - 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. + Be aware of data ordering in your language of choice (row-major or column-major) as depicted in the figure above. + Data decomposition is done by the application, 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 Value**: single value-per-rank variables that are local to the MPI process. They are defined by passing the ``adios2::LocalValueDim`` enum as follows: +3. **Local Value**: +Values that are local to the MPI process. +They are defined by passing the ``adios2::LocalValueDim`` enum as follows: .. code-block:: c++ - adios2::Variable varProcessID = - io.DefineVariable("ProcessID", {adios2::LocalValueDim}) + adios2::Variable varProcessID = + io.DefineVariable("ProcessID", {adios2::LocalValueDim}) //... - engine.Put(varProcessID, rank); + engine.Put(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. +4. **Local Array**: +Arrays that are local to the MPI process. +These are commonly used to write checkpoint-restart data. +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:: https://i.imgur.com/XLh2TUG.png -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++ - - adios2::Variable varTable = io.DefineVariable( - "table", {adios2::JoinedDim, Ncolumns}, {}, {Nrows, Ncolumns}); - - .. note:: - - Only one dimension can be joinable, every other dimension must be the same on each process. - - .. note: - - The local dimension size in the joinable dimension is allowed to change over time within each processor. However, if the sum of all local sizes changes over time, the result will look like a local array. Since global arrays with changing global dimension over time can only be handled as local arrays in ADIOS2. - - .. note:: - Constants are not handled separately from step-varying values in ADIOS2. Simply write them only once from one rank. - + Constants are not handled separately from step-varying values in ADIOS2. + Simply write them only once from one rank.