1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
// Copyright 2024-2026 Jonathan Shook
// SPDX-License-Identifier: Apache-2.0
//! # polydat (formerly nbrs-variates)
//!
//! Deterministic variate generation kernel (GK) for workload testing.
//!
//! Transforms named `u64` coordinate tuples into typed output variates
//! via a compiled DAG of composable function nodes. The same coordinate
//! always produces the same outputs — deterministic, reproducible, and
//! parallelizable with zero shared mutable state.
//!
//! ## Quick Start
//!
//! ### From DSL source
//!
//! The simplest way to build a kernel is from GK DSL source:
//!
//! ```rust
//! use polydat::dsl::compile_gk;
//!
//! let mut kernel = compile_gk(r#"
//! input cycle: u64
//! hashed := hash(cycle)
//! user_id := mod(hashed, 1000000)
//! "#).unwrap();
//!
//! kernel.set_inputs(&[42]);
//! let user_id = kernel.pull("user_id").as_u64();
//! assert!(user_id < 1_000_000);
//! ```
//!
//! ### From the assembler API
//!
//! For programmatic construction:
//!
//! ```rust
//! use polydat::assembly::{GkAssembler, WireRef};
//! use polydat::nodes::hash::Hash64;
//! use polydat::nodes::arithmetic::ModU64;
//!
//! let mut asm = GkAssembler::new(vec!["cycle".into()]);
//! asm.add_node("hashed", Box::new(Hash64::new()), vec![WireRef::input("cycle")]);
//! asm.add_node("user_id", Box::new(ModU64::new(1_000_000)), vec![WireRef::node("hashed")]);
//! asm.add_output("user_id", WireRef::node("user_id"));
//!
//! let mut kernel = asm.compile().unwrap();
//! kernel.set_inputs(&[42]);
//! assert!(kernel.pull("user_id").as_u64() < 1_000_000);
//! ```
//!
//! ## Architecture
//!
//! ```text
//! coordinates (u64 tuple)
//! │
//! ▼
//! ┌─────────────────────────┐
//! │ GkProgram (immutable) │ Shared via Arc across threads
//! │ - nodes: Vec<GkNode> │
//! │ - wiring: Vec<Vec<..>> │
//! │ - output_map │
//! └──────────┬──────────────┘
//! │
//! ┌──────┴──────┐
//! │ GkState │ One per thread — no locks
//! │ - buffers │
//! │ - coords │
//! └──────┬──────┘
//! │
//! ▼
//! pull("user_id") → Value::U64(527897)
//! ```
//!
//! ## Compilation Levels
//!
//! The kernel supports four compilation levels:
//!
//! - **Phase 1** (default): Pull-through interpreter. ~70ns/node.
//! - **Phase 2**: Compiled `u64` closures. ~4.5ns/node.
//! - **Hybrid**: Per-node optimal (JIT where supported, closures elsewhere).
//! - **Phase 3**: Cranelift JIT native code. ~0.2ns/node.
//! Requires the `jit` feature (enabled by default).
//!
//! ## Features
//!
//! - **`jit`** (default): Cranelift JIT compilation for Phase 3.
//! Disable with `default-features = false` for a lighter build.
//! - **`vectordata`**: Vector dataset access nodes for ML/AI workloads.
//!
//! ## Modules
//!
//! - [`node`]: Core types — [`node::Value`], [`node::GkNode`] trait,
//! [`node::Port`], [`node::PortType`]
//! - [`kernel`]: Runtime — [`kernel::GkProgram`], [`kernel::GkKernel`],
//! [`kernel::GkState`]
//! - [`assembly`]: DAG construction — [`assembly::GkAssembler`],
//! [`assembly::WireRef`]
//! - [`dsl`]: GK language — [`dsl::compile_gk`], lexer, parser, registry
//! - [`nodes`]: 250+ built-in function nodes (hash, arithmetic, string,
//! math, distributions, datetime, noise, etc.)
//! - [`sampling`]: Alias tables, LUT interpolation, ICD sampling
//! - [`compiled`]: Phase 2 compiled kernel
//! - [`hybrid`]: Per-node optimal compilation
//! - [`jit`]: Phase 3 Cranelift JIT (feature-gated)
//! - [`fusion`]: Graph-level node fusion optimization
//! - [`viz`]: DAG visualization (DOT, Mermaid)