# Node Library
A **node** in Polydat is a typed function registered under a string name.
Once compiled into a function graph, a node becomes a vertex the runtime
evaluates against the current coordinates and upstream outputs. Most nodes are
pure and deterministic. Nodes that intentionally observe runtime context,
publish a side effect, or produce nondeterministic values declare that behavior
in their metadata so the compiler can preserve their semantics.
Workload authors rarely reach for nodes by name. The Polydat DSL and the
op-template binding cascade compose them on the author's behalf — you
write `mod(hash(cycle), 1000)` and the resolver wires `hash` and `mod`
nodes into the graph. The catalog below is the menu the resolver picks
from, not a usage manual.
**Inventory:** Built-in nodes live in
[`polydat-nodes/src/`](../../../polydat-nodes/src/) (the node library) and,
for the nodes the runtime itself needs,
[`polydat-core/src/library/`](../../../polydat-core/src/library/). This
file is a hand-curated snapshot; when the runtime diverges, the source
files are authoritative.
## Engines
The engine parity suite drives 294 coverage programs, one per node or node form, through every engine a host can choose.
Every one of them runs on the interpreter, the closure tier, and P3 (native code where a node has a lowering, its closure elsewhere).
Pure native code, the differential tier behind P3, runs every one of them as well.
---
## Numeric core
The arithmetic and comparison building blocks every workload reaches
for, plus the type-conversion bridges between `u64`, `f64`, and `bool`.
### `arithmetic` — common math operations
`add`, `mul`, `div`, `mod`, `clamp`, `interleave`, `mixed_radix`,
`ceil_to_multiple`, `multiples_at_least`, `div_wire`, `mod_wire`,
`set_or_get`. The `_wire` variants take the divisor as a wire instead
of a const; `mixed_radix` decomposes a `u64` into positional digits
(useful for `(device, reading) := mixed_radix(cycle, 100, 0)` style
coordinate splits).
### `bitwise` — explicit `u64` ops + overflow-checked variants
`u64_add`, `u64_sub`, `u64_mul`, `u64_div`, `u64_mod`, `u64_and`,
`u64_or`, `u64_xor`, `u64_not`, `u64_shl`, `u64_shr`, `checked_add`,
`checked_sub`, `checked_mul`. Distinct from `arithmetic` because the
type discipline is stricter — no implicit f64 coercion — and the
`checked_*` family surfaces overflow as a typed result.
### `math` — trig, exp/log, f64 arithmetic
`sin`, `cos`, `tan`, `asin`, `acos`, `atan`, `atan2`, `sqrt`, `exp`,
`ln`, `pow`, `abs_f64`, `f64_add`, `f64_sub`, `f64_mul`, `f64_div`,
`f64_mod`. The `f64_*` arithmetic is the floating-point counterpart to
`bitwise`'s `u64_*` family.
### `compare` — predicates and ternary selection
`u64_eq`, `u64_ne`, `u64_lt`, `u64_le`, `u64_gt`, `u64_ge`,
`f64_eq`, `f64_ne`, `f64_lt`, `f64_le`, `f64_gt`, `f64_ge`,
`str_eq`, `str_ne`, `select_u64`, `select_f64`, `select_str`. The
`select_*` family is a typed `if (cond, then, else)` returning the
matching branch.
### `convert` — cross-type coercion and rounding
`to_f64`, `f64_to_u64`, `floor_to_u64`, `ceil_to_u64`, `round_to_u64`,
`clamp_f64`, `unit_interval`, `discretize`, `format_u64`, `format_f64`,
`zero_pad_u64`. `unit_interval` maps a `u64` hash to `[0.0, 1.0)` —
the input most distribution-sampling nodes expect.
### `lerp` — interpolation and range remap
`lerp`, `scale_range`, `quantize`. `scale_range` is the common
"map this u64 hash into [low, high]" workhorse.
---
## Determinism and sampling
How polydat turns a single `cycle` integer into reproducible variates
spread across a population — without shared state, without RNG
seeding.
### `hash` — the source of all randomness
`hash`, `splitmix64`, `scatter`, `xxhash3`, `xxh3`, `hash_range`,
`hash_interval`. `hash` maps one `u64` to a 64-bit SplitMix64 hash
(`splitmix64` and `scatter` are the same permutation under explicit
names; `xxhash3`/`xxh3` are the xxHash3 digest); `hash_range` and
`hash_interval` fold the hash into a bounded `u64` range or an `f64`
interval. Chaining `hash(hash(x))` produces independent streams from
the same coordinate without an RNG.
### `pcg` — PCG-RXS-M-XS 64/64 random sequences
`pcg`, `pcg_stream`, `shuffle`, `cycle_walk`. Used when a single
hash isn't enough — e.g., generating an N-element permutation
(`shuffle`) or walking a stream of independent values from one seed.
### `probability` — modeled probabilistic selection
`chance`, `fair_coin`, `unfair_coin`, `one_of`, `one_of_weighted`,
`n_of`, `select`, `blend`, `default_or`, `a`, `b`, `c`. The
single-letter `a`/`b`/`c` are positional outputs of multi-output nodes
(e.g. `pick`).
### `weighted` — convenience weighted-output selection
`weighted_pick`, `weighted_u64`, `weighted_strings`,
`dynamic_weighted_select`. Author-facing shortcuts for the common
"pick one with these weights" pattern; lower-level nodes do the actual
work.
### `partition` — partition-typed indexing ([SRD 71](../design/cursor_partitions.md))
`partitions`, `partition_count`, `partition_at`, `at`, `start_of`, `end_of`, `cardinality`, `idx_of`,
`mod_in`, `clamp_in`. The `Partition` type wraps a closed-open `u64`
range and the partition nodes give type-checked access to its bounds
and to per-index slicing.
### `noise` — coherent noise
`perlin_1d`, `perlin_2d`, `simplex_2d`, `fractal_noise_1d`,
`fractal_noise_2d`. Smooth pseudo-random fields for procedural
landscape / texture / time-series workloads.
---
## Strings, encoding, formatting
### `string` — construction and case
`str_concat`, `str_lower`, `str_upper`, `char_buf`, `combinations`,
`number_to_words`, `hashed_uuid`, `file_line_at`. `combinations`
generates the k-th element of an ordered cross-product over symbol
alphabets — useful for generating "label_01", "label_02", … without
storing the list.
### `format` — printf-style
`printf`. Format-string node accepting positional `{0}`, `{1}` slots.
### `regex` — match and substitute
`regex_match`, `regex_replace`.
### `encoding` — HTML and URL
`html_encode`, `html_decode`, `url_encode`, `url_decode`.
### `digest` — cryptographic hashes and base encoding
`sha256`, `md5`, `to_base64`, `from_base64`.
### `bytebuf` — raw byte assembly
`u64_to_bytes`, `bytes_from_hash`, `to_hex`, `from_hex`. The
hex/bytes nodes are the bridge between integer hashes and on-the-wire
byte payloads.
---
## Structured data
### `json` — construction, merge, projection
`json_text`, `to_json`, `json_to_str`, `json_merge`, `escape_json`,
`array_at`, `array_len`, `body_column_i32`, `normalize_vector`,
`random_vector`. `to_json` accepts a wire and returns its JSON
serialization; `json_merge` composes two JSON objects with right-wins
precedence.
### `datetime` — timestamps and epoch math
`epoch_offset`, `epoch_scale`, `to_timestamp`, `date_components`.
`epoch_scale` + `epoch_offset` together let you map a cycle index
into a timestamp distribution (e.g., "spread 1M events over the last
24 hours").
---
## Runtime context and I/O
These nodes break determinism on purpose — they read state that exists
outside the function graph (env vars, the wall clock, live metrics,
runtime controls). Use sparingly; most workload values should stay
hash-derived.
### `context` — session-scoped state
`counter`, `current_epoch_millis`, `session_start_millis`,
`elapsed_millis`, `thread_id`, `tmp_dir`, `env`, `env_or`, `limit`.
### Registered by hosts (not in this workspace)
None of the names below is registered by any crate in this workspace.
A host such as nmbrs registers them into polydat's node catalog at link
time through the `inventory` channel, so they resolve only in a binary
that links the host crate that defines them.
- **Runtime-context nodes** — declared controls and the host's runtime
axes: `cycle`, `phase`, `rate`, `concurrency`, `control`,
`control_u64`, `control_str`, `control_bool`, `control_set`. The
`control` family reads dynamic controls (SRD-23) declared on the
active component.
- **Live-metric nodes** — `metric`, `metric_window`, `rate`, `mean`,
`p50`, `p99`, `cycles`, `errors`. These read live values from a
session's metrics store and are useful inside `relevancy:` /
stop-condition expressions. They live in the host's metrics crate,
registered through `inventory`; the host's runner installs the query
hook they read from.
### `log_levels` — pass-through logging at each level
`log_debug`, `log_info`, `log_warn`, `log_error`. Each takes a value,
emits it to the named log level, and returns the value unchanged
(taps in a graph for debugging without breaking the data flow).
### `diagnostic` — introspection tools
`inspect`, `debug_repr`, `type_of`, `fft_analyze`. `inspect` is the
on-graph equivalent of a print statement; `type_of` returns the
runtime PortType for debugging type-error chains.
---
## Real-world data and external sources
### `realer` — bundled human-readable datasets
`first_names`, `full_names`, `country_names`, `state_codes`. Backed by
CSV files in [`data/`](../../../polydat-nodes/data/) — Census names, ISO country codes,
US state abbreviations.
### `datafile` — ordinal access to user-provided files
`csv_field`, `csv_row`, `csv_row_count`, `jsonl_field`, `jsonl_row`,
`jsonl_row_count`. Reads a row or field by index from a CSV or JSONL
file the workload points at — the bridge from polydat to arbitrary
tabular data. CSV fields follow RFC 4180 quoting: a field wrapped in
double quotes may contain commas, line breaks, and `""` for a literal
quote, and `csv_field` serves the unwrapped text; unquoted fields are
taken as written.
### `vectors` — vectordata integration (feature `vectordata`)
35 nodes for ML/AI vector dataset access — `dataset_open`,
`dataset_prebuffer`, `vector_at`, `query_vector_at`, `neighbor_indices`,
`neighbor_distances`, `matching_profiles`, `profile_facets`, and many
profile / filter / metadata accessors. Used by recall-benchmark
workloads that need to compare generated query vectors against
pre-computed ground-truth neighbor sets.
---
## Validation and assertion
### `param_helpers` — declarative validation predicates
`required`, `in_range`, `is_positive`, `is_one_of`, `matches`,
`this_or`. Used in op-template parameter validation — fail at compile
time rather than letting a bad param surface at cycle dispatch.
### `exactly_one` — explicit unary unwrap
`exactly_one_value`. Asserts a multi-element structural body has
exactly one element and returns it. SRD-66 §"Surface 4" details
the dispatch contract.
### `assertions` — type and value assertions
Family of nodes (`assert_u64`, `assert_f64`, `assert_str`,
`assert_vec_f32`, `assert_u64_nonzero`, `assert_u64_range`, …)
generated by type/constraint builders rather than registered under
fixed names. Used by the runtime to enforce port-type and
const-constraint contracts at wire boundaries.
---
## Source layout
| [`polyfill_narrow.rs`](../../../polydat-core/src/library/polyfill_narrow.rs) | 87 (narrow-width adapters: `u8`/`i8`/`u16`/`i16`/`f16`) |
| [`polyfill.rs`](../../../polydat-core/src/library/polyfill.rs) | 83 (type-matrix edge adapters: narrowings, sign changes, byte/text views) |
| [`polyfill_128.rs`](../../../polydat-core/src/library/polyfill_128.rs) | 37 (128-bit integer adapters: `u128`/`i128`) |
| [`vectors.rs`](../../../polydat-core/src/library/vectors.rs) | 35 |
| [`polyfill_complete.rs`](../../../polydat-core/src/library/polyfill_complete.rs) | 27 attribute sites, macro-expanded (matrix-completion class-B adapters) |
| [`math.rs`](../../../polydat-nodes/src/math.rs) | 17 |
| [`compare.rs`](../../../polydat-nodes/src/compare.rs) | 17 |
| [`round_numbers.rs`](../../../polydat-nodes/src/round_numbers.rs) | 15 (round-number selectors: base10, decade, fibonacci, binomial, interval) |
| [`probability.rs`](../../../polydat-nodes/src/probability.rs) | 12 |
| [`bitwise.rs`](../../../polydat-nodes/src/bitwise.rs) | 14 |
| [`arithmetic.rs`](../../../polydat-nodes/src/arithmetic.rs) | 12 |
| [`convert.rs`](../../../polydat-core/src/library/convert.rs) | 11 |
| [`json.rs`](../../../polydat-core/src/library/json.rs) | 10 |
| [`context.rs`](../../../polydat-core/src/library/context.rs) | 9 |
| [`vector_math.rs`](../../../polydat-nodes/src/vector_math.rs) | 9 (element-wise vector math: `vec_add`, `vec_dot`, `vec_l2`, `vec_cosine`, `hash_vec`, …) |
| [`sampling/icd.rs`](../../../polydat-nodes/src/sampling/icd.rs) | 9 (inverse-CDF distributions: `dist_normal`, `dist_exponential`, `dist_zipf`, `unit_interval`, …) |
| [`partition.rs`](../../../polydat-nodes/src/partition.rs) | 8 |
| [`string.rs`](../../../polydat-nodes/src/string.rs) | 8 |
| [`hash.rs`](../../../polydat-nodes/src/hash.rs) | 7 |
| [`param_helpers.rs`](../../../polydat-nodes/src/param_helpers.rs) | 6 |
| [`datafile.rs`](../../../polydat-core/src/library/datafile.rs) | 6 |
| [`noise.rs`](../../../polydat-nodes/src/noise.rs) | 5 |
| [`weighted.rs`](../../../polydat-nodes/src/weighted.rs) | 4 |
| [`log_levels.rs`](../../../polydat-core/src/library/log_levels.rs) | 4 |
| [`digest.rs`](../../../polydat-nodes/src/digest.rs) | 4 |
| [`encoding.rs`](../../../polydat-nodes/src/encoding.rs) | 4 |
| [`pcg.rs`](../../../polydat-nodes/src/pcg.rs) | 4 |
| [`bytebuf.rs`](../../../polydat-nodes/src/bytebuf.rs) | 4 |
| [`realer.rs`](../../../polydat-nodes/src/realer.rs) | 4 |
| [`datetime.rs`](../../../polydat-nodes/src/datetime.rs) | 4 |
| [`diagnostic.rs`](../../../polydat-core/src/library/diagnostic.rs) | 4 |
| [`lerp.rs`](../../../polydat-nodes/src/lerp.rs) | 3 |
| [`regex.rs`](../../../polydat-nodes/src/regex.rs) | 2 |
| [`sampling/metashift.rs`](../../../polydat-nodes/src/sampling/metashift.rs) | 2 (LFSR permutations: `shuffle`, `lfsr_step`) |
| [`tile_render.rs`](../../../polydat-core/src/library/tile_render.rs) | 2 (the tile nodes: `tile_encode`, `tile_render`) |
| [`format.rs`](../../../polydat-core/src/library/format.rs) | 1 |
| [`exactly_one.rs`](../../../polydat-core/src/library/exactly_one.rs) | 1 |
| [`emit.rs`](../../../polydat-nodes/src/emit.rs) | 1 (`emit_row`, the binary's `--emit` transform) |
| [`stability.rs`](../../../polydat-nodes/src/stability.rs) | 1 (`is_stable`, steady-state detection) |
| [`streamer.rs`](../../../polydat-nodes/src/streamer.rs) | 1 (`streamer`, the `for` producer node) |
| [`sampling/alias.rs`](../../../polydat-nodes/src/sampling/alias.rs) | 1 (`alias_sample`, Vose alias-table sampling) |
| [`sampling/histribution.rs`](../../../polydat-nodes/src/sampling/histribution.rs) | 1 (`histribution`, inline discrete histogram) |
| [`sampling/lut.rs`](../../../polydat-nodes/src/sampling/lut.rs) | 1 (`dist_empirical`, interpolating lookup table) |
| [`assertions.rs`](../../../polydat-core/src/library/assertions.rs) | (typed family — not name-registered) |
| [`pick.rs`](../../../polydat-nodes/src/pick.rs) | (op-template dispatch primitive) |
| [`random.rs`](../../../polydat-nodes/src/random.rs) | (non-deterministic prototyping) |
| [`fixed.rs`](../../../polydat-core/src/library/fixed.rs) | (const / fixed-value family) |
| [`identity.rs`](../../../polydat-core/src/library/identity.rs) | (identity / constant) |