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//! The flat form the text parser produces and the parser itself are
34//! internal to `polydat_grammar` (comprehension_forms.md §14.8):
35//! text reaches the canonical tree through
36//! [`spec::parse_comprehension_algebra`], a spec document through
37//! [`spec::ComprehensionSpec::into_algebra`] or [`spec::parse_text`].
38//! [`eval`] is the runtime-evaluation helper module
39//! ([`eval::evaluate_spec`], [`eval::pre_evaluate_clause`]) that
40//! both the scope-walker and the runtime evaluator consume.
41//!
42//! ## Why Polydat owns it
43//!
44//! Comprehensions cut across three subsystems:
45//!
46//! - The **YAML parser** (in the host) needs to recognise
47//!   the textual shapes (`for_each`, `for_combinations`,
48//!   `for_each_union`).
49//! - The **scope synthesiser** (in the host)
50//!   needs to emit the Polydat source for each comprehension's child
51//!   kernel — extern declarations for the coordinates, final
52//!   injections for workload params the spec interpolates, etc.
53//! - The **executor** (in the host) needs to
54//!   enumerate the iteration tuples, drive the per-iteration
55//!   `PolydatKernel::for_iteration` (which wires the parent scope
56//!   internally), 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::{ast, cardinality, metadata, source, spec, strategy};
65
66// --- The runtime's reading of the algebra.
67pub mod eval_source;
68pub mod flatten;
69pub mod ir;
70pub mod measure;
71pub mod optimize;
72pub mod predicate;
73pub mod runtime;
74pub mod source_values;
75pub mod strategies;
76pub mod surfaces;
77pub mod validate;
78
79// --- The runtime-evaluation helper both the algebra runtime
80// evaluator and the scope-walker consume.
81pub mod eval;
82pub mod streamer_value;
83pub use streamer_value::StreamerValue;
84
85// --- Canonical algebra re-exports — `polydat::iteration::comprehension::Comprehension`
86// resolves to the algebra type; same for Source, ZipMode, etc.
87pub use ast::Comprehension;
88pub use cardinality::{CardinalityClass, Hybrid, Interval, MeasureName, ProductMeasure};
89pub use eval_source::{EvalClass, EvalContext, EvalError, EvaluatedSource, SourceEval};
90pub use metadata::{IndexFn, Materialization, Metadata, NaturalOrder};
91pub use runtime::{
92    ClauseYield, EvaluatedIteration, IndexedTuples, evaluate_for_iteration,
93    evaluate_for_iteration_materialized, evaluate_for_iteration_reported, evaluate_indexed,
94};
95pub use source::Source;
96pub use strategy::{StrategyName, ZipMode};
97pub use validate::{
98    Mode, NameRead, ReadSite, Surface, ValidationError, ValidationReport, ValidationWarning,
99    check_names, outer_reads, unresolved_names, validate,
100};
101
102// --- Parse-pipeline support re-exports. These are evaluator
103// utilities used by the algebra runtime evaluator and the
104// scope-walker — not part of the comprehension AST surface.
105//
106// `parse_list_with_types` is not re-exported at this level; it
107// remains reachable as `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
