Skip to content

Commit

Permalink
Merge pull request #1039 from aronhelser/doc_tweaks
Browse files Browse the repository at this point in the history 
Docs: many small wording and punctuation changes.
  • Loading branch information
@williamfgc
williamfgc committed Dec 6, 2018
2 parents 6e53dfb + 7085bd2 commit d93dd5c
Show file tree
Hide file tree
Showing 11 changed files with 266 additions and 266 deletions.
50 changes: 25 additions & 25 deletions docs/user_guide/source/components/adios.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
ADIOS
*****

The `adios2::ADIOS` component is the initial point between an application and the ADIOS2 library. Applications can be classified as MPI and non-MPI based. We start focusing on MPI applications as their non-MPI equivalent just removes the MPI-specific communicator.
The `adios2::ADIOS` component is the initial contact point between an application and the ADIOS2 library. Applications can be classified as MPI and non-MPI based. We start by focusing on MPI applications as their non-MPI equivalent just removes the MPI-specific communicator.

.. code-block:: c++

Expand All @@ -11,18 +11,18 @@ The `adios2::ADIOS` component is the initial point between an application and th
This component is created by passing:

1. **Runtime config file** (optional): ADIOS2 xml runtime config file, see :ref:`Runtime Configuration Files`
2. **MPI communicator**: which determines the scope of the ADIOS library components in an application.
1. **Runtime config file** (optional): ADIOS2 xml runtime config file, see :ref:`Runtime Configuration Files`
2. **MPI communicator**: which determines the scope of the ADIOS library components in an application.
3. **debug mode flag**: turns on/off exceptions triggered by user inputs.

.. caution::

Running with the default debug mode (turned on) is highly recommended as it performs additional exception checks that the user can fix in case of an error or ill-formed object (std::invalid_argument). Turning the debug mode option should be used with caution when the user inputs to the resulting workflow is stable.
Running with the default debug mode (turned on) is highly recommended as it performs additional exception checks that the user can fix in case of an error or ill-formed object (std::invalid_argument). Turning the debug mode option off should be used with caution, when the user inputs to the resulting workflow is stable.

.. note::

Unexpected system failures and runtime errors are always checked by throwing std::runtime_error. Keep in mind that Segmentation Faults are NOT runtime exceptions. We try to keep user interactions as friendly as possible, please report if any bugs on github: https://github.com/ornladios/ADIOS2/issues
Unexpected system failures and runtime errors are always checked by throwing std::runtime_error. Keep in mind that Segmentation Faults are NOT runtime exceptions. We try to keep user interactions as friendly as possible, please report any bugs on github: https://github.com/ornladios/ADIOS2/issues


`adios2::ADIOS` objects can be created in MPI and non-MPI (serial) mode. Optionally, a runtime configuration file can be passed to the constructor indicating the full file path, name and extension. Thus resulting in:

Expand All @@ -31,13 +31,13 @@ This component is created by passing:
.. code-block:: c++

/** Constructors */
// version that accepts an optional runtime adios2 config file
adios2::ADIOS (const std::string configFile,
MPI_COMM mpiComm = MPI_COMM_SELF,
adios2::ADIOS (const std::string configFile,
MPI_COMM mpiComm = MPI_COMM_SELF,
const bool debugMode = adios2::DebugON );
adios2::ADIOS (MPI_COMM mpiComm = MPI_COMM_SELF,

adios2::ADIOS (MPI_COMM mpiComm = MPI_COMM_SELF,
const bool debugMode = adios2::DebugON );

/** Examples */
Expand All @@ -49,18 +49,18 @@ This component is created by passing:
.. code-block:: c++

/** Constructors */
adios2::ADIOS (const std::string configFile,
adios2::ADIOS (const std::string configFile,
const bool debugMode = adios2::DebugON );
adios2::ADIOS (const bool debugMode = adios2::DebugON );

/** Examples */
adios2::ADIOS adios("config.xml", adios2::DebugON);
adios2::ADIOS adios; // Do not use () for empty constructor.
.. tip::
adios2::DebugON and adios::DebugOFF are aliases to true and false, respectively. Use them for code clarity.

adios2::DebugON and adios::DebugOFF are aliases to true and false, respectively. Use them for code clarity.


**Factory of IO components**: Multiple IO components (IO tasks) can be created from within the scope of an ADIOS object by calling the **DeclareIO** function:
Expand All @@ -73,26 +73,26 @@ This component is created by passing:
/** Examples */
adios2::IO bpWriter = adios.DeclareIO("BPWriter");
adios2::IO bpReader = adios.DeclareIO("BPReader");
This function returns a reference to an existing IO class object that lives inside the ADIOS object that created it. The ioName identifier input must be unique for each IO. Trying to declare an IO object with the same name twice will throw an exception if the debugMode is on in the ADIOS object constructor.
IO names are used to identify IO components in the runtime configuration file, `ref:Runtime Configuration Files`

This function returns a reference to an existing IO class object that lives inside the ADIOS object that created it. The `ioName` identifier input must be unique for each IO. Trying to declare an IO object with the same name twice will throw an exception if the debugMode is on in the ADIOS object constructor.
IO names are used to identify IO components in the runtime configuration file, :ref:`Runtime Configuration Files`

As shown in the diagram below, each resulting IO object is self-managed and independent, thus providing an adaptable way to perform different kinds of I/O operations. Users must be careful not to create conflicts between system level unique I/O identifiers: file names, IP address and port, MPI Send/Receive message rank and tag, etc.

.. blockdiag::

diagram {
default_fontsize = 18;
default_shape = roundedbox;
default_linecolor = blue;
span_width = 150;
ADIOS -> IO_1, B, IO_N [label = "DeclareIO",fontsize = 13];
B [shape = "dots"];

ADIOS -> IO_1, B, IO_N [label = "DeclareIO",fontsize = 13];
B [shape = "dots"];
ADIOS -> B [style = "none"];
}

.. tip::

The ADIOS component is the only one whose memory is owned by the application. Thus applications must decide on its scope. Any other component of the ADIOS2 API refers to a component that lives inside the ADIOS component (e.g. IO, Operator) or indirectly in the IO component (Variable, Engine)
66 changes: 33 additions & 33 deletions docs/user_guide/source/components/engine.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,33 +7,33 @@ The Engine abstraction component serves as the base interface to the actual IO S
Engine functionality works around two concepts from the application point-of-view:

1. Self-describing variables are published and consumed in "steps" in either "File" mode (all steps are available) or "Streaming" mode (steps are available are they are produced).
2. Self-describing variables are published and consumed using a "sync" or "deferred" (lazy evaluation) policy.
2. Self-describing variables are published and consumed using a "sync" or "deferred" (lazy evaluation) policy.

.. caution::

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.


Engine API Functions
--------------------

Recall that Engines are created through the ``IO::Open`` function which must contain a Mode (Write, Read, Append). Therefore, the current functionalty of all Engines are provided through the basic API functions:

For Publishing data (Write, Append mode)

* **Put**
* **Put**
**Default mode: deferred (lazy evaluation).** Data pointer (or array) to memory must not be reused until first encounter with PerformPuts, EndStep or Close. Use sync mode to allow the pointer memory to be reusable immediately. This is enabled by passing the flag adios2::Mode::Sync as the 3rd argument.

* **PerformsPuts**
* **PerformsPuts**
Executes all pending Put calls in deferred mode until this line.


For Consuming data (Read mode)

* **Get**
* **Get**
**Default mode: deferred (lazy evaluation).** Data pointer (or array) to memory must not be reused until first encounter with PerformPuts, EndStep or Close. Use sync mode to populate the data pointer memory immediately. This is enabled by passing the flag adios2::Mode::Sync as the 3rd argument.

* **PerformsGets**
* **PerformsGets**
Executes all pending deferred Get calls in deferred mode until this line.

Common Functionality (Write, Read, Append modes)
Expand All @@ -51,45 +51,45 @@ The following example illustrates the basic API usage in write mode for data gen
for( size_t i = 0; i < steps; ++i )
{
// ... Application *data generation
engine.BeginStep(); //next "logical" step for this application

engine.Put(variableT, dataT, adios2::Mode::Sync);
// dataT memory already subscribed
// dataT memory already subscribed
// Application can modify its contents
//deferred functions return immediately (lazy evaluation),
// dataU, dataV and dataW must not be resued

//deferred functions return immediately (lazy evaluation),
// dataU, dataV and dataW must not be resued
//1st batch
engine.Put(variableU, dataU);
engine.Put(variableV, dataV);
// in this case adios2::Mode::Deferred is redundant,
// as this is the default option
engine.Put(variableW, dataW, adios2::Mode::Deferred);
// effectively dataU, dataV, dataW memory subscription is "deferred"
// until the first call toPerformPuts, EndStep or Close.
engine.Put(variableW, dataW, adios2::Mode::Deferred);
// effectively dataU, dataV, dataW memory subscription is "deferred"
// until the first call toPerformPuts, EndStep or Close.
// Application MUST NOT modify their contents.
engine.PerformPuts();
// dataU, dataV, data4W subscribed
// dataU, dataV, data4W subscribed
// Application can modify their contents

// ... Application modifies dataU, dataV, dataW

//2nd batch
engine.Put(variableUi, dataU);
engine.Put(variableVi, dataV);
engine.Put(variableWi, dataW);
// Application MUST NOT modify dataU, dataV and dataW
engine.EndStep();
// end of current logical step,
// default behavior: transport data

engine.EndStep();
// end of current logical step,
// default behavior: transport data
// if buffering is not fine-tuned with io.SetParameters
// dataU, dataV, data4W subscribed

// dataU, dataV, data4W subscribed
// Application can modify their contents
}
}

engine.Close();
// engine is unreachable and all data should be transported
...
Expand All @@ -101,15 +101,15 @@ 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.
Do not assume the data pointer is usable after a Put and Get, before EndStep, Close or the corresponding PerformPuts/PerformGets.
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
-----------------

A particular engine is set within the IO object that creates it with the ``IO::SetEngine`` function in a case insensitive manner. If the SetEngine function is not invoked the default engine is the **BPFile** for writing and reading self-describing bp (binary-pack) files.

+-------------------------+---------+---------------------------------------------+
| Application | Engine | Description |
+-------------------------+---------+---------------------------------------------+
Expand All @@ -125,10 +125,10 @@ A particular engine is set within the IO object that creates it with the ``IO::S

Engine Polymorphism has a two-fold goal:

1. Each Engine targets orthogonal IO scenarios targeting use cases (e.g. Files, WAN, InSitu MPI, etc) using a simple, unified API.
1. Each Engine implements an orthogonal IO scenario targeting a use case (e.g. Files, WAN, InSitu MPI, etc) using a simple, unified API.

2. Allow developers to build their own custom system solution based on their particular requirements in the own playground space. Resusable toolkit objects are available inside ADIOS2 for common tasks: bp buffering, transport management, transports, etc.

A class that extends the Engine must be thought of a solution to a range of IO applications. Each engine must provide a list of supported parameters, set in the IO object creating this engine in ``IO::SetParameters, IO::SetParameter``, and supported transports (and their parameters) in ``IO::AddTransport``. Each Engine particular options are documented in Chapter XX.
A class that extends Engine must be thought of as a solution to a range of IO applications. Each engine must provide a list of supported parameters, set in the IO object creating this engine using ``IO::SetParameters, IO::SetParameter``, and supported transports (and their parameters) in ``IO::AddTransport``. Each Engine's particular options are documented in :ref:`Supported Engines`.


0 comments on commit d93dd5c

Please sign in to comment.