ADIOS2.jl

@enum Error begin
    error_none
    error_invalid_argument
    error_system_error
    error_runtime_error
    error_exception
end

Error return types for all ADIOS2 functions

Based on the library C++ standardized exceptions. Each error will issue a more detailed description in the standard error output, stderr

const AdiosType = Union{AbstractString,
                        Float32,Float64,
                        Complex{Float32},Complex{Float64},
                        Int8,Int16,Int32,Int64,
                        UInt8,UInt16,UInt32,UInt64}

A Union of all scalar types supported in ADIOS files.

@enum Mode begin
    mode_undefined
    mode_write
    mode_read
    mode_append
    mode_readRandomAccess

    mode_deferred
    mode_sync
end

Mode specifies for various functions. write, read, append, and readRandomAccess are used for file operations. deferred and sync are used for get and put operations.

@enum StepMode begin
    step_mode_append
    step_mode_update
    step_mode_read
end

@enum StepStatus begin
    step_status_other_error
    step_status_ok
    step_status_not_ready
    step_status_end_of_stream
end

@enum ShapeId begin
    shapeid_unknown
    shapeid_global_value
    shapeid_global_array
    shapeid_joined_array
    shapeid_local_value
    shapeid_local_array
end

mutable struct Adios

Holds a C pointer adios2_adios *.

This value is finalized automatically. It can also be explicitly finalized by calling finalize(adios).

adios = adios_init_mpi(comm::MPI.Comm)
adios = adios_init_mpi(config_file::AbstractString, comm::MPI.Comm)
adios::Union{Adios,Nothing}

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

adios = adios_init_serial()
adios = adios_init_serial(config_file::AbstractString)
adios::Union{Adios,Nothing}

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

See also the ADIOS2 documentation.

io = declare_io(adios::Adios, name::AbstractString)
io::Union{AIO,Nothing}

Declare a new IO handler.

See also the ADIOS2 documentation.

err = adios_finalize(adios::Adios)
err::Error

Finalize the ADIOS context adios. It is usually not necessary to call this function.

Instead of calling this function, one can also call the finalizer via finalize(adios). This finalizer is also called automatically when the Adios object is garbage collected.

See also the ADIOS2 documentation

struct AIO

Holds a C pointer adios2_io *.

variable = define_variable(io::AIO, name::AbstractString, type::Type,
                     shape::Union{Nothing,NTuple{N,Int} where N,CartesianIndex}=nothing,
                     start::Union{Nothing,NTuple{N,Int} where N,CartesianIndex}=nothing,
                     count::Union{Nothing,NTuple{N,Int} where N,CartesianIndex}=nothing,
                     constant_dims::Bool=false)
variable::Union{Nothing,Variable}

Define a variable within io.

Arguments

• io: handler that owns the variable
• name: unique variable identifier
• type: primitive type
• ndims: number of dimensions
• shape: global dimension
• start: local offset
• count: local dimension
• constant_dims: true: shape, start, count won't change; false: shape, start, count will change after definition

variable = inquire_variable(io::AIO, name::AbstractString)
variable::Union{Nothing,Variable}

Retrieve a variable handler within current io handler.

Arguments

• io: handler to variable io owner
• name: unique variable identifier within io handler

variables = inquire_all_variables(io::AIO)
variables::Union{Nothing,Vector{Variable}}

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

Arguments

• io: handler to variables io owner

vars = inquire_group_variables(io::AIO, full_prefix::AbstractString)
vars::Vector{String}

List all variables in the group full_prefix.

attribute = define_attribute(io::AIO, name::AbstractString, value)
attribute::Union{Nothing,Attribute}

Define an attribute value inside io.

attribute = define_attribute_array(io::AIO, name::AbstractString,
                                   values::AbstractVector)
attribute::Union{Nothing,Attribute}

Define an attribute array inside io.

attribute = define_variable_attribute(io::AIO, name::AbstractString, value,
                                      variable_name::AbstractString,
                                      separator::AbstractString="/")
attribute::Union{Nothing,Attribute}

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

attribute = define_variable_attribute_array(io::AIO, name::AbstractString,
                                            values::AbstractVector,
                                            variable_name::AbstractString,
                                            separator::AbstractString="/")
attribute::Union{Nothing,Attribute}

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

attribute = inquire_attribute(io::AIO, name::AbstractString)
attribute::Union{Nothing,Attribute}

Return a handler to a previously defined attribute by name.

attribute = inquire_variable_attribute(io::AIO, name::AbstractString,
                                       variable_name::AbstractString,
                                       separator::AbstractString="/")
attribute::Union{Nothing,Attribute}

Return a handler to a previously defined attribute by name.

attributes = inquire_all_attributes(io::AIO)
attributes::Union{Nothing,Vector{Attribute}}

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

vars = inquire_group_attributes(io::AIO, full_prefix::AbstractString)
vars::Vector{String}

List all attributes in the group full_prefix.

groups = inquire_subgroups(io::AIO, full_prefix::AbstractString)
groups::Vector{String}

List all subgroups in the group full_prefix.

engine = open(io::AIO, name::AbstractString, mode::Mode)
engine::Union{Nothing,Engine}

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

In MPI version reuses the communicator from adios_init_mpi. MPI Collective function as it calls MPI_Comm_dup.

Arguments

• io: engine owner
• name: unique engine identifier
• mode: mode_write, mode_read, mode_append (not yet supported)

type = engine_type(io::AIO)
type::Union{Nothing,String}

Return engine type string. See set_engine.

engine = get_engine(io::AIO, name::AbstractString)
engine::Union{Nothing,Engine}

struct Variable

Holds a C pointer adios2_variable *.

var_name = name(variable::Variable)
var_name::Union{Nothing,String}

Retrieve variable name.

var_type = type(variable::Variable)
var_type::Union{Nothing,Type}

Retrieve variable type.

var_shapeid = shapeid(variable::Variable)
var_shapeid::Union{Nothing,ShapeId}

Retrieve variable shapeid.

var_ndims = ndims(variable::Variable)
var_ndims::Union{Nothing,Int}

Retrieve current variable number of dimensions.

var_shape = shape(variable::Variable)
var_shape::Union{Nothing,NTuple{N,Int} where N}

Retrieve current variable shape.

var_start = start(variable::Variable)
var_start::Union{Nothing,NTuple{N,Int} where N}

Retrieve current variable start.

var_count = count(variable::Variable)
var_count::Union{Nothing,NTuple{N,Int} where N}

Retrieve current variable count.

var_steps_start = steps_start(variable::Variable)
var_steps_start::Union{Nothing,Int}

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

This returns the absolute first available step, don't use with adios2_set_step_selection as inputs are relative, use 0 instead.

var_steps = steps(variable::Variable)
var_steps::Union{Nothing,Int}

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

var_selection_size = selection_size(variable::Variable)
var_selection_size::Union{Nothing,Int}

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

var_min = minimum(variable::Variable)
var_min::Union{Nothing,T}

Read mode only: return the absolute minimum for variable.

var_max = maximum(variable::Variable)
var_max::Union{Nothing,T}

Read mode only: return the absolute maximum for variable.

struct Attribute

Holds a C pointer adios2_attribute *.

attr_name = name(attribute::Attribute)
attr_name::Union{Nothing,String}

Retrieve attribute name.

attr_type = type(attribute::Attribute)
attr_type::Union{Nothing,Type}

Retrieve attribute type.

attr_is_value = is_value(attribute::Attribute)
attr_is_value::Union{Nothing,Bool}

Retrieve attribute type.

attr_size = size(attribute::Attribute)
attr_size::Union{Nothing,Int}

Retrieve attribute size.

attr_data = data(attribute::Attribute)
attr_data::Union{Nothing,AdiosType,Vector{<:AdiosType}}

Retrieve attribute Data.

struct Engine

Holds a C pointer adios2_engine *.

var_name = name(variable::Variable)
var_name::Union{Nothing,String}

Retrieve variable name.

attr_name = name(attribute::Attribute)
attr_name::Union{Nothing,String}

Retrieve attribute name.

engine_name = name(engine::Engine)
engine_name::Union{Nothing,String}

Retrieve engine name.

var_type = type(variable::Variable)
var_type::Union{Nothing,Type}

Retrieve variable type.

attr_type = type(attribute::Attribute)
attr_type::Union{Nothing,Type}

Retrieve attribute type.

engine_type = type(engine::Engine)
engine_type::Union{Nothing,String}

Retrieve engine type.

engine_openmode = openmode(engine::Engine)
engine_openmode::Union{Nothing,Mode}

Retrieve engine openmode.

status = begin_step(engine::Engine, mode::StepMode,
                    timeout_seconds::Union{Integer,AbstractFloat})
status = begin_step(engine::Engine)
status::Union{Noting,StepStatus}

Begin a logical adios2 step stream.

step = current_step(engine::Engine)
step::Union{Noting,Int}

Inspect current logical step.

var_steps = steps(variable::Variable)
var_steps::Union{Nothing,Int}

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

step = steps(engine::Engine)
step::Union{Noting,Int}

Inspect total number of available steps.

err = Base.put!(engine::Engine, variable::Variable,
                data::Union{Ref,DenseArray,SubArray,Ptr},
                launch::Mode=mode_deferred)
err = Base.put!(engine::Engine, variable::Variable, data::AdiosType,
                launch::Mode=mode_deferred)
err::Error

Schedule writing a variable to file. The buffer data must be contiguous in memory.

Call perform_puts! to perform the actual write operations.

The reference/array/pointer target must not be modified before perform_puts! is called. It is most efficient to schedule multiple put! operations before calling perform_puts!.

perform_puts!(engine::Engine)

Execute all currently scheduled write operations.

err = Base.get(engine::Engine, variable::Variable,
               data::Union{Ref,DenseArray,SubArray,Ptr},
               launch::Mode=mode_deferred)
err::Error

Schedule reading a variable from file into the provided buffer data. data must be contiguous in memory.

Call perform_gets to perform the actual read operations.

The reference/array/pointer target must not be modified before perform_gets is called. It is most efficient to schedule multiple get operations before calling perform_gets.

perform_gets(engine::Engine)

Execute all currently scheduled read operations.

end_step(engine::Engine)

Terminate interaction with current step.

flush(engine::Engine)

Flush all buffered data to file. Call this after perform_puts! to ensure data are actually written to file.

close(engine::Engine)

Close a file. This implicitly also flushed all buffered data.

struct AdiosFile

Context for the high-level API for an ADIOS file

adios = adios_open_serial(filename::AbstractString, mode::Mode)
adios::AdiosFile

Open an ADIOS file. Use mode = mode_write for writing and mode = mode_read for reading.

adios = adios_open_mpi(comm::MPI.Comm, filename::AbstractString, mode::Mode)
adios::AdiosFile

Open an ADIOS file for parallel I/O. Use mode = mode_write for writing and mode = mode_read for reading.

flush(file::AdiosFile)

Flush an ADIOS file. When writing, flushing or closing a file is necesssary to ensure that data are actually written to the file.

close(file::AdiosFile)

Close an ADIOS file. When writing, flushing or closing a file is necesssary to ensure that data are actually written to the file.

groups = adios_subgroup_names(file::AdiosFile, groupname::AbstractString)
vars::Vector{String}

List (non-recursively) all subgroups in the group groupname in the file.

adiosdefineattribute(file::AdiosFile, name::AbstractString, value::AdiosType)

Write a scalar attribute.

adios_define_attribute(file::AdiosFile, name::AbstractString,
                       value::AbstractArray{<:AdiosType})

Write an array-valued attribute.

adios_define_attribute(file::AdiosFile, path::AbstractString,
                       name::AbstractString, value::AdiosType)

Write a scalar attribute into the path path in the file.

adios_define_attribute(file::AdiosFile, path::AbstractString,
                       name::AbstractString,
                       value::AbstractArray{<:AdiosType})

Write an array-valued attribute into the path path in the file.

attrs = adios_all_attribute_names(file::AdiosFile)
attrs::Vector{String}

List (recursively) all attributes in the file.

vars = adios_group_attribute_names(file::AdiosFile, groupname::AbstractString)
vars::Vector{String}

List (non-recursively) all attributes in the group groupname in the file.

attr_data = adios_attribute_data(file::AdiosFile, name::AbstractString)
attr_data::Union{Nothing,AdiosType}

Read an attribute from a file. Return nothing if the attribute is not found.

attr_data =  adios_attribute_data(file::AdiosFile, path::AbstractString,
                                  name::AbstractString)
attr_data::Union{Nothing,AdiosType}

Read an attribute from a file in path path. Return nothing if the attribute is not found.

adios_put!(file::AdiosFile, name::AbstractString, scalar::AdiosType)

Schedule writing a scalar variable to a file.

The variable is not written until adios_perform_puts! is called and the file is flushed or closed.

adios_put!(file::AdiosFile, name::AbstractString,
           array::AbstractArray{<:AdiosType}; make_copy::Bool=false)

Schedule writing an array-valued variable to a file.

make_copy determines whether to make a copy of the array, which is expensive for large arrays. When no copy is made, then the array must not be modified before adios_perform_puts! is called.

The variable is not written until adios_perform_puts! is called and the file is flushed or closed.

adios_perform_puts!(file::AdiosFile)

Execute all scheduled adios_put! operations.

The data might not be in the file yet; they might be buffered. Call adios_flush or adios_close to ensure all data are written to file.

vars = adios_all_variable_names(file::AdiosFile)
vars::Vector{String}

List (recursively) all variables in the file.

vars = adios_group_variable_names(file::AdiosFile, groupname::AbstractString)
vars::Vector{String}

List (non-recursively) all variables in the group groupname in the file.

mutable struct IORef{T,D}

A reference to the value of a variable that has been scheduled to be read from disk. This value cannot be accessed bofre the read operations have actually been executed.

Use fetch(ioref::IORef) to access the value. fetch will trigger the actual reading from file if necessary. It is most efficient to schedule multiple read operations at once.

Use adios_perform_gets to trigger reading all currently scheduled variables.

isready(ioref::IORef)::Bool

Check whether an IORef has already been read from file.

value = fetch(ioref::IORef{T,D}) where {T,D}
value::Array{T,D}

Access an IORef. If necessary, the variable is read from file and then cached. (Each IORef is read at most once.)

Scalars are handled as zero-dimensional arrays. To access the value of a zero-dimensional array, write array[] (i.e. use array indexing, but without any indices).

ioref = adios_get(file::AdiosFile, name::AbstractString)
ioref::Union{Nothing,IORef}

Schedule reading a variable from a file.

The variable is not read until adios_perform_gets is called. This happens automatically when the IORef is accessed (via fetch). It is most efficient to first schedule multiple variables for reading, and then executing the reads together.

adios_perform_gets(file::AdiosFile)

Execute all currently scheduled read opertions. This makes all pending IORefs ready.