Crate polydat 

Polydat — a variates construction engine: one function graph, compiled from Polydat source or built programmatically, run on the interpreter, as closures, or as native code, with the same values on every engine.

This crate is the facade over three crates and re-exports each at the paths it always had: polydat_grammar (the language), polydat_core (the runtime), and polydat_nodes (the node library, under library beside the nodes the core keeps). A program that compiles against polydat sees one crate.

Quick start

From DSL source

The simplest way to build a kernel is from Polydat DSL source, on the default engine (native code with the jit feature, closures without):

use polydat::dsl::compile_polydat_kernel;

let mut kernel = compile_polydat_kernel(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:

use polydat::compile::assembly::{PolydatAssembler, WireRef};
use polydat::library::hash::Hash;
use polydat::library::arithmetic::Mod;

let mut asm = PolydatAssembler::new(vec!["cycle".into()]);
asm.add_node("hashed", Box::new(Hash::new()), vec![WireRef::input("cycle")]);
asm.add_node("user_id", Box::new(Mod::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);

(The crate runs no doctests; both examples are tests/rustdoc_examples.rs.)

Documentation

The rustdoc covers the API. The narrative documentation lives in the repository under crates/polydat/docs/, organized by the documentation index.

Re-exports

pub use half;

pub use inventory;

Modules

ast

Core types for Polydat nodes: values, ports, metadata, and the evaluation trait.

audit

Host-log sink bridge — the sanctioned public path for installing a leveled log sink into the kernel (set_log_fn) and for emitting through it (warn / info / …). The activity runner installs its observer::log here so polydat’s cycle-time data-source audit lines land in session.log. This is the one public entry point for the audit channel; the implementation lives under library::support, which is library-internal and must not be reached directly. Cycle-time data-source audit log.

binder

Typed-binding contracts between adapters and the polydat runtime.

compile

Kernel compilation: assembled DAG → fast executable kernel.

convert

Converting a value to a port type, the one way polydat does it (input_variance.md).

derive_support

Trait surface that the #[polydat_node] proc-macro (polydat-derive) calls into for boxing / unboxing wire values.

dsl

The Polydat compiler: from a parsed .polydat program to an assembler and a kernel. The language itself (lexer, parser, AST, pretty printer, pragmas, tile templates) lives in polydat_grammar and is re-exported here at its old paths.

iteration

Iteration & coordinate algebra.

kernel

Polydat runtime kernel: compiled DAG with pull-through evaluation.

library

The node library: the nodes the compiler keeps (polydat_core::library) and the node library (polydat_nodes), side by side at the paths they always had.

numeric

The numeric bodies the node library and the native lowerings share. A node in polydat-nodes is a thin wrapper over a function here, and the JIT helper for that node calls the same function, so the interpreter and native code compute the same bits by construction (compiled_handles.md §6, the corner suite).

resource

Dependency-inverted resource-accessor bridge.

tile

Polytile at the host boundary (polytile.md §5.6): build a tile from template text, from structural JSON text, or from a parsed JSON value, then add it to a program with tile::add_tiles.

viz

DAG visualization for Polydat Kernels.

Structs

Const

Marker wrapper for const arguments in #[polydat_node] function signatures.

EnginePlan

The engine a host chooses and the one error of every constructor that takes it (docs/design/engines.md §3.5). What a kernel’s engine decided for its program: how much of it runs as native segments, as closure steps, and on the interpreter. The one planning detail a kernel exposes, on every engine (Kernel::plan).

ProgramId

One kernel API for every engine, and the one error a write to a declared slot can fail with. WriteError sits beside KernelError at the root because they are the pair a host handles: one for building a kernel, one for writing to it. The identity of a compiled program; see Kernel::program_id.

ResourceScope

The resource-accessor bridge at the crate root: the host implements polydat::ResourceAccessor and installs it into a program tree’s polydat::ResourceScope, which nodes reach through their build context. A program tree’s slot for its host’s ResourceAccessor.

Enums

Engine

The engine a host chooses and the one error of every constructor that takes it (docs/design/engines.md §3.5). The engine a program runs on. Every engine accepts every program the interpreter accepts, or refuses it with a reason (KernelError::Refused); the choice changes how fast the program runs and nothing else (docs/design/engines.md §7).

JitMode

How much of the interpreter’s graph is fused into native cones: what Engine::Interpreter carries. How much of the interpreter’s graph is fused into native cones: the interpreter engine’s one knob, carried by Engine::Interpreter and settable per assembler with set_jit_mode. It is a property of the kernel being built, never of the process: two hosts in one process compiling under different modes get the kernels they each asked for.

KernelError

The engine a host chooses and the one error of every constructor that takes it (docs/design/engines.md §3.5). Why a kernel was not built: the one error type of every constructor that takes an Engine.

Provenance

The engine a host chooses and the one error of every constructor that takes it (docs/design/engines.md §3.5). How much of a kernel’s work is skipped when inputs repeat: the provenance mode a compiled engine is built with. Every mode computes the same values; the modes differ in what they recompute.

ScopeJoinError

The resource-accessor bridge at the crate root: the host implements polydat::ResourceAccessor and installs it into a program tree’s polydat::ResourceScope, which nodes reach through their build context. Why ResourceScope::join left a scope joined to nothing.

Traits

Kernel

One kernel API for every engine, and the one error a write to a declared slot can fail with. WriteError sits beside KernelError at the root because they are the pair a host handles: one for building a kernel, one for writing to it. A kernel on any engine: the interpreter, the closure tier, the hybrid kernel, or pure native code. Every engine accepts every program the interpreter accepts, or refuses it at construction with a reason, and computes the same values for the same inputs; the choice of engine changes how fast a program runs and nothing else. This trait is the surface a host drives an engine through without knowing which one it has.

KernelProgram

One kernel API for every engine, and the one error a write to a declared slot can fail with. WriteError sits beside KernelError at the root because they are the pair a host handles: one for building a kernel, one for writing to it. A program on some engine, shared across threads through an Arc; every kernel created from it computes the same values and owns its own inputs, buffers, and outputs.

ResourceAccessor

The resource-accessor bridge at the crate root: the host implements polydat::ResourceAccessor and installs it into a program tree’s polydat::ResourceScope, which nodes reach through their build context. Type-erased accessor over the host’s live resource store.

SlotKernel

The slot surface of a compiled kernel: the extended API, opt-in at the import, over and above the Kernel trait every engine answers. The slot surface of a compiled kernel: the extended API, over and above the Kernel trait every engine answers.

Functions

set_panic_reporting_downstream

Declare that a downstream reporter will render eval-panic diagnostics in full (see PANIC_REPORTING_DOWNSTREAM).

Attribute Macros

polydat_node

#[polydat_node] — derive a polydat node from a typed Rust function signature.