Selection

The Selection class provides an explicit, self-contained specification for Get() operations. It bundles all the parameters that describe what data to read — bounding box, block ID, step range, memory layout, and accuracy — into a single object that is passed to Engine::Get().

Motivation

The traditional ADIOS2 read pattern requires mutating a Variable object before calling Get():

var.SetSelection({{0, 0}, {10, 20}});
var.SetStepSelection({0, 5});
engine.Get(var, data);

This works, but the selection state lives inside the Variable and can become stale or unclear when the same variable is read with different selections in different parts of the code. The Selection class makes each Get() call self-documenting by specifying the selection explicitly at the call site:

auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20}).WithSteps(0, 5);
engine.Get(var, data, sel);

Creating Selections

Selections are created using static factory methods. A selection has two independent aspects:

Spatial selection — All (the entire variable) or BoundingBox (a hyperslab with start offsets and counts).
Block selection — optionally targets an individual write block by ID.

These are orthogonal: a block ID can be combined with either spatial type.

// All — select the entire variable (this is also the default)
auto sel = adios2::Selection::All();

// Bounding box (hyperslab) — specify start offsets and counts per dimension
auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20});

// Block selection — read an entire write block
// (equivalent to All().WithBlock(3))
auto sel = adios2::Selection::Block(3);

// Block + bounding box — read a sub-region within a specific block
auto sel = adios2::Selection::BoundingBox({0}, {10}).WithBlock(3);

// Using Box<Dims> convenience type
adios2::Box<adios2::Dims> box = {{0, 0}, {10, 20}};
auto sel = adios2::Selection::BoundingBox(box);

A default-constructed Selection is equivalent to Selection::All():

adios2::Selection sel;
engine.Get(var, data, sel);  // reads the whole variable

Fluent Style (Immutable)

The With*() methods return a new Selection with the modification applied, leaving the original unchanged. This is useful for one-shot expressions:

auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20})
               .WithBlock(2)
               .WithSteps(0, 5)
               .WithMemory({0, 0}, {10, 40})
               .WithAccuracy({0.01, 0.0, false});
engine.Get(var, data, sel);

Mutable Style (Reuse)

The Set*() methods modify the Selection in place and return *this for chaining. This is useful when reusing a selection across iterations:

adios2::Selection sel;
sel.SetBoundingBox({0, 0}, {10, 20});
sel.SetAccuracy({0.01, 0.0, false});

for (size_t step = 0; step < nsteps; ++step)
{
    sel.SetSteps(step, 1);
    engine.Get(var, buffers[step], sel);
}

Using Selections with Get()

New Engine::Get() overloads accept a Selection parameter:

// Raw pointer version
engine.Get(var, data_ptr, sel, adios2::Mode::Sync);

// std::vector version (auto-resized)
std::vector<double> data;
engine.Get(var, data, sel);

Buffer Pre-allocation with SelectionSize()

Variable::SelectionSize() now accepts a Selection to compute the required buffer size without modifying the variable:

auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20});
size_t nelems = var.SelectionSize(sel);
double *buf = new double[nelems];
engine.Get(var, buf, sel);

Available Selection Parameters

Parameter	Factory / Setter	Non-mutating modifier	Description
All	`All()`	—	Select the entire variable (default)
Bounding Box	`BoundingBox(start, count)` / `SetBoundingBox()`	—	Hyperslab selection with start offsets and counts
Block	`Block(blockID)` / `SetBlock()`	`WithBlock()`	Select an individual write block by ID (can combine with any spatial type)
Steps	`SetSteps(start, count)`	`WithSteps()`	Step range to read (default: current step, count 1)
Memory	`SetMemory(start, count)`	`WithMemory()`	Memory layout specification for the destination buffer
Accuracy	`SetAccuracy(error, norm, relative)`	`WithAccuracy()`	Lossy accuracy requirements

Other methods:

Clear() — reset the selection to default state (All, no block)
ClearBlock() — remove block selection
ClearMemory() — remove memory layout specification
ToString() — human-readable string representation for debugging

auto sel = adios2::Selection::BoundingBox({0, 0}, {10, 20}).WithSteps(0, 5);
std::cout << sel.ToString() << std::endl;
// Output: Selection(BoundingBox start={0, 0} count={10, 20}, steps=[0, 5])

Engine Support

Selection-based Get() is currently supported by the BP5 and SST (with BP5 marshalling) engines. Other engines will throw a runtime error if a Selection is passed to Get().

Compatibility

The existing Variable::SetSelection(), SetBlockSelection(), SetStepSelection(), and SetMemorySelection() APIs remain available and are not deprecated. The Selection class is a convenience alternative that makes the selection explicit at the Get() call site rather than relying on state previously set on the Variable.