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.

The flat form the text parser produces and the parser itself are internal to polydat_grammar (comprehension_forms.md §14.8): text reaches the canonical tree through spec::parse_comprehension_algebra, a spec document through spec::ComprehensionSpec::into_algebra or spec::parse_text. 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::NoneRead;

pub use eval_source::SourceEval;

pub use runtime::ClauseYield;

pub use runtime::EvaluatedIteration;

pub use runtime::IndexedTuples;

pub use runtime::NoneReads;

pub use runtime::evaluate_for_iteration;

pub use runtime::evaluate_for_iteration_materialized;

pub use runtime::evaluate_for_iteration_materialized_with_none_reads;

pub use runtime::evaluate_for_iteration_reported;

pub use runtime::evaluate_for_iteration_with_none_reads;

pub use runtime::evaluate_indexed;

pub use validate::Mode;

pub use validate::NameRead;

pub use validate::ReadSite;

pub use validate::Surface;

pub use validate::ValidationError;

pub use validate::ValidationReport;

pub use validate::ValidationWarning;

pub use validate::check_names;

pub use validate::outer_reads;

pub use validate::unresolved_names;

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 (comprehension_forms.md §3).

cardinality

Cardinality classes (comprehension_forms.md §6.1).

eval

Comprehension spec evaluation — text → typed value list.

eval_source

Source evaluation — comprehension_forms.md §10.7.0, §10.7.6, §10.7.8.

flatten

Compile-time flattening of context-free sources (comprehension_forms.md §10.7.0, §10.7.7). Whether a generator call can be evaluated before traversal is a property of its expression, not of its name: a call that references no name, and none that scope cannot resolve, is evaluated once here, and its clause becomes a literal of the values it produced. The values are then what the runtime binds, computed once instead of on every activation, and the clause’s cardinality is exact, so the V-axioms that need a bound (V4, V6) fire at compile with the real shape.

ir

IR + compiler + interpreter — comprehension_forms.md §9.1, §9.2, §9.3.

measure

A continuous axis’s measure as the sampler maps onto it (comprehension_forms.md §10.2 R2): a sampling strategy draws a point in [0, 1) per continuous axis, and the axis’s measure carries it onto the axis’s interval, affinely for Uniform and by the inverse CDF for a named measure. A named measure on an interval narrower than its support is the measure restricted to that interval: the unit point is placed between the CDF values of the two ends and then inverted, so the draws keep the measure’s shape inside the interval.

metadata

Metadata algebra (comprehension_forms.md §10.7).

optimize

Post-parse optimizer — comprehension_forms.md §10.

predicate

Filter predicates — comprehension_forms.md §10.9: their evaluation (§10.9.1) and their analysis.

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 (comprehension_forms.md §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 — comprehension_forms.md §3.6, §10.2 R2, §10.7.8.

strategy

Strategy taxonomy and zip modes (comprehension_forms.md §3.6, §3.3).

streamer_value

The value a producer wire carries (for_traversal.md §3.1).

surfaces

Consumption surfaces — comprehension_forms.md §9.5.

validate

Validation — comprehension_forms.md §5 (V1-V9) and §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 (comprehension_forms.md §10.7.1).

Materialization

Streaming-vs-barrier classification (comprehension_forms.md §6.2).

MeasureName

Named continuous distribution. A closed enum, per comprehension_forms.md §10.7.5’s “User-defined extensions” non-goal: a new distribution is a coordinated addition to it.

NaturalOrder

Natural enumeration order (comprehension_forms.md §10.7.1).

ProductMeasure

Product measure over one or more continuous axes.

Source

A clause’s source of values.

StrategyName

Named ordering strategies (comprehension_forms.md §3.6).

ZipMode

Zip combination mode (comprehension_forms.md §3.3).