polydat_core/iteration/comprehension/
mod.rs

1// Copyright 2024-2026 Jonathan Shook
2// SPDX-License-Identifier: Apache-2.0
3
4//! Comprehensions — the formal model of iteration shape in GK.
5//!
6//! ## What it is
7//!
8//! A *comprehension* is a structured description of the
9//! iteration position a scope occupies — the variables it
10//! binds, where their value lists come from, and how those
11//! lists combine. The algebra of six constructors
12//! (`clause`, `cartesian`, `zip`, `union`, `filter`, `order`),
13//! closed under composition, is the canonical representation;
14//! see `polydat/docs/design/comprehension_forms.md` for the
15//! full spec.
16//!
17//! It's the static-shape counterpart to the run-time
18//! [`crate::kernel::ScopeCoord`]: the comprehension says
19//! "this scope binds `k` and `limit`, drawn from `{k_values}`
20//! and `{k_{k}_limits}`"; the scope coordinate says "right
21//! now `k=10` and `limit=20`."
22//!
23//! ## Module layout
24//!
25//! The algebra modules ([`ast`], [`source`], [`strategy`],
26//! [`spec`], [`runtime`], [`surfaces`], [`ir`], [`optimize`],
27//! [`predicate`], [`metadata`], [`validate`](fn@validate), [`cardinality`],
28//! [`strategies`]) are the canonical comprehension layer.
29//! Top-level re-exports surface the common types
30//! ([`Comprehension`], [`Source`], [`ZipMode`], etc.) for
31//! ergonomic consumer access.
32//!
33//! [`ast_legacy`] and [`parse`] retain the older flat-struct
34//! comprehension types as parse-pipeline implementation
35//! details: the YAML loader uses [`parse::parse_clause_list`]
36//! etc. to lex the textual form, then
37//! [`spec::ComprehensionSpec::into_algebra`] converts to the
38//! canonical algebra AST via [`spec::legacy_to_algebra`].
39//! [`eval`] is the runtime-evaluation helper module
40//! ([`eval::evaluate_spec`], [`eval::pre_evaluate_clause`]) that
41//! both the scope-walker and the runtime evaluator consume.
42//!
43//! ## Why Polydat owns it
44//!
45//! Comprehensions cut across three subsystems:
46//!
47//! - The **YAML parser** (in the host) needs to recognise
48//!   the textual shapes (`for_each`, `for_combinations`,
49//!   `for_each_union`).
50//! - The **scope synthesiser** (in the host)
51//!   needs to emit the Polydat source for each comprehension's child
52//!   kernel — extern declarations for the coordinates, final
53//!   injections for workload params the spec interpolates, etc.
54//! - The **executor** (in the host) needs to
55//!   enumerate the iteration tuples, drive the per-iteration
56//!   `PolydatKernel::for_iteration` (which wires the parent scope
57//!   internally), and run the children.
58//!
59//! All three flow through this module's canonical algebra AST.
60
61// --- The sub-language: its text form, the flat form text parses to,
62// the canonical algebra with its sources, strategies, cardinalities,
63// and metadata, and the spec forms between them. These live in
64// `polydat_grammar`, reachable here at the paths they always had.
65pub use polydat_grammar::comprehension::{
66    ast, ast_legacy, cardinality, metadata, parse, source, spec, strategy,
67};
68
69// --- The runtime's reading of the algebra.
70pub mod eval_source;
71pub mod ir;
72pub mod optimize;
73pub mod predicate;
74pub mod runtime;
75pub mod source_values;
76pub mod strategies;
77pub mod surfaces;
78pub mod validate;
79
80// --- Parse-pipeline support modules. `ast_legacy` and `parse`
81// produce the older flat-struct form that the YAML parser
82// generates; `spec::ComprehensionSpec::into_algebra` converts
83// that into the canonical algebra AST above via
84// `spec::legacy_to_algebra`. `eval` is the runtime-evaluation
85// helper used by both the algebra runtime evaluator and the
86// scope-walker.
87pub mod eval;
88pub mod streamer_value;
89pub use streamer_value::StreamerValue;
90
91// --- Canonical algebra re-exports — `polydat::iteration::comprehension::Comprehension`
92// resolves to the algebra type; same for Source, ZipMode, etc.
93pub use ast::Comprehension;
94pub use cardinality::{CardinalityClass, Hybrid, Interval, MeasureName, ProductMeasure};
95pub use eval_source::{EvalClass, EvalContext, EvalError, EvaluatedSource, SourceEval};
96pub use metadata::{IndexFn, Materialization, Metadata, NaturalOrder};
97pub use source::Source;
98pub use strategy::{StrategyName, ZipMode};
99pub use validate::{Mode, ValidationError, ValidationReport, ValidationWarning, validate};
100
101// --- Parse-pipeline support re-exports. These are evaluator
102// utilities used by the algebra runtime evaluator and the
103// scope-walker — not part of the comprehension AST surface.
104//
105// `enumerate_tuples` and `parse_list_with_types` are not
106// re-exported at this level; they remain reachable as
107// `eval::enumerate_tuples` / `eval::parse_list_with_types`.
108pub use eval::{evaluate_spec, pre_evaluate_clause, value_to_polydat_type_name};
polydat_core/iteration/comprehension/mod.rs

polydat_core/iteration/comprehension/
mod.rs
