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

Public Functions

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

nameIO 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

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

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

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

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 to either host (default) or device (currently only CUDA supported)

Parameters

mem – memory space where Put buffers are allocated

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

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 read mode, inspect the number of available steps

Returns

available steps

size_t StepsStart() const

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

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

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

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

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.

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

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

Public Functions

void BuildTree()

Builds map that represents tree structure from m_Variable and m_Attributes from IO class.

Param

void PrintTree()

Prints map that represents tree structure.

Param

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

std::map<std::string, std::set<std::string>> &getTreeMap()

returns a reference to the map representing the tree stucture

Parameters

delimiter – symbol

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
    ! 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:
    
    ! 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_variable(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_steps_selection set a list of steps by specifying the starting step and the step count

    subroutine adios2_set_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(debug)
adios2_init_config(config_file, debug)

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.

Returns

success: handler, failure: NULL

ADIOS2_DEPRECATED adios2_adios * adios2_init_serial_debug (adios2_debug_mode)
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_DEPRECATED adios2_adios * adios2_init_config_serial_debug (const char *config_file, adios2_debug_mode)
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_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_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_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

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.

ADIOS class

class adios2.ADIOS
AtIO(self: adios2.ADIOS, arg0: str) adios2::py11::IO

returns an IO object previously defined IO object with DeclareIO, throws an exception if not found

DeclareIO(self: adios2.ADIOS, arg0: str) adios2::py11::IO

spawn IO object component returning a IO object with a unique name, throws an exception if IO with the same name is declared twice

DefineOperator(self: adios2.ADIOS, arg0: str, arg1: str, arg2: Dict[str, str]) adios2::py11::Operator
FlushAll(self: adios2.ADIOS) None

flushes all engines in all spawned IO objects

InquireOperator(self: adios2.ADIOS, arg0: str) adios2::py11::Operator
RemoveAllIOs(self: adios2.ADIOS) None

DANGER ZONE: remove all IOs in current ADIOS object, creates dangling objects to parameters, variable, attributes, engines created with removed IO

RemoveIO(self: adios2.ADIOS, arg0: str) bool

DANGER ZONE: remove a particular IO by name, creates dangling objects to parameters, variable, attributes, engines created with removed IO

IO class

class adios2.IO
AddTransport(self: adios2.IO, type: str, parameters: Dict[str, str] = {}) int
AvailableAttributes(self: adios2.IO) Dict[str, Dict[str, str]]
AvailableVariables(self: adios2.IO) Dict[str, Dict[str, str]]
DefineAttribute(*args, **kwargs)

Overloaded function.

  1. DefineAttribute(self: adios2.IO, name: str, array: array, variable_name: str=’’, separator: str=’/’) -> adios2::py11::Attribute

  2. DefineAttribute(self: adios2.IO, name: str, stringValue: str, variable_name: str=’’, separator: str=’/’) -> adios2::py11::Attribute

  3. DefineAttribute(self: adios2.IO, name: str, strings: List[str], variable_name: str=’’, separator: str=’/’) -> adios2::py11::Attribute

DefineVariable(*args, **kwargs)

Overloaded function.

  1. DefineVariable(self: adios2.IO, name: str, array: array, shape: List[int]=[], start: List[int]=[], count: List[int]=[], isConstantDims: bool=False) -> adios2::py11::Variable

  2. DefineVariable(self: adios2.IO, name: str) -> adios2::py11::Variable

EngineType(self: adios2.IO) str
FlushAll(self: adios2.IO) None
InquireAttribute(self: adios2.IO, arg0: str) adios2::py11::Attribute
InquireVariable(self: adios2.IO, arg0: str) adios2::py11::Variable
Open(*args, **kwargs)

Overloaded function.

  1. Open(self: adios2.IO, arg0: str, arg1: int) -> adios2::py11::Engine

  2. Open(self: adios2.IO, arg0: str, arg1: int, arg2: MPI4PY_Comm) -> adios2::py11::Engine

Parameters(self: adios2.IO) Dict[str, str]
RemoveAllAttributes(self: adios2.IO) None
RemoveAllVariables(self: adios2.IO) None
RemoveAttribute(self: adios2.IO, arg0: str) bool
RemoveVariable(self: adios2.IO, arg0: str) bool
SetEngine(self: adios2.IO, arg0: str) None
SetParameter(self: adios2.IO, arg0: str, arg1: str) None
SetParameters(self: adios2.IO, parameters: Dict[str, str] = {}) None

Variable class

class adios2.Variable
AddOperation(self: adios2.Variable, arg0: adios2::py11::Operator, arg1: Dict[str, str]) int
BlockID(self: adios2.Variable) int
Count(self: adios2.Variable) List[int]
Name(self: adios2.Variable) str
Operations(self: adios2.Variable) List[adios2::py11::Variable::Operation]
SelectionSize(self: adios2.Variable) int
SetBlockSelection(self: adios2.Variable, arg0: int) None
SetSelection(self: adios2.Variable, arg0: Tuple[List[int], List[int]]) None
SetShape(self: adios2.Variable, arg0: List[int]) None
SetStepSelection(self: adios2.Variable, arg0: Tuple[int, int]) None
Shape(self: adios2.Variable, step: int = 18446744073709551615) List[int]
ShapeID(self: adios2.Variable) adios2.ShapeID
Sizeof(self: adios2.Variable) int
Start(self: adios2.Variable) List[int]
Steps(self: adios2.Variable) int
StepsStart(self: adios2.Variable) int
Type(self: adios2.Variable) str

Attribute class

class adios2.Attribute
Data(self: adios2.Attribute) array
DataString(self: adios2.Attribute) List[str]
Name(self: adios2.Attribute) str
Type(self: adios2.Attribute) str

Engine class

class adios2.Engine
BeginStep(*args, **kwargs)

Overloaded function.

  1. BeginStep(self: adios2.Engine, mode: adios2.StepMode, timeoutSeconds: float=-1.0) -> adios2.StepStatus

  2. BeginStep(self: adios2.Engine) -> adios2.StepStatus

Close(self: adios2.Engine, transportIndex: int = - 1) None
CurrentStep(self: adios2.Engine) int
EndStep(self: adios2.Engine) None
Flush(self: adios2.Engine, arg0: int) None
Get(*args, **kwargs)

Overloaded function.

  1. Get(self: adios2.Engine, variable: adios2.Variable, array: array, launch: adios2.Mode=Mode.Deferred) -> None

  2. Get(self: adios2.Engine, variable: adios2.Variable, string: str, launch: adios2.Mode=Mode.Deferred) -> None

LockReaderSelections(self: adios2.Engine) None
LockWriterDefinitions(self: adios2.Engine) None
Name(self: adios2.Engine) str
PerformGets(self: adios2.Engine) None
PerformPuts(self: adios2.Engine) None
Put(*args, **kwargs)

Overloaded function.

  1. Put(self: adios2.Engine, variable: adios2.Variable, array: array, launch: adios2.Mode=Mode.Deferred) -> None

  2. Put(self: adios2.Engine, arg0: adios2.Variable, arg1: str) -> None

Steps(self: adios2.Engine) int
Type(self: adios2.Engine) str

Operator class

class adios2.Operator
Parameters(self: adios2.Operator) Dict[str, str]
SetParameter(self: adios2.Operator, arg0: str, arg1: str) None
Type(self: adios2.Operator) str