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 :ref: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 adios2::ADIOS

Public Functions

ADIOS(const std::string &configFile, const bool debugMode = true)

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

Parameters
  • configFile: runtime config file

  • debugMode: is deprecated and has no effect on library behavior

Exceptions
  • std::invalid_argument: if user input is incorrect

ADIOS(const bool debugMode = true)

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

Parameters
  • debugMode: is deprecated and has no effect on library behavior

Exceptions
  • std::invalid_argument: if user input is incorrect

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)

Declares a new IO class object

Return

reference to newly created IO object inside current ADIOS object

Parameters
  • name: unique IO name identifier within current ADIOS object

Exceptions
  • std::invalid_argument: if IO with unique name is already declared

IO AtIO(const std::string name)

Retrieve an existing IO object previously created with DeclareIO.

Return

if IO exists returns a reference to existing IO object inside ADIOS, else throws an exception. IO objects can’t be invalid.

Parameters
  • name: IO unique identifier key in current ADIOS object

Exceptions
  • std::invalid_argument: if IO was not created with DeclareIO

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

Defines an adios2 supported operator by its type.

Return

Operator object

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

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

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.

Return

Operator object

Parameters
  • name: unique operator name within ADIOS object

  • function: C++11 callable target

  • parameters: key/value parameters at the operator level

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

Operator InquireOperator(const std::string name)

Retrieve an existing Operator object in current ADIOS object

Return

object to an existing operator in current ADIOS object, Operator object is false if name is not found

Parameters

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.

Exceptions
  • 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

Return

true: IO was found and removed, false: IO not found and not removed

Parameters
  • name: io input name

void RemoveAllIOs() noexcept

DANGER ZONE: removes all IOs created with DeclareIO. This will effectively eliminate any parameter from the config.xml file also.

IO class

class adios2::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

operator bool() const noexcept

true: valid object, false: invalid object

std::string Name() const

Inspects IO name

Return

name

bool InConfigFile() const

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

Return

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

Return

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().

Return

transportIndex handler

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

Exceptions
  • std::invalid_argument: if type=transport

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

Exceptions
  • 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

Return

Variable<T> object

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

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

Retrieve a Variable object within current IO object

Return

if found Variable object is true and has functionality, else false and has no functionality

Parameters
  • name: unique variable identifier within IO object

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 = "/")

Define attribute inside io. Array input version.

Return

object reference to internal Attribute in IO

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.

Exceptions

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

Define single value attribute.

Return

object reference to internal Attribute in IO

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.

Exceptions

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

Retrieve an existing attribute.

Return

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

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.

bool RemoveVariable(const std::string &name)

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

Return

true: found and removed variable, false: not found, nothing to remove

Parameters

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.

Return

true: found and removed attribute, false: not found, nothing to remove

Parameters

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.

Return

engine object

Parameters
  • name: unique engine identifier

  • mode: adios2::Mode::Write, adios2::Mode::Read, or adios2::Mode::Append (not yet support)

void FlushAll()

Flushes all engines created with this IO with the Open function

std::map<std::string, Params> AvailableVariables()

Returns a map with variable information

Return

map:

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

Return

map:

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

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

Return

type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if variable not found

Parameters
  • name: unique variable name identifier in current IO

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

Return

type as in adios2::GetType<T>() (e.g. “double”, “float”), empty std::string if attribute not found

Parameters
  • name: unique attribute name identifier in current IO

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

EXPERIMENTAL: Adds operation and parameters to current IO object

Return

operation index handler in Operations()

Parameters
  • op: operator to be added

  • 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

Return

current engine type

struct Operation

EXPERIMENTAL: carries information about an Operation added with AddOperation

Public Members

const Operator Op

Operator associated with this operation

const adios2::Params Parameters

Parameters settings for this operation

const adios2::Params Info

Information associated with this operation

Variable <T> class

template<class T>
class adios2::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

operator bool() const noexcept

Checks if object is valid, e.g. if( variable ) { //..valid }

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}

size_t SelectionSize() const

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

Return

elements of type T required for pre-allocation

std::string Name() const

Inspects Variable name

Return

name

std::string Type() const

Inspects Variable type

Return

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

size_t Sizeof() const

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

Return

sizeof(T) for current system

adios2::ShapeID ShapeID() const

Inspects shape id for current variable

Return

from enum adios2::ShapeID

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

Inspects shape in global variables

Return

shape vector

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

adios2::Dims Start() const

Inspects current start point

Return

start vector

adios2::Dims Count() const

Inspects current count from start

Return

count vector

size_t Steps() const

For read mode, inspect the number of available steps

Return

available steps

size_t StepsStart() const

For read mode, inspect the start step for available steps

Return

available start step

size_t BlockID() const

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

Return

current block id

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

Adds operation and parameters to current Variable object

Return

operation index handler in Operations()

Parameters
  • op: operator to be added

  • parameters: key/value settings particular to the Variable, not to be confused by op own parameters

std::vector<Operation> Operations() const

Inspects current operators added with AddOperator

Return

vector of Variable<T>::OperatorInfo

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

Return

pair.first = min pair.second = max

Parameters
  • step: input step

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

Return

variable minimum

Parameters
  • step: input step

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

Return

variable minimum

Parameters
  • step: input step

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

Return

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

struct Operation

EXPERIMENTAL: carries information about an Operation added with AddOperation

Public Members

const adios2::Operator Op

Operator associated with this operation

const adios2::Params Parameters

Parameters settings for this operation

adios2::Params Info

Information associated with this operation

Attribute <T> class

template<class T>
class adios2::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.

operator bool() const noexcept

Checks if object is valid, e.g. if( attribute ) { //..valid }

std::string Name() const

Inspect attribute name

Return

unique name identifier

std::string Type() const

Inspect attribute type

Return

type

std::vector<T> Data() const

Inspect attribute data

Return

data

Engine class

class adios2::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

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

Return

name from IO::Open

std::string Type() const

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

Return

engine type as lower case string

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.

Return

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.

Return

current step status

Parameters
  • mode: see enum adios2::StepMode for options, Read is the common use case

  • timeoutSeconds:

size_t CurrentStep() const

Inspect current logical step

Return

current logical step

template<class T>
Variable<T>::Span Put(Variable<T> variable, const size_t bufferID, 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. Requires a call to PerformPuts, EndStep, or Close to extract the Min/Max bounds.

Return

span to variable data in engine internal buffer

Parameters
  • variable: input variable

  • bufferID: if engine has multiple buffers, input 0 when this information is not known

  • value: provide an initial fill value

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 with the default fill value T().

Return

span to variable data in engine internal buffer

Parameters
  • variable: input variable

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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • std::invalid_argument: if variable is invalid or nullptr &datum

void PerformPuts()

Perform all Put calls in Deferred mode up to this point

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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

Exceptions
  • 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

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

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.

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.

Return

map with all variable blocks information

Parameters
  • variable:

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.

Return

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

Parameters
  • variable: input variable

  • step: input from which block information is extracted

size_t Steps() const

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

Return

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 adios2::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.

operator bool() const noexcept

true: valid object, false: invalid object

std::string Type() const noexcept

Inspect current Operator type

Return

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

Return

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 ``ostream``s.

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

Fortran bindings

The Fortran bindings API consist entirely on subroutines calls. Always, the 1st argument is a Fortran type (struct) to an ADIOS2 component, while the last argument is an error integer flag, integer ierr. ierr==0 means normal execution while any other 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 before digging into the description of each subroutine. This test will compile under your build/bin/ directory.

The following subsections describe the overall component representation and the main subroutines versions in the Fortran bindings API.

ADIOS2 typed handlers

ADIOS2 Fortran bindings handlers are mapped 1-to-1 to the ADIOS 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
    ! Debug mode = ON (.true.) by default
    subroutine adios2_init(adios, comm, ierr)
    subroutine adios2_init(adios, config_file, comm, ierr)
    
    subroutine adios2_init(adios, comm, adios2_debug_mode, ierr)
    subroutine adios2_init(adios, config_file, comm, adios2_debug_mode, ierr)
    
    ! Non-MPI serial versions
    ! Debug mode = ON (.true.) by default
    subroutine adios2_init(adios, ierr)
    subroutine adios2_init(adios, config_file, ierr)
    
    subroutine adios2_init(adios, adios2_debug_mode, ierr)
    subroutine adios2_init(adios, config_file, adios2_debug_mode, ierr)
    
    ! WHERE:
    
    ! adios 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
    
    ! .true. (adios2_debug_mode_on): enable extra user input checks-> recommended
    ! .false. (adios2_debug_mode_of): disable extra user input checks
    logical, intent(in):: adios2_debug_mode
    
  • subroutine adios2_declare_io spawn io components

    subroutine adios2_declare_io(io, adios, io_name, ierr)
    
    ! WHERE:
    
    ! io component that defines an IO tasks inside adios component
    type(adios2_io), intent(out):: io
    
    ! adios component from adios2_init spawning io tasks
    type(adios2_adios), intent(in):: adios
    
    ! unique name associated with this io component inside adios
    character*(*), intent(in):: io_name
    
  • subroutine adios2_at_io retrieve an existing io component, useful when the original handler for adios2_declare_io goes out of scope

    subroutine adios2_at_io(io, adios, io_name, ierr)
    
    ! WHERE:
    
    ! io component that defines an IO tasks inside adios component
    type(adios2_io), intent(out):: io
    
    ! adios 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
    
  • subroutine adios2_flush_all flush all current engines in all ios

    subroutine adios2_flush_all(adios, ierr)
    
    ! WHERE:
    
    ! adios component from adios2_init owning ios and engines
    type(adios2_adios), intent(in):: adios
    
  • subroutine adios2_finalize final point for the adios component

    subroutine adios2_finalize(adios, ierr)
    
    ! WHERE:
    
    ! adios handler to be deallocated
    type(adios2_adios), intent(in):: adios
    

Caution

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

IO subroutines

  • subroutine adios2_define_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
    
    ! .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_define_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
    
  • subroutine adios2_set_engine set engine type in code, see Supported Engines for a list of available engines

    subroutine adios2_set_engine(io, engine_type, ierr)
    
    ! WHERE:
    
    ! io component owning the attribute
    type(adios2_io), intent(in):: io
    
    ! engine_type: BPFile (default), HDF5, DataMan, SST, InSituMPI
    character*(*), intent(in):: engine_type
    
  • subroutine adios2_set_parameter set IO key/value pair parameter in code, 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
    
  • subroutine adios2_inquire_variable inquire for existing variable by its unique name

    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
    
  • 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
    

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_remove_variable remove existing variable by its unique name

    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
    
  • 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
    
  • subroutine adios2_remove_all_variables remove all existing variables

    subroutine adios2_remove_variable(io, ierr)
    
    ! WHERE:
    
    ! io in which search and removal for all variables is performed
    type(adios2_io), intent(in) :: io
    
  • 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
    
  • subroutine adios2_flush_all_engines flushes all existing engines opened by this io

    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
    
  • subroutine adios2_open opens an engine to executes 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
    
    ! open mode parameter:
    !                      adios2_mode_write,
    !                      adios2_mode_append,
    !                      adios2_mode_read,
    integer, intent(in):: adios2_mode
    

Variable subroutines

  • subroutine adios2_set_shape set new shape_dims if dims are variable in adios2_define_variable

    subroutine adios2_set_selection(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
    
  • subroutine adios2_set_selection set new 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
    
  • subroutine adios2_set_steps_selection set new step_start and step_count

    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 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
    

Engine subroutines

  • subroutine adios2_begin_step moves to next step, starts at 0

    ! Full signature
    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
    
  • subroutine adios2_current_step extracts current step

    ! Full signature
    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
    
  • subroutine adios2_steps Inspect total number of available steps,

    use for file engines in read mode only

    ! Full signature
    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
    
  • subroutine adios2_end_step ends current step and default behavior is to execute transport IO (flush or read).

    ! Full signature
    subroutine adios2_end_step(engine, ierr)
    
    ! WHERE:
    ! engine handler
    type(adios2_engine), intent(in) :: engine
    
  • subroutine adios2_put put variable metadata and data into adios2 for IO operations. Default is deferred mode, optional sync mode, see Put: modes and memory contracts. Variable and data types must match.

    ! Full signature
    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
    
  • subroutine adios2_perform_puts executes deferred calls to adios2_put

    ! Full signature
    subroutine adios2_perform_puts(engine, ierr)
    
    ! WHERE:
    
    ! engine handler
    type(adios2_engine), intent(in) :: engine
    
  • subroutine adios2_get get variable data into adios2 for IO operations. Default is deferred mode, optional sync mode, see Get: modes and memory contracts. Variable and data types must match, variable can be obtained from adios2_inquire_variable. Data must be pre-allocated.

    ! Full signature
    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
    
  • subroutine adios2_perform_gets executes deferred calls to adios2_get

    ! Full signature
    subroutine adios2_perform_gets(engine, ierr)
    
    ! WHERE:
    
    ! engine handler
    type(adios2_engine), intent(in) :: engine
    
  • subroutine adios2_close closes engine, can’t reuse unless is opened again

    ! Full signature
    subroutine adios2_close(engine, ierr)
    
    ! WHERE:
    
    ! engine handler
    type(adios2_engine), intent(in) :: engine
    

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, on when adios2_debug_mode_on is passed to adios2_init
     * or adios2_init_config
     */
    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(debug_mode)
adios2_init_config(config_file, debug_mode)

Functions

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.

Return

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.

Return

success: handler, failure: NULL

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

Declares a new io handler

Return

success: handler, failure: NULL

Parameters
  • adios: owner the io handler

  • name: unique io identifier within current adios handler

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

Retrieves a previously declared io handler by name

Return

success: handler, failure: NULL

Parameters
  • adios: owner the io handler

  • name: unique name for the previously declared io handler

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

Defines an adios2 supported operator by its type.

Return

success: handler, failure: NULL

Parameters
  • adios: owner the op handler

  • name: unique operator name identifier within current ADIOS object

  • type: supported ADIOS2 operator type: zfp, sz

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

Retrieves a previously defined operator handler

Return

success: handler, failure: NULL

Parameters
  • adios: owner the op handler

  • name: unique name for the previously defined op handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • adios: owner of all io and engines to be flushed

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • adios: handler to be deallocated, must be initialized with adios2_init or adios2_init_config

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • adios: owner of all ios to be removed

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • result: output adios2_true=1: in config file, adios2_false=0: not in config file

  • io: handler

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

Set the engine type for current io handler.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler

  • engine_type: predefined engine type, default is bpfile

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

Set several parameters at once.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler

  • string: parameters in the format “param1=value1 , param2 = value2”

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

Set a single parameter. Overwrites value if key exists.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler

  • key: parameter key

  • value: parameter value

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

adios2_error adios2_clear_parameters(adios2_io *io)

Clear all parameters.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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”

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler

  • transport_index: handler from adios2_add_transport

  • key: parameter key

  • value: parameter value

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.

Return

success: handler, failure: NULL

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

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

Retrieve a variable handler within current io handler.

Return

found: handler, not found: NULL

Parameters
  • io: handler to variable io owner

  • name: unique variable identifier within io handler

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • variables: output array of variable pointers (pointer to an adios2_variable**)

  • size: output number of variables

  • io: handler to variables io owner

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

Define an attribute value inside io.

Return

success: handler, failure: NULL

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

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.

Return

success: handler, failure: NULL

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

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

Return

success: handler, failure: NULL

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 )

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

Return

success: handler, failure: NULL

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 )

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

Returns a handler to a previously defined attribute by name

Return

found: handler, not found: NULL

Parameters
  • io: handler to attribute io owner

  • name: unique attribute identifier within io handler

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

Return

found: handler, not found: NULL

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 )

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • attributes: output array of attribute pointers (pointer to an adios2_attribute**)

  • size: output number of attributes

  • io: handler to attributes io owner

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

adios2_error adios2_remove_all_variables(adios2_io *io)

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler variables io owner

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

adios2_error adios2_remove_all_attributes(adios2_io *io)

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler attributes io owner

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

Return

success: handler, failure: NULL

Parameters
  • io: engine owner

  • name: unique engine identifier

  • mode: adios2_mode_write, adios2_mode_read, adios2_mode_append (not yet supported)

adios2_error adios2_flush_all_engines(adios2_io *io)

Flushes all engines created with current io handler using adios2_open

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • io: handler whose engine will be flushed

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine_type: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, engine_type size without ‘\0’

  • io: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • variable: handler for which new selection will be applied to

  • ndims: number of dimensions for start and count

  • shape: new shape dimensions array

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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}

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)

Return

adios2_error 0: success, see enum adios2_error for errors

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

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • name: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, name size without ‘\0’

  • variable: handler

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

Retrieve variable type

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type: output, from enum adios2_type

  • variable: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, type size without ‘\0’

  • variable: handler

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

Retrieve variable shapeid

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • shapeid: output, from enum adios2_shapeid

  • variable: handler

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

Retrieve current variable number of dimensions

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • ndims: output

  • variable: handler

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

Retrieve current variable shape

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • shape: output, must be pre-allocated with ndims

  • variable: handler

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

Retrieve current variable start

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • start: output, single value

  • variable: handler

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

Retrieve current variable start

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • count: output, must be pre-allocated with ndims

  • variable: handler

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).

Return

adios2_error 0: success, see enum adios2_error for errors

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

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • steps: output available steps, single value

  • variable: handler

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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)

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Read mode only: return the absolute minimum for current variable

Return

adios2_error 0: success, see enum adios2_error for errors

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

  • variable: handler

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

Read mode only: return the absolute maximum for current variable

Return

adios2_error 0: success, see enum adios2_error for errors

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

  • variable: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • name: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, name size without ‘\0’

  • attribute: handler

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

Retrieve attribute type

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type:

  • attribute: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, type size without ‘\0’

  • attribute: handler

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

Checks if attribute is a single value or an array

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • result: output, adios2_true: single value, adios2_false: array

  • attribute: handler

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • size: output, number of elements in attribute

  • attribute: handler

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

Retrieve attribute data pointer (read-only)

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • data: output attribute values, must be pre-allocated

  • size: data size

  • attribute: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • name: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, engine_type size without ‘\0’

  • engine: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, engine_type size without ‘\0’

  • engine: handler

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.

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Inspect current logical step

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • current_step: output

  • engine: input handler

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • steps: output available steps in engine

  • engine: input handler

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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 putting the data in the Engine. User data can be reused after this point.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: handler for a particular engine where data will be put

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: handler for a particular engine where data will be obtained

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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: handler executing IO tasks

adios2_error adios2_flush(adios2_engine *engine)

Explicit engine buffer flush to transports

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: input

adios2_error adios2_flush_by_index(adios2_engine *engine, const int transport_index)

Explicit engine buffer flush to transport index

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: input

  • transport_index: index to be flushed

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

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • engine: handler containing all transports to be closed. NOTE: engines NEVER become NULL after this function is called.

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

Return

adios2_error 0: success, see enum adios2_error for errors

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

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_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.

Return

adios2_error 0: success, see enum adios2_error for errors

Parameters
  • type: output, string without trailing ‘\0’, NULL or preallocated buffer

  • size: output, type size without ‘\0’

  • op: operator handler to be inspected

Python bindings

Note

Product Application Developers targeting finer-level control for their IO tasks for optimization should use the current full APIs. If you want to use ADIOS2 in simple use cases (e.g. reading a file for analysis, interactive Python, or saving some data for a small project) please refer to the High-Level APIs for a flat learning curve.

The full Python APIs follow very closely the full C++11 API interface. This section is Work In Progress, we recommend Python users start with the High-Level APIs.