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//!   `materialize_wiring_from_outer`, and run the children.
57//!
58//! All three flow through this module's canonical algebra AST.
59
60// --- The sub-language: its text form, the flat form text parses to,
61// the canonical algebra with its sources, strategies, cardinalities,
62// and metadata, and the spec forms between them. These live in
63// `polydat_grammar`, reachable here at the paths they always had.
64pub use polydat_grammar::comprehension::{
65    ast, ast_legacy, cardinality, metadata, parse, source, spec, strategy,
66};
67
68// --- The runtime's reading of the algebra.
69pub mod eval_source;
70pub mod ir;
71pub mod optimize;
72pub mod predicate;
73pub mod runtime;
74pub mod source_values;
75pub mod strategies;
76pub mod surfaces;
77pub mod validate;
78
79// --- Parse-pipeline support modules. `ast_legacy` and `parse`
80// produce the older flat-struct form that the YAML parser
81// generates; `spec::ComprehensionSpec::into_algebra` converts
82// that into the canonical algebra AST above via
83// `spec::legacy_to_algebra`. `eval` is the runtime-evaluation
84// helper used by both the algebra runtime evaluator and the
85// scope-walker.
86pub mod eval;
87pub mod streamer_value;
88pub use streamer_value::StreamerValue;
89
90// --- Canonical algebra re-exports — `polydat::iteration::comprehension::Comprehension`
91// resolves to the algebra type; same for Source, ZipMode, etc.
92pub use ast::Comprehension;
93pub use cardinality::{CardinalityClass, Hybrid, Interval, MeasureName, ProductMeasure};
94pub use eval_source::{EvalClass, EvalContext, EvalError, EvaluatedSource, SourceEval};
95pub use metadata::{IndexFn, Materialization, Metadata, NaturalOrder};
96pub use source::Source;
97pub use strategy::{StrategyName, ZipMode};
98pub use validate::{Mode, ValidationError, ValidationReport, ValidationWarning, validate};
99
100// --- Parse-pipeline support re-exports. These are evaluator
101// utilities used by the algebra runtime evaluator and the
102// scope-walker — not part of the comprehension AST surface.
103//
104// `enumerate_tuples` and `parse_list_with_types` are crate-
105// private — only `runtime` and `eval` use them internally
106// after the synthesis dissolve. Kept available via
107// `eval::*` for crate-internal callers.
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
