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

err = set_engine(io::AIO, engine_type::AbstractString)
err::Error

Set the engine type for current io handler.

Arguments

• io: handler
• engine_type: predefined engine type, default is bpfile

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; global_value=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

Keywords

• global_value: for scalar variables (shape=nothing), global_value=true can be passed to indicate that the variable will be a 'global' variable, written once per step, as opposed to a 'local' variable written once per MPI rank per step.

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

set_block_selection(variable::Variable, block_id::Int)

set_selection(variable::Variable, start::Union{Nothing,NTuple{N,Int} where N,
CartesianIndex}, count::Union{Nothing,NTuple{N,Int} where N,
CartesianIndex})

set_step_selection(variable::Variable, step_start::Int, step_count::Int)
Only works with file-based engines, not streaming engines (e.g. does not work with SST)

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.

Keywords

• global_value: for scalar variables (shape=nothing), global_value=true can be passed to indicate that the variable will be a 'global' value, written once per step, as opposed to a 'local' value written once per MPI rank per step.

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; start=nothing, count=nothing)
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.

start and counts can be used to select a subset of the data, as defined by set_selection.

adios_perform_gets(file::AdiosFile)

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

adios_load(file::AdiosFile, [varName(s)], [step(s)]; start=nothing, count=nothing)

Read variable data from ADIOS file with optional variable name(s) and step selection(s).

Arguments

• First:
  • file (::AdiosFile): ADIOS file (opened with mode_readRandomAccess)
• Second (Optional):
  • varName (::AbstractString): Single variable name or nothing (reads all)
  • varNames (::AbstractArray{<:AbstractString}`): Array of variable names
  • name_pattern (::Regex): To find variables whose name contains the pattern (e.g., r"temp.*")
• Third (Optional):
  • step (::Integer): Single step index (0-based)
  • step_list (::AbstractArray{<:Integer}): Array of step indices

Keywords

• start: when loading a single variable, can be passed a length-N Tuple giving the positions to start reading data in each dimension. Note than start should be given in standard Julian 1-based indexing.
• count: when loading a single variable, can be passed a length-N Tuple giving the number of entries to read in each dimension.

Returns

For a variable of N-D data, returns an (N+1)-D array with the last dimension being the steps.

• Single variable:
  • Single step: original dimensionality preserved (N-D array)
  • Multiple steps: returns (N+1)-D array with shape (dim1, dim2, ..., dimN, N_steps)
• Multiple variables:
  • Dictionary with variable names as keys and their data arrays as values

Examples

# Open file in random access mode
file = adios_open_serial("simulation.bp", mode_readRandomAccess)

# Read all steps of all variables in the file
data_dict = adios_load(file)

# Read all steps of a variable
data = adios_load(file, "temperature")
data = adios_load(file, "temperature"; start=[3,4], count=[10,20])

# Read of a variable at a specific step
data = adios_load(file, "temperature", 5)
data = adios_load(file, "temperature", 5; start=[3,4], count=[10,20])

# Read specific steps at multiple steps (order is not sorted)
data = adios_load(file, "temperature", [1,3,6])
data = adios_load(file, "temperature", [6,3,1]) # reverse of previous example
data = adios_load(file, "temperature", 50:100)
data = adios_load(file, "temperature", 50:100; start=[3,4], count=[10,20])

# Read multiple variables at a specific step
data_dict = adios_load(file, ["temperature", "pressure"], 5)

# Read multiple variables at multiple steps (order is not sorted)
data_dict = adios_load(file, ["temperature", "pressure"], [1,3,6])
data_dict = adios_load(file, ["temperature", "pressure"], [6,3,1]) # reverse of previous example
data_dict = adios_load(file, ["temperature", "pressure"], 50:100)

# Read multiple variables contain the given name pattern at multiple steps
data_dict = adios_load(file, r"temper", 50:100) # will read (electron_temperature, ion_temperature, abc_temper_abc, etc.)
data_dict = adios_load(file, r"ion.*temper", 50:100) # will read (ion_temperature)
data_dict = adios_load(file, r"temper|pres", 50:100) # will read (temperature, temperature, pressure, ion_pressure, electron_pressure, etc.)

close(file)

adios_load(bpPath::AbstractString)
adios_load(bpPath::AbstractString, args...; kwargs...)

Convenient highest-level API to read variable data directly from ADIOS's BP file path.

This is a convenience wrapper that automatically opens the file in mode_readRandomAccess, reads the data, and closes the file. All the functionality of adios_load(file::AdiosFile, ...) is available through the same argument patterns.

Arguments

• bpPath (AbstractString): Path to ADIOS's BP file/directory ending with .bp extension
• args...: Same arguments as adios_load(file::AdiosFile, ...) - variable names, steps, etc.

Keywords

• kwargs...: Same keyword arguments as adios_load(file::AdiosFile, ...).

Returns

Same return types as adios_load(file::AdiosFile, ...):

• Single variable, single step: N-D array
• Single variable, multiple steps: (N+1)-D array with steps as last dimension
• Multiple variables: Dictionary with variable names as keys

Examples

# Read all variables and all steps
data_dict = adios_load("simulation.bp")

# Read specific variable, all steps
temperature = adios_load("simulation.bp", "temperature")

# Read specific variable at specific step
temp_step5 = adios_load("simulation.bp", "temperature", 5)

# Read multiple variables at multiple steps
data = adios_load("simulation.bp", ["temperature", "pressure"], [1,3,5])

# Read variables matching pattern
temps = adios_load("simulation.bp", r".*temperature.*", 10:20)

Notes

• File is automatically opened with mode_readRandomAccess and closed after reading
• Throws ErrorException if the file path does not exist or is invalid
• More efficient to use adios_load(file::AdiosFile, ...) directly if reading multiple times from the same file to avoid repeated open/close operations

See also: adios_load(::AdiosFile), adios_open_serial