Module comprehension 

Comprehensions — the formal model of iteration shape in GK.

What it is

A comprehension is a structured description of the iteration position a scope occupies — the variables it binds, where their value lists come from, and how those lists combine. The algebra of six constructors (clause, cartesian, zip, union, filter, order), closed under composition, is the canonical representation; see polydat/docs/design/comprehension_forms.md for the full spec.

It’s the static-shape counterpart to the run-time crate::kernel::ScopeCoord: the comprehension says “this scope binds k and limit, drawn from {k_values} and {k_{k}_limits}”; the scope coordinate says “right now k=10 and limit=20.”

Module layout

The algebra modules (ast, source, strategy, spec, runtime, surfaces, ir, optimize, predicate, metadata, validate, cardinality, strategies) are the canonical comprehension layer. Top-level re-exports surface the common types (Comprehension, Source, ZipMode, etc.) for ergonomic consumer access.

ast_legacy and parse retain the older flat-struct comprehension types as parse-pipeline implementation details: the YAML loader uses parse::parse_clause_list etc. to lex the textual form, then spec::ComprehensionSpec::into_algebra converts to the canonical algebra AST via spec::legacy_to_algebra. eval is the runtime-evaluation helper module (eval::evaluate_spec, eval::pre_evaluate_clause) that both the scope-walker and the runtime evaluator consume.

Why Polydat owns it

Comprehensions cut across three subsystems:

• The YAML parser (in the host) needs to recognise the textual shapes (for_each, for_combinations, for_each_union).
• The scope synthesiser (in the host) needs to emit the Polydat source for each comprehension’s child kernel — extern declarations for the coordinates, final injections for workload params the spec interpolates, etc.
• The executor (in the host) needs to enumerate the iteration tuples, drive the per-iteration PolydatKernel::for_iteration (which wires the parent scope internally), and run the children.

All three flow through this module’s canonical algebra AST.

Re-exports

pub use streamer_value::StreamerValue;

pub use eval_source::EvalClass;

pub use eval_source::EvalContext;

pub use eval_source::EvalError;

pub use eval_source::EvaluatedSource;

pub use eval_source::SourceEval;

pub use validate::Mode;

pub use validate::ValidationError;

pub use validate::ValidationReport;

pub use validate::ValidationWarning;

pub use validate::validate;

pub use eval::evaluate_spec;

pub use eval::pre_evaluate_clause;

pub use eval::value_to_polydat_type_name;

Modules

ast

Operator-tree comprehension AST — spec §3.

ast_legacy

Comprehension AST — the static shape of an iteration scope.

cardinality

Cardinality classes — spec §6.1.

eval

Comprehension spec evaluation — text → typed value list.

eval_source

Source evaluation — spec §10.7.0, §10.7.6, §10.7.8.

ir

IR + compiler + interpreter — spec §9.1, §9.2, §9.3.

metadata

Metadata algebra — spec §10.7.

optimize

Post-parse optimizer — spec §10.

parse

Comprehension spec parser — text → AST.

predicate

Predicate analyzer — spec §10.9.

runtime

Runtime evaluator — walks an algebra Comprehension AST against a Lookup scope (a PolydatKernel or a Layered view) to produce typed coordinate tuples.

source

Clause source values — spec §3.1.

source_values

The runtime’s reading of a value as a comprehension source: which values peel into elements, and how a string source strips into typed tokens. The grammar’s separator rule (source::split_string_comprehension) is the one both sides use.

spec

Comprehension specification surface — author-friendly input form for YAML / JSON consumers.

strategies

Strategy implementations — spec §3.6 + §10.2 R2 + §10.7.8.

strategy

Strategy taxonomy and zip modes — spec §3.6 + §3.3.

streamer_value

The value a producer wire carries (SRD 113 §3.1).

surfaces

Consumption surfaces — spec §9.5.

validate

Validation — spec §5 (V1-V9) + §5.8 (modes).

Structs

Hybrid

Mixed discrete × continuous cartesian shape.

Interval

Real interval [lo, hi] (or open variants) for continuous sources. Unbounded sides use f64::NEG_INFINITY / f64::INFINITY; the V8 integrability check determines whether such intervals are valid given the measure.

Metadata

The metadata bundle carried by every well-formed AST node.

Enums

CardinalityClass

Cardinality of a comprehension’s dispense stream.

Comprehension

The six-variant operator-tree comprehension.

IndexFn

Closed-form addressing schemes — spec §10.7.1.

Materialization

Streaming-vs-barrier classification per spec §6.2.

MeasureName

Named continuous distribution. Closed enum per spec §10.7.5’s “User-defined extensions” non-goal — new distributions land as coordinated additions.

NaturalOrder

Natural enumeration order — spec §10.7.1.

ProductMeasure

Product measure over one or more continuous axes.

Source

A clause’s source of values.

StrategyName

Named ordering strategies per spec §3.6 (plus Shuffle).

ZipMode

Zip combination mode per spec §3.3.