Module selection

Selection algebra for describing multidimensional mesh regions. This module defines a recursive algebra for selecting coordinates in a multidimensional space.

A Selection describes constraints across dimensions of an ndslice::Slice. Variants like [All], [First], and Range operate dimensionally, while [Intersection] and [Union] allow for logical composition of selections.

Example

Suppose a 3-dimensional mesh system of:

• 2 zones
• 4 hosts per zone
• 8 GPUs per host

The corresponding Slice will have shape [2, 4, 8]. An expression to denote the first 4 GPUs of host 0 together with the last 4 GPUs on host 1 across all regions can be written as:

use ndslice::selection::dsl::all;
use ndslice::selection::dsl::range;
use ndslice::selection::dsl::true_;
use ndslice::selection::dsl::union;

let s = all(range(0, range(0..4, true_())));
let t = all(range(1, range(4.., true_())));
let selection = union(s, t);

Assuming a row-major layout, that is the set of 4 x 2 x 2 = 16 coordinates {(0, 0, 0), … (0, 0, 3), (0, 1, 5), …, (0, 1, 7), (1, 0, 0), …, (1, 0, 3), (1, 1, 4), …, (1, 1, 7)} where code to print that set might read as follows.

use ndslice::Slice;
use ndslice::selection::EvalOpts;
use ndslice::selection::dsl::all;
use ndslice::selection::dsl::range;
use ndslice::selection::dsl::true_;
use ndslice::selection::dsl::union;

let slice = Slice::new(0usize, vec![2, 4, 8], vec![32, 8, 1]).unwrap();
let s = all(range(0, range(0..4, true_())));
let t = all(range(1, range(4.., true_())));

for r in union(s, t).eval(&EvalOpts::lenient(), &slice).unwrap() {
    println!("{:?}", slice.coordinates(r).unwrap());
}

which is using the eval function described next.

Evaluation

Selections are evaluated against an ndslice::Slice using the Selection::eval method, which returns a lazy iterator over the flat (linearized) indices of elements that match.

Evaluation proceeds recursively, dimension by dimension, with each variant of Selection contributing logic at a particular level of the slice.

If a Selection is shorter than the number of dimensions, it is implicitly extended with true_() at the remaining levels. This means Selection::True acts as the identity element, matching all remaining indices by default.

Modules

dsl

SelectionSYM-based constructors specialized to the Selection AST.

normal

Normalization logic for Selection.

parse

A parser for selection expressions in a compact textual syntax.

pretty

Formatting utilities for Selection expressions.

routing

Shape navigation guided by Selection expressions.

test_utils

token_parser

A TokenStream to Selection parser. Used at compile time in [sel!]. See [selection::parse] for syntax details and examples. A TokenStream to Selection parser used by the sel! procedural macro.

Structs

EvalOpts

EvalOpts controls runtime behavior of Selection::eval by enforcing stricter validation rules.

NormalizedSelectionKey

Wraps a normalized selection and derives Eq and Hash, relying on the canonical structure of the normalized form.

Enums

LabelKey

A metadata label used to constrain values at a given coordinate dimension.

Selection

An algebra for expressing node selection.

Traits

ReifySlice

Connects the select! API to the Selection algebra by enabling base.reify_slice(slice) syntax, where base: Slice.

SelectionSYM

This trait defines an abstract syntax without committing to a specific representation. It follow the tagless-final style where Selection is a default AST representation.

Functions

is_equivalent_true

Trivial all(true) equivalence.

normalize

Normalizes a Selection toward a canonical form for structural comparison.

selection_from

Construct a Selection from a Shape and multiple labeled range constraints.

selection_from_one

Construct a Selection from a Shape and a single labeled constraint.

structurally_equal

Compares two Selection values for structural equality.