Full APIs

Note

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 High-Level APIs.

Currently ADIOS2 support bindings for the following languages and their minimum standards:

Language	Standard	Interface
C++	11/newer older	`#include adios2.h` use C bindings
C	99	`#include adios2_c.h`
Fortran	90	`use adios2`
Python	2.7 3	`import adios2` `import adios2`

Tip

Prefer the C++11 bindings if your application C++ compiler supports the 2011 (or later) standard. For code using previous C++ standards (98 or 03) use the C bindings for ABI compatibility.

Caution

Statically linked libraries (*.a) might result in conflicting ABIs between an older C++ project, the C bindings, and the adios native C++11 library. Test to make sure it works for your platform.

The current interaction flow for each language binding API with the ADIOS2 library is specified as follows

The following sections provide a summary of the API calls on each language and links to Write and Read examples to put it all together.

C++11 bindings

Caution

DO NOT use the clause using namespace adios2 in your code. This is in general a bad practices that creates potential name conflicts. Always use adios2:: explicitly, e.g. adios2::ADIOS, adios2::IO.

Tip

Prefer the C++11 bindings to take advantage of added functionality (e.g. move semantics, lambdas, etc.). If you must use an older C++ standard (98 or 03) to avoid application binary interface (ABI) incompatibilities use the C bindings.

ADIOS2 components classes

ADIOS2 C++ bindings objects are mapped 1-to-1 to the ADIOS components described in the Components Overview section. Only the adios2::ADIOS object is “owned” by the developer’s program using adios2, all other components are light-weight objects that point internally to a component that lives inside the adios2::ADIOS “factory” object.

c++11
adios2::ADIOS
adios2::IO
adios2::Variable<T>
adios2::Attribute<T>
adios2::Engine
adios2::Operator

The following section provides a summary of the available functionality for each class.

ADIOS class

class ADIOS

Public Functions

ADIOS(MPI_Comm comm)

Starting point for MPI apps. Creates an ADIOS object. MPI Collective Operation as it call MPI_Comm_dup

Parameters:: comm – defines domain scope from application
Throws:: std::invalid_argument – if user input is incorrect

ADIOS(const std::string &configFile, MPI_Comm comm)

Starting point for MPI apps. Creates an ADIOS object allowing a runtime config file. MPI collective and it calls MPI_Comm_dup and MPI_Bcast to pass the configFile contents

Parameters:

configFile – runtime config file
comm – defines domain scope from application

Throws:

std::invalid_argument – if user input is incorrect

ADIOS(const std::string &configFile, MPI_Comm comm, const std::string &hostLanguage): extra constructor for R and other languages that use the public C++ API but has data in column-major. Pass “” for configfile if there is no config file. Last bool argument exist only to ensure matching this signature by having different number of arguments. Supported languages are “R”, “Matlab”, “Fortran”, all these names mean the same thing: treat all arrays column-major e.g. adios2::ADIOS(“”, comm, “Fortran”, false);

ADIOS(const std::string &configFile)

Starting point for non-MPI serial apps. Creates an ADIOS object allowing a runtime config file.

Parameters:: configFile – runtime config file
Throws:: std::invalid_argument – if user input is incorrect

ADIOS()

Starting point for non-MPI apps. Creates an ADIOS object

Throws:: std::invalid_argument – if user input is incorrect

ADIOS(const std::string &configFile, const std::string &hostLanguage): extra constructor for R and other languages that use the public C++ API but has data in column-major. Pass “” for configfile if there is no config file. Last bool argument exist only to ensure matching this signature by having different number of arguments. Supported languages are “R”, “Matlab”, “Fortran”, all these names mean the same thing: treat all arrays column-major e.g. adios2::ADIOS(“”, “Fortran”, false);

explicit operator bool() const noexcept: object inspection true: valid object, false: invalid object

ADIOS(const ADIOS&) = delete: DELETED Copy Constructor. ADIOS is the only object that manages its own memory. Create a separate object for independent tasks

ADIOS(ADIOS&&) = default: default move constructor exists to allow for auto ad = ADIOS(…) initialization

~ADIOS() = default: MPI Collective calls MPI_Comm_free Uses RAII for all other members

ADIOS &operator=(const ADIOS&) = delete: copy assignment is forbidden for the same reason as copy constructor

ADIOS &operator=(ADIOS&&) = default: move assignment is allowed, though, to be consistent with move constructor

IO DeclareIO(const std::string name, const ArrayOrdering ArrayOrder = ArrayOrdering::Auto)

Declares a new IO class object

Parameters:: name – unique IO name identifier within current ADIOS object
Throws:: std::invalid_argument – if IO with unique name is already declared
Returns:: reference to newly created IO object inside current ADIOS object

IO AtIO(const std::string name)

Retrieve an existing IO object previously created with DeclareIO.

Parameters:: name – IO unique identifier key in current ADIOS object
Throws:: std::invalid_argument – if IO was not created with DeclareIO
Returns:: if IO exists returns a reference to existing IO object inside ADIOS, else throws an exception. IO objects can’t be invalid.

Operator DefineOperator(const std::string name, const std::string type, const Params &parameters = Params())

Defines an adios2 supported operator by its type.

Parameters:

name – unique operator name identifier within current ADIOS object
type – supported ADIOS2 operator type: zfp, sz
parameters – key/value parameters at the operator object level

Throws:

std::invalid_argument – if adios2 can’t support current operator due to missing dependency or unsupported type

Returns:

Operator object

template<class R, class ...Args> Operator DefineOperator(const std::string name, const std::function<R(Args...)> &function, const Params &parameters = Params())

Defines an adios2 supported operator by its type. Variadic template version for Operators of type Callback function with signatures suported in ADIOS2. For new signature support open an issue on github.

Parameters:

name – unique operator name within ADIOS object
function – C++11 callable target
parameters – key/value parameters at the operator level

Throws:

std::invalid_argument – if adios2 can’t support current operator due to missing dependency or unsupported type

Returns:

Operator object

Operator InquireOperator(const std::string name)

Retrieve an existing Operator object in current ADIOS object

Parameters:: name – Operator unique identifier key in current ADIOS object
Returns:: object to an existing operator in current ADIOS object, Operator object is false if name is not found

void FlushAll()

Flushes all engines in write mode in all IOs created with the current ADIOS object. If no IO or Engine exist, it does nothing.

Throws:: std::runtime_error – if any engine Flush fails

bool RemoveIO(const std::string name)

DANGER ZONE: removes a particular IO. This will effectively eliminate any parameter from the config.xml file

Parameters:: name – io input name
Returns:: true: IO was found and removed, false: IO not found and not removed

void RemoveAllIOs() noexcept: DANGER ZONE: removes all IOs created with DeclareIO. This will effectively eliminate any parameter from the config.xml file also.

void EnterComputationBlock() noexcept: Inform ADIOS about entering communication-free computation block in main thread. Useful when using Async IO

void ExitComputationBlock() noexcept: Inform ADIOS about exiting communication-free computation block in main thread. Useful when using Async IO

IO class

class IO

Public Functions

IO() = default: Empty (default) constructor, use it as a placeholder for future IO objects from ADIOS::IO functions. Can be used with STL containers.

~IO() = default: Use RAII

explicit operator bool() const noexcept: true: valid object, false: invalid object

std::string Name() const

Inspects IO name

Returns:: name

bool InConfigFile() const

Checks if IO exists in a config file passed to ADIOS object that created this IO.

Returns:: true: in config file, false: not in config file

void SetEngine(const std::string engineType)

Sets the engine type for current IO object.

Parameters:: engineType – predefined engine type, default is bpfile

void SetParameter(const std::string key, const std::string value)

Sets a single parameter. Overwrites value if key exists;.

Parameters:

key – parameter key
value – parameter value

void SetParameters(const adios2::Params &parameters = adios2::Params())

Version that passes a map to fill out parameters initializer list = { “param1”, “value1” }, {“param2”, “value2”}, Replaces any existing parameter. Otherwise use SetParameter for adding new parameters.

Parameters:: parameters – adios::Params = std::map<std::string, std::string> key/value parameters

void SetParameters(const std::string &parameters): Version that passes a single string to fill out many parameters. Replaces any existing parameter. initializer string = “param1=value1 , param2 = value2”.

void ClearParameters(): Remove all existing parameters. Replaces any existing parameter. initializer string = “param1=value1 , param2 = value2”.

adios2::Params Parameters() const

Return current parameters set from either SetParameters/SetParameter functions or from config XML for currrent IO object

Returns:: string key/value map of current parameters (not modifiable)

size_t AddTransport(const std::string type, const adios2::Params &parameters = adios2::Params())

Adds a transport and its parameters to current IO. Must be supported by current EngineType().

Parameters:

type – must be a supported transport type for a particular Engine. CAN’T use the keywords “Transport” or “transport”
parameters – acceptable parameters for a particular transport

Throws:

std::invalid_argument – if type=transport

Returns:

transportIndex handler

void SetTransportParameter(const size_t transportIndex, const std::string key, const std::string value)

Sets a single parameter to an existing transport identified with a transportIndex handler from AddTransport. Overwrites existing parameter with the same key.

Parameters:

transportIndex – index handler from AddTransport
key – parameter key
value – parameter value

Throws:

std::invalid_argument – if transportIndex not valid, e.g. not a handler from AddTransport.

template<class T> Variable<T> DefineVariable(const std::string &name, const Dims &shape = Dims(), const Dims &start = Dims(), const Dims &count = Dims(), const bool constantDims = false)

Define a Variable<T> object within IO

Parameters:

name – unique variable identifier
shape – global dimension
start – local offset
count – local dimension
constantDims – true: shape, start, count won’t change, false: shape, start, count will change after definition

Returns:

Variable<T> object

template<class T> Variable<T> InquireVariable(const std::string &name)

Retrieve a Variable object within current IO object

Parameters:: name – unique variable identifier within IO object
Returns:: if found Variable object is true and has functionality, else false and has no functionality

template<class T> Attribute<T> DefineAttribute(const std::string &name, const T *data, const size_t size, const std::string &variableName = "", const std::string separator = "/", const bool allowModification = false)

Define attribute inside io. Array input version.

Parameters:

name – unique attribute identifier IO object or for a Variable if variableName is not empty (associated to a variable)
data – pointer to user data
size – number of data elements
variableName – default is empty, if not empty attributes is associated to a variable
separator – default is “/”, hierarchy between variable name and attribute, e.g. variableName/attribute1, variableName::attribute1. Not used if variableName is empty.
allowModification – true allows redefining existing attribute

Throws:

std::invalid_argument – if Attribute with unique name (in IO or Variable) is already defined

Returns:

object reference to internal Attribute in IO

template<class T> Attribute<T> DefineAttribute(const std::string &name, const T &value, const std::string &variableName = "", const std::string separator = "/", const bool allowModification = false)

Define single value attribute.

Parameters:

name – must be unique for the IO object or for a Variable if variableName is not empty (associated to a variable)
value – single data value
variableName – default is empty, if not empty attributes is associated to a variable
separator – default is “/”, hierarchy between variable name and attribute, e.g. variableName/attribute1, variableName::attribute1. Not used if variableName is empty.
allowModification – true allows redefining existing attribute

Throws:

std::invalid_argument – if Attribute with unique name (in IO or Variable) is already defined

Returns:

object reference to internal Attribute in IO

template<class T> Attribute<T> InquireAttribute(const std::string &name, const std::string &variableName = "", const std::string separator = "/")

Retrieve an existing attribute.

Parameters:

name – must be unique for the IO object or for a Variable if variableName is not empty (associated to a variable)
variableName – default is empty, if not empty attributes is expected to be associated to a variable
separator – default is “/”, hierarchy between variable name and attribute, e.g. variableName/attribute1, variableName::attribute1. Not used if variableName is empty.

Returns:

object reference to internal Attribute in IO, object is false if Attribute is not found

bool RemoveVariable(const std::string &name)

DANGEROUS! Removes an existing Variable in current IO object. Might create dangling objects.

Parameters:: name – unique Variable input
Returns:: true: found and removed variable, false: not found, nothing to remove

void RemoveAllVariables(): DANGEROUS! Removes all existing variables in current IO object. Might create dangling objects.

bool RemoveAttribute(const std::string &name)

DANGEROUS! Removes an existing Attribute in current IO object. Might create dangling objects.

Parameters:: name – unique Attribute identifier
Returns:: true: found and removed attribute, false: not found, nothing to remove

void RemoveAllAttributes(): DANGEROUS! Removes all existing attributes in current IO object. Might create dangling objects.

Engine Open(const std::string &name, const Mode mode)

Open an Engine to start heavy-weight input/output operations.

Parameters:

name – unique engine identifier
mode – adios2::Mode::Write, adios2::Mode::Read, adios2::Mode::ReadStreaming, or adios2::Mode::Append (BP4 only)

Returns:

engine object

Group InquireGroup(char delimiter = '/')

Return a Group object for hierarchical reading.

Parameters:

name – starting path
a – delimiter to separate groups in a string representation

Returns:

Group object

Engine Open(const std::string &name, const Mode mode, MPI_Comm comm)

Open an Engine to start heavy-weight input/output operations. This version allows passing a MPI communicator different from the one used in the ADIOS object contructor MPI Collective function as it calls MPI_Comm_dup

Parameters:

name – unique engine identifier within IO
mode – adios2::Mode::Write, adios2::Mode::Read, or adios2::Mode::Append (BP4 only)
comm – new communicator other than ADIOS object’s communicator

Returns:

engine object

void FlushAll(): Flushes all engines created with this IO with the Open function

std::map<std::string, Params> AvailableVariables(bool namesOnly = false)

Returns a map with variable information.

key: variable name
value: Params is a map<string,string>
- key: “Type”, “Shape”, “AvailableStepsCount”, “Min”, “Max”, “SingleValue”

value: variable info value as string

Parameters:: namesOnly – returns a map with the variable names but with no Parameters. Use this if you only need the list of variable names and call VariableType() and InquireVariable() on the names individually.
Returns:: map<string, map<string, string>>

std::map<std::string, Params> AvailableAttributes(const std::string &variableName = "", const std::string separator = "/", const bool fullNameKeys = false)

Returns a map with available attributes information associated to a particular variableName

Parameters:

variableName – unique variable name associated with resulting attributes, if empty (default) return all attributes
separator – optional name hierarchy separator (/, ::, _, -, \, etc.)
fullNameKeys – true: return full attribute names in keys, false (default): return attribute names relative to variableName

Returns:

map:

std::string VariableType(const std::string &name) const

Inspects variable type. This function can be used in conjunction with MACROS in an else if (type == adios2::GetType<T>() ) {} loop

Parameters:: name – unique variable name identifier in current IO
Returns:: type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if variable not found

std::string AttributeType(const std::string &name) const

Inspects attribute type. This function can be used in conjunction with MACROS in an else if (type == adios2::GetType<T>() ) {} loop

Parameters:: name – unique attribute name identifier in current IO
Returns:: type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if attribute not found

void AddOperation(const std::string &variable, const std::string &operatorType, const Params &parameters = Params())

Adds operation and parameters to current IO object

Parameters:

variable – variable to add operator to
operatorType – operator type to define
parameters – key/value settings particular to the IO, not to be confused by op own parameters

std::string EngineType() const

Inspect current engine type from SetEngine

Returns:: current engine type

Variable `<T>` class

template<class T> class Variable

Public Functions

Variable() = default: Empty (default) constructor, use it as a placeholder for future variables from IO:DefineVariable<T> or IO:InquireVariable<T>. Can be used with STL containers.

~Variable() = default: Default, using RAII STL containers

explicit operator bool() const noexcept: Checks if object is valid, e.g. if( variable ) { //..valid }

void SetMemorySpace(const MemorySpace mem)

Sets the memory space for all following Puts/Gets to either host (default) or device

Parameters:: mem – memory space where Put/Get buffers are allocated

MemorySpace GetMemorySpace()

Get the memory space that was set by the application

Returns:: the memory space stored in the Variable object

void SetShape(const adios2::Dims &shape)

Set new shape, care must be taken when reading back the variable for different steps. Only applies to Global arrays.

Parameters:: shape – new shape dimensions array

void SetBlockSelection(const size_t blockID)

Read mode only. Required for reading local variables, ShapeID() = ShapeID::LocalArray or ShapeID::LocalValue. For Global Arrays it will Set the appropriate Start and Count Selection for the global array coordinates.

Parameters:: blockID – variable block index defined at write time. Blocks can be inspected with bpls -D variableName

void SetSelection(const adios2::Box<adios2::Dims> &selection)

Sets a variable selection modifying current {start, count} Count is the dimension from Start point

Parameters:: selection – input {start, count}

void SetMemorySelection(const adios2::Box<adios2::Dims> &memorySelection)

Set the local start (offset) point to the memory pointer passed at Put and the memory local dimensions (count). Used for non-contiguous memory writes and reads (e.g. multidimensional ghost-cells). Currently Get only works for formats based on BP3.

Parameters:: memorySelection – {memoryStart, memoryCount}

void SetStepSelection(const adios2::Box<size_t> &stepSelection)

Sets a step selection modifying current startStep, countStep countStep is the number of steps from startStep point

Parameters:: stepSelection – input {startStep, countStep}

void SetAccuracy(const adios2::Accuracy &a): Sets the requested accuracy for the next read operation. The actual accuracy after the read is provided in GetAccuracy()

size_t SelectionSize() const

Returns the number of elements required for pre-allocation based on current count and stepsCount

Returns:: elements of type T required for pre-allocation

std::string Name() const

Inspects Variable name

Returns:: name

std::string Type() const

Inspects Variable type

Returns:: type string literal containing the type: double, float, unsigned int, etc.

size_t Sizeof() const

Inspects size of the current element type, sizeof(T)

Returns:: sizeof(T) for current system

adios2::ShapeID ShapeID() const

Inspects shape id for current variable

Returns:: from enum adios2::ShapeID

adios2::Dims Shape(const size_t step = adios2::EngineCurrentStep) const

Inspects shape in global variables

Parameters:: step – input for a particular Shape if changing over time. If default, either return absolute or in streaming mode it returns the shape for the current engine step
Returns:: shape vector

adios2::Dims Start() const

Inspects current start point

Returns:: start vector

adios2::Dims Count() const

Inspects current count from start

Returns:: count vector

size_t Steps() const

For readRandomAccess mode, inspect the number of available steps

Returns:: available steps

size_t StepsStart() const

For readRandomAccess mode, inspect the start step for available steps

Returns:: available start step

size_t BlockID() const

For read mode, retrieve current BlockID, default = 0 if not set with SetBlockID

Returns:: current block id

size_t AddOperation(const Operator op, const adios2::Params &parameters = adios2::Params())

Adds operation and parameters to current Variable object

Parameters:

op – operator to be added
parameters – key/value settings particular to the Variable, not to be confused by op own parameters

Returns:

operation index handler in Operations()

std::vector<Operator> Operations() const

Inspects current operators added with AddOperator

Returns:: vector of Variable<T>::OperatorInfo

void RemoveOperations(): Removes all current Operations associated with AddOperation. Provides the posibility to apply or not operators on a block basis.

std::pair<T, T> MinMax(const size_t step = adios2::DefaultSizeT) const

Read mode only: return minimum and maximum values for current variable at a step. For streaming mode (BeginStep/EndStep): use default (leave empty) for current Engine Step At random access mode (File Engines only): default = absolute MinMax

Parameters:: step – input step
Returns:: pair.first = min pair.second = max

T Min(const size_t step = adios2::DefaultSizeT) const

Read mode only: return minimum values for current variable at a step. For streaming mode (within BeginStep/EndStep): use default (leave empty) for current Engine Step At random access mode (File Engines only): default = absolute MinMax

Parameters:: step – input step
Returns:: variable minimum

T Max(const size_t step = adios2::DefaultSizeT) const

Read mode only: return minimum values for current variable at a step. For streaming mode (within BeginStep/EndStep): use default (leave empty) for current Engine Step At random access mode (File Engines only): default = absolute MinMax

Parameters:: step – input step
Returns:: variable minimum

adios2::Accuracy GetAccuracy(): Get the provided accuracy for the last read operation. Most operations provide data as it was written, meaning that error is reported as 0.0

std::vector<std::vector<typename Variable<T>::Info>> AllStepsBlocksInfo()

Read mode only and random-access (no BeginStep/EndStep) with file engines only. Allows inspection of variable info on a per relative step (returned vector index) basis

Returns:: first vector: relative steps, second vector: blocks info within a step

struct Info

Contains block information for a particular Variable<T>

Public Functions

const T *Data() const: reference to internal block data (used by inline Engine). For deferred variables, valid pointer is not returned until EndStep/PerformGets has been called.

Public Members

adios2::Dims Start: block start

adios2::Dims Count: block count

IOType Min = IOType(): block Min, if IsValue is false

IOType Max = IOType(): block Max, if IsValue is false

IOType Value = IOType(): block Value, if IsValue is true

int WriterID = 0: WriterID, source for stream ID that produced this block

size_t BlockID = 0: blockID for Block Selection

size_t Step = 0: block corresponding step

bool IsReverseDims = false: true: Dims were swapped from column-major, false: not swapped

bool IsValue = false: true: value, false: array

Attribute `<T>` class

template<class T> class Attribute

Public Functions

Attribute() = default: Empty (default) constructor, use it as a placeholder for future attributes from IO:DefineAttribute<T> or IO:InquireAttribute<T>. Can be used with STL containers.

explicit operator bool() const noexcept: Checks if object is valid, e.g. if( attribute ) { //..valid }

std::string Name() const

Inspect attribute name

Returns:: unique name identifier

std::string Type() const

Inspect attribute type

Returns:: type

std::vector<T> Data() const

Inspect attribute data

Returns:: data

bool IsValue() const

Distinguish single-value attributes from vector attributes

Returns:: true if single-value, false otherwise

Engine class

class Engine

Public Functions

Engine() = default: Empty (default) constructor, use it as a placeholder for future engines from IO::Open. Can be used with STL containers.

~Engine() = default: Using RAII STL containers only

explicit operator bool() const noexcept: true: valid engine, false: invalid, not created with IO::Open or post IO::Close

std::string Name() const

Inspect engine name

Returns:: name from IO::Open

std::string Type() const

From ADIOS2 engine type: “bpfile”, “sst”, “dataman”, “insitumpi”, “hdf5”

Returns:: engine type as lower case string

Mode OpenMode() const

Returns the Mode used at Open for current Engine

Returns:

StepStatus BeginStep()

Begin a logical adios2 step, overloaded version with timeoutSeconds = 0 and mode = Read Check each engine documentation for MPI collective/non-collective behavior.

Returns:: current step status

StepStatus BeginStep(const StepMode mode, const float timeoutSeconds = -1.f)

Begin a logical adios2 step, overloaded version for advanced stream control Check each engine documentation for MPI collective/non-collective behavior.

Parameters:

mode – see enum adios2::StepMode for options, Read is the common use case
timeoutSeconds –

Returns:

current step status

size_t CurrentStep() const

Inspect current logical step

Returns:: current logical step

template<class T> Variable<T>::Span Put(Variable<T> variable, const bool initialize, const T &value)

Put signature that provides access to the internal engine buffer for a pre-allocated variable including a fill value. Returns a fixed size Span (based on C++20 std::span) so applications can populate data value after this Put and before PerformPuts/EndStep. Requires a call to PerformPuts, EndStep, or Close to extract the Min/Max bounds.

Parameters:

variable – input variable
initialize – bool flag indicating if allocated memory should be initialized with the provided value. Some engines (BP3/BP4) may initialize the allocated memory anyway to zero if this flag is false.
value – provide an initial fill value

Returns:

span to variable data in engine internal buffer

template<class T> Variable<T>::Span Put(Variable<T> variable)

Put signature that provides access to an internal engine buffer (decided by the engine) for a pre-allocated variable. Allocated buffer may or may not be initialized to zero by the engine (e.g. BP3/BP4 does, BP5 does not).

Parameters:: variable – input variable
Returns:: span to variable data in engine internal buffer

template<class T> void Put(Variable<T> variable, const T *data, const Mode launch = Mode::Deferred)

Put data associated with a Variable in the Engine

Parameters:

variable – contains variable metadata information
data – user data to be associated with a variable
launch – mode policy

Throws:

std::invalid_argument – for invalid variable or nullptr data

template<class T> void Put(const std::string &variableName, const T *data, const Mode launch = Mode::Deferred)

Put data associated with a Variable in the Engine Overloaded version that accepts a variable name string.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open
data – user data to be associated with a variable
launch – mode policy

Throws:

std::invalid_argument – if variable not found or nullptr data

template<class T> void Put(Variable<T> variable, const T &datum, const Mode launch = Mode::Deferred)

Put data associated with a Variable in the Engine Overloaded version that accepts r-values and single variable data.

Parameters:

variable – contains variable metadata information
datum – user data to be associated with a variable, r-value or single data value
launch – mode policy, optional for API consistency, internally is always sync

Throws:

std::invalid_argument – if variable is invalid or nullptr &datum

template<class T> void Put(const std::string &variableName, const T &datum, const Mode launch = Mode::Deferred)

Put data associated with a Variable in the Engine Overloaded version that accepts variables names, and r-values and single variable data.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open
datum – user data to be associated with a variable r-value or single data value
launch – mode policy, optional for API consistency, internally is always sync

Throws:

std::invalid_argument – if variable is invalid or nullptr &datum

template<class T, typename U, class = typename std::enable_if<std::is_convertible<U, AdiosView<U>>::value>::type> inline void Put(Variable<T> variable, U const &data, const Mode launch = Mode::Deferred)

The next two Put functions are used to accept a variable, and an AdiosViews which is a placeholder for Kokkos::View

Parameters:

variable – contains variable metadata information
data – represents any user defined object that is not a vector (used for an AdiosView)
launch – mode policy, optional for API consistency, internally is always sync

void PerformPuts(): Perform all Put calls in Deferred mode up to this point. Specifically, this causes Deferred data to be copied into ADIOS internal buffers as if the Put had been done in Sync mode.

void PerformDataWrite(): Write already-Put() array data to disk. If supported by the engine, this may relieve memory pressure by clearing ADIOS buffers. It is a collective call and can only be called between Begin/EndStep pairs.

template<class T> void Get(Variable<T> variable, T *data, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine

Parameters:

variable – contains variable metadata information
data – user data to be associated with a variable, it must be pre-allocated
launch – mode policy

Throws:

std::invalid_argument – for invalid variable or nullptr data

template<class T> void Get(const std::string &variableName, T *data, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine. Overloaded version to get variable by name.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open
data – user data to be associated with a variable. It must be pre-allocated
launch – mode policy

Throws:

std::invalid_argument – for invalid variableName (variable doesn’t exist in IO) or nullptr data

template<class T> void Get(Variable<T> variable, T &datum, const Mode launch = Mode::Deferred)

Get single value data associated with a Variable from the Engine Overloaded version that accepts r-values and single variable data.

Parameters:

variable – contains variable metadata information
datum – user data to be populated, r-value or single data value
launch – mode policy, optional for API consistency, internally is always sync

Throws:

std::invalid_argument – if variable is invalid or nullptr &datum

template<class T> void Get(const std::string &variableName, T &datum, const Mode launch = Mode::Deferred)

Get single value data associated with a Variable from the Engine Overloaded version that accepts r-values and single variable data.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open
datum – user data to be populated, r-value or single data value
launch – mode policy, optional for API consistency, internally is always sync

Throws:

std::invalid_argument – for invalid variableName (variable doesn’t exist in IO) or nullptr data

template<class T> void Get(Variable<T> variable, std::vector<T> &dataV, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine. Overloaded version that accepts a std::vector without pre-allocation.

Parameters:

variable – contains variable metadata information
dataV – user data vector to be associated with a variable, it doesn’t need to be pre-allocated. Engine will resize.
launch – mode policy

Throws:

std::invalid_argument – for invalid variable

template<class T> void Get(const std::string &variableName, std::vector<T> &dataV, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine. Overloaded version that accepts a std::vector without pre-allocation.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open or BeginStep (streaming mode)
dataV – user data vector to be associated with a variable, it doesn’t need to be pre-allocated. Engine will resize.
launch – mode policy

Throws:

std::invalid_argument – for invalid variableName (variable doesn’t exist in IO)

template<class T> void Get(Variable<T> variable, typename Variable<T>::Info &info, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine. Data is associated with a block selection, and data is retrieved from variable’s BlockInfo.

Note

Preliminary, experimental API, may change soon.

Parameters:

variable – contains variable metadata information
info – block info struct associated with block selection, call will link with implementation’s block info.
launch – mode policy

Throws:

std::invalid_argument – for invalid variable or nullptr data

template<class T> void Get(const std::string &variableName, typename Variable<T>::Info &info, const Mode launch = Mode::Deferred)

Get data associated with a Variable from the Engine. Data is associated with a block selection, and data is retrieved from variable’s BlockInfo. Overloaded version to get variable by name.

Note

Preliminary, experimental API, may change soon.

Parameters:

variableName – find variable by name inside IO that created this Engine with Open or BeginStep (streaming mode)
info – block info struct associated with block selection, call will link with implementation’s block info.
launch – mode policy

Throws:

std::invalid_argument – for invalid variableName (variable doesn’t exist in IO)

template<class T>
void Get(Variable<T> variable, T **data) const: Assign the value of data to the start of the internal ADIOS buffer for variable variable. The value is immediately available.

template<class T, typename U, class = typename std::enable_if<std::is_convertible<U, AdiosView<U>>::value>::type> inline void Get(Variable<T> variable, U const &data, const Mode launch = Mode::Deferred)

The next two Get functions are used to accept a variable, and an AdiosViews which is a placeholder for Kokkos::View

Parameters:

variable – contains variable metadata information
data – represents any user defined object that is not a vector (used for an AdiosView)
launch – mode policy, optional for API consistency, internally is always sync

void PerformGets(): Perform all Get calls in Deferred mode up to this point

void EndStep(): Ends current step, by default calls PerformsPut/Get internally Check each engine documentation for MPI collective/non-collective behavior.

bool BetweenStepPairs(): Returns True if engine status is between BeginStep()/EndStep() pair, False otherwise.

void Flush(const int transportIndex = -1)

Manually flush to underlying transport to guarantee data is moved

Parameters:: transportIndex –

void Close(const int transportIndex = -1)

Closes current engine, after this call an engine becomes invalid MPI Collective, calls MPI_Comm_free for duplicated communicator at Open

Parameters:: transportIndex –

template<class T> std::map<size_t, std::vector<typename Variable<T>::Info>> AllStepsBlocksInfo(const Variable<T> variable) const

Extracts all available blocks information for a particular variable. This can be an expensive function, memory scales up with metadata: steps and blocks per step Valid in read mode only.

Parameters:: variable –
Returns:: map with all variable blocks information

template<class T> std::vector<typename Variable<T>::Info> BlocksInfo(const Variable<T> variable, const size_t step) const

Extracts all available blocks information for a particular variable and step. Valid in read mode only.

Parameters:

variable – input variable
step – input from which block information is extracted

Returns:

vector of blocks with info for each block per step, if step not found it returns an empty vector

template<class T> std::vector<size_t> GetAbsoluteSteps(const Variable<T> variable) const: Get the absolute steps of a variable in a file. This is for information purposes only, because absolute steps cannot be used in any ADIOS2 calls.

size_t Steps() const

Inspect total number of available steps, use for file engines in read mode only

Returns:: available steps in engine

void LockWriterDefinitions(): Promise that no more definitions or changes to defined variables will occur. Useful information if called before the first EndStep() of an output Engine, as it will know that the definitions are complete and constant for the entire lifetime of the output and may optimize metadata handling.

void LockReaderSelections(): Promise that the reader data selections of are fixed and will not change in future timesteps. This information, provided before the EndStep() representing a fixed read pattern, may be utilized by the input Engine to optimize data flow.

Operator class

class Operator

Public Functions

Operator() = default: Empty (default) constructor, use it as a placeholder for future operators from ADIOS::DefineOperator functions. Can be used with STL containers.

explicit operator bool() const noexcept: true: valid object, false: invalid object

std::string Type() const noexcept

Inspect current Operator type

Returns:: type as string, if invalid returns an empty std::string

void SetParameter(const std::string key, const std::string value)

Set a key/value parameters associated with this operator (global parameter from the object it’s applied to: Variable, IO). If key exists, it replace the current value.

Parameters:

key – parameter key
value – parameter value

Params &Parameters() const

Inspect current operator parameters

Returns:: map of key/value parameters

Debugging

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 an ostream.

Example:

auto myVar = io.DefineVariable<double>("myVar");
std::cout << myVar << " has shape id " << myVar.ShapeID() << std::endl;

// will print:
// Variable<double>(Name: "myVar") has shape id ShapeID::GlobalValue

if (myVar.ShapeID() != adios2::ShapeID::GlobalArray)
{
    throw std::invalid_argument("can't handle " +
                                ToString(myVar.ShapeID()) + " in " +
                                ToString(myVar));
}

// will throw exception like this:
// C++ exception with description "can't handle ShapeID::GlobalValue
// in Variable<double>(Name: "myVar")" thrown

Group API

class Group

Public Functions

std::vector<std::string> AvailableGroups()

returns available groups on the path set

Param :

std::vector<std::string> AvailableVariables()

returns available variables on the path set

Param :

std::vector<std::string> AvailableAttributes()

returns available attributes on the path set

Param :

std::string InquirePath()

returns the current path

Param :

void setPath(std::string path)

set the path, points to a particular node on the tree

Parameters:: next – possible path extension

Group InquireGroup(std::string group_name)

returns a new group object

Parameters:: name – of the group
Returns:: new group object

template<class T> Variable<T> InquireVariable(const std::string &name)

Gets an existing variable of primitive type by name. A wrapper for the corresponding function of the IO class.

Parameters:: name – of variable to be retrieved
Returns:: pointer to an existing variable in current IO, nullptr if not found

template<class T> Attribute<T> InquireAttribute(const std::string &name, const std::string &variableName = "", const std::string separator = "/")

Gets an existing attribute of primitive type by name. A wrapper for the corresponding function of the IO class

Parameters:: name – of attribute to be retrieved
Returns:: pointer to an existing attribute in current IO, nullptr if not found

DataType VariableType(const std::string &name) const

Inspects variable type. This function can be used in conjunction with MACROS in an else if (type == adios2::GetType<T>() ) {} loop

Parameters:: name – unique variable name identifier in current IO
Returns:: type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if variable not found

DataType AttributeType(const std::string &name) const

Inspects attribute type. This function can be used in conjunction with MACROS in an else if (type == adios2::GetType<T>() ) {} loop

Parameters:: name – unique attribute name identifier in current IO
Returns:: type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if attribute not found

The Group API can be used for inquiring other group objects, variables, and attributes by reading, provided that variable and attribute names were written in a tree-like way similar that is used in a file system:

"group1/group2/group3/variable1"
"group1/group2/group3/attribute1"

A group object containing the tree structure is obtained by the InquireGroup function of the IO object.

Group g = io.InquireGroup("group1");

Another group object can be generated by the predecessor group object.

Group g1 = g.InquireGroup("group2");

The absolute path can be inquired or set explicitly

std::string path =  g.InquirePath();
g.setPath("group1/group2/group3");

Names of available groups, variables and attributes could be inquired:

std::vector<std::string> groups = g.AvailableGroups();
std::vector<std::string> variables = g.AvailableVariables();
std::vector<std::string> attributes = g.AvailableVariables();

Finally, variables can be inquired

auto var = g.InquireVariable("variable1");

An extra function is provided that returns a type of a variable

DataType varType  = g.VariableType("variable1");

Step selection

Steps for reading can be selected using a pre-set parameter with as a file name as a key and a list of selected steps separated by comma as a value.

io.SetParameter(filename, "1,3");

Fortran bindings

The Fortran API is a collection of subroutine calls. The first argument is usually a Fortran type (struct) to an ADIOS2 component, while the last argument is an error integer flag, integer ierr. ierr==0 represents successful execution whereas a non-zero value represents an error or a different state. ADIOS2 Fortran bindings provide a list of possible errors coming from the C++ standardized error exception library:

! error possible values for ierr
integer, parameter :: adios2_error_none = 0
integer, parameter :: adios2_error_invalid_argument = 1,
integer, parameter :: adios2_error_system_error = 2,
integer, parameter :: adios2_error_runtime_error = 3,
integer, parameter :: adios2_error_exception = 4

Click here for a Fortran write and read example to illustrate the use of the APIs calls. This test will compile under your build/bin/ directory.

The following subsections describe the overall components and subroutines in the Fortran bindings API.

ADIOS2 typed handlers

ADIOS2 Fortran bindings handlers are mapped 1-to-1 to the ADIOS2 components described in the Components Overview section. For convenience, each type handler contains descriptive components used for read-only inspection.

type(adios2_adios)     :: adios
type(adios2_io)        :: io
type(adios2_variable)  :: variable
type(adios2_attribute) :: attribute
type(adios2_engine)    :: engine

!Read-only components for inspection and ( = defaults)

type adios2_adios
     logical :: valid = .false.
 end type

 type adios2_io
     logical :: valid = .false.
     character(len=15):: engine_type = 'BPFile'
 end type

 type adios2_variable
     logical :: valid = .false.
     character(len=4095):: name = ''
     integer :: type = -1
     integer :: ndims = -1
 end type

 type adios2_attribute
     logical :: valid = .false.
     character(len=4095):: name = ''
     integer :: type = -1
     integer :: length = 0
 end type

 type adios2_engine
     logical :: valid = .false.
     character(len=63):: name = ''
     character(len=15):: type = ''
     integer :: mode = adios2_mode_undefined
 end type

 type adios2_operator
     logical :: valid = .false.
     character(len=63):: name = ''
     character(len=63):: type = ''
 end type

Caution

Use the type read-only components for information purposes only. Changing their values directly, e.g. variable%name = new_name does not have any effect inside the ADIOS2 library

ADIOS subroutines

subroutine adios2_init starting point for the ADIOS2 library

! MPI versions
subroutine adios2_init(adios, comm, ierr)
subroutine adios2_init(adios, config_file, comm, ierr)

! Non-MPI serial versions
subroutine adios2_init(adios, ierr)
subroutine adios2_init(adios, config_file, ierr)

! WHERE:

! ADIOS2 handler to allocate
type(adios2_adios), intent(out):: adios

! MPI Communicator
integer, intent(in):: comm

! Optional runtime configuration file (*.xml), see Runtime Configuration Files
character*(*), intent(in) :: config_file

! error code
integer, intent(out) :: ierr

subroutine adios2_declare_io spawn/create an IO component

subroutine adios2_declare_io(io, adios, io_name, ierr)

! WHERE:

! output ADIOS2 IO handler
type(adios2_io), intent(out):: io

! ADIOS2 component from adios2_init spawning io tasks
type(adios2_adios), intent(in):: adios

! unique name associated with this IO component inside ADIOS2
character*(*), intent(in):: io_name

! error code
integer, intent(out) :: ierr

subroutine adios2_at_io retrieve an existing io component. Useful when the original IO handler goes out of scope

subroutine adios2_at_io(io, adios, io_name, ierr)

! WHERE:

! output IO handler
type(adios2_io), intent(out):: io

! ADIOS2 component from adios2_init that owns IO tasks
type(adios2_adios), intent(in):: adios

! unique name associated with an existing IO component (created with adios2_declare_io)
character*(*), intent(in):: io_name

! error code
integer, intent(out) :: ierr

subroutine adios2_define_operator define an ADIOS2 data compression/reduction operator

subroutine adios2_define_operator(op, adios, op_name, op_type, ierr)

! WHERE

! Operator handler
type(adios2_operator), intent(out) :: op

! ADIOS2 handler
type(adios2_adios), intent(in) :: adios

! Operator name
character*(*), intent(in)  :: op_name

! Operator type
character*(*), intent(in)  :: op_type

! error code
integer, intent(out) :: ierr

subroutine adios2_inquire_operator inquire an ADIOS2 data compression/reduction operator

subroutine adios2_inquire_operator(op, adios, op_name, ierr)

! WHERE

! Operator handler
type(adios2_operator), intent(out) :: op

! ADIOS2 handler
type(adios2_adios), intent(in) :: adios

! Operator name
character*(*), intent(in)  :: op_name

! error code
integer, intent(out) :: ierr

subroutine adios2_flush_all flush all current engines in all IO objects

subroutine adios2_flush_all(adios, ierr)

! WHERE:

! ADIOS2 component from adios2_init owning IO objects and engines
type(adios2_adios), intent(in):: adios

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_io DANGER ZONE: remove an IO object. This will effectively eliminate any parameter from the config xml file

subroutine adios2_remove_io(result, adios, name, ierr)

! WHERE

! Returns True if IO was found, False otherwise
logical, intent(out):: result

! ADIOS2 handler
type(adios2_adios), intent(in) :: adios

! IO input name
character*(*), intent(in):: name

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_all_ios DANGER ZONE: remove all IO objects created for this ADIOS2 handler. This will effectively eliminate any parameter from the config xml file as well.
subroutine adios2_remove_all_ios(adios, ierr) ! WHERE ! ADIOS2 handler type(adios2_adios), intent(in) :: adios ! error code integer, intent(out) :: ierr

subroutine adios2_finalize final point for the ADIOS2 component

subroutine adios2_finalize(adios, ierr)

! WHERE:

! ADIOS2 handler to be deallocated
type(adios2_adios), intent(in):: adios

! error code
integer, intent(out) :: ierr

Caution

Make sure that for every call to adios2_init there is a call to adios2_finalize for the same ADIOS2 handler. Not doing so will result in memory leaks.

subroutine adios2_enter_computation_block inform ADIOS2 about entering communication-free computation block in main thread. Useful when using Async IO.

subroutine adios2_enter_computation_block(adios, ierr)

! WHERE

! ADIOS2 handler
type(adios2_adios), intent(in) :: adios

! error code
integer, intent(out) :: ierr

subroutine adios2_exit_computation_block inform ADIOS2 about exiting communication-free computation block in main thread. Useful when using Async IO.

subroutine adios2_exit_computation_block(adios, ierr)

! WHERE

! ADIOS2 handler
type(adios2_adios), intent(in) :: adios

! error code
integer, intent(out) :: ierr

IO subroutines

subroutine adios2_set_engine set the engine type, see Supported Engines for a list of available engines

subroutine adios2_set_engine(io, engine_type, ierr)

! WHERE:

! IO component
type(adios2_io), intent(in):: io

! engine_type: BP (default), HDF5, DataMan, SST, SSC
character*(*), intent(in):: engine_type

! error code
integer, intent(out) :: ierr

subroutine adios2_in_config_file checks if an IO object exists in a config file passed to ADIOS2.

subroutine adios2_in_config_file(result, io, ierr)

! WHERE

! Output result to indicate whether IO exists
logical, intent(out):: result

! IO handler
type(adios2_io), intent(in):: io

! error code
integer, intent(out):: ierr

subroutine adios2_set_parameter set IO key/value pair parameter in an IO object, see Supported Engines for a list of available parameters for each engine type

subroutine adios2_set_parameter(io, key, value, ierr)

! WHERE:

! IO component owning the attribute
type(adios2_io), intent(in):: io

! key in the key/value pair parameter
character*(*), intent(in):: key

! value in the key/value pair parameter
character*(*), intent(in):: value

! error code
integer, intent(out) :: ierr

subroutine adios2_set_parameters set a map of key/value parameters in an IO object. Replaces any existing parameters. Otherwise use set_parameter for adding single parameters.

subroutine adios2_set_parameters(io, parameters, ierr)

! WHERE

! IO handler
type(adios2_io), intent(in) :: io

! Comma-separated parameter list. E.g. "Threads=2, CollectiveMetadata=OFF"
character*(*), intent(in) :: parameters

! error code
integer, intent(out) :: ierr

subroutine adios2_get_parameter get parameter value from IO object for a given parameter name

subroutine adios2_get_parameter(value, io, key, ierr)

! WHERE

! parameter value
character(len=:), allocatable, intent(out) :: value

! IO handler
type(adios2_io), intent(in) :: io

! parameter key to look for in the IO object
character*(*), intent(in) :: key

! error code
integer, intent(out) :: ierr

subroutine adios2_clear_parameters clear all parameters from the IO object

subroutine adios2_clear_parameters(io, ierr)

! WHERE

! IO handler
type(adios2_io), intent(in) :: io

! error code
integer, intent(out) :: ierr

subroutine adios2_add_transport add a transport to current IO. Must be supported by the currently used engine.

subroutine adios2_add_transport(transport_index, io, type, ierr)

! WHERE

! returns a transport_index handler
integer, intent(out):: transport_index

! IO handler
type(adios2_io), intent(in) :: io

! transport type. must be supported by the engine. CAN’T use the keywords “Transport” or “transport”
character*(*), intent(in) :: type

! error code
integer, intent(out) :: ierr

subroutine adios2_set_transport_parameter set a parameter for a transport. Overwrites existing parameter with the same key.

subroutine adios2_set_transport_parameter(io, transport_index, key, value, ierr)

! WHERE

! IO handler
type(adios2_io), intent(in):: io

! transport_index handler
integer, intent(in):: transport_index

! transport key
character*(*), intent(in) :: key

! transport value
character*(*), intent(in) :: value

! error code
integer, intent(out):: ierr

subroutine adios2_available_variables get a list of available variables

subroutine adios2_available_variables(io, namestruct, ierr)

! WHERE

! IO handler
type(adios2_io), intent(in) :: io

! name struct handler
type(adios2_namestruct), intent(out) :: namestruct

! error code
integer, intent(out) :: ierr

subroutine adios2_retrieve_names retrieve variable names from namestruct obtained from adios2_available_variables. namelist must be pre-allocated.

subroutine adios2_retrieve_names(namestruct, namelist, ierr)

! WHERE

! namestruct obtained from adios2_available_variables
type(adios2_namestruct), intent(inout) :: namestruct

! namelist that will contain variable names
character(*), dimension(*), intent(inout) :: namelist

! error code
integer, intent(out) :: ierr

subroutine adios2_available_attributes get list of attributes in the IO object

subroutine adios2_available_attributes(io, namestruct, ierr)

! WHERE

! IO handler
type(adios2_io), intent(in) :: io

! list of available attributes
type(adios2_namestruct), intent(out) :: namestruct

! error code
integer, intent(out) :: ierr

subroutine adios2_flush_all_engines flush all existing engines opened by this IO object

subroutine adios2_flush_all_engines(io, ierr)

! WHERE:

! IO in which search and flush for all engines is performed
type(adios2_io), intent(in) :: io

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_variable remove an existing variable from an IO object

subroutine adios2_remove_variable(io, name, result, ierr)

! WHERE:

! IO in which search and removal for variable is performed
type(adios2_io), intent(in) :: io

! unique key name to search for variable
character*(*), intent(in) :: name

! true: variable removed, false: variable not found, not removed
logical, intent(out) :: result

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_all_variables remove all existing variables from an IO object

subroutine adios2_remove_all_variables(io, ierr)

! WHERE:

! IO in which search and removal for all variables is performed
type(adios2_io), intent(in) :: io

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_attribute remove existing attribute by its unique name

subroutine adios2_remove_attribute(io, name, result, ierr)

! WHERE:

! IO in which search and removal for attribute is performed
type(adios2_io), intent(in) :: io

! unique key name to search for attribute
character*(*), intent(in) :: name

! true: attribute removed, false: attribute not found, not removed
logical, intent(out) :: result

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_all_attributes remove all existing attributes

subroutine adios2_remove_all_attributes(io, ierr)

! WHERE:

! IO in which search and removal for all attributes is performed
type(adios2_io), intent(in) :: io

! error code
integer, intent(out) :: ierr

Variable subroutines

subroutine adios2_define_variable define/create a new variable

! Global array variables
subroutine adios2_define_variable(variable, io, variable_name, adios2_type, &
                                  ndims, shape_dims, start_dims, count_dims, &
                                  adios2_constant_dims, ierr)
! Global single value variables
subroutine adios2_define_variable(variable, io, variable_name, adios2_type, ierr)

! WHERE:

! handler to newly defined variable
type(adios2_variable), intent(out):: variable

! IO component owning the variable
type(adios2_io), intent(in):: io

! unique variable identifier within io
character*(*), intent(in):: variable_name

! defines variable type from adios2 parameters, see next
integer, intent(in):: adios2_type

! number of dimensions
integer, value, intent(in):: ndims

! variable shape, global size, dimensions
! to create local variables optional pass adios2_null_dims
integer(kind=8), dimension(:), intent(in):: shape_dims

! variable start, local offset, dimensions
! to create local variables optional pass adios2_null_dims
integer(kind=8), dimension(:), intent(in):: start_dims

! variable count, local size, dimensions
integer(kind=8), dimension(:), intent(in):: count_dims

! error code
integer, intent(out) :: ierr

! .true. : constant dimensions, shape, start and count won't change
!          (mesh sizes, number of nodes)
!          adios2_constant_dims = .true. use for code clarity
! .false. : variable dimensions, shape, start and count could change
!           (number of particles)
!           adios2_variable_dims = .false. use for code clarity
logical, value, intent(in):: adios2_constant_dims

available adios2_type parameters in subroutine adios2_define_variable

integer, parameter :: adios2_type_character = 0
integer, parameter :: adios2_type_real = 2
integer, parameter :: adios2_type_dp = 3
integer, parameter :: adios2_type_complex = 4
integer, parameter :: adios2_type_complex_dp = 5

integer, parameter :: adios2_type_integer1 = 6
integer, parameter :: adios2_type_integer2 = 7
integer, parameter :: adios2_type_integer4 = 8
integer, parameter :: adios2_type_integer8 = 9

integer, parameter :: adios2_type_string = 10
integer, parameter :: adios2_type_string_array = 11

Tip

Always prefer using adios2_type_xxx parameters explicitly rather than raw numbers. e.g. use adios2_type_dp instead of 3

subroutine adios2_inquire_variable inquire and get a variable. See variable%valid to check if variable exists.

subroutine adios2_inquire_variable(variable, io, name, ierr)

! WHERE:

! output variable handler:
! variable%valid = .true. points to valid found variable
! variable%valid = .false. variable not found
type(adios2_variable), intent(out) :: variable

! IO in which search for variable is performed
type(adios2_io), intent(in) :: io

! unique key name to search for variable
character*(*), intent(in) :: name

! error code
integer, intent(out) :: ierr

subroutine adios2_set_shape set new shape_dims for a variable if its dims are marked as varying in the define call adios2_define_variable

subroutine adios2_set_shape(variable, ndims, shape_dims, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! number of dimensions in shape_dims
integer, intent(in) :: ndims

! new shape_dims
integer(kind=8), dimension(:), intent(in):: shape_dims

! error code
integer, intent(out) :: ierr

subroutine adios2_set_selection selects part of a variable through start_dims and count_dims

subroutine adios2_set_selection(variable, ndims, start_dims, count_dims, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! number of dimensions in start_dims and count_dims
integer, intent(in) :: ndims

! new start_dims
integer(kind=8), dimension(:), intent(in):: start_dims

! new count_dims
integer(kind=8), dimension(:), intent(in):: count_dims

! error code
integer, intent(out) :: ierr

subroutine adios2_set_step_selection set a list of steps by specifying the starting step and the step count

subroutine adios2_set_step_selection(variable, step_start, step_count, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! new step_start
integer(kind=8), intent(in):: step_start

! new step_count (or number of steps to read from step_start)
integer(kind=8), intent(in):: step_count

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_max get the maximum value in the variable array

subroutine adios2_variable_max(maximum, variable, ierr)

! WHERE

! scalar variable that will contain the maximum value
Generic Fortran types, intent(out) :: maximum

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_min get the minimum value in the variable array

subroutine adios2_variable_min(minimum, variable, ierr)

! WHERE

! scalar variable that will contain the minimum value
Generic Fortran types, intent(out) :: minimum

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_add_operation add an operation to a variable

subroutine adios2_add_operation(operation_index, variable, op, key, value, ierr)

! WHERE

! reference to the operator handle that will be created
integer, intent(out):: operation_index

! variable handler
type(adios2_variable), intent(in):: variable

! Operator handler
type(adios2_operator), intent(in):: op

! Operator key
character*(*), intent(in):: key

! Operator value
character*(*), intent(in):: value

! error code
integer, intent(out):: ierr

subroutine adios2_set_operation_parameter set a parameter for a operator. Replaces value if parameter already exists.

subroutine adios2_set_operation_parameter(variable, operation_index, key, value, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in):: variable

! Operation index handler
integer, intent(in):: operation_index

! parameter key
character*(*), intent(in):: key

! parameter value
character*(*), intent(in):: value

! error code
integer, intent(out):: ierr

subroutine adios2_variable_name retrieve variable name

subroutine adios2_variable_name(name, variable, ierr)

! WHERE

! variable name
character(len=:), allocatable, intent(out) :: name

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_type retrieve variable datatype

subroutine adios2_variable_type(type, variable, ierr)

! WHERE

! variable type
integer, intent(out) :: type

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_ndims retrieve number of dimensions for a variable

subroutine adios2_variable_ndims(ndims, variable, ierr)

! WHERE

! No. of dimensions
integer, intent(out) :: ndims

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_shape retrieve the shape of a variable

subroutine adios2_variable_shape(shape_dims, ndims, variable, ierr)

! WHERE

! array that contains the shape
integer(kind=8), dimension(:), allocatable, intent(out) :: shape_dims

! no. of dimensions
integer, intent(out) :: ndims

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_variable_steps retrieve the number of available steps

subroutine adios2_variable_steps(steps, variable, ierr)

! WHERE

! no. of steps
integer(kind=8), intent(out) :: steps

! variable handler
type(adios2_variable), intent(in) :: variable

! error code
integer, intent(out) :: ierr

subroutine adios2_set_block_selection Read mode only. Required for reading local variables. For global arrays it will set the appropriate Start and Count selection for the global array coordinates.

subroutine adios2_set_block_selection(variable, block_id, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! variable block index defined at write time. Blocks can be inspected with `bpls -D variableName`
integer(kind=8), intent(in) :: block_id

! error code
integer, intent(out) :: ierr

subroutine adios2_set_memory_selection set the local start (offset) point to the memory pointer passed at adios2_put and the memory local dimensions (count). Used for non-contiguous memory writes and reads (e.g. multidimensional ghost-cells). Currently Get only works for formats based on BP.

subroutine adios2_set_memory_selection(variable, ndims, memory_start_dims, memory_count_dims, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! no. of dimensions of the variable
integer, intent(in) :: ndims

! memory start offsets
integer(kind=8), dimension(:), intent(in) :: memory_start_dims

! no. of elements in each dimension
integer(kind=8), dimension(:), intent(in) :: memory_count_dims

! error code
integer, intent(out) :: ierr

subroutine adios2_set_step_selection set a step selection modifying current step_start, step_count. step_count is the number of steps from step_start

subroutine adios2_set_step_selection(variable, step_start, step_count, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in) :: variable

! starting step
integer(kind=8), intent(in) :: step_start

! no. of steps from start
integer(kind=8), intent(in) :: step_count

! error code
integer, intent(out) :: ierr

subroutine adios2_remove_operations remove all current operations associated with the variable. Provides the posibility to apply operators on a block basis.

subroutine adios2_remove_operations(variable, ierr)

! WHERE

! variable handler
type(adios2_variable), intent(in):: variable

! error code
integer, intent(out):: ierr

Engine subroutines

subroutine adios2_open opens an engine to execute IO tasks

! MPI version: duplicates communicator from adios2_init
! Non-MPI serial version
subroutine adios2_open(engine, io, name, adios2_mode, ierr)

! MPI version only to pass a communicator other than the one from adios_init
subroutine adios2_open(engine, io, name, adios2_mode, comm, ierr)

! WHERE:

! handler to newly opened adios2 engine
type(adios2_engine), intent(out) :: engine

! IO that spawns an engine based on its configuration
type(adios2_io), intent(in) :: io

! unique engine identifier within io, file name for default BPFile engine
character*(*), intent(in) :: name

! Optional MPI communicator, only in MPI library
integer, intent(in) :: comm

! error code
integer, intent(out) :: ierr

! open mode parameter:
!                      adios2_mode_write,
!                      adios2_mode_append,
!                      adios2_mode_read,
integer, intent(in):: adios2_mode

subroutine adios2_begin_step begin a new step or progress to the next step. Starts from 0

subroutine adios2_begin_step(engine, adios2_step_mode, timeout_seconds, status, ierr)
! Default Timeout = -1.    (block until step available)
subroutine adios2_begin_step(engine, adios2_step_mode, ierr)
! Default step_mode for read and write
subroutine adios2_begin_step(engine, ierr)

! WHERE

! engine handler
type(adios2_engine), intent(in) :: engine

! step_mode parameter:
!     adios2_step_mode_read (read mode default)
!     adios2_step_mode_append (write mode default)
integer, intent(in):: adios2_step_mode

! optional
! engine timeout (if supported), in seconds
real, intent(in):: timeout_seconds

! status of the stream from adios2_step_status_* parameters
integer, intent(out):: status

! error code
integer, intent(out) :: ierr

subroutine adios2_current_step extracts current step number

subroutine adios2_current_step(current_step, engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! populated with current_step value
integer(kind=8), intent(out) :: current_step

! error code
integer, intent(out) :: ierr

subroutine adios2_steps inspect total number of available steps, use for file engines in read mode only

subroutine adios2_steps(steps, engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! populated with steps value
integer(kind=8), intent(out) :: steps

! error code
integer, intent(out) :: ierr

subroutine adios2_end_step end current step and execute transport IO (flush or read).

subroutine adios2_end_step(engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! error code
integer, intent(out) :: ierr

subroutine adios2_put put variable data and metadata into adios2 for IO operations. Default is deferred mode. For optional sync mode, see Put: modes and memory contracts. Variable and data types must match.

subroutine adios2_put(engine, variable, data, adios2_mode, ierr)

! Default adios2_mode_deferred
subroutine adios2_put(engine, variable, data, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! variable handler containing metadata information
type(adios2_variable), intent(in) :: variable

! Fortran bindings supports data types from adios2_type in variables,
! up to 6 dimensions
! Generic Fortran type from adios2_type
Generic Fortran types, intent(in):: data
Generic Fortran types, dimension(:), intent(in):: data
Generic Fortran types, dimension(:,:), intent(in):: data
Generic Fortran types, dimension(:,:,:), intent(in):: data
Generic Fortran types, dimension(:,:,:,:), intent(in):: data
Generic Fortran types, dimension(:,:,:,:,:), intent(in):: data
Generic Fortran types, dimension(:,:,:,:,:,:), intent(in):: data

! mode:
! adios2_mode_deferred: won't execute until adios2_end_step, adios2_perform_puts or adios2_close
! adios2_mode_sync: special case, put data immediately, can be reused after this call
integer, intent(in):: adios2_mode

! error code
integer, intent(out) :: ierr

subroutine adios2_perform_puts execute deferred calls to adios2_put

subroutine adios2_perform_puts(engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! error code
integer, intent(out) :: ierr

subroutine adios2_get get variable data into ADIOS2 for IO operations. Default is deferred mode. For optional sync mode, see Get: modes and memory contracts. Variable and data types must match, variable can be obtained from adios2_inquire_variable. Memory for data must be pre-allocated.

subroutine adios2_get(engine, variable, data, adios2_mode, ierr)

! Default adios2_mode_deferred
subroutine adios2_get(engine, variable, data, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! variable handler containing metadata information
type(adios2_variable), intent(in) :: variable

! Fortran bindings supports data types from adios2_type in variables,
! up to 6 dimensions. Must be pre-allocated
! Generic Fortran type from adios2_type
Generic Fortran types, intent(out):: data
Generic Fortran types, dimension(:), intent(out):: data
Generic Fortran types, dimension(:,:), intent(out):: data
Generic Fortran types, dimension(:,:,:), intent(out):: data
Generic Fortran types, dimension(:,:,:,:), intent(out):: data
Generic Fortran types, dimension(:,:,:,:,:), intent(out):: data
Generic Fortran types, dimension(:,:,:,:,:,:), intent(out):: data

! mode:
! adios2_mode_deferred: won't execute until adios2_end_step, adios2_perform_gets or adios2_close
! adios2_mode_sync: special case, get data immediately, can be reused after this call
integer, intent(in):: adios2_mode

! error code
integer, intent(out) :: ierr

subroutine adios2_perform_gets execute deferred calls to adios2_get

subroutine adios2_perform_gets(engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! error code
integer, intent(out) :: ierr

subroutine adios2_close close engine. May re-open.

subroutine adios2_close(engine, ierr)

! WHERE:

! engine handler
type(adios2_engine), intent(in) :: engine

! error code
integer, intent(out) :: ierr

subroutine adios2_io_engine_type get current engine type

subroutine adios2_io_engine_type(type, io, ierr)

! WHERE

! engine type (BP, SST, SSC, HDF5, DataMan)
character(len=:), allocatable, intent(out) :: type

! IO handler
type(adios2_io), intent(in) :: io

! error code
integer, intent(out) :: ierr

subroutine adios2_lock_writer_definitions promise that no more definitions or changes to defined variables will occur. Useful information if called before the first EndStep() of an output Engine, as it will know that the definitions are complete and constant for the entire lifetime of the output and may optimize metadata handling.
subroutine adios2_lock_writer_definitions(engine, ierr) ! WHERE ! adios2 engine handler type(adios2_engine), intent(in) :: engine ! error code integer, intent(out) :: ierr
subroutine adios2_lock_reader_selections promise that the reader data selections of are fixed and will not change in future timesteps. This information, provided before the end_step() representing a fixed read pattern, may be utilized by the input Engine to optimize data flow.
subroutine adios2_lock_reader_selections(engine, ierr) ! WHERE ! adios2 engine handler type(adios2_engine), intent(in) :: engine ! error code integer, intent(out) :: ierr

Operator subroutines

subroutine adios2_operator_type get current Operator type

subroutine adios2_operator_type(type, op, ierr)

! WHERE

! Operator type name. See list of supported operator types.
character(len=:), allocatable, intent(out) :: type

! Operator handler
type(adios2_operator), intent(in) :: op

! error code
integer, intent(out) :: ierr

Attribute subroutines

subroutine adios2_define_attribute define/create a new user attribute

! Single value attributes
subroutine adios2_define_attribute(attribute, io, attribute_name, data, ierr)

! 1D array attributes
subroutine adios2_define_attribute(attribute, io, attribute_name, data, elements, ierr)

! WHERE:

! handler to newly defined attribute
type(adios2_attribute), intent(out):: attribute

! IO component owning the attribute
type(adios2_io), intent(in):: io

! unique attribute identifier within io
character*(*), intent(in):: attribute_name

! overloaded subroutine allows for multiple attribute data types
! they can be single values or 1D arrays
Generic Fortran types, intent(in):: data
Generic Fortran types, dimension(:), intent(in):: data

! number of elements if passing a 1D array in data argument
integer, intent(in):: elements

! error code
integer, intent(out) :: ierr

subroutine adios2_inquire_attribute inquire for existing attribute by its unique name

subroutine adios2_inquire_attribute(attribute, io, name, ierr)

! WHERE:

! output attribute handler:
! attribute%valid = .true. points to valid found attribute
! attribute%valid = .false. attribute not found
type(adios2_attribute), intent(out) :: attribute

! IO in which search for attribute is performed
type(adios2_io), intent(in) :: io

! unique key name to search for attribute
character*(*), intent(in) :: name

! error code
integer, intent(out) :: ierr

Caution

Use the adios2_remove_* subroutines with extreme CAUTION. They create outdated dangling information in the adios2_type handlers. If you don’t need them, don’t use them.

subroutine adios2_attribute_data retrieve attribute data

subroutine adios2_attribute_data(data, attribute, ierr)

! WHERE

! data handler
character*(*), intent(out):: data
real, intent(out):: data
real(kind=8), intent(out):: data
integer(kind=1), intent(out):: data
integer(kind=2), intent(out):: data
integer(kind=4), intent(out):: data
integer(kind=8), intent(out):: data
character*(*), dimension(:), intent(out):: data
real, dimension(:), intent(out):: data
real(kind=8), dimension(:), intent(out):: data
integer(kind=2), dimension(:), intent(out):: data
integer(kind=4), dimension(:), intent(out):: data
integer(kind=8), dimension(:), intent(out):: data


! attribute
type(adios2_attribute), intent(in):: attribute

! error code
integer, intent(out) :: ierr

subroutine adios2_attribute_name inspect attribute name

subroutine adios2_attribute_name(name, attribute, ierr)

! WHERE

! name to be output
character(len=:), allocatable, intent(out) :: name

! attribute handler
type(adios2_attribute), intent(in) :: attribute

! error code
integer, intent(out) :: ierr

subroutine adios2_inquire_variable_attribute retrieve a handler to a previously defined attribute associated to a variable

subroutine adios2_inquire_variable_attribute(attribute, io, attribute_name, variable_name, separator, ierr)

! WHERE

! attribute handler
type(adios2_attribute), intent(out) :: attribute

! IO handler
type(adios2_io), intent(in) :: io

! attribute name
character*(*), intent(in) :: attribute_name

! variable name
character*(*), intent(in) :: variable_name

! hierarchy separator (e.g. “/” in variable/attribute )
character*(*), intent(in) :: separator

! error code
integer, intent(out) :: ierr

C bindings

The C bindings are specifically designed for C applications and those using an older C++ standard (98 and 03). If you are using a C++11 or more recent standard, please use the C++11 bindings.

The C bindings are based on opaque pointers to the components described in the Components Overview section.

C API handlers:

adios2_adios*
adios2_io*
adios2_variable*
adios2_attribute*
adios2_engine*
adios2_operator*

Every ADIOS2 function that generates a new adios2_* unique handler returns the latter explicitly. Therefore, checks can be applied to know if the resulting handler is NULL. Other functions used to manipulate these valid handlers will return a value of type enum adios2_error explicitly. These possible errors are based on the C++ standardized exceptions . Each error will issue a more detailed description in the standard error output: stderr.

adios2_error possible values:

typedef enum {
    /** success */
    adios2_error_none = 0,

    /**
     * user input error
     */
    adios2_error_invalid_argument = 1,

    /** low-level system error, e.g. system IO error */
    adios2_error_system_error = 2,

    /** runtime errors other than system errors, e.g. memory overflow */
    adios2_error_runtime_error = 3,

    /** any other error exception */
    adios2_error_exception = 4
} adios2_error;

Usage:

adios2_variable* var = adios2_define_variable(io, ...)
if(var == NULL )
{
    // ... something went wrong with adios2_define_variable
    // ... check stderr
}
else
{
    adios2_type type;
    adios2_error errio = adios2_variable_type(&type, var)
    if(errio){
      // ... something went wrong with adios2_variable_type
      if( errio == adios2_error_invalid_argument)
      {
          // ... user input error
          // ... check stderr
      }
    }
}

Note

Use #include "adios2_c.h" for the C bindings, adios2.h is the C++11 header.

`adios2_adios` handler functions

Defines

adios2_init(comm)

adios2_init_config(config_file, comm)

Functions

adios2_adios *adios2_init_mpi(MPI_Comm comm)

Starting point for MPI apps. Creates an ADIOS handler. MPI collective and it calls MPI_Comm_dup

Parameters:: comm – defines domain scope from application
Returns:: success: handler, failure: NULL

adios2_adios *adios2_init_config_mpi(const char *config_file, MPI_Comm comm)

Starting point for MPI apps. Creates an ADIOS handler allowing a runtime config file. MPI collective and it calls MPI_Comm_dup and MPI_Bcast to pass the configFile contents

Parameters:

config_file – runtime configuration file in xml format
comm – defines domain scope from application

Returns:

success: handler, failure: NULL

adios2_adios *adios2_init_serial(void)

Initialize an ADIOS struct pointer handler in a serial, non-MPI application. Doesn’t require a runtime config file.

Returns:: success: handler, failure: NULL

adios2_adios *adios2_init_config_serial(const char *config_file)

Initialize an ADIOS struct pointer handler in a serial, non-MPI application. Doesn’t require a runtime config file.

Returns:: success: handler, failure: NULL

adios2_io *adios2_declare_io(adios2_adios *adios, const char *name)

Declares a new io handler

Parameters:

adios – owner the io handler
name – unique io identifier within current adios handler

Returns:

success: handler, failure: NULL

adios2_io *adios2_declare_io_order(adios2_adios *adios, const char *name, adios2_arrayordering order)

Declares a new io handler with specific array ordering

Parameters:

adios – owner the io handler
name – unique io identifier within current adios handler
order – array ordering

Returns:

success: handler, failure: NULL

adios2_io *adios2_at_io(adios2_adios *adios, const char *name)

Retrieves a previously declared io handler by name

Parameters:

adios – owner the io handler
name – unique name for the previously declared io handler

Returns:

success: handler, failure: NULL

adios2_operator *adios2_define_operator(adios2_adios *adios, const char *name, const char *type)

Defines an adios2 supported operator by its type.

Parameters:

adios – owner the op handler
name – unique operator name identifier within current ADIOS object
type – supported ADIOS2 operator type: zfp, sz

Returns:

success: handler, failure: NULL

adios2_operator *adios2_inquire_operator(adios2_adios *adios, const char *name)

Retrieves a previously defined operator handler

Parameters:

adios – owner the op handler
name – unique name for the previously defined op handler

Returns:

success: handler, failure: NULL

adios2_error adios2_flush_all(adios2_adios *adios)

Flushes all adios2_engine in write mode in all adios2_io handlers. If no adios2_io or adios2_engine exists it does nothing.

Parameters:: adios – owner of all io and engines to be flushed
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_finalize(adios2_adios *adios)

Final point for adios handler. Deallocates adios pointer. Required to avoid memory leaks. MPI collective and it calls MPI_Comm_free

Parameters:: adios – handler to be deallocated, must be initialized with adios2_init or adios2_init_config
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_remove_io(adios2_bool *result, adios2_adios *adios, const char *name)

DANGER ZONE: removes an io created with adios2_declare_io. Will create dangling pointers for all the handlers inside removed io. NOTE: Use result, not adios2_error to check if the IO was removed.

Parameters:

result – output adios2_true: io not found and not removed, adios2_false: io not found and not removed
adios – owner of io to be removed
name – input unique identifier for io to be removed

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_remove_all_ios(adios2_adios *adios)

DANGER ZONE: removes all ios created with adios2_declare_io. Will create dangling pointers for all the handlers inside all removed io.

Parameters:: adios – owner of all ios to be removed
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_enter_computation_block(adios2_adios *adios): Inform ADIOS about entering communication-free computation block in main thread. Useful when using Async IO

adios2_error adios2_exit_computation_block(adios2_adios *adios): Inform ADIOS about exiting communication-free computation block in main thread. Useful when using Async IO

`adios2_io` handler functions

Functions

adios2_error adios2_in_config_file(adios2_bool *result, const adios2_io *io)

Check if io exists in a config file passed to the adios handler that created this io.

Parameters:

result – output adios2_true=1: in config file, adios2_false=0: not in config file
io – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_engine(adios2_io *io, const char *engine_type)

Set the engine type for current io handler.

Parameters:

io – handler
engine_type – predefined engine type, default is bpfile

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_parameters(adios2_io *io, const char *parameters)

Set several parameters at once.

Parameters:

io – handler
string – parameters in the format “param1=value1 , param2 = value2”

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_parameter(adios2_io *io, const char *key, const char *value)

Set a single parameter. Overwrites value if key exists.

Parameters:

io – handler
key – parameter key
value – parameter value

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_get_parameter(char *value, size_t *size, const adios2_io *io, const char *key)

Return IO parameter value string and length without ‘\0\ character For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

value – output
size – output, value size without ‘\0’
io – input handler
key – input parameter key, if not found return size = 0 and value is untouched

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_clear_parameters(adios2_io *io)

Clear all parameters.

Parameters:: io – handler
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_add_transport(size_t *transport_index, adios2_io *io, const char *type)

Add a transport to current io handler. Must be supported by current engine type.

Parameters:

transport_index – handler used for setting transport parameters or at adios2_close
io – handler
type – must be a supported transport type for a particular Engine. CAN’T use the keywords “Transport” or “transport”

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_transport_parameter(adios2_io *io, const size_t transport_index, const char *key, const char *value)

Set a single parameter to an existing transport identified with a transport_index handler from adios2_add_transport. Overwrites existing parameter with the same key.

Parameters:

io – handler
transport_index – handler from adios2_add_transport
key – parameter key
value – parameter value

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_variable *adios2_define_variable(adios2_io *io, const char *name, const adios2_type type, const size_t ndims, const size_t *shape, const size_t *start, const size_t *count, const adios2_constant_dims constant_dims)

Define a variable within io.

Parameters:

io – handler that owns the variable
name – unique variable identifier
type – primitive type from enum adios2_type in adios2_c_types.h
ndims – number of dimensions
shape – global dimension
start – local offset
count – local dimension
constant_dims – adios2_constant_dims_true:: shape, start, count won’t change; adios2_constant_dims_false: shape, start, count will change after definition

Returns:

success: handler, failure: NULL

adios2_variable *adios2_inquire_variable(adios2_io *io, const char *name)

Retrieve a variable handler within current io handler.

Parameters:

io – handler to variable io owner
name – unique variable identifier within io handler

Returns:

found: handler, not found: NULL

adios2_error adios2_inquire_all_variables(adios2_variable ***variables, size_t *size, adios2_io *io)

Returns an array of variable handlers for all variable present in the io group

Parameters:

variables – output array of variable pointers (pointer to an adios2_variable**)
size – output number of variables
io – handler to variables io owner

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_inquire_group_variables(adios2_variable ***variables, const char *full_group_name, size_t *size, adios2_io *io)

adios2_attribute *adios2_define_attribute(adios2_io *io, const char *name, const adios2_type type, const void *value)

Define an attribute value inside io.

Parameters:

io – handler that owns the attribute
name – unique attribute name inside IO handler
type – primitive type from enum adios2_type in adios2_c_types.h
value – attribute single value

Returns:

success: handler, failure: NULL

adios2_attribute *adios2_define_attribute_array(adios2_io *io, const char *name, const adios2_type type, const void *data, const size_t size)

Define an attribute array inside io.

Parameters:

io – handler that owns the attribute
name – unique attribute name inside IO handler
type – primitive type from enum adios2_type in adios2_c_types.h
data – attribute data array
size – number of elements of data array

Returns:

success: handler, failure: NULL

adios2_attribute *adios2_define_variable_attribute(adios2_io *io, const char *name, const adios2_type type, const void *value, const char *variable_name, const char *separator)

Define an attribute single value associated to an existing variable by its name

Parameters:

io – handler that owns the variable and attribute
name – unique attribute name inside a variable in io handler
type – primitive type from enum adios2_type in adios2_c_types.h
value – attribute single value
variable_name – unique variable identifier in io handler. If variable doesn’t exist adios2_error is adios2_error_invalid_argument.
separator – hierarchy separator (e.g. “/” in variable_name/name )

Returns:

success: handler, failure: NULL

adios2_attribute *adios2_define_variable_attribute_array(adios2_io *io, const char *name, const adios2_type type, const void *data, const size_t size, const char *variable_name, const char *separator)

Define an attribute array associated to an existing variable by its name

Parameters:

io – handler that owns the variable and attribute
name – unique attribute name inside a variable in io handler
type – primitive type from enum adios2_type in adios2_c_types.h
data – attribute data single value or array
size – number of elements of data array
variable_name – unique variable identifier in io handler. If variable doesn’t exist adios2_error is true.
separator – hierarchy separator (e.g. “/” in variable/attribute )

Returns:

success: handler, failure: NULL

adios2_attribute *adios2_inquire_attribute(adios2_io *io, const char *name)

Returns a handler to a previously defined attribute by name

Parameters:

io – handler to attribute io owner
name – unique attribute identifier within io handler

Returns:

found: handler, not found: NULL

adios2_attribute *adios2_inquire_variable_attribute(adios2_io *io, const char *name, const char *variable_name, const char *separator)

Retrieve a handler to a previously defined attribute associated to a variable

Parameters:

io – handler to attribute and variable io owner
name – unique attribute name inside a variable in io handler
variable_name – name of the variable associate with this attribute
separator – hierarchy separator (e.g. “/” in variable/attribute )

Returns:

found: handler, not found: NULL

adios2_error adios2_inquire_all_attributes(adios2_attribute ***attributes, size_t *size, adios2_io *io)

Returns an array of attribute handlers for all attribute present in the io group

Parameters:

attributes – output array of attribute pointers (pointer to an adios2_attribute**)
size – output number of attributes
io – handler to attributes io owner

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_inquire_group_attributes(adios2_attribute ***attributes, const char *full_prefix, size_t *size, adios2_io *io)

adios2_error adios2_inquire_subgroups(char ***subGroupNames, const char *full_prefix, size_t *size, adios2_io *io): Return a list of list sub group names

adios2_error adios2_remove_variable(adios2_bool *result, adios2_io *io, const char *name)

DANGEROUS! Removes a variable identified by name. Might create dangling pointers.

Parameters:

result – output adios2_true(1): found and removed variable, adios2_false(0): not found, nothing to remove
io – handler variable io owner
name – unique variable name within io handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_remove_all_variables(adios2_io *io)

DANGEROUS! Removes all existing variables in current IO object. Might create dangling pointers.

Parameters:: io – handler variables io owner
Returns:: adios2_error 0: success, see enum adios2_error for errors

char **adios2_available_variables(adios2_io *io, size_t *size)

returns an array or c strings for names of available variables Might create dangling pointers

Parameters:

io – handler variables io owner
length – of array of strings

Returns:

names of variables as an array of strings

char **adios2_available_attributes(adios2_io *io, size_t *size)

returns an array or c strings for names of available attributes Might create dangling pointers

Parameters:

io – handler variables io owner
length – of array of strings

Returns:

names of variables as an array of strings

adios2_error adios2_remove_attribute(adios2_bool *result, adios2_io *io, const char *name)

DANGEROUS! Removes an attribute identified by name. Might create dangling pointers.

Parameters:

result – output adios2_true(1): found and removed attribute, adios2_false(0): not found, nothing to remove
io – handler attribute io owner
name – unique attribute name within io handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_remove_all_attributes(adios2_io *io)

DANGEROUS! Removes all existing attributes in current IO object. Might create dangling pointers.

Parameters:: io – handler attributes io owner
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_engine *adios2_open(adios2_io *io, const char *name, const adios2_mode mode)

Open an Engine to start heavy-weight input/output operations. In MPI version reuses the communicator from adios2_init or adios2_init_config MPI Collective function as it calls MPI_Comm_dup

Parameters:

io – engine owner
name – unique engine identifier
mode – adios2_mode_write, adios2_mode_read, adios2_mode_append, and adios2_mode_readRandomAccess

Returns:

success: handler, failure: NULL

adios2_engine *adios2_open_new_comm(adios2_io *io, const char *name, const adios2_mode mode, MPI_Comm comm)

Open an Engine to start heavy-weight input/output operations. MPI Collective function as it calls MPI_Comm_dup

Parameters:

io – engine owner
name – unique engine identifier
mode – adios2_mode_write, adios2_mode_read, adios2_mode_append, and adios2_mode_readRandomAccess
comm – communicator other than adios’ handler comm. MPI only.

Returns:

success: handler, failure: NULL

adios2_error adios2_flush_all_engines(adios2_io *io)

Flushes all engines created with current io handler using adios2_open

Parameters:: io – handler whose engine will be flushed
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_engine_type(char *engine_type, size_t *size, const adios2_io *io)

return engine type string and length without null character For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

engine_type – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, engine_type size without ‘\0’
io – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_engine *adios2_get_engine(adios2_io *io, const char *name)

`adios2_variable` handler functions

Functions

adios2_error adios2_set_shape(adios2_variable *variable, const size_t ndims, const size_t *shape)

Set new shape, care must be taken when reading back the variable for different steps. Only applies to Global arrays.

Parameters:

variable – handler for which new selection will be applied to
ndims – number of dimensions for start and count
shape – new shape dimensions array

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_memory_space(adios2_variable *variable, const adios2_memory_space mem)

Sets the memory space for all following Puts/Gets to either host (default) or device

Parameters:: mem – memory space where Put/Get buffers are allocated
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_get_memory_space(adios2_memory_space *mem, adios2_variable *variable)

Get the memory space that was set by the application for a given variable

Parameters:

memory – space output, the variable memory space
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_block_selection(adios2_variable *variable, const size_t block_id)

Read mode only. Required for reading local variables. For Global Arrays it will Set the appropriate Start and Count Selection for the global array coordinates.

Parameters:

variable – handler for which new selection will be applied to
block_id – variable block index defined at write time. Blocks can be inspected with bpls -D variableName

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_selection(adios2_variable *variable, const size_t ndims, const size_t *start, const size_t *count)

Set new start and count dimensions

Parameters:

variable – handler for which new selection will be applied to
ndims – number of dimensions for start and count
start – new start dimensions array
count – new count dimensions array

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_memory_selection(adios2_variable *variable, const size_t ndims, const size_t *memory_start, const size_t *memory_count)

Set the local start (offset) point to the memory pointer passed at Put and the memory local dimensions (count). Used for non-contiguous memory writes and reads (e.g. multidimensional ghost-cells). Currently not working for calls to Get.

Parameters:

variable – handler for which new memory selection will be applied to
ndims – number of dimensions for memory_start and memory_count
memory_start – relative local offset of variable.start to the contiguous memory pointer passed at Put from which data starts. e.g. if variable start = {rank*Ny,0} and there is 1 ghost cell per dimension, then memory_start = {1,1}
memory_count – local dimensions for the contiguous memory pointer passed at adios2_put, e.g. if there is 1 ghost cell per dimension and variable count = {Ny,Nx}, then memory_count = {Ny+2,Nx+2}

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_step_selection(adios2_variable *variable, const size_t step_start, const size_t step_count)

Set new step selection using step_start and step_count. Used mostly for reading from file-based engines (e.g. bpfile, hdf5)

Parameters:

variable – handler for which new selection will be applied to
step_start – starting step for reading
step_count – number of steps to read from step start

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_name(char *name, size_t *size, const adios2_variable *variable)

Retrieve variable name For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

name – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, name size without ‘\0’
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_type(adios2_type *type, const adios2_variable *variable)

Retrieve variable type

Parameters:

type – output, from enum adios2_type
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_type_string(char *type, size_t *size, const adios2_variable *variable)

Retrieve variable type in string form “char”, “unsigned long”, etc. For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

type – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, type size without ‘\0’
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_shapeid(adios2_shapeid *shapeid, const adios2_variable *variable)

Retrieve variable shapeid

Parameters:

shapeid – output, from enum adios2_shapeid
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_ndims(size_t *ndims, const adios2_variable *variable)

Retrieve current variable number of dimensions

Parameters:

ndims – output
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_shape(size_t *shape, const adios2_variable *variable)

Retrieve current variable shape

Parameters:

shape – output, must be pre-allocated with ndims
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_shape_with_memory_space(size_t *shape, const adios2_variable *variable, const adios2_memory_space mem)

Retrieve current variable shape for a given memory space

Parameters:

shape – output, must be pre-allocated with ndims
variable – handler
memory – space

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_start(size_t *start, const adios2_variable *variable)

Retrieve current variable start

Parameters:

start – output, single value
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_count(size_t *count, const adios2_variable *variable)

Retrieve current variable start

Parameters:

count – output, must be pre-allocated with ndims
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_steps_start(size_t *steps_start, const adios2_variable *variable)

Read API, get available steps start from available steps count (e.g. in a file for a variable).

Parameters:

steps_start – output absolute first available step, don’t use with adios2_set_step_selection as inputs are relative, use 0 instead.
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_steps(size_t *steps, const adios2_variable *variable)

Read API, get available steps count from available steps count (e.g. in a file for a variable). Not necessarily contiguous.

Parameters:

steps – output available steps, single value
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_selection_size(size_t *size, const adios2_variable *variable)

Returns the minimum required allocation (in number of elements of a certain type, not bytes) for the current selection

Parameters:

size – number of elements of current type to be allocated by a pointer/vector to read current selection
variable – handler for which data size will be inspected from

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_add_operation(size_t *operation_index, adios2_variable *variable, adios2_operator *op, const char *key, const char *value)

Adds an operation to a variable (e.g. compression)

Parameters:

operation_index – output handler to be used with adios2_add_operation_param
variable – handler on which operation is applied to
op – handler to adios2_operator associated to current operation
key – parameter key supported by the operation, empty if none
value – parameter value supported by the operation, empty if none

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_set_operation_parameter(adios2_variable *variable, const size_t operation_id, const char *key, const char *value)

Adds a parameter to an operation created with adios2_add_operation

Parameters:

variable – handler on which operation is applied to
operation_id – handler returned from adios2_add_operation
key – parameter key supported by the operation
value – parameter value supported by the operation

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_remove_operations(adios2_variable *variable)

Removes all current Operations associated with AddOperation. Provides the posibility to apply or not operators on a block basis.

Parameters:: variable – handler on which operation is applied to
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_min(void *min, const adios2_variable *variable)

Read mode only: return the absolute minimum for current variable

Parameters:

min – output: variable minimum, must be of the same type as the variable handler
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_variable_max(void *max, const adios2_variable *variable)

Read mode only: return the absolute maximum for current variable

Parameters:

max – output: variable minimum, must be of the same type as the variable handler
variable – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

`adios2_attribute` handler functions

Functions

adios2_error adios2_attribute_name(char *name, size_t *size, const adios2_attribute *attribute)

Retrieve attribute name For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

name – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, name size without ‘\0’
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_attribute_type(adios2_type *type, const adios2_attribute *attribute)

Retrieve attribute type

Parameters:

type –
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_attribute_type_string(char *type, size_t *size, const adios2_attribute *attribute)

Retrieve attribute type in string form “char”, “unsigned long”, etc. For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

type – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, type size without ‘\0’
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_attribute_is_value(adios2_bool *result, const adios2_attribute *attribute)

Checks if attribute is a single value or an array

Parameters:

result – output, adios2_true: single value, adios2_false: array
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_attribute_size(size_t *size, const adios2_attribute *attribute)

Returns the number of elements (as in C++ STL size() function) if attribute is a 1D array. If single value returns 1

Parameters:

size – output, number of elements in attribute
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_attribute_data(void *data, size_t *size, const adios2_attribute *attribute)

Retrieve attribute data pointer (read-only)

Parameters:

data – output attribute values, must be pre-allocated
size – data size
attribute – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

`adios2_engine` handler functions

Functions

adios2_error adios2_engine_name(char *name, size_t *size, const adios2_engine *engine)

Return engine name string and length without ‘\0\ character For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

name – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, engine_type size without ‘\0’
engine – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_engine_get_type(char *type, size_t *size, const adios2_engine *engine)

Return engine type string and length without ‘\0\ character For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

type – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, engine_type size without ‘\0’
engine – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_engine_openmode(adios2_mode *mode, const adios2_engine *engine)

Return the engine’s Open mode.

Parameters:

mode – output, adios2_mode parameter used in adios2_open()
engine – handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_begin_step(adios2_engine *engine, const adios2_step_mode mode, const float timeout_seconds, adios2_step_status *status)

Begin a logical adios2 step stream Check each engine documentation for MPI collective/non-collective behavior.

Parameters:

engine – handler
mode – see enum adios2_step_mode in adios2_c_types.h for options, read is the common use case
timeout_seconds – provide a time out in Engine opened in read mode
status – output from enum adios2_step_status in adios2_c_types.h

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_current_step(size_t *current_step, const adios2_engine *engine)

Inspect current logical step

Parameters:

current_step – output
engine – input handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_between_step_pairs(size_t *between_step_pairs, const adios2_engine *engine)

Inspect current between step status

Parameters:

between_step_pairs – output boolean
engine – input handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_steps(size_t *steps, const adios2_engine *engine)

Inspect total number of available steps, use for file engines in read mode only

Parameters:

steps – output available steps in engine
engine – input handler

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_put(adios2_engine *engine, adios2_variable *variable, const void *data, const adios2_mode launch)

Put data associated with a Variable in an engine, used for engines with adios2_mode_write at adios2_open

Parameters:

engine – handler for a particular engine where data will be put
variable – contains variable metadata information
data – user data to be associated with a variable, must be the same type passed to adios2_define_variable
launch – mode launch policy

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_put_by_name(adios2_engine *engine, const char *variable_name, const void *data, const adios2_mode launch)

Put data associated with a Variable in an engine, used for engines with adios2_mode_write at adios2_open. This is the name string version

Parameters:

engine – handler for a particular engine where data will be put
variable_name – variable with this name must exists in adios2_io that opened the engine handler (1st parameter)
data – user data to be associated with a variable, must be the same type passed to adios2_define_variable
launch – mode launch policy

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_perform_puts(adios2_engine *engine)

Performs all the adios2_put and adios2_put_by_name called with mode adios2_mode_deferred, up to this point, by copying user data into internal ADIOS buffers. User data can be reused after this point.

Parameters:: engine – handler for a particular engine where data will be put
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_perform_data_write(adios2_engine *engine)

Write array data to disk. This may relieve memory pressure by clearing ADIOS buffers. It is a collective call. User data can be reused after this point.

Parameters:: engine – handler for a particular engine where data will be put
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_get(adios2_engine *engine, adios2_variable *variable, void *data, const adios2_mode launch)

Gets data associated with a Variable from an engine, used for engines with adios2_mode_read at adios2_open. This is the name string version

Parameters:

engine – handler for a particular engine where data will be put
variable – handler must exists in adios2_io that opened the engine handler (1st parameter). Typically from adios2_inquire_variable
data – user data to be associated with a variable, must be the same type passed to adios2_define_variable. Must be pre-allocated for the required variable selection.
launch – mode launch policy

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_get_by_name(adios2_engine *engine, const char *variable_name, void *data, const adios2_mode launch)

Gets data associated with a Variable from an engine, used for engines with adios2_mode_read at adios2_open. This is the name string version

Parameters:

engine – handler for a particular engine where data will be put
variable_name – variable with this name must exists in adios2_io that opened the engine handler (1st parameter).
data – user data to be associated with a variable, must be the same type passed to adios2_define_variable. Must be pre-allocated for the required variable selection.
launch – mode launch policy

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_perform_gets(adios2_engine *engine)

Performs all the adios2_get and adios2_get_by_name called with mode adios2_mode_deferred up to this point by getting the data from the Engine. User data can be reused after this point.

Parameters:: engine – handler for a particular engine where data will be obtained
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_end_step(adios2_engine *engine)

Terminates interaction with current step. By default puts/gets data to/from all transports Check each engine documentation for MPI collective/non-collective behavior.

Parameters:: engine – handler executing IO tasks
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_flush(adios2_engine *engine)

Explicit engine buffer flush to transports

Parameters:: engine – input
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_flush_by_index(adios2_engine *engine, const int transport_index)

Explicit engine buffer flush to transport index

Parameters:

engine – input
transport_index – index to be flushed

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_close(adios2_engine *engine)

Close all transports in adios2_Engine. Call is required to close system resources. MPI Collective, calls MPI_Comm_free for duplicated communicator at Open

Parameters:: engine – handler containing all transports to be closed. NOTE: engines NEVER become NULL after this function is called.
Returns:: adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_close_by_index(adios2_engine *engine, const int transport_index)

Close a particular transport from the index returned by adios2_add_transport

Parameters:

engine – handler containing all transports to be closed. NOTE: engines NEVER become NULL due to this function.
transport_index – handler from adios2_add_transport

Returns:

adios2_error 0: success, see enum adios2_error for errors

adios2_error adios2_lock_writer_definitions(adios2_engine *engine)

Promise that no more definitions or changes to defined variables will occur. Useful information if called before the first adios2_end_step() of an output Engine, as it will know that the definitions are complete and constant for the entire lifetime of the output and may optimize metadata handling.

Parameters:: engine – handler

adios2_error adios2_lock_reader_selections(adios2_engine *engine)

Promise that the reader data selections of are fixed and will not change in future timesteps. This information, provided before the EndStep() representing a fixed read pattern, may be utilized by the input Engine to optimize data flow.

Parameters:: engine – handler

adios2_varinfo *adios2_inquire_blockinfo(adios2_engine *engine, adios2_variable *variable, const size_t step)

Get the list of blocks for a variable in a given step. In Streaming mode, step is unused, always the current step is processed.

Returns:: Newly allocated adios2_varinfo structure, NULL pointer if step does not exist. The memory must be freed by the adios2_free_blockinfo function

void adios2_free_blockinfo(adios2_varinfo *data_blocks)

free adios2_varinfo structure

Parameters:: data_blocks –
Returns:: void

`adios2_operator` handler functions

Functions

adios2_error adios2_operator_type(char *type, size_t *size, const adios2_operator *op)

Retrieve operator type For safe use, call this function first with NULL name parameter to get the size, then preallocate the buffer (with room for ‘\0’ if desired), then call the function again with the buffer. Then ‘\0’ terminate it if desired.

Parameters:

type – output, string without trailing ‘\0’, NULL or preallocated buffer
size – output, type size without ‘\0’
op – operator handler to be inspected

Returns:

adios2_error 0: success, see enum adios2_error for errors

Full APIs

C++11 bindings

ADIOS2 components classes

ADIOS class

IO class

Variable <T> class

Attribute <T> class

Engine class

Operator class

Fortran bindings

ADIOS2 typed handlers

ADIOS subroutines

IO subroutines

Variable subroutines

Engine subroutines

Operator subroutines

Attribute subroutines

C bindings

adios2_adios handler functions

adios2_io handler functions

adios2_variable handler functions

adios2_attribute handler functions

adios2_engine handler functions

adios2_operator handler functions

Variable `<T>` class

Attribute `<T>` class

`adios2_adios` handler functions

`adios2_io` handler functions

`adios2_variable` handler functions

`adios2_attribute` handler functions

`adios2_engine` handler functions

`adios2_operator` handler functions