Skip to content

Core API ​

Exported interfaces are grouped by kind. The entries below come from the revision used to build this site.

Types ​

ReactiveKernels.CompiledReactiveState Type
julia
CompiledReactiveState

An instance of a ReactiveProgram. Values live in typed Ref slots; valid and frozen are runtime state, while all recipe selection and lowering belong to the shared program. Instances are mutable and not thread-safe.

source
ReactiveKernels.DAGVisualization Type
julia
DAGVisualization

An inspectable visualization of a Graph or Plan. Construct one with visualize, display it in a rich Julia frontend for SVG, pass it to dot_source, or save it with save_visualization.

source
ReactiveKernels.DerivativeRule Type
julia
DerivativeRule{Name,N,Inputs}

Callable produced by derivative_rule from one pure-math graph with authored forward and/or reverse branches. Calling it with the N inputs runs the primal cut. forward_cut runs the JVP branch over every direction, reverse_cut runs the VJP branch of one activity pattern, and reverse_residuals says which inputs that cut reads. Backend extensions stage those cuts into their rule protocols. The callable's fields are the cuts' operation tables and lane, the primal cut lowered for a position residual (_lane_kernel), or nothing. Result records the primal's inferred result type for the graph's declared input types, when both are concrete (_promote_op), or is nothing.

source
ReactiveKernels.Graph Type
julia
Graph()

A mutable builder collecting Values and Recipes plus the producer index the planner needs. Building executes nothing.

source
ReactiveKernels.JAXEmissionError Type
julia
JAXEmissionError(message)

A program, or a construct in one of its recipes, that jax_source cannot translate to JAX. The message names the recipe and the construct.

source
ReactiveKernels.JAXFunction Type
julia
JAXFunction

One function of a JAXSource module: its Python name, its parameters inputs and its results outputs (each name => Julia type).

source
ReactiveKernels.JAXSource Type
julia
JAXSource

The Python module jax_source emits: text is the module source and functions the JAXFunctions it defines. prepared maps each value prepare_data returns, by its name in the program, to its key in that dict (a name that is no Python identifier, such as a submodel's b_g.z, has another key). write(path, src) saves the module and print(src) shows it.

source
ReactiveKernels.KernelObjectSpec Type
julia
KernelObjectSpec

A transparent specialization produced by binding kernel-valued ports of a method-bearing @kernel object. Pure endpoint properties such as normal.logpdf are ordinary KernelSpec views; use extract to choose any other named HAVE/WANT cut. Inside another @kernel, a constructed endpoint may bind owner graph ports by name, for example normal(; location = μ, scale = σ, log_scale = log_σ).logpdf(x). Those names form an authoritative HAVE cut and the endpoint graph is spliced transparently. Literal or computed owner values are materialized as hygienic caller recipes.

source
ReactiveKernels.KernelSpec Type
julia
KernelSpec

A declaratively authored kernel graph. graph is the ordinary Graph consumed by the planner, ports maps author-facing names to graph Value objects, and inputs(spec) / outputs(spec) report the default have/want boundary declared by @kernel.

Look up a named port with spec.name or spec[:name]. Dot names matching a KernelSpec storage field (graph, ports, port_order, have_names, want_names, or call_signature) return that field; a colliding port therefore uses bracket lookup. Planning and preparation accept either port names or Values in their have and want overrides.

source
ReactiveKernels.NativeScheduling Type
julia
NativeScheduling(; chunk_size, workers=Threads.nthreads())

Explicit native position-scheduling hints for vectorize and prepare_batched. chunk_size bounds the positions retained in each worker's output buffers; workers is an upper bound, capped by available Julia execution threads and chunks. Both must be positive integers. There is no automatic cost estimate: choose these hints for the workload you measured.

For calls using several position workers, materialized data-only prefix plates also use the worker budget. Their cells share equal-input results within the call; changing data between calls recomputes the prefix. Scalar dependencies, reductions and scans retain their native order.

Ordinary batching stays serial. The schedule applies to native primal calls; an owning batch retains its ordinary serial compiler path. Per-position AD uses the scalar kernel with prepare_ad and replica, independently of this hint.

source
ReactiveKernels.NonAllocatingKernel Type
julia
NonAllocatingKernel

A stateful prepared kernel whose selected single-output recipes are invoked through MutatingFunctions.apply!!. Each recipe owns a persistent typed cache: the first call seeds it and later calls offer it back for in-place reuse.

Each cache slot retains whatever its operation returned on the first call. Registered allocating operations such as copy normally seed fresh kernel-retained storage, but aliasing operations may retain caller-owned inputs, and a no-recipe plan returns its have value directly. Treat mutable results as borrowed values that may alias inputs or be overwritten by later calls. A kernel instance is therefore neither reentrant nor safe for concurrent calls; prepare one instance per independent caller.

A kernel prepared from exemplar arguments (prepare_nonallocating(spec, args...)) is typed for exactly those argument types (S, a Tuple type); calling it with arguments of other types is an ArgumentError. S is Nothing for a kernel typed by its declared HAVE port types.

source
ReactiveKernels.PartitionLocalityError Type
julia
PartitionLocalityError(cell, violations)

Preparation of a plate cell (or partition) with locality = :error found values the cell reads at its rows that would be computed whole. Each entry of violations is a partition_locality entry with status :whole whose reason is not :cascade: the value, its producer's authored source, the reason, and the reader that asked for it at rows.

source
ReactiveKernels.PartitionSeparabilityError Type
julia
PartitionSeparabilityError(cell, label, port, positions, labels)

A partition declared separable in a port (plate_partition's partitioned) reads positions of it that belong to other labels: positions are those positions and labels their labels (:whole when the partition reads the port whole).

source
ReactiveKernels.Plan Type
julia
Plan

The inspectable result of plan(g; have, want): the selected recipes in execution (topological) order, the total graph cost, the ordered have/want value lists, and the per-value producer assignment used for lowering.

source
ReactiveKernels.PlanningError Type
julia
PlanningError

Thrown when a want cannot be produced from have, or when the required computation contains a cycle. Carries a human-readable message.

source
ReactiveKernels.PreparationCache Type
julia
PreparationCache()

A cache of prepared kernels keyed by graph identity+version and the ordered, canonicalized have/want signature plus pass identities (gist §17). Cache lookup happens only in prepare! and in a positional call of a KernelSpec (which keeps its kernel in the graph's own cache), never inside a prepared kernel; a graph mutation bumps its version and so cannot return a stale kernel.

A bound preparation (prepare!(cache, …; bound = …)) is cached one level deeper: the planned boundary, the compiled data-only prefix and the compiled residual body are kept per graph version, have/want/pass signature and bound PORT set, so every later binding of new values to the same ports pays only the prefix's execution (the bound-data mathematics) and a fresh constant table. The entry is keyed on the PORTS, not on the bound values or their types: a later binding of differently typed data on the same ports (a different plan struct, an Int vector for a Float64 one) reuses the entry and its compiled bodies, which are generic over those types and specialize per concrete type on first use like any other Julia call; a lazy branch on a hoisted constant stays a per-call branch and follows each binding's value. An authored plate that reads a bound argument lowers for that argument's class — scalar, vector, rank-N array or tuple — as if its port declared it, so its residual is kept per class: a bound 1:n and a bound Vector domain share one, a bound scalar operand has another. Element types and extents never split it. The cache is caller-owned and grows with the distinct boundaries (and those shapes) prepared through it; it never observes the bound values afterwards and retains none of them. Rebinding is not specialized on the graph's kernel types, so a graph's first rebinding in a process compiles nothing once any graph has rebound. Lookups and first-time preparations hold the cache's lock, so one cache may serve concurrent tasks.

Plain prepare(g; …, bound) and prepare(spec; …, bound) reuse the same bound entries through a cache the graph itself holds (see prepare); a caller-owned cache gives those entries an explicit lifetime instead, independent of the graph's.

source
ReactiveKernels.PreparedADAccumulator Type
julia
PreparedADAccumulator

Prepared additive derivative operator returned by prepare_ad_accumulator. Allocate its destination with ad_accumulator_storage, then add weighted scalar-contraction derivatives with ad_accumulate!.

source
ReactiveKernels.PreparedADHVP Type
julia
PreparedADHVP

A prepared DifferentiationInterface Hessian-vector product for one explicit scalar ReactiveKernels WANT port. Construct one with prepare_ad_hvp, providing a tuple of input tangent exemplars. Calls evaluate one Hessian-vector product per tangent with ad_hvp, ad_hvp! or ad_gradient_and_hvp.

Like PreparedADKernel, the stored differentiation preparation is mutable and not thread-safe. Prepare one object per concurrent caller.

source
ReactiveKernels.PreparedADKernel Type
julia
PreparedADKernel

A prepared DifferentiationInterface gradient for a ReactiveKernels scalar objective. Construct one with prepare_ad, naming one selected HAVE port or an ordered tuple of ports that remain active; every other selected HAVE port is supplied to DifferentiationInterface as a DifferentiationInterface.Constant context. A tuple selector is differentiated as one structured point, so one reverse pass returns a tuple of gradients in the selector's order.

The stored differentiation preparation is mutable and not thread-safe. Prepare one PreparedADKernel per concurrent caller.

source
ReactiveKernels.PreparedADOperator Type
julia
PreparedADOperator{I,K,R,F,B,P,E,O,S}

One prepared DifferentiationInterface operator over a ReactiveKernels boundary. The parameter O names the operator: :gradient (PreparedADKernel), :pullback (PreparedADPullback), :pushforward (PreparedADPushforward), :hvp (PreparedADHVP) or :third (PreparedADThird). Every operator shares the same boundary: one selected HAVE port or ordered tuple of ports is active, every other selected HAVE is rebound on each call as a DifferentiationInterface.Constant context, and the differentiated callable is the exact primal kernel body. Only the DifferentiationInterface preparation stored in the object differs.

The stored preparation is mutable and not thread-safe. Prepare one object per concurrent caller.

source
ReactiveKernels.PreparedADPullback Type
julia
PreparedADPullback

A prepared DifferentiationInterface reverse pullback for one selected ReactiveKernels WANT port or several. Construct one with prepare_ad_pullback, providing an output cotangent exemplar (one per port for several). Calls may then evaluate vector-Jacobian products with ad_pullback or ad_value_and_pullback.

Like PreparedADKernel, the stored differentiation preparation is mutable and not thread-safe. Prepare one object per concurrent caller.

source
ReactiveKernels.PreparedADPushforward Type
julia
PreparedADPushforward

A prepared DifferentiationInterface pushforward (Jacobian-vector product) for one selected ReactiveKernels WANT port, which may be non-scalar, or several. Construct one with prepare_ad_pushforward, providing a tuple of input tangent exemplars. Calls evaluate one Jacobian-vector product per tangent with ad_pushforward or ad_value_and_pushforward.

Like PreparedADKernel, the stored differentiation preparation is mutable and not thread-safe. Prepare one object per concurrent caller.

source
ReactiveKernels.PreparedADThird Type
julia
PreparedADThird

A prepared third-order directional derivative of one explicit scalar ReactiveKernels WANT port: for each input tangent v, the gradient of the Hessian quadratic form, ∇(vᵀ H v), i.e. the contraction D³f[v, v, ·]. Construct one with prepare_ad_third, providing a tuple of input tangent exemplars. Calls evaluate one such vector per tangent with ad_third, ad_third! or ad_gradient_hvp_and_third.

Like PreparedADKernel, the stored differentiation preparation is mutable and not thread-safe. Prepare one object per concurrent caller.

source
ReactiveKernels.PreparedKernel Type
julia
PreparedKernel

A small callable object holding the RGF-generated function, the positional ops tuple, and metadata (graph values in call/return order, the plan, and the lowered AST). Runtime invocation does not consult any planning logic.

source
ReactiveKernels.ReactiveProgram Type
julia
ReactiveProgram

A prepared, inspectable state program produced by prepare_reactive. It contains a single selected Plan, an initialization kernel, compiled lazy getter kernels, and a precomputed dependency graph for invalidation.

source
ReactiveKernels.ReactiveState Type
julia
ReactiveState(g; materialize=(), frozen=nothing)

A stateful convenience layer over a frozen graph g. It owns current source values, monotonic version stamps, selected materialized/cache values with provenance, frozen authoritative values, and a cache of prepared kernels. It does not change planner semantics.

  • materialize nominates intermediate values that should persist across requests (gist §18 materialization boundaries).

  • frozen seeds authoritative frozen values (e.g. from checkpoint), as an id => value mapping.

source
ReactiveKernels.ReactiveValue Type
julia
ReactiveValue

A state-local typed handle returned by statevalue. Keep these handles in hot code: their slot index is a type parameter, so get!, set!, and touch! use literal tuple indices without dictionary lookup.

source
ReactiveKernels.Recipe Type
julia
Recipe

A pure computation mapping input graph values to one or more output graph values via op. RK does not inspect op to prove purity: registering an ordinary recipe asserts this contract. Set effectful=true when the operation is known not to satisfy it; effectful operations are rejected by the stateless planner and therefore cannot enter a prepared kernel or plate. cost is a deterministic planning hint (not measured runtime). cse_key, when non-nothing, opts the operation into structural CSE (gist §8). source is optional authored-RHS metadata for cold-path readable rendering; it is kept on the planning recipe rather than the executable operation so it never enters prepared hot-state tuples. recipe_kind classifies a recipe as an authored plate, an authored scan or an ordinary recipe.

source
ReactiveKernels.ReplicatedKernel Type
julia
ReplicatedKernel

A callable produced by replica. It preserves a scalar prepared kernel as the single source of truth and maps that complete callable over a trailing replica axis on selected HAVE ports.

source
ReactiveKernels.ScalarDerivativeRule Type
julia
ScalarDerivativeRule{Name,N,Inputs}

Callable produced by scalar_derivative_rule. Calling it with N scalar arguments runs the primal cut of its graph (want = primal), so as a function it is exactly the authored primal formula, generic over the argument types. The activity-selected cuts are reached through derivative_cut; backend extensions attach their rule protocols to Const{<:ScalarDerivativeRule} and read the partials from those cuts. The callable is an immutable value whose only fields are the cuts' operation tables (an isbits value when those operations are singletons), so a closure capturing it needs no activity annotation.

source
ReactiveKernels.TraceableSource Type
julia
TraceableSource(argument_names, body, mod::Module)

The Julia source of one method, as a package that generates the method hands it to jax_source through register_source_provider!: the method's formal names in order, its body, and the module whose globals the body reads. jax_source translates a call of the method from this body as it translates an @traceable body: a for loop becomes jax.lax.fori_loop, an if becomes jax.lax.cond, A[i] = v becomes A.at[i].set(v), and prepare_data runs the body as host Python with Python loops and branches.

The body is one expression whose value is the method's result. Body-level early returns become lazy conditional expressions; returns inside loops remain unsupported. Code that runs inside the JAX functions takes the subset an @traceable body takes there: no break, and a for binds one name over one range. A continue keeps the current carry and skips the rest of that iteration. prepare_data also supports break. Static parameters of the method (where T) are not bound: the body reads its arguments and the globals of mod.

Native execution, prepare and the compiled paths never read the source: the method itself runs there.

source
ReactiveKernels.TypeInstabilityError Type
julia
TypeInstabilityError(messages)

Thrown by a preparation checked with type_stability = :error when the prepared program is not type stable at the checked type_stability_level. messages holds one message per finding, as the warning of the default type_stability = :warn words it: a value whose type the program does not infer concretely, or a method whose code holds non-concrete values or calls dispatched at run time.

source
ReactiveKernels.Value Type
julia
Value{T}

A stable graph identity for a runtime value of Julia type T. id is the identity (a ValueId, unique across processes and package images); name exists only for diagnostics and for generated-code readability. Values are immutable and cheap to hash/compare.

source

Functions ​

Base.get! Method
julia
get!(state, want) -> value(s)

Compute want (a Value or tuple of Values) incrementally: form the effective HAVE set, plan/prepare the minimal missing computation (reusing a cached kernel when the effective signature repeats), execute it, persist any nominated materialization boundaries with provenance, and return the requested values (a scalar for one want, a tuple otherwise).

source
ReactiveKernels.ad_accumulate! Method
julia
ad_accumulate!(prepared, destination, direction, weight, args...)

Add weight * ∇Dⁿf[direction,…] to destination, where n is the prepared order, and return the weighted scalar contraction. For order zero pass direction = nothing. Destination arrays and refs must match the active point's types and shapes and must not alias primal inputs. No destination is cleared or copied; a repeated call adds another contribution. A direction follows the directional selector's structure, not the full active boundary. weight and the direction are held fixed in the enclosing reverse pass.

source
ReactiveKernels.ad_accumulator_storage Method
julia
ad_accumulator_storage(prepared, args...)

Allocate zero derivative storage for the active boundary of a PreparedADAccumulator at args. Do this once per accumulation pass, or reuse and zero the storage between passes, not between individual terms.

source
ReactiveKernels.ad_gradient Method
julia
ad_gradient(spec, backend, args...; active, want, kwargs...)
ad_gradient(kernel, backend, args...; active)
ad_gradient(prepared, args...; kwargs...)

Compute a gradient with respect to one named active HAVE port or an ordered tuple of ports. The KernelSpec form selects an explicit scalar want and preserves authored defaults and keywords. The low-level PreparedKernel / NonAllocatingKernel forms require an already selected, positional, single-scalar boundary. The reusable form uses a PreparedADKernel returned by prepare_ad. Tuple selectors return tuple gradients in the same order from one differentiation call.

The one-shot forms require the backend's package to be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension.

source
ReactiveKernels.ad_gradient_and_hvp! Method
julia
ad_gradient_and_hvp!(prepared, gradient, results, tangents, args...; kwargs...)

In-place form of ad_gradient_and_hvp: writes the gradient into gradient and the Hessian-vector products into results, a tuple holding one destination array per direction. Returns (gradient, results).

source
ReactiveKernels.ad_gradient_and_hvp Method
julia
ad_gradient_and_hvp(prepared, tangents, args...; kwargs...)

Evaluate the gradient of the prepared scalar WANT and one Hessian-vector product per input tangent at one point. Returns (gradient, hvps). With a reverse-over-forward backend (SecondOrder(reverse, forward)) the gradient takes one sweep of the reverse backend and each Hessian-vector product one sweep of the Hessian-vector backend.

source
ReactiveKernels.ad_gradient_hvp_and_third! Method
julia
ad_gradient_hvp_and_third!(prepared, gradient, hvps, thirds, tangents,
                           args...; kwargs...)

In-place form of ad_gradient_hvp_and_third: writes the gradient into gradient, and the Hessian-vector products and third-order derivatives into hvps and thirds, tuples holding one destination array per direction. Returns (gradient, hvps, thirds).

source
ReactiveKernels.ad_gradient_hvp_and_third Method
julia
ad_gradient_hvp_and_third(prepared, tangents, args...; kwargs...)

Evaluate, at one point, the gradient of the prepared scalar WANT and, per input tangent v, the Hessian-vector product H v and the third-order directional derivative ∇(vᵀ H v). Returns (gradient, hvps, thirds). The gradient takes one sweep of the outermost backend, each Hessian-vector product one sweep of the Hessian-vector backend, and each third-order derivative one sweep as in ad_third.

source
ReactiveKernels.ad_hvp! Method
julia
ad_hvp!(prepared, results, tangents, args...; kwargs...) -> results

Evaluate the Hessian-vector products of ad_hvp into caller-owned results, a tuple holding one destination array per direction.

source
ReactiveKernels.ad_hvp Method
julia
ad_hvp(prepared, tangents, args...; kwargs...) -> Tuple

Evaluate one Hessian-vector product of the prepared scalar WANT per input tangent in tangents, returning a tuple of results in the same order. tangents must hold as many directions as the preparation exemplar.

source
ReactiveKernels.ad_pullback Method
julia
ad_pullback(spec, backend, seed, args...; active, want, kwargs...)
ad_pullback(kernel, backend, seed, args...; active)
ad_pullback(prepared, seed, args...; kwargs...)

Evaluate a reverse pullback for one output cotangent seed, returning the cotangent of the selected active HAVE port. For a vector-valued WANT this is the vector-Jacobian product J' * seed; constructing a full Jacobian still requires multiple seeds. Over several WANT ports, seed holds one cotangent per port and the result is the sum of their vector-Jacobian products, from one primal and one reverse sweep (see prepare_ad_pullback). A seed or argument that shares memory with a value an earlier call on the same prepared non-allocating pullback returned is copied first (see ad_value_and_pullback).

The one-shot forms require the backend's package to be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension.

source
ReactiveKernels.ad_pushforward Method
julia
ad_pushforward(prepared, tangents, args...; kwargs...) -> Tuple

Evaluate one Jacobian-vector product of the prepared WANT per input tangent in tangents, returning a tuple of output tangents in the same order. Each output tangent has the WANT's structure: over several WANT ports, a tuple with one tangent per port. tangents must hold as many directions as the preparation exemplar.

source
ReactiveKernels.ad_retains_primal_sweep Method
julia
ad_retains_primal_sweep(backend) -> Bool

Whether backend's gradient evaluates the differentiated target once at the requested point and keeps the target's writes, so WANT values retained during that sweep (prepare_ad(...; retain)) are the primal values at the point. Core RK knows no AD engine, so the default is false; the engine's package extension declares its supporting modes (ReactiveKernels' Enzyme extension: reverse-mode AutoEnzyme). A backend that perturbs the point (finite differences), carries dual numbers, or restores mutated memory in its reverse pass (Mooncake) must stay false.

source
ReactiveKernels.ad_third! Method
julia
ad_third!(prepared, results, tangents, args...; kwargs...) -> results

Evaluate the third-order directional derivatives of ad_third into caller-owned results, a tuple holding one destination array per direction.

source
ReactiveKernels.ad_third Method
julia
ad_third(prepared, tangents, args...; kwargs...) -> Tuple

Evaluate one third-order directional derivative ∇(vᵀ H v) of the prepared scalar WANT per input tangent v in tangents, returning a tuple of results in the same order, each shaped like the active point. tangents must hold as many directions as the preparation exemplar.

source
ReactiveKernels.ad_value_and_gradient! Method
julia
ad_value_and_gradient!(prepared, gradient, args...; kwargs...)

Compute the scalar value and gradient for a reusable PreparedADKernel, writing the gradient into gradient. Runtime arguments follow the original RK HAVE boundary; the prepared active port or ordered tuple of ports is reordered to DI position one, and every other current argument is rebound as a fresh DifferentiationInterface.Constant context. For a tuple selector, gradient is a matching tuple of mutable destinations. Reverse Enzyme can fill matching tuples of disjoint dense arrays and scalar Refs directly when the prepared call has DI contexts, and also without contexts when Enzyme reports dogfood repair structured_gradient_inplace. Other destination shapes and backends copy the structured gradient after the same single reverse pass. Before that copy writes anything, a tuple of another length, a named tuple with other keys, an array of another length or an unsupported destination raises. Scalar normalization storage is owned by the preparation and reused by mutating calls.

Returns the (value, gradient) pair from DifferentiationInterface.value_and_gradient!. The destination must be valid for the active argument's gradient and is mutated in place. Like ad_gradient, this prepared object and its DI preparation are not thread-safe; use one per concurrent caller.

source
ReactiveKernels.ad_value_and_gradient Method
julia
ad_value_and_gradient(prepared, args...; kwargs...)

Compute a scalar value and gradient without requiring caller-owned gradient storage. This is the structured counterpart to ad_value_and_gradient!: it preserves DifferentiationInterface's returned cotangent structure, including NamedTuple active inputs supported by the backend.

source
ReactiveKernels.ad_value_and_pullback! Method
julia
ad_value_and_pullback!(prepared, cotangent, seed, args...; kwargs...)

Evaluate the selected WANT and reverse pullback while writing the active-input cotangent into caller-owned cotangent storage. Returns (value, cotangent). For a scalar active selector, the destination must satisfy the differentiation backend's in-place pullback contract. For a tuple selector, supply a matching tuple of mutable arrays or Ref destinations; the structured cotangent is copied into them after the one reverse pass. A tuple of another length, a named tuple with other keys, an array of another length or an unsupported destination raises before anything is written.

The destination may share memory with the seed, the active point, another argument or a borrowed value of the same preparation (see ad_value_and_pullback). The call then computes into an owned temporary and copies the cotangent into the destination, and a returned value that overlaps the destination is returned as a copy. A disjoint destination is written directly.

source
ReactiveKernels.ad_value_and_pullback Method
julia
ad_value_and_pullback(prepared, seed, args...; kwargs...)

Evaluate the selected WANT and its reverse pullback together. Returns (value, active_cotangent), unwrapping DifferentiationInterface's one-direction tuple. A tuple active selector produces a tuple cotangent in the selector's order; several WANT ports produce the tuple of their values. The prepared object is reusable with new runtime arguments and seeds compatible with its preparation exemplars.

A pullback prepared from a NonAllocatingKernel can return its values in storage the preparation owns: such a value is borrowed, and the next call on the same preparation overwrites it, so copy a value to keep it past that call. A later call may take such a value, or storage overlapping it, as the seed or an argument. That input is then copied before the call, so the call uses the contents the input had when it was made; an input that shares no memory with the preparation's storage is used as passed.

source
ReactiveKernels.ad_value_and_pushforward Method
julia
ad_value_and_pushforward(prepared, tangents, args...; kwargs...)

Evaluate the prepared WANT and one Jacobian-vector product per input tangent together. Returns (value, output_tangents); see ad_pushforward.

source
ReactiveKernels.ad_value_gradient_and_retained! Method
julia
ad_value_gradient_and_retained!(prepared, gradient, args...; kwargs...)

Like ad_value_and_gradient!, for a PreparedADKernel prepared with retain: returns (value, gradient, retained), where retained is a NamedTuple of the retained WANT values computed by the same primal sweep as value. No separate primal call runs. Each call stores fresh retained values; a previously returned retained is not modified.

source
ReactiveKernels.ad_value_gradient_and_retained Method
julia
ad_value_gradient_and_retained(prepared, args...; kwargs...)

Out-of-place counterpart of ad_value_gradient_and_retained!: returns (value, gradient, retained) from one reverse pass, preserving the structured gradient as ad_value_and_gradient does.

source
ReactiveKernels.add! Method
julia
add!(g, inputs => outputs, op; cost=1.0, cse_key=nothing, effectful=false)
add!(g; inputs, outputs, op, cost=1.0, cse_key=nothing, effectful=false)

Register a recipe (inputs...) --op--> (outputs...). inputs/outputs may be a single Value or a tuple of Values. Referenced values are auto-registered. Returns the Recipe.

source
ReactiveKernels.batched_ports Method

Names of HAVE ports carrying the shared trailing batch axis.

source
ReactiveKernels.canon_id Method
julia
canon_id(g, id) -> ValueId

Resolve a value id to its structural-CSE canonical representative (gist §8). Absent any structural CSE this is the identity.

source
ReactiveKernels.checkpoint Method

Checkpoint valid derived values for a later program(...; frozen=cp) instance.

source
ReactiveKernels.checkpoint Method
julia
checkpoint(state, values) -> Dict

Package the current runtime values of values (which must already be present, e.g. via a prior get!) into an id => value mapping suitable for seeding a new ReactiveState(g; frozen=cp) for cross-phase replay (gist §18).

source
ReactiveKernels.code_expr Method
julia
code_expr(spec_or_plan_or_kernel) -> Expr

The generated Julia Expr before RGF compilation. A KernelSpec or Graph is planned at its default boundary unless have/want are given. A Plan is lowered to its generated expression; a prepared kernel returns its stored expression. Useful for asserting that unused operations are literally absent.

source
ReactiveKernels.compile Method
julia
compile(ast::Expr) -> callable

Compile a lowered Expr into a native Julia function via RuntimeGeneratedFunctions. The returned callable takes (constants, callables, args...). Prepared callables may be stored as package-level constants: during package precompilation, the package being compiled owns the generated expression cache. Global names in the lowered body still resolve in ReactiveKernels. The callable does not hold the expression; the cache retains it for RuntimeGeneratedFunctions.get_expression. A program that a loaded package image compiled returns that image's generated function, with the code the image compiled for it.

source
ReactiveKernels.compose Method
julia
compose(specs::KernelSpec...; boundary=:base) -> KernelSpec

Compose declarative specs by named ports. The default preserves the first spec's boundary through every merge. boundary=:fragment explicitly adopts the final spec's boundary. To join a port to a value of another name, rename the port first with ReactiveKernels.rename.

source
ReactiveKernels.compose Method
julia
compose(graphs...) -> Graph

Merge several graphs into one. Because Value identities are process-global, a value shared between fragments is automatically the same node in the result — composition preserves stable value identity with no explicit port mapping (gist §13). Structural-CSE aliases are carried over and duplicate recipes across fragments coalesce.

source
ReactiveKernels.copy_group! Method
julia
copy_group!(state, dest_handles, src_handles)

Copy each source slot in src_handles into the paired destination slot in dest_handles, in place where the value is an array (buffer reused, 0-alloc), then invalidate each destination's downstream. Every destination handle must be a declared HAVE source; sources may be any readable slot. This is an additive composition over the HAVE-boundary API — it changes no invalidation or copy internals — and is the group-copy building block for phase-point proposal/endpoint bookkeeping. dest_handles and src_handles are equal-length tuples of ReactiveValue handles; the pairing is walked by type-stable tuple recursion so a homogeneous array group copies with zero allocation.

Pairs are applied sequentially, left to right, and an array destination is mutated in place. Overlapping destination/source groups are therefore order-dependent and generally NOT a swap: copy_group!(state, (a, b), (b, a)) copies b into a first, so both end holding the original b. To exchange two groups, route through a temporary group (t ← a, a ← b, b ← t) — the allocation-free idiom the sampler uses for endpoint/proposal swaps. Sources are read (get!) before their paired destination is written, but later pairs see earlier destinations' new values.

source
ReactiveKernels.derivative_cut Method
julia
derivative_cut(rule::ScalarDerivativeRule, active::NTuple{N,Bool}, args...)
    -> (y, ∂y/∂xᵢ for every active i, in input order)

Run the cut of the rule's graph that computes the primal together with the partials of the inputs flagged active. The cut is selected from the activity pattern alone, so a backend adapter whose activity pattern is a compile-time property of the call signature reaches one concretely typed cut; inactive inputs cost nothing beyond the primal. At least one input must be active.

source
ReactiveKernels.derivative_rule Method
julia
derivative_rule(graph::KernelSpec; primal, directions, tangent, covector,
                cotangents, name) -> DerivativeRule

Generate an RK-owned callable from one pure-math graph that authors its own derivative branches. The graph's HAVE ports are the function's inputs plus, optionally, one direction port per input and one covector port; its WANT ports include the primal output and, matching the supplied branches, the tangent output and one cotangent output per input.

Calling the returned rule evaluates the primal cut. The forward branch (directions + tangent) and the reverse branch (covector + cotangents) are each optional, but at least one must be given; every AD adapter is generated from the cuts of this one graph, attached to the returned callable. Inputs are the HAVE ports that are neither directions nor the covector, in HAVE order.

Each mapping must name every input in that order. A literal nothing entry declares a data-only input, with no corresponding graph port, for example cotangents = (x = :x_bar, geometry = nothing) and directions = (x = :x_dot, geometry = nothing). When both branches are given, their data-only declarations must agree. Data still participates in the primal and any derivative that reads it; requesting its derivative is an error. Enzyme callers pass it as Const, and ChainRules pullbacks return NoTangent() for it. A symbol naming a graph output that returns nothing does not declare a data-only input.

The graph may hold plates, scans and embedded kernels, in any branch. A cut that runs one is compiled from its native lowering, so its values are those of prepare(graph; have, want). In a position residual (vectorize, prepare_batched) the primal cut fills lane buffers like the same mathematics spliced into the caller.

Reverse staging selects the primal and active cotangents together using the graph's declared recipe costs, then splits that selected plan at the covector boundary. This can reuse a joint producer that an independently selected VJP would miss. Costs do not model tape storage or measured execution time. If the selected primal needs the covector, staging keeps the independent cuts.

source
ReactiveKernels.dot_source Method
julia
dot_source(graph_or_plan; alternatives=false, orientation=:horizontal) -> String
dot_source(visualization) -> String

Return a Graphviz DOT description. DOT is generated without invoking Graphviz and can be stored, diffed, or rendered by any compatible external tool.

source
ReactiveKernels.explain Method
julia
explain(p::Plan) -> String

Human-readable account of the plan: the have/want boundary, the selected recipes with costs, the total cost, and the backward-reachable alternatives that were not selected (gist §16).

source
ReactiveKernels.extract Method
julia
extract(spec::KernelSpec; have=inputs(spec), want=outputs(spec)) -> KernelSpec

Create a transparent named-boundary view of spec. The returned value shares the same ordinary graph and named ports; only its default HAVE/WANT boundary is changed. Planning and preparation therefore use exactly the same recipes as an explicit plan(spec; have, want) call.

source
ReactiveKernels.extract Method
julia
extract(object; have, want) -> KernelSpec

Splice every pure endpoint template and bound child kernel into one ordinary named graph, then return the requested boundary view. Supplying an endpoint as want automatically adds its parameter ports to the default HAVE boundary.

source
ReactiveKernels.forward_cut Method
julia
forward_cut(rule::DerivativeRule, inputs..., directions...) -> (y, ẏ)

Run the graph's JVP branch: the primal together with the tangent for the given directions (one per differentiable input, in input order; an inactive differentiable input takes a zero direction). Data-only inputs have no direction argument. Requires the rule to have a forward branch.

source
ReactiveKernels.freeze! Method
julia
freeze!(state, v::Value, x)

Install x as an authoritative frozen value for v, deliberately detached from upstream provenance. It is reused without upstream validation until replaced or unfrozen (gist §18 replay/checkpoint).

source
ReactiveKernels.freeze! Method

Install and freeze a derived slot, invalidating only its downstream consumers.

source
ReactiveKernels.freeze! Method

Freeze the current value of a derived slot as an authoritative cut point.

source
ReactiveKernels.has_forward_branch Method
julia
has_forward_branch(rule::DerivativeRule) -> Bool
has_reverse_branch(rule::DerivativeRule) -> Bool
source
ReactiveKernels.inputs Method

Graph values in positional call order.

source
ReactiveKernels.jax_source Method
julia
jax_source(spec::KernelSpec; have, want, types = nothing, name = :kernel,
           float_type = Float64) -> JAXSource
jax_source(spec::KernelSpec; have, functions, types = nothing, constants = (;),
           doc = nothing, float_type = Float64, rejecting = ()) -> JAXSource
jax_source(p::Plan; types = nothing, name = :kernel, doc = nothing,
           float_type = Float64) -> JAXSource

Translate the program that computes want from have into a Python module whose function name takes the HAVE values, in order, and returns the WANT value (a tuple for several WANTs), computed with jax.numpy. With functions, a NamedTuple of function name => WANT, the module defines one function per entry over the same HAVE values; a WANT is a value name, a tuple of them (the function returns a tuple) or a NamedTuple of key => value name (it returns a dict). constants, a NamedTuple, adds module-level constants (numbers, strings, symbols, vectors, tuples, named tuples and dictionaries of these). function_docs, a NamedTuple of function name => text, gives functions their docstrings; the others state what they compute. Module functions annotate their parameters (ArrayLike) and results.

Where a numerical method cannot produce a value at a valid input (natively a ReactiveKernels.NumericalFailure: an ODE solve that exceeds its per-output budget or fails), a module function raises, as the native program throws, except that the functions rejecting names (function names of functions, each with one WANT value) answer -inf, as a log density outside the model's support does. The failure is a jax.experimental.checkify check, which JAX carries out of every vmap, scan, cond and loop, so a plate cell's or scan step's failure rejects the whole evaluation, under jax.jit, jax.grad and jax.vmap too; a gradient there is unspecified. Only a module that can fail so wraps its functions in checkify, and its other runtime checks are checkify checks too: the first failure in program order decides, as the native program stops at its first throw, so a check on a failed solve's state (a solve continuing from it) neither raises nor hides the failure. Such a module needs a JAX whose checkify has checkify.Error.has_error and differentiates a custom_vjp (every diffrax solve) after a check. No JAX release has either yet: jax 0.12.0.1 gives a wrong or failing gradient there (benchmark/repro_jax_checkify_custom_vjp_control_flow.py). Branch jax-v0.12.0.1-checkify of https://github.com/nsiccha/jax carries both; without them, the module refuses to import.

The module docstring starts with the generated line Generated by ReactiveKernels.jax_source; do not edit. doc adds the author's description of the program after it, separated by a blank line: a string, or a Julia docstring such as @doc TOY_KERNEL (its Markdown text). A docstring written above a const binding of a kernel belongs to the binding, not to the kernel value jax_source receives, so the caller passes it. Docstrings keep their text as written: backslashes and quotes are escaped in the Python source.

types gives each HAVE value's Julia type, as a NamedTuple by port name or a tuple in HAVE order; by default the ports' declared types are used, and they must be concrete. Value ranks follow from these types, so the module is generic in array sizes: one module serves every size of the same program.

float_type (Float64, the default, or Float32) is the dtype of every float value the program does not type Float32 itself: Julia's default Float64 values, the inputs and data among them, are float32 in a module emitted with float_type = Float32, for an accelerator whose float64 is slow. Such a module casts its float inputs to float32, prepare_data returns float32 data, and the dtype metadata says so. It does not turn on JAX's 64-bit mode (jax_enable_x64), so its device integers are JAX's default (int32), unless it rounds an fma once, which takes a float64 product; it stays float32 where another module turned that mode on. Its results carry float32 rounding: compare it with the Float64 module of the same program at a tolerance relative to eps(Float32) and the size of the value.

The translation keeps the program's structure. A plate is jax.vmap of its cell, a scan is jax.lax.scan of its step, a lazy branch is jax.lax.cond of its arms, and nothing is unrolled per element. Arrays keep Julia's dimension order, Julia's broadcasting rules are kept, and integer index data stay 1-based. Gradients are jax.grad of a function. A construct without a translation raises a JAXEmissionError naming its recipe.

A bounded for loop, generator, comprehension or slice over a range takes a shape-bounded number of steps, so jax.grad reverses it. Static ends and a stop that is a padded row's length have such a bound. So do ends that are entries of integer arrays of the prepared data (data): for starts[r]:stops[r], entries of two arrays at one position (also a plate cell's entries of both), it is the longest such range; for one end that is data, the largest stop less the least start. prepare_data computes these bounds and returns them with the data, under keys starting with _rk_. A range from or to an element of another such range, or of a static range (for j in i:n), is bounded by that range's ends. A step past a range's stop is a lazy branch (jax.lax.cond) that leaves the loop's values unchanged and reads nothing, so Julia's values and derivatives, empty ranges included, are kept; the work is the bound for every range, so a long range among short ones costs each of them its length. A for or while loop without a shape bound retains a runtime loop. JAX cannot reverse that loop directly; an owned derivative_rule supplies the authored reverse graph when one is available. Generators and slices still need a capacity bound for their output storage. A range known to be empty from shapes runs no JAX loop, so its body's empty-array reads are not traced.

source
ReactiveKernels.kernel_graph Method

The underlying low-level Graph for a declaratively authored kernel.

source
ReactiveKernels.lower Method
julia
lower(p::Plan) -> Expr

Lower a plan to an ordinary anonymous-function Expr of the form

function (__constants__, __callables__, x::T1, y::T2)
    a = let var"#x#op1" = x, var"#y#op1" = y
        <the first recipe's source over x and y>
    end
    b = (__callables__[2])(a)
    c = __constants__[3]
    ...
    return out
end

A recipe's authored source runs in the body over its arguments (inline_sources.jl); a bound constant is read from the constants table; an operation whose code is not its source (a plate, a scan, a raw function, a branch) is called through the callables table. Both tables have one entry per lowered recipe, at the recipe's position.

This Expr is a first-class artifact: it may be inspected (code_expr) and rewritten (transform) before compilation (gist §9). Pair it with its tables via lower_with_ops.

source
ReactiveKernels.lower_batched Method
julia
lower_batched(p::Plan; batched, reduce = :+) -> Expr

Lower a pure plan to a batched, dependency-stratified kernel. The batched HAVE ports participate in ordinary Julia broadcasting: compatible axes zip, singleton dimensions expand, scalars repeat, and Ref(x) keeps an array-valued input atomic. Broadcast axes are instantiated and checked before any recipe or output mutation executes.

Every recipe inherits the transitive set of batched HAVE ports it depends on. During Cartesian broadcast traversal, its scalar result is recomputed only when a kept broadcast dimension of one of those roots changes. This is equivalent to placing the recipe at the narrowest valid nested-loop boundary: an outer-only scale transform runs once per scale coordinate and is reused through all inner coordinates without an intermediate buffer. Recipes independent of every batched port are emitted once above the traversal.

The single scalar want is accumulated by reduce (default :+, a sum). Pass reduce=nothing to collect the broadcast-shaped pointwise wants instead; only that requested output is materialized.

Restricted (this lowering) to single-output recipes and a single scalar want that is itself batched (the per-element density). reduce is spliced as a bare callee, so use a Base reducer symbol (:+).

source
ReactiveKernels.lower_with_ops Method
julia
lower_with_ops(p::Plan; inline_embedded=false) -> (ast, constants, callables, recipes)

Lower a plan to an executable straight-line function Expr plus the two tables it reads. ast is function (__constants__, __callables__, ports...) ... end over the plan HAVE ports in order; constants[i] is the value the body reads as __constants__[i] (a bound constant's), callables[i] the operation it calls as __callables__[i], each nothing where the body does neither (a recipe whose source runs in the body); recipes is the parallel recipe metadata, one per table position.

Evaluate functionally with compile (or eval) and call with the tables first:

ast, constants, callables, _ = lower_with_ops(p)
f = compile(ast)
f(constants, callables, port_values...)

lower(p) is first(lower_with_ops(p)). With inline_embedded = true embedded prepared kernels are spliced as statements (the form prepare compiles) instead of calls through the table.

source
ReactiveKernels.materialize! Method

Add materialization boundaries after construction.

source
ReactiveKernels.mutate! Method
julia
mutate!(state, source) do value
    ...
end

Mutate the stored object for a declared HAVE source, then automatically mark it changed and invalidate its downstream slots. Invalidation also runs if the mutation throws, because the object may already have been modified.

source
ReactiveKernels.outputs Method

Graph values in return order.

source
ReactiveKernels.partial_evaluation Method
julia
partial_evaluation(p::Plan, bound, values) -> Plan

The general partial-evaluation pre-pass. bound names the HAVE ports (as Values) whose runtime values are fixed for this binding; they must form a subset of p.have. The data-only prefix — every recipe whose transitive inputs reach only bound ports — is prepared and executed exactly once, inside this call. The result is an ordinary residual Plan whose HAVE boundary is the remaining ports, with each hoisted value re-entering as a zero-input _BoundConstant recipe, so every preparation surface consumes it unchanged and per-call work contains no data-only recomputation.

For a residual authored plate(...) do with a transparent scalar plan, named bound-only inner recipes are also evaluated at preparation. Each recipe uses only its bound inputs' broadcast coordinates, so a prefix with singleton axes is not expanded to a larger live domain. Boolean, standard 8–64-bit integer, and Float16/32/64 results needed by the residual, and dense Arrays of those element types (a per-cell index list, for example), enter as additional ordinary plate inputs; per-cell arrays are cached as an array of arrays and, like every bound or hoisted value, are shared read-only by later calls. Intermediate prefix values need only a concrete type. The original arguments remain available for shape and marker validation: their storage is retained even if the scalar residual no longer reads their elements. This trades setup and cache storage for repeated computation; inexpensive recipes need not run faster. Rebinding rebuilds these caches.

When the cell result itself reads only bound data and every other plate input is atomic (Ref), the plate's whole result is computed at preparation and replaces the plate. Its consumers that then read only bind-time values, such as reduce(vcat, cells; init = Float64[]), are computed at preparation as well, so no evaluation reads the shared hoisted storage. A cell result that is such an array but sits beside a live non-atomic input keeps its original per-cell execution: caching it would store the same shared arrays in every evaluation's output.

The inner pass retains the original plate for known empty domains. A live array whose declared type fixes its rank (whatever its element type), each of whose dimensions a bound axis of length greater than one fixes, cannot change which cells the plate visits; live numeric scalars and explicit atomic inputs do not contribute dimensions. Any other live input could make the domain smaller than the bound one, or empty, so the eligible computations run over the bound domain and the original plate is retained if any of them throws: preparation never raises an error that no evaluation of the original plate would. Their cached values serve every cell the plate visits, as they vary only along bound axes. Other exclusions are non-array/non-numeric batched bound inputs, non-concrete prefix results and overlapping inner producers. A nested plate, scan or embedded prepared kernel is never evaluated here: it stays in the residual cell, as does the producer of any data-only value that is neither such a number nor a dense Array of them (a tuple, struct, view or range); the cell's other eligible values are still cached. Ordinary recipe purity remains required. Like top-level partial evaluation, eligible computations execute eagerly at preparation over their bound domain.

A recipe, at top level or in such a cell, that reads bound and live values alike is split where its authored expression allows (_KernelSplit): each maximal strict subexpression that reads only bound data and calls more than cheap arithmetic (loggamma(n + 1.0) - loggamma(y + 1.0) beside a live logit, log(y) beside a live location) becomes a recipe of its own, computed once per binding (per lane in a cell), and the remainder reads its value. Branch arms, short-circuit operands, generators and closures are not entered, so no part runs where its expression would not; a data-bound branch arm is split after the plate partitions its lanes. The parts apply the authored operations to the same operands in the same order, so values are unchanged; nothing is algebraically simplified or reassociated.

The pass only transforms the plan: it adds no runtime wrapper and never mutates the original graph. New cached value identities use a private graph copy. Rebinding new data means running the pass again from the same original plan.

source
ReactiveKernels.partition_footprint Method
julia
partition_footprint(kernel::PreparedKernel, args...) -> NamedTuple

The positions of each HAVE port of kernel that evaluating it with args (its HAVE arguments, in order, including a plan port when present) reads: port => Vector{Int} of linear positions (sorted, unique), or :whole when the evaluation reads the port whole (a scalar port, a port read by a value computed whole). The positions follow from the bound index data and the label or cell index by the same row analysis that computes the evaluation: a lazy branch contributes both arms, a bound-indexed read its constant positions, and a view the parent positions its readers read (constructing a view reads none; a typed local that converts a view into a copy reads every viewed position). A read nested in a larger expression, tanh.(view(u, 2:3:8)), contributes its literal positions. A product over a bound sparse factor reads its operand at the columns its rows store. A scalar generator sum with init contributes its visible gathers, including through views, when its domains, filters and indices do not read the captured array's values. Nested sums keep runtime loops; empty domains contribute no positions. Opaque reads, lazy term branches and other generator consumers retain conservative footprints. Direct captures in one scalar expression also request only the needed rows of eligible producers, including copying packed-parameter slices. Retained branches use capture row windows when bound indices prove both arms' requests in range; unproven requests may conservatively contribute the whole capture. Arm arithmetic remains lazy. For a partition or cell of a packed parameter vector this is its structural read set, a conservative support for its gradient; numerical zeros and cancellations do not remove positions. This also works on a plate_cell kernel, with its cell index among args. For a planned partition, pass nothing in the plan port: footprint lowering computes its own bookkeeping.

A kernel prepared from exemplars is typed for exactly their types, and so is its partition_footprint_kernel. Called with arguments of other types (another label type, a view of the point), partition_footprint returns the footprint of the same plan lowered from those arguments' types, which is what a kernel prepared from them would read; it prepares that once per type.

source
ReactiveKernels.partition_footprint_kernel Method
julia
partition_footprint_kernel(kernel::PreparedKernel) -> PreparedKernel

The kernel partition_footprint evaluates: called with kernel's HAVE arguments, it returns their footprint. partition_footprint prepares and keeps one per kernel for the process; a caller evaluating many labels or cells prepares it once here and holds it itself. Call a freshly prepared kernel through Base.invokelatest when crossing Julia's world-age boundary.

source
ReactiveKernels.partition_locality Method
julia
partition_locality(kernel::PreparedKernel) -> Vector{NamedTuple}

The locality classification of every value each plate cell (or partition) of a prepared kernel reads: one entry per cell and value, with fields value, status (:rows, :input, :data, :scalar, :shared or :whole), reason, reader, source and cell. A :whole entry is a value the cell reads at its rows but computes whole; its reason is :no_form, :unshaped, :operands, or :cascade when it is read whole by another :whole value. Empty for a kernel without cells. The classification is the one the kernel's preparation applied (plate_cell's locality); for a kernel prepared with bound=, it is that of the residual program.

source
ReactiveKernels.partition_plan Method
julia
partition_plan(kernel::PreparedKernel, args...) -> NamedTuple

The plan of a partition kernel prepared with a plan port (plate_partition(…; plan)): the constant bookkeeping and data of the label among args (the kernel's HAVE arguments in order; pass nothing for the plan port), computed from the bound data. The kernel's body reads it from the port instead of recomputing it per call, and a derivative carries none of it: kernel(args..., label, partition_plan(kernel, args..., label, nothing)). Compute it once per label and keep it; a label no plate has throws ArgumentError naming the keys.

source
ReactiveKernels.partition_plan_kernel Method
julia
partition_plan_kernel(spec::KernelSpec; have, want, bound, on_error) -> PreparedKernel

The plan kernel of a partition prepared from spec with these arguments (prepare's), without preparing the partition itself: it computes a label's plan from the exemplar's data, and the type of that plan declares the plan port of the partition to prepare (plate_partition(…; plan = port => T)), which then reads every plan field with that type.

source
ReactiveKernels.partition_plan_kernel Method
julia
partition_plan_kernel(kernel::PreparedKernel) -> PreparedKernel

The kernel partition_plan evaluates: called with kernel's HAVE arguments (the plan port's own value is ignored; pass nothing), it returns the plan: the named tuple of label-constant bookkeeping and data the body reads from its plan port. partition_plan prepares and keeps one per kernel for the process; a caller evaluating many labels prepares it once here and holds it. A kernel prepared from exemplars has its plan lowered from the same argument types, with nothing at the plan port as prepare documents, so the plan has the type prepare gave kernel's plan port.

source
ReactiveKernels.partition_separability Method
julia
partition_separability(kernel::PreparedKernel, args...)

Check the separability rule of the partition in kernel (plate_partition's partitioned) for the evaluation with args (the HAVE arguments in order, including a plan port when present): every position read of a partitioned port carries its own label or missing. Returns the footprint (partition_footprint); throws PartitionSeparabilityError naming the port and the other partitions' positions otherwise. A kernel with no partition, or one with no rule, passes.

source
ReactiveKernels.plan Method
julia
plan(g; have, want) -> Plan

Select the minimum-cost executable set of recipes producing every value in want from the boundary have. Values in have are authoritative and are never recomputed (gist §7). Cyclic alternatives may use external grounding producers; throws PlanningError when no executable selection exists.

source
ReactiveKernels.plate Method
julia
plate(spec::KernelSpec; have, want, batched, reduce = :+, simplify = nothing) -> PreparedKernel

Prepare a batched, loop-invariant-hoisting kernel from a scalar @kernel spec. The batched HAVE ports (a name or a collection of names) are passed as arrays; recipes that depend only on shared scalar ports are computed once, and the single scalar want is mapped over the batched values and reduced (a sum by default). Pass reduce = nothing to collect the per-element wants instead.

The generated map/reduction form is allocation-free for native reducing execution. See lower_batched. simplify is as for prepare: unless it is false, numerically fragile compositions are computed in their stable form (log(exp(u)) as u).

source
ReactiveKernels.plate_body Method

The transparent scalar plan captured by an authored plate(...) do recipe.

source
ReactiveKernels.plate_cell Method
julia
plate_cell(spec::KernelSpec, plate::Symbol; index = :cell, name = Symbol(plate, :_cell), locality = nothing) -> KernelSpec

A new kernel in which the value name is ONE cell of the authored plate that produces plate, at the position held by the HAVE port index: a linear position or a CartesianIndex in the plate's broadcast domain. For a plate over x (or an @plate for i in eachindex(x) loop), cell i is the plate's value at x[i].

Planning a WANT of name runs only that cell, through the plate's own scalar body and the same native plate lowering, so the value is the plate's element at that position. An authored plate whose only consumer is this one is composed into the cell, as plate chains are composed (see prepare), and so also runs at that cell only. So is a plate read only by cells at the same position (several plate_cell values sharing index): each of those cells runs it at that position. Every other value the cell reads is planned as usual. A cell outside the plate's domain throws BoundsError; the plate's broadcast-domain checks are kept.

The default boundary of the result is the original HAVE ports plus index, and the WANT name. spec is unchanged: the result has its own graph, sharing the original values and recipes. index may name an existing HAVE port of spec (or of an earlier plate_cell result) to evaluate several plates at the same cell.

A value the cell reads only at its own rows is computed at those rows when its producer has a row form (see the package guide). locality says what preparation does with a value the cell reads at rows but would compute whole: :error throws a PartitionLocalityError naming every such value, :warn names each once per process, :ignore says nothing. nothing (the default) reads the project preference cell_locality ("warn" unless set). partition_locality reports the classification of every value.

source
ReactiveKernels.plate_partition Method
julia
plate_partition(spec::KernelSpec, plates; by, index = :partition, name = :partition_total,
                locality = :error, partitioned = (), plan = nothing,
                plan_constant = (), single = false) -> KernelSpec

A new kernel in which the value name is the sum of the cells of the authored plates named in plates (one name or several) whose key equals the label held by the HAVE port index: a partition of the plates, such as one subject's observations. by gives each plate's key, a value of spec (usually a bound data port) with one entry per cell of the plate in the plate's linear order (another length is refused at evaluation, so no cell can fall outside every partition): one name for every plate or, per plate, a named tuple, a dictionary, one plate => key pair or a collection of such pairs.

A partition runs as ONE compiled pass over its cells: each named plate loops once over the positions holding the label, through the plate's own scalar body and the same native plate lowering, and every value the partition's cells read at their rows is computed once per partition at the union of those rows (plate_cell's row forms). Values the partition reads whole are computed once per call. The positions of each label are computed from the key once per binding under bound= (a label's lookup is then one dictionary read per call). A label that no cell of any named plate has throws ArgumentError; a named plate without a cell of the label contributes nothing (an empty partition of it). A plate whose domain is not one-dimensional is refused at evaluation.

locality is as for plate_cell, with the default :error: a partition is prepared only when every value its cells read at rows is computed at those rows; otherwise preparation throws a PartitionLocalityError naming each such value. partition_locality reports every value.

partitioned is the separability rule: pairs port => labels, each a per-partition HAVE port of spec with the label of each of its linear positions (missing for a position every partition may read, such as a shared parameter). partition_separability then checks, for one label, that the partition reads no other label's positions of those ports; the check needs the kernel's arguments, so it runs where an exemplar exists (ReactiveKernelsPPL.prepare_partition_sampler runs it for every label).

plan = port adds a HAVE port for partition_plan, which caches label-constant bookkeeping and data. Declare its type with port => T or supply exemplars to prepare. Compute a plan for each label; cached rows are checked against that label, and planned shapes against the arguments at evaluation. plan_constant names additional HAVE ports whose values the caller guarantees are constant per label while reusing a plan.

single = true declares that every key holds each label of the partition exactly once, so a partition is one cell of each named plate (one subject's cell of a plate over subjects). The partition then runs that cell at one row, as plate_cell does: the values it reads at rows are computed at that row only, and values of one element per row can stay numbers instead of one-element arrays. A label that a key holds once is unchanged; a key that holds a label zero or several times throws ArgumentError at evaluation.

The default boundary of the result is the original HAVE ports plus index, and the WANT name. spec is unchanged. index may name an existing HAVE port of spec to partition several specs at the same label.

source
ReactiveKernels.plate_reverse_report Function
julia
plate_reverse_report(kernel, active = 1) -> Vector{Pair{Symbol,String}}

For a gradient of kernel with HAVE port active (its position, or a tuple of positions) active: each plate program's result name and either "rule", when the source is eligible for generated reverse, or its fallback reason. Accepts a PreparedKernel or NonAllocatingKernel. This is a static report, independent of whether the preference is enabled; cache rewrites and backend operand annotations can affect the rule used by a prepared gradient. Single-plate programs are listed even when ordinary native execution inlines them.

source
ReactiveKernels.port Method

Look up a named graph port. Equivalent to spec[name].

source
ReactiveKernels.prepare! Method
julia
prepare!(cache, spec::KernelSpec; have, want, passes=(), bound=(;), type_stability=nothing, type_stability_level=nothing) -> callable

Like prepare on an authored kernel, reusing cache. With a non-empty bound NamedTuple the partial_evaluation pre-pass runs as in prepare, and the cache keeps its value-independent work — the plan, the prepared data-only prefix and the compiled residual — per bound port set, so rebinding new data to the same ports costs the prefix's execution and nothing else. Use it where one graph is prepared repeatedly with fresh bound data (a request-time binding per user interaction); the returned kernel is positional over the remaining HAVE ports exactly as prepare(spec; bound) returns it. A shaped want returns its shape, as for prepare.

source
ReactiveKernels.prepare Method
julia
prepare(spec::KernelSpec; have, want, passes=(), bound=(;), on_error=nothing, exemplars=nothing, type_stability=nothing, type_stability_level=nothing) -> callable

Prepare an authored kernel. With a non-empty bound NamedTuple (bound = (; X, y)), the partial_evaluation pre-pass runs first: each named HAVE port is fixed to the supplied value, the data-only subgraph reachable from only those ports executes once here, and the returned kernel is positional over the remaining HAVE ports in their selected order. The authored signature convenience layer (positional defaults and keywords) applies only to unbound default-boundary preparations.

exemplars follows prepare on a Plan: it opts into native type evidence for the remaining positional HAVE ports after binding.

A repeated bound preparation of the same kernel, boundary and bound port set reuses the plan and compiled code of earlier bindings and runs only the data-only subgraph on the new values (see prepare on a Graph), so binding per request needs no caller-held cache; prepare! with a PreparationCache gives that reuse an explicit lifetime.

The default on_error = nothing preserves authored assertions and throws. Opt in with on_error = :ignore to replace visible throw(...) sites in captured @kernel and @traceable source with nothing, including expanded @asserts. The policy applies to native execution, tracing and bound-data mathematics. Ordinary opaque function bodies keep their behavior. This first policy continues execution; it does not catch exceptions or return a fallback.

type_stability selects whether preparation warns about a type instability or refuses it, and type_stability_level how far it checks, as for prepare on a Plan.

want is a port name, whose value the kernel returns, or a tuple of them, returned as a tuple (one name returns its value). It may also be a shaped WANT: a NamedTuple, or a tuple holding a tuple or a NamedTuple, whose leaves are port names, nested as deep as wanted, as js_source and jax_source accept. The kernel then returns that shape, each name replaced by its port's value: want = (curve = :curve, count = :n) returns (curve = …, count = …), and want = (a = (:x, :y), b = :z) returns (a = (x, y), b = z). A port named twice is computed once.

source
ReactiveKernels.prepare Method
julia
prepare(p::Plan; passes=(), bound=(), on_error=nothing, exemplars=nothing, type_stability=nothing, type_stability_level=nothing) -> PreparedKernel
prepare(g::Graph; have, want, passes=(), bound=(), on_error=nothing, exemplars=nothing, type_stability=nothing, type_stability_level=nothing) -> PreparedKernel

Ergonomic composition of plan -> lower -> transform -> compile. passes is a tuple of AST passes applied before compilation.

bound opts into the partial_evaluation pre-pass: pass one Value => data pair (or an iterable of them) naming HAVE ports whose runtime values are fixed for this preparation. The data-only subgraph reachable from only those ports runs once, here, and the returned kernel takes just the remaining HAVE ports positionally (in their original relative order); the hoisted values are baked in as constants. With bound = () (the default) behavior is unchanged. passes apply to the residual (per-call) kernel.

Preparing a Graph (or an authored KernelSpec) with a non-empty bound reuses everything that does not depend on the bound values — the plan, the compiled data-only prefix and the compiled residual — from earlier bindings of the same graph version, HAVE/WANT boundary, bound port set and passes, exactly as prepare! does with a PreparationCache. A binding of new values then costs the prefix's execution, not a fresh planning, lowering and compilation. The graph holds these entries, so they live as long as the graph, a mutation of the graph starts afresh, and they keep no bound values. Passes that are not singletons (closures) are not retained: such a binding is prepared afresh. A Plan is always prepared afresh.

exemplars = (x, ...) opts into native type evidence from one value per remaining positional HAVE port. Native calls then require those exact input types; prepare another kernel for different types. The native signature keeps the declared port types; only plate lowering reads the exemplar evidence. Lengths and values are not baked into the program. A graph prepared with exemplars is compiled afresh.

Preparation computes numerically fragile compositions in their stable form (simplify = true, the default): log(exp(u)) as u, log(logistic(x)) as loglogistic(x), log(1 + x) as log1p(x), y / exp(u) as y * exp(-u), log(exp(a) + exp(b)) as a log-sum-exp, and the rest of the rule table in src/stable_rewrites.jl. The literal composition is finite only where its intermediate is representable, and its ordinary reverse forms 0 * Inf at the edges; the stable form agrees with it to within rounding wherever it is finite and stays finite, with a finite derivative, beyond. Errors, lazy branches and non-Real operands keep the literal program. The rewrite applies across statements and inside plate cells, to compositions the generated program spells (recipe sources, a law's hoisted terms); it never sees inside an opaque function. simplify = false compiles the literal arithmetic; nothing takes the setting of an enclosing preparation, else the project's ReactiveKernels preference simplify (Preferences.set_preferences!(ReactiveKernels, "simplify" => false)), else true. Cached preparations are kept per setting. The same setting governs prepare_nonallocating, plate over a scalar spec, vectorize and prepare_reactive, which take simplify too, and jax_source, which reads the enclosing setting or the preference.

The same setting takes shared work out of a summed plate. When a cell's value is a + c * t, with a and c reading only values its cells share, the cells sum t alone and the plate adds n * a + c * sum(t) once: a Normal observation plate with one scale sums its squared residuals and divides by the scale once, and its ordinary reverse no longer accumulates the scale's derivative cell by cell. A law's guard on a shared value (scale == 0 before a cell's own test) is decided once per call. The plate's own loop runs instead whenever such a guard holds, a shared factor is not a normal number, or the factored sum is not finite, so every finite value and its derivatives agree with the plate's own to rounding.

With bound data and bound_statistics = true (the default, with simplify) a summed plate that sums (y - mu)^2 this way, y bound and mu linear in live values with bound coefficients, is evaluated from least-squares statistics of the bound rows computed at binding. mu may be a bound matrix times a live vector, live numbers, or live vectors gathered through one bound index, each times bound coefficients, plus bound offsets. A call then costs time in the number of parameters, not of rows, and mu is not computed; the plate's own loop, where it runs, reads it row by row. A binding whose data do not fit (fewer than two rows per parameter of a block, a non-finite entry, a response that is not a vector) compiles the plate as before. bound_statistics = false keeps the rows; nothing takes the enclosing setting (with_bound_statistics), else the project's ReactiveKernels preference bound_statistics, else true.

Selected authored plates with a single plate consumer are composed during lowering, eliminating the intermediate array. Named ports remain in p: asking for an intermediate, supplying it as HAVE, or selecting another consumer keeps that boundary. Whole-array (Ref) consumers and opaque intervening recipes also retain their materialization boundary.

Preparation checks that the program is type stable, from the declared types of the HAVE ports where those are concrete and from the bound data. How far it checks is type_stability_level:

  • :values checks that every value of the program infers a concrete type. A recipe whose inputs are concretely typed but whose result Julia does not infer concretely (Any, an abstract type, a Union, or an array of such elements), such as a call to a function whose result is not inferable, is reported, naming the value and its recipe.

  • :rk also audits the code of the prepared program: the body ReactiveKernels generates and the functions it calls from the packages of ReactiveKernels' repository (ReactiveKernels, ReactiveKernelsPPL, the other packages under packages/, and their extensions), identified by package UUID. A used value Julia does not infer concretely, or a call dispatched at run time, is reported with its method. Every other function the code calls is a leaf, whatever its package's name: its call must be dispatched statically and return a concrete type.

  • :all (the default) also audits every function that code calls, a client function's body included, except Julia's own Base, Core and standard libraries, which stay leaves.

Every recipe and plate cell that reads a non-concrete value dispatches dynamically, and native reverse-mode AD may refuse the program. prepare_ad repeats the check with the types of its exemplar arguments, auditing the callable its backend differentiates.

type_stability is what preparation does with a finding: :warn (the default) logs a warning once per process and preparation succeeds; :error throws a TypeInstabilityError naming every finding, at every preparation. Either keyword's default nothing takes the setting of an enclosing preparation, else the project's ReactiveKernels preference of the same name (read at the first preparation of a Julia session), else the default. A project sets them for every preparation, including those other packages make for it, with for example Preferences.set_preferences!(ReactiveKernels, "type_stability" => "error"), which writes [ReactiveKernels] type_stability = "error" to its LocalPreferences.toml. A keyword applies to the preparations its call makes, nested ones included, and cached preparations are kept per setting.

source
ReactiveKernels.prepare_ad Method
julia
prepare_ad(spec, backend, args...; active, want, bound=(;), retain=(), warm=false, native_forward_batch=false, type_stability=nothing, type_stability_level=nothing, kwargs...)

Prepare a reusable DifferentiationInterface gradient of the explicit scalar want port in a KernelSpec. active names one selected HAVE port or an ordered tuple of ports that remain differentiable; all other selected HAVE values are rebound on every call and passed as Constant contexts. A tuple selector is differentiated as one structured point, and gradients are returned in the same order.

retain = (:name, ...) names further WANT ports whose values the gradient's own primal sweep also returns: ad_value_gradient_and_retained! yields (value, gradient, retained) with retained a NamedTuple of those values at the same point, with no second primal pass. Only the scalar want is differentiated. Retention needs a backend that evaluates the objective once at the point and keeps its writes (ad_retains_primal_sweep; reverse-mode AutoEnzyme); other backends are refused at preparation.

The ordinary authored call surface is preserved: positional defaults and keyword HAVE ports are resolved exactly as they are by prepare(spec). The preparation arguments are type/shape exemplars, not frozen data. Some preparations also evaluate the program at them: a NonAllocatingKernel seeds its buffers with one primal call there (see its method), warm = true runs one gradient there, and an objective whose declared type is not a Number and whose inferred type is not one either is checked by one call there. None needs a point where the program evaluates. A program that throws at the exemplars is prepared anyway, with a warning that names the error; the objective check then falls back to inference, and only an objective that inference does not prove a Number is refused, with the program's error as the cause.

The backend's package must be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension, and preparation without it fails loudly naming the missing using.

A prepared operator serves one caller at a time, so no other thread updates the shadows its derivative accumulates into. Where the loaded Enzyme has Enzyme.set_atomic_add, a reverse-mode AutoEnzyme that leaves that setting to Enzyme (AutoEnzyme(), AutoEnzyme(; mode = Enzyme.Reverse), or the reverse part of a SecondOrder) is prepared with set_atomic_add(mode, false): plain shadow updates, where Enzyme would otherwise compile atomic ones in any process with several default-pool threads. A mode that sets it either way is kept. Every prepare_ad_* preparation does the same, and the prepared operator stores the backend it was prepared with.

A non-empty bound NamedTuple runs the partial_evaluation pre-pass first: the named ports are fixed to the supplied values, their data-only subgraph executes once during preparation, and both the differentiated call and its Constant contexts cover only the remaining ports. args and active then refer to those remaining ports positionally; authored keyword arguments do not apply to a bound preparation. Array-valued residual constants are passed to the backend as hidden Constant contexts rather than captured in the differentiated callable; this does not change the public HAVE boundary. Bound views cross as owning copies with identical contents, since a prebuilt view operand defeats reverse-mode static activity analysis.

Like prepare, preparation checks that the kernel is type stable for the exemplar argument types: each value of the kernel at type_stability_level = :values, and at :rk and :all (the default) also the code of the callable the backend differentiates. It warns once per process about each finding and continues. A non-concrete value makes every recipe and plate cell that reads it dispatch dynamically, and native reverse mode may refuse the derivative. type_stability = :error refuses such a kernel instead, throwing a TypeInstabilityError that names every finding. Both keywords default to the enclosing preparation's setting or the project's preference, as for prepare. Every prepare_ad_* preparation takes the same keywords.

warm = true compiles the gradient during preparation for the exemplar's argument types, so evaluations with those types run compiled code. It infers the prepared call, which builds a backend derivative compiled during type inference (AutoEnzyme) without stalling JIT compilation on other threads, then evaluates the gradient once at a copy of the exemplar. An array active input warms ad_value_and_gradient!; any other warms ad_value_and_gradient. The default compiles at the first evaluation. If the program throws at the exemplar, preparation warns and returns the prepared gradient: whatever that evaluation did not reach compiles at its first call instead.

With AutoEnzyme() (no explicit mode), native_forward_batch = true requests one ordinary Enzyme forward sweep with one tangent lane per coordinate. It applies to a single active Vector{Float64} of one to four entries and no retained WANT values. The exemplar length fixes the batch width; calls with another length use the stored ordinary reverse preparation. It does not rewrite the kernel or attach a derivative rule. Explicit reverse mode stays reverse even when this optimization hint is set. This is an explicit option for measured small-width workloads; the default remains ordinary reverse preparation.

source
ReactiveKernels.prepare_ad Method
julia
prepare_ad(kernel, backend, args...; active, warm=false) -> PreparedADKernel

Prepare a reusable gradient for a low-level NonAllocatingKernel whose boundary is already fully selected. Such kernels accept only their positional HAVE values and must expose exactly one scalar WANT. active may be one port identifier or an ordered tuple of identifiers.

The preparation seeds the kernel's caches once with the exemplar arguments, then differentiates the same step program through AD-owned concretely-typed cache copies threaded as a DifferentiationInterface.Cache context, so the backend shadows them itself. Cache steps that cannot see the active input (bound constants in particular) run as plain operation calls inside the differentiated program: storing caller-owned constant data into a shadowed slot would be a static-activity error. The kernel's borrowed primal caches are never exposed to the backend, and primal calls keep using them independently of the prepared object. Bound values, and the steps that read only bound values (computed once during preparation), reach the backend as hidden DifferentiationInterface.Constant contexts, as for a dataflow kernel, so the differentiated callable carries no bound data and ordinary reverse-mode AutoEnzyme needs no function annotation.

The seeding call evaluates the program at the exemplar arguments, so their values decide which operations the gradient gives a reusable buffer: those that call reaches, which excludes a branch it does not take. The exemplar need not be a point where the program evaluates. If the program throws there (an ODE that does not integrate at the exemplar, a domain error), preparation warns, naming the error, and continues: the operations that call did not reach allocate on every gradient call, as an untaken branch's do, and values and gradients are unchanged. For every buffer to be reused, prepare at a point where the program evaluates. An InterruptException is rethrown.

Result types must be stable across calls: a step whose result type changes after preparation fails loudly instead of silently reseeding. Each materialized plate or scan output fills the buffer the exemplar call produced, so the gradient also keeps those shapes: a call whose output has another shape fails loudly; prepare the gradient again for it. Like every PreparedADKernel, the stored preparation is mutable and not thread-safe; prepare one object per concurrent caller.

Forward-mode backends that push dual numbers through the differentiated arguments (e.g. AutoForwardDiff) are not supported: the cache slots cannot carry duals, and preparation fails loudly inside the backend. Reverse-mode (AutoEnzyme) and primal-call-based (finite-difference) backends work. warm = true compiles the gradient during preparation, as for the KernelSpec method.

The backend's package must be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension, and preparation without it fails loudly naming the missing using.

source
ReactiveKernels.prepare_ad Method
julia
prepare_ad(kernel, backend, args...; active, retain=(), warm=false, native_forward_batch=false)

Prepare a reusable gradient for a low-level PreparedKernel whose boundary is already fully selected. Such kernels accept only their positional HAVE values and must expose exactly one scalar WANT. active may be one port identifier or an ordered tuple of identifiers. With retain, the kernel's WANT ports are the scalar objective plus the retained ports named there, whose values the gradient's primal sweep returns (see the KernelSpec method). warm = true compiles the gradient during preparation, as for the KernelSpec method. native_forward_batch has the same bounded native meaning as for the KernelSpec method.

The backend's package must be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension, and preparation without it fails loudly naming the missing using.

source
ReactiveKernels.prepare_ad_accumulator Method
julia
prepare_ad_accumulator(kernel, backend, args...; active, directional=active, order=0)

Prepare additive derivatives of one scalar WANT. active names the HAVE ports whose derivatives are accumulated; directional names a subset of them. order = 0, 1, or 2 differentiates f, Df[v], or D²f[v,v], respectively. Directions act only on directional. The result remains differentiable with respect to every active port, including the ports held fixed by the directional passes. This gives mixed derivatives without allocating zero directions for large shared operands.

The backend is a reverse backend for order zero, SecondOrder(reverse, forward) for order one, or SecondOrder(SecondOrder(reverse, forward), forward) for order two, as for prepare_ad_hvp and prepare_ad_third. Currently accumulation is supported by native reverse AutoEnzyme with a constant function annotation. Load Enzyme before preparation.

Use ad_accumulator_storage once to allocate a matching destination, then ad_accumulate! repeatedly. Storage follows active as a tuple, even for one port; scalar ports, and the scalar fields of a tuple or NamedTuple port, use Ref storage. The operator and its destinations serve one caller at a time.

source
ReactiveKernels.prepare_ad_hvp Method
julia
prepare_ad_hvp(spec, backend, tangents, args...;
               active, want, bound=(;), kwargs...) -> PreparedADHVP
prepare_ad_hvp(kernel, backend, tangents, args...; active) -> PreparedADHVP

Prepare reusable Hessian-vector products of one explicit scalar want port with respect to the active HAVE port. tangents is a nonempty tuple of input-tangent exemplars, one per direction ((v,) for one direction); each call then returns H * v for every direction. All other current HAVE values are rebound as Constant contexts on every call, exactly as for prepare_ad, and bound runs the same partial-evaluation pre-pass.

Pass a second-order backend. Reverse over forward, DifferentiationInterface.SecondOrder(AutoEnzyme(; mode = Enzyme.Reverse), AutoEnzyme(; mode = Enzyme.Forward)), also differentiates objectives that multiply a constant matrix by the active vector (a design-matrix linear predictor), which native Enzyme forward over reverse cannot analyse statically. Its preparation holds memory linear in the number of active coordinates: RK prepares the reverse gradient of the directional derivative x -> Df(x)[v] itself, without the forward-mode gradient that DifferentiationInterface's own reverse-over-forward preparation adds, whose Enzyme preparation holds n one-hot vectors of length n. A tuple active selector works there too. Directions with disjoint supports give a compressed Hessian: when active coordinates fall into groups that never interact (per-subject effects of a population model, say), one direction per coordinate within a group, summed across groups, recovers every group's diagonal Hessian block.

The backend's packages must be loaded in the calling session (using Enzyme for AutoEnzyme); preparation without them fails loudly naming the missing using.

source
ReactiveKernels.prepare_ad_pullback Method
julia
prepare_ad_pullback(spec, backend, seed, args...;
                    active, want, kwargs...) -> PreparedADPullback
prepare_ad_pullback(kernel, backend, seed, args...;
                    active) -> PreparedADPullback

Prepare a reusable reverse pullback (vector-Jacobian product) of the explicit want port or ordered tuple of ports. seed is an exemplar output cotangent. Unlike prepare_ad, the selected WANT may be non-scalar. One HAVE port or an ordered tuple of HAVE ports is active, and all other current HAVE values are rebound as Constant contexts on every call.

Several WANT ports (want = (:a, :b, ...), or a low-level kernel prepared with several) are differentiated together as the kernel's tuple result, the way prepare(spec; want = (:a, :b, ...)) evaluates them in one sweep. seed is then a tuple with one cotangent per port, in WANT order, each shaped like its port's value, and the pullback returns the active cotangent of Σᵢ ⟨seedᵢ, yᵢ⟩, the sum of every port's vector-Jacobian product, from one primal and one reverse sweep (the gradient of that seeded inner product). ad_value_and_pullback returns the tuple of port values; a backend that keeps its primal sweep (ad_retains_primal_sweep, reverse-mode AutoEnzyme) yields them from the same sweep, any other with one separate primal evaluation.

A selected port that no active HAVE port reaches (bound data alone, inactive HAVE values alone, or an inactive HAVE port) has a zero derivative: it is left out of the differentiated call and adds nothing to the pullback, and its value comes from the same sweep. When no selected port depends on an active port, the pullback is zero and no backend runs.

The backend's package must be loaded in the calling session (using Enzyme for AutoEnzyme); the backend value alone does not load DifferentiationInterface's backend extension, and preparation without it fails loudly naming the missing using.

source
ReactiveKernels.prepare_ad_pushforward Method
julia
prepare_ad_pushforward(spec, backend, tangents, args...;
                       active, want, bound=(;), kwargs...) -> PreparedADPushforward
prepare_ad_pushforward(kernel, backend, tangents, args...;
                       active) -> PreparedADPushforward

Prepare a reusable forward pushforward (Jacobian-vector product) of the explicit want port, which may be non-scalar (a vector, a NamedTuple of arrays, …), or of an ordered tuple of ports. tangents is a nonempty tuple of input-tangent exemplars, one per direction, each shaped like the active point: (v,) for one direction, (v1, v2, v3) for three directions evaluated together. A tuple active selector takes one tuple of component tangents per direction. One HAVE port or an ordered tuple of HAVE ports is active, and all other current HAVE values are rebound as Constant contexts on every call, exactly as for prepare_ad. bound runs the same partial-evaluation pre-pass.

Several WANT ports (want = (:a, :b, ...), or a low-level kernel prepared with several) are differentiated together as the kernel's tuple result, the way prepare(spec; want = (:a, :b, ...)) evaluates them in one sweep: one forward sweep carries every direction through the shared graph, and each output tangent is a tuple with one tangent per port, in WANT order. Whether a backend differentiates a tuple-valued function is the backend's own contract; forward-mode AutoEnzyme does. A port that no active HAVE port reaches is left out of the differentiated call and gets a zero tangent; when no selected port depends on an active port, no backend runs.

Several directions with disjoint supports give a compressed Jacobian: for a WANT whose entries each depend on one group of active coordinates, one direction per coordinate within a group, summed across groups, recovers every group's Jacobian block.

The backend's package must be loaded in the calling session (using Enzyme for AutoEnzyme(; mode = Enzyme.Forward)); preparation without it fails loudly naming the missing using.

source
ReactiveKernels.prepare_ad_third Method
julia
prepare_ad_third(spec, backend, tangents, args...;
                 active, want, bound=(;), kwargs...) -> PreparedADThird
prepare_ad_third(kernel, backend, tangents, args...; active) -> PreparedADThird

Prepare reusable third-order directional derivatives of one explicit scalar want port with respect to the active HAVE port: for each input tangent v, the gradient of the Hessian quadratic form, ∇(vᵀ H v) = D³f[v, v, ·], a vector shaped like the active point. tangents is a nonempty tuple of input-tangent exemplars, one per direction ((v,) for one direction). All other current HAVE values are rebound as Constant contexts on every call, exactly as for prepare_ad, and bound runs the same partial-evaluation pre-pass.

Pass SecondOrder(hvp_backend, pushforward_backend): the Hessian-vector backend differentiates the directional derivative x -> Df(x)[v] that the pushforward backend computes. Reverse over forward over forward extends prepare_ad_hvp's reverse over forward by one forward layer and also differentiates objectives that multiply a constant matrix by the active vector. Each direction costs one reverse sweep over a doubly forward-differentiated primal.

Higher-order backend support depends on the operators and backend version. Dense products have exposed uninitialized tangent storage in Enzyme's nested forward rules. Check the required operator against an analytical derivative; benchmark/repro_enzyme_forward_over_forward_view_matvec.jl retains the development reproducer.

Directions with disjoint supports compress, as for Hessian-vector products: when active coordinates fall into groups that never interact (per-subject effects), a direction summed across groups, v = Σᵢ vᵢ, returns Σᵢ D³f[vᵢ, vᵢ, ·], because every cross term D³f[vᵢ, vⱼ, ·] vanishes. A bilinear contraction D³f[w, v, ·] follows by polarization, (D³f[w + v, w + v, ·] - D³f[w - v, w - v, ·]) / 4.

The backend's packages must be loaded in the calling session (using Enzyme for AutoEnzyme); preparation without them fails loudly naming the missing using.

source
ReactiveKernels.prepare_batched Method
julia
prepare_batched(spec::KernelSpec; batched, have=inputs(spec),
                want=outputs(spec), passes=(), reuse=false,
                schedule=nothing, simplify=nothing) -> callable

First-class position batching for a scalar @kernel. The named HAVE ports carry one shared trailing batch axis; all other HAVE ports are shared by every position. A scalar batched port becomes a vector, a rank-r array batched port becomes rank-r + 1, and every selected output is stacked on the same trailing axis. Tuple and named-tuple trees preserve their structure and stack each numeric leaf. Untyped ports infer their rank from the actual batch container; known numeric annotations retain strict rank checks. batched may be one port name or a tuple of names; those names must be unique and agree on the batch length.

This is position batching, not a likelihood plate: one scalar parameter position is evaluated at each slice while data remains shared. The scalar graph stays the mathematical authority, plan still owns HAVE/WANT selection and CSE, and native execution evaluates independent positions in a generated typed driver. A PreparedADKernel lifted with replica produces one gradient per position.

The lifted kernel requires pure recipes and retains their internal loops and lazy branches. Native execution hoists shared-only recipes, including plates, scans and embedded kernels, and lowers both the hoisted prefix and the per-position residual as prepare lowers a scalar kernel, so an inline plate runs as its fused loop at every position. Unless simplify = false, each part computes numerically fragile compositions in their stable form, as prepare does; a composition of a per-position value over a hoisted one (log(s) of a shared s = exp(a)) is computed as written, so the hoisted value is computed once. The default allocates fresh stacked outputs; retaining a result across calls is safe. It is not the allocation-free reducing plate contract.

Native batching is serial unless schedule=NativeScheduling(chunk_size=..., workers=...) explicitly opts in. The scheduler computes shared-only work once, then distributes runtime position ranges among independent borrowed workers. Each worker retains at most chunk_size positions and copies completed chunks into the final stacked result. The result still spans the whole batch. Hints are caller-selected: there is no automatic cost threshold. Empty batches and one-worker calls use the ordinary serial driver. Scheduled instances, including owning ones, retain worker buffers and are not reentrant; use copy(template) per concurrent caller. Copies share computation and start with empty buffers. Scheduling applies to native primal evaluation; prepare scalar AD with scalar_kernel and lift it with replica for the existing per-position derivative path.

reuse=true opts into native borrowed stacked-output buffers. A later call may overwrite every returned array; consume synchronously or deepcopy before publishing, retaining or passing it to a callback. Prepare a template once, then use copy(template) for each independent caller. Copy shares the scalar graph and compiled callable with fresh empty buffer slots, without planning, lowering or code generation, even when the template was already called. Keyword/default signatures are preserved. Bound data and computation metadata remain shared and read-only; previous outputs are neither shared nor copied. One instance can serve sequential batches; it is not reentrant. Shape/type changes reseed buffers, and buffers aliasing this call's inputs detach. This reuses final outputs and the native lane buffers: batched dense array inputs and the position values produced by authored plates and scans, top-level dotted calls and array slices, including those values inside a plate's cells other than each cell's result. Other scalar recipes may still allocate intermediates.

To bind shared values, lift prepare(spec; have, want, bound=(; shared...)) with vectorize. Rebinding new values to the same ports and vectorizing again reuses the position drivers lowered for an earlier binding; only the bound-data work runs again. To retain position-dependent work across calls, build a named intermediate with one vectorized WANT cut, then supply that stacked intermediate as a batched HAVE in a second cut of the same graph. No second model is needed.

source
ReactiveKernels.prepare_nonallocating Method
julia
prepare_nonallocating(p::Plan, exemplars...; passes=(), simplify=nothing) -> NonAllocatingKernel
prepare_nonallocating(g::Graph, exemplars...; have, want, passes=(), simplify=nothing) -> NonAllocatingKernel

Optional MutatingFunctions-backed preparation interface. Install and load MutatingFunctions alongside ReactiveKernels to activate the package extension that supplies these methods (for a Plan, a Graph, an authored KernelSpec, or an already-prepared PreparedKernel's plan). The extension lowers the same native program as prepare: plate chains compose, summed plates fold into running totals, scans stream into the plates they feed. It then routes the program's remaining allocations to storage the kernel keeps: each materialized authored plate or scan output fills a buffer kept across calls, and every other operation with a destination-passing form goes through MutatingFunctions.apply!! and a persistent per-step cache. User passes run on the native program before this final transform.

simplify selects the stable rewrites as for prepare, and they reach the buffered steps. A PreparedKernel argument contributes its plan, not its own setting: pass simplify = false here too to keep a literal program.

A step keeps a cache only when its result is fresh storage that a destination-passing method fills: the decomposition's own steps below, or an operation with a registered apply!! method for its concrete cache and argument types. Every other operation is called directly, and its result is never written into: a cached value may alias caller data (a field read, row slices of a caller matrix), and apply!!'s generic fallback would copy the next call's result into it.

Operations synthesized from captured @kernel source are decomposed into destination-passing steps where the captured expression allows: lazy wrappers and isbits-valued calls run inline, broadcast materializations, vcat, range getindex, and zeros/ones reuse typed destination buffers, and every other resolved call with a registered apply!! method (e.g. mul!-backed *) becomes its own cache step. Source shapes outside that grammar run as one operation.

Cache types and step selection are fixed at preparation from static types. A HAVE port without a concrete declared type leaves everything computed from it untyped. Pass exemplars, one value per positional HAVE port in inputs order, to type the program from those values' types instead; the returned kernel then accepts exactly those argument types (any other is an ArgumentError). A declared array output of an authored plate (y::Vector{Float64} = plate(...)) fixes the element type of its buffer, as the native kernel's typed local does.

The first invocation populates the caches and may allocate. Later invocations reuse them when the selected operations provide allocation-free apply!! methods for the runtime argument and cache types. Operations without one allocate their result as the ordinary kernel does, so allocation freedom is a property of the complete lowered operation set rather than a planner guarantee.

Every selected recipe must have exactly one output. A no-recipe plan returns its input directly, and a directly called operation's result may alias an input. Treat mutable results as borrowed values that may alias inputs or be overwritten by the next call; a prepared instance is not reentrant or thread-safe.

source
ReactiveKernels.prepare_reactive Method
julia
prepare_reactive(graph; have, want, simplify = nothing) -> ReactiveProgram

Prepare a closed-world stateful program. have declares the mutable, authoritative state boundary; want declares all downstream values the state may demand. Planning happens once. Each reachable value receives a compiled lazy getter that reuses valid slots and recomputes only invalid dependencies.

Instantiate with state = program(have_values...), then obtain typed handles once with x = statevalue(program, graph_value). Mutate a source with set!, or mutate its stored object in a mutate! transaction. Both invalidate downstream state; get! performs the generated minimal recomputation.

The selected graph and runtime slot types are fixed. This is the efficient state-machine counterpart to the open-ended, dictionary-backed ReactiveState.

Unless simplify = false (or the project preference [ReactiveKernels] simplify = false), each recipe computes the numerically fragile compositions in its own source in the stable form prepare computes (log(exp(u)) as u). A composition across two state values is computed as written: w = log(v) reads v's slot, which freeze! can set, even where v = exp(u).

source
ReactiveKernels.prepare_reactive Method
julia
prepare_reactive(spec::KernelSpec; have, want) -> ReactiveProgram

Prepare an authoring [KernelSpec] through the same compiled reactive state engine as a hand-built graph. Symbol and Value boundary overrides are resolved against the spec before delegating, so the authoring surface does not introduce a second runtime or a sampler-specific refresh path.

source
ReactiveKernels.prepare_reactive_nonallocating Method
julia
prepare_reactive_nonallocating(graph; have, want, is_mutating=_default_is_mutating,
                               simplify=nothing)
prepare_reactive_nonallocating(spec::KernelSpec; ...)

Optional MutatingFunctions-backed reactive preparation. Install and load MutatingFunctions alongside ReactiveKernels to activate the package extension that supplies these methods. It prepares the same closed-world state program as prepare_reactive, but selected single-output recipes reuse their per-instance slot buffer in place through MutatingFunctions.apply!! instead of allocating a fresh recipe return on every recomputation. simplify is as for prepare_reactive; a recipe reused in place runs its own operation, which selects its in-place method.

Selection is per recipe via is_mutating(recipe)::Bool (default: mutable/ array-like outputs). With the MutatingFunctions hook a selected recipe is reused in place only when a registered apply!! method fills its slot for its declared port types; any other recipe recomputes on the pure path, because its first result may alias caller data that the generic fallback would overwrite. The injected core hook is a single MF-agnostic callable cache_apply(cache, op, args...) -> newcache; MutatingFunctions.apply!! supplies it, and any conforming hand-written mutating op (including a non-MutatingFunctions one) fits the same codegen. Contract on cache_apply: it must return the (possibly new) result object, and it must treat an immutable/isbits cache as passthrough-recompute (ignore the cache bits and return op(args...) fresh) — apply!! already does both.

Slots are per CompiledReactiveState instance, so caches are owned per instance; copy/copyto! deep-copy buffers, so distinct instances never alias mutable storage. Reused results are borrowed values that may be overwritten by the next recomputation; a state is mutable and not thread-safe.

source
ReactiveKernels.reactive_program Function
julia
reactive_program(object)

Return the ReactiveProgram backing a public wrapper around compiled reactive state. Concrete wrapper types define the corresponding method; a bare CompiledReactiveState exposes its program directly as state.program.

source
ReactiveKernels.recipe_inventory Method
julia
recipe_inventory(spec::KernelSpec)
recipe_inventory(graph::Graph)
recipe_inventory(plan::Plan)
recipe_inventory(kernel::PreparedKernel)
recipe_inventory(kernel::NonAllocatingKernel)

Every recipe of a program and, recursively, of each plate and scan body, as a Vector of (; kind, depth, parent, recipe) entries in depth-first order: a plate or scan entry is followed by the entries of its body. kind is recipe_kind(recipe); depth is 0 for a top-level recipe and one more for each enclosing plate or scan; parent is the index in the returned vector of the enclosing plate or scan entry, or 0 at top level.

A KernelSpec is inventoried through its graph (kernel_graph), so every registered recipe is listed. A Plan lists the recipes it selected. A PreparedKernel lists the recipes of the plan it was prepared from; with bound= data that is the residual plan, in which each folded value is an ordinary recipe. A body is always its plate's plate_body or its scan's scan_body plan. The inventory only reads its argument; nothing is planned, prepared or evaluated.

Filter entries whose kind is not :ordinary to inspect the nesting of plates and scans. Read kind and depth from those entries.

source
ReactiveKernels.recipe_kind Method
julia
recipe_kind(recipe::Recipe) -> Symbol

The structural kind of recipe: :plate for an authored plate(...) do recipe, :scan for an authored scan(...) do recipe, and :ordinary for every other recipe. It never throws. The body of a :plate recipe is plate_body(recipe) and the body of a :scan recipe is scan_body(recipe); an :ordinary recipe has no body. These symbols are the supported classification; the operation types behind them are internal.

source
ReactiveKernels.register_source_provider! Method
julia
register_source_provider!(provider) -> provider

Register provider to supply the Julia source of methods that jax_source has no other source for, so their loops and branches translate. For a method that a package generates, such as one a macro writes into its caller's module, the method's author cannot write @traceable; the generating package supplies the source instead.

When jax_source meets a call of a function f with no translation of its own and no @traceable method for the call, it calls provider(f, argument_types), with argument_types the Tuple type of the call's argument types, in the JAX functions and in prepare_data alike. The provider returns nothing when it has no source for that call, or the TraceableSource of the method that arguments of those types call natively, so the translation computes what native execution computes. Providers are asked in the order they were registered, and the first source wins. A call that no provider answers is translated from its lowered code, which must be straight-line. An error the provider throws propagates out of jax_source.

Register a provider once, from the __init__ of the package extension that loads with ReactiveKernels; registering the same provider again changes nothing. A provider only hands over source: nothing is evaluated, and native execution is unchanged.

source
ReactiveKernels.replica Method
julia
replica(spec::KernelSpec; batched, have=inputs(spec), want=outputs(spec), passes=())

Prepare the scalar authored kernel and lift the complete callable over a shared trailing replica axis. See replica(::PreparedKernel).

source
ReactiveKernels.replica Method
julia
replica(kernel::PreparedKernel; batched) -> ReplicatedKernel

Lift a complete scalar prepared kernel over a trailing replica axis. batched names the HAVE ports that receive that extra final dimension. Scalar batched ports therefore become vectors, vectors become matrices, and so on; shared ports retain their scalar-kernel shapes. Outputs receive the same trailing replica axis.

The scalar kernel remains the only mathematical definition. In particular, reductions inside it still reduce only their original dimensions, so a scalar dot(q, q) becomes one dot product per replica rather than a reduction across replicas. Native Julia evaluates scalar replicas and stacks their results.

source
ReactiveKernels.reverse_cut Method
julia
reverse_cut(rule::DerivativeRule, ::Val{mask}, inputs..., covector)
    -> (cotangents of the active inputs, in input order)

Run the graph's VJP branch for one activity pattern. Inputs the cut does not read (see reverse_residuals) may be passed as nothing. Always returns a tuple. Requires the rule to have a reverse branch and at least one active input. Bits retain their original input positions; selecting a data-only input is an error.

source
ReactiveKernels.reverse_residuals Method
julia
reverse_residuals(rule::DerivativeRule, ::Val{mask}) -> NTuple{N,Bool}

Which inputs the reverse cut of activity mask (bit i set when input i is active) reads; an adapter retains exactly those across the primal/cotangent staging boundary and may pass nothing for the others.

source
ReactiveKernels.rk_affine_logistic Function
julia
rk_affine_logistic(lo, hi, u)

Map an unconstrained scalar u into (lo, hi) with the affine logistic primal. Its generated derivative rule multiplies an incoming cotangent by the complete interval partial, avoiding overflow in a width-first reverse chain when the final derivative is representable.

source
ReactiveKernels.rk_cholesky_lower Method
julia
rk_cholesky_lower(A::AbstractMatrix) -> LowerTriangular{Float64}

Compute the lower Cholesky factor of the symmetric matrix represented by the lower triangle of A, using an ordinary pure-Julia factorization with no LAPACK call. The arithmetic uses Float64. The result wraps a fresh matrix whose strict upper triangle is zero; A is never mutated, and its upper triangle does not participate in the factorization.

A must be square (ArgumentError otherwise). A non-positive or NaN pivot throws LinearAlgebra.PosDefException, whose info identifies the pivot. An empty square matrix has an empty factor. jax_source translates the factorization with the same lower-triangle convention and runtime validity checks. Both native and JAX execution use ordinary backend differentiation; this callable has no custom AD rule.

source
ReactiveKernels.rk_expm Function
julia
rk_expm(A::Matrix{Float64}) -> Matrix{Float64}

Matrix exponential as an RK-owned primitive: rk_expm(A) == exp(A), with forward- and reverse-mode rules generated from the one pure-math graph rk_expm_rule (JVP and VJP via augmented-matrix exponentials). Differentiating through it with Enzyme — directly or via DifferentiationInterface with AutoEnzyme — uses those generated cuts, so the LAPACK ccall inside is never differentiated. Native @kernel and @traceable source also selects this callable for resolved exp calls on Matrix{Float64} (see docs/src/manual-derivative-rules.md).

source
ReactiveKernels.rk_log1pexp Function
julia
rk_log1pexp(x::Float64)

Stable log(1 + exp(x)) with a generated scalar derivative rule. The joint value/partial graph shares exp(-abs(x)); neither tail evaluates exp(abs(x)). The primal-only call selects the value cut. Ordinary supported AD backends select the same graph's active derivative cut.

source
ReactiveKernels.rk_ode_bdf_tol Function
julia
rk_ode_bdf_tol(f, y0, t0, ts, reltol, abstol, maxsteps, args...)

Integrate dy/dt = f(t, y, args...) with Julia's standard OrdinaryDiffEqBDF.FBDF(), retaining one solver history across all output times. Return a fresh Matrix{Float64} with output times in rows and state coordinates in columns. Load OrdinaryDiffEqBDF, SciMLBase, and SciMLSensitivity to activate this native numerical extension; without them a call throws an error naming them.

y0 and ts are nonempty real vectors with finite entries; ts is strictly increasing and starts after finite t0. Tolerances must be finite and nonnegative, with at least one positive; maxsteps is a positive integer. The limit counts accepted solver steps between consecutive requested outputs (starting at t0), without restarting the solver. Caller tolerances are passed to the solver unchanged. Invalid inputs throw ArgumentError or DomainError, and a wrong RHS length throws DimensionMismatch. A solve the method cannot complete from valid inputs (an unsuccessful return code, or the limit exceeded) throws ReactiveKernels.ODESolveFailure, a ReactiveKernels.NumericalFailure: a sampler target may answer -Inf there, as Stan rejects such a proposal.

The RHS returns a state-length vector and reads its arguments without mutating them. Extra arguments may be floating scalars or arrays, integer scalars or arrays, and tuples or named tuples of these. Inputs remain read-only, including on failure. Numeric states, times, and floating arguments are packed as Float64. The RHS must also accept dual-number states and floating arguments, because the solver's Newton Jacobian and the forward sensitivities below evaluate it with ForwardDiff numbers. The current adapter differentiates floating parameters packed through args. Active parameters captured only in f are unsupported: the scalar-decay reproducer benchmark/repro_native_bdf_captured_rhs.jl yields a zero gradient instead of its nonzero analytic derivative. A closure is valid for primal evaluation; move its active parameters into args for this adapter's Reverse. Ordinary native Enzyme Reverse uses SciMLSensitivity's ForwardDiffSensitivity(): the solver integrates the sensitivities with respect to the initial state and every packed floating value as dual numbers, and its error test covers them as well as the states. Gradient accuracy therefore follows the caller tolerances, comparably to CVODES with sensitivity error control. A gradient costs one dual solve per chunk of at most 12 packed floating values, data included, plus one per chunk of at most 12 states. No consumer AD rule or activity setting is required. Initial and output times participate in differentiation.

This is the generic numerical callable. Source/transpilation layers can bind an ODE call to it or restructure equivalent helpers and parameter layouts; preserve the scientific equations and accuracy controls. This signature is a compatibility entry point, not a required downstream source layout. The bridge does not install a method on a foreign source token.

See also rk_ode_rk45_tol, the same bridge over an explicit method.

source
ReactiveKernels.rk_ode_rk45_tol Function
julia
rk_ode_rk45_tol(f, y0, t0, ts, reltol, abstol, maxsteps, args...)

Integrate dy/dt = f(t, y, args...) with Julia's standard OrdinaryDiffEqLowOrderRK.DP5(), the explicit adaptive Dormand–Prince 5(4) Runge–Kutta method that Stan's ode_rk45_tol also uses. Load OrdinaryDiffEqLowOrderRK, SciMLBase, and SciMLSensitivity to activate this native numerical extension; without them a call throws an error naming them.

The arguments, the returned times-by-states Matrix{Float64}, the per-output step budget, the read-only and dual-number requirements on the RHS, the packing of args, and ordinary native Enzyme Reverse through ForwardDiffSensitivity() are exactly those of rk_ode_bdf_tol: both are one shared adapter. Besides the integration method, they differ in one respect: outputs come from DP5's dense interpolant, as in Stan's dense-output RK45, so requesting more output times adds no solver steps, whereas rk_ode_bdf_tol ends a step at every output time. As an explicit method, DP5 suits nonstiff systems and needs no Newton Jacobian; a stiff system takes many small steps and can exhaust maxsteps, where rk_ode_bdf_tol is the stiff choice.

Stan's ode_rk45(f, y0, t0, ts, args...) is this call with reltol = 1e-6, abstol = 1e-6 and maxsteps = 10^6. Stan returns one state vector per output time; this callable returns them as matrix rows.

source
ReactiveKernels.rk_symmetric_eigvals Function
julia
rk_symmetric_eigvals(A::Matrix{Float64}) -> Vector{Float64}

Eigenvalues of a symmetric matrix as an RK-owned primitive: rk_symmetric_eigvals(A) == eigen(Symmetric(A)).values, with forward- and reverse-mode rules generated from the one pure-math graph rk_symmetric_eigvals_rule. Differentiating through it with Enzyme — directly or via DifferentiationInterface with AutoEnzyme — uses those generated cuts, so the LAPACK syevr! ccall inside is never differentiated (see docs/src/manual-derivative-rules.md).

A must be symmetric (only the upper triangle is read) with distinct eigenvalues.

source
ReactiveKernels.rk_symmetric_eigvecs Function
julia
rk_symmetric_eigvecs(A::Matrix{Float64}) -> Matrix{Float64}

Orthonormal eigenvectors (columns) of a symmetric matrix as an RK-owned primitive: rk_symmetric_eigvecs(A) == eigen(Symmetric(A)).vectors, with forward- and reverse-mode rules generated from the one pure-math graph rk_symmetric_eigvecs_rule. Differentiating through it with Enzyme — directly or via DifferentiationInterface with AutoEnzyme — uses those generated cuts, so the LAPACK syevr! ccall inside is never differentiated (see docs/src/manual-derivative-rules.md).

A must be symmetric (only the upper triangle is read) with distinct eigenvalues. Columns are defined up to sign; align a covector's signs with the primal's columns.

source
ReactiveKernels.rule_inputs Method
julia
rule_inputs(rule) -> Tuple{Vararg{Symbol}}

The input port names of a generated rule, in signature order.

source
ReactiveKernels.save_visualization Method
julia
save_visualization(path, graph_or_plan; alternatives=false, orientation=:horizontal)
save_visualization(path, visualization)

Write a visualization to .html, .svg, .dot, or .gv. HTML loads pinned Cytoscape.js + ELK assets when its host has not bundled them and always carries a self-contained SVG fallback. SVG is the dependency-free static surface, and DOT preserves the graph for Graphviz and other compatible tools. Returns path.

source
ReactiveKernels.scalar_derivative_rule Method
julia
scalar_derivative_rule(graph::KernelSpec; primal, partials, name) -> ScalarDerivativeRule

Generate an RK-owned callable whose value and derivatives all come from graph, an ordinary @kernel whose HAVE ports are the function's real scalar arguments in signature order and whose WANT ports include the primal output primal::Symbol and one partial derivative per input, named in partials::NamedTuple (input name => WANT port name, in signature order).

The returned callable evaluates the graph's primal cut (the partial is pruned), and every AD backend with a ReactiveKernels extension loaded treats it as a primitive whose reverse and forward rules are generated from the activity-selected cuts (see derivative_cut): no backend-specific derivative code is authored, and no rule attaches to a function this repository does not own. Every input, the primal, and every partial must be declared with a Real scalar type. A cut that runs a plate, a scan or an embedded kernel is compiled natively (see derivative_rule).

source
ReactiveKernels.scalar_kernel Method

The scalar prepared kernel retained as the mathematical authority.

source
ReactiveKernels.scan Method
julia
scan(xs, ys...; init, include_init = false) do carry, x, y...
    …
    (new_carry, output)
end
scan(xs, ys...; init, history = h0) do carry, x, y..., earlier
    …
    (new_carry, output)
end

Author a bounded SEQUENTIAL recurrence inside a @kernel / @ppl body. The positionals are the sequences to scan over, advanced in lockstep (they must share axes); init seeds the threaded carry. The step reads any other enclosing value whole, as a closure. A trailing Ref(shared) operand also passes a value whole. The do-block receives (carry, x, y...) and must end with the 2-tuple (new_carry, output); scan returns the vector [output…]. A compound carry may be carried as a NamedTuple (init = (; a, b), read carry.a). Empty sequences run no step and return an empty vector of the step's inferred output type.

With the literal include_init = true, scan returns [init, output…], one element longer than the sequences and written into a single buffer: the trajectory [R₀, R₁, …, Rₙ] of a recurrence whose output is its next carry. Its value and element type (promote_type(typeof(init), output type)) are those of vcat([init], scan(…; init)) without the second vector; empty sequences return [init].

With history = h0 (a number) the do-block takes one more, last argument: the result vector being written, read-only. At step j its entry i is step i's output for i < j and h0 from j on, on every backend, so a recurrence over all earlier outputs (sum(earlier[i] * u[j - i] for i in 1:j-1; init = 0.0), with j from a lockstep eachindex(xs)) needs no carried copy of them. The result's element type is typeof(h0). A carry may not hold the history, and history cannot be combined with include_init = true.

With history = leading (a vector), the result starts with those entries: it is [leading; output…], step j writes entry length(leading) + j, and the last argument is that whole vector, with entries not written yet at zero(eltype(leading)). A recurrence seeded with a[1:m] thus reads its seeds and earlier steps from one vector.

With history = (a = leading_a, b = leading_b, ...), each named column uses the number or vector semantics above independently. The last argument and the scan result are named tuples of column vectors; the step returns a named tuple of scalar outputs with those same names. Each vector seed contributes its own prefix, and each column retains its seed's element type.

It lowers to one retained ordered loop, so a natural sequential recurrence needs no closed-form rewrite. This is @kernel authoring sugar recognized by the macro as a recipe's right-hand side, like an authored plate; it is not a callable runtime function outside a kernel body.

source
ReactiveKernels.scan_body Method

The transparent scalar step plan captured by an authored scan(...) do recipe.

source
ReactiveKernels.set! Method
julia
set!(state, v::Value, x)

Set an external source value and bump its version. Source values are authoritative have cut points; the planner never recomputes them and invalidation never traverses upstream of them.

source
ReactiveKernels.set! Method

Set a declared HAVE value and invalidate its downstream slots.

source
ReactiveKernels.stage_primal Method
julia
stage_primal(rule::DerivativeRule, ::Val{mask}, inputs...) -> (y, residuals)

First stage of reverse mode for activity mask: the primal output together with the residual tuple named by stage_residuals, computed by one cut of the graph (shared intermediates are computed once).

source
ReactiveKernels.stage_residuals Method
julia
stage_residuals(rule::DerivativeRule, ::Val{mask}) -> Tuple{Vararg{Symbol}}

The residual environment of the staged reverse branch for activity mask: the covector-independent values its selected VJP reads — inputs (in signature order), the primal output, or graph intermediates (a stable residual such as a shared exp). stage_primal computes them once; stage_reverse reads them instead of recomputing the intermediates from the inputs.

source
ReactiveKernels.stage_reverse Method
julia
stage_reverse(rule::DerivativeRule, ::Val{mask}, residuals::Tuple, covector)
    -> (cotangents of the active inputs, in input order)

Second stage of reverse mode: the VJP branch for activity mask, planned from the residuals returned by stage_primal and the output covector. Equal to reverse_cut on the same inputs, without recomputing the retained intermediates.

source
ReactiveKernels.statevalue Method

Return the typed, literal-index state handle for a graph Value.

source
ReactiveKernels.touch! Method

Mark an in-place mutation of a declared HAVE value and invalidate downstream slots.

source
ReactiveKernels.transform Method
julia
transform(ast, passes...) -> Expr

Apply zero or more AST passes (each an Expr -> Expr function) in order. This is the extension point for simplification, mutation/bufferization, or backend-specific rewrites; it must not change planning semantics (gist §9).

source
ReactiveKernels.unfreeze! Method

Remove a frozen/cached value so its graph producers apply again.

source
ReactiveKernels.unfreeze! Method

Remove a compiled-state frozen cut point and recompute it lazily on demand.

source
ReactiveKernels.valtype Method

The declared Julia runtime type of a value.

source
ReactiveKernels.value! Method
julia
value!(g, name, T) -> Value{T}

Create a Value{T} and register it into graph g.

source
ReactiveKernels.value Method
julia
value(name, T)

Construct a standalone Value{T} with a fresh global identity. Use value! to also register it into a graph.

source
ReactiveKernels.vectorize Method
julia
vectorize(kernel::PreparedKernel; batched, reuse=false, schedule=nothing,
          simplify=nothing) -> callable
vectorize(spec::KernelSpec; batched, have=inputs(spec),
          want=outputs(spec), passes=(), reuse=false, schedule=nothing,
          simplify=nothing) -> callable

Lift a scalar kernel over position batching. This is the concise public spelling for prepare_batched; replica remains the equivalent lower-level name. See that docstring for the batch-axis, output-shape, purity, and allocation contract.

simplify is as for prepare: unless it is false, the position driver computes numerically fragile compositions in their stable form. A PreparedKernel argument contributes its plan, not its setting, as for prepare_nonallocating.

For a native reuse=true result, copy(kernel) creates an independent execution instance with empty output buffers and the same prepared computation. See prepare_batched for its lifetime and concurrency contract.

source
ReactiveKernels.visualize Method
julia
visualize(graph; orientation=:horizontal) -> DAGVisualization
visualize(plan; alternatives=false, orientation=:horizontal) -> DAGVisualization

Create a DAG visualization. Values and recipes are separate nodes, with edges value → recipe → value, so multi-input and multi-output recipes remain unambiguous.

For a Plan, the default shows only selected recipes. Set alternatives=true to add backward-reachable but unselected candidates as muted dashed nodes. orientation may be :horizontal (left to right) or :vertical (top to bottom).

Rich Julia displays render the result as Cytoscape.js + ELK interactive HTML when supported, with self-contained SVG as the static and offline fallback. Documentation bundles the libraries locally; standalone rich displays load the same pinned libraries on demand. The underlying Graph and Plan types expose both representations directly, so a notebook can display them without calling visualize explicitly.

source
ReactiveKernels.with_bound_statistics Function
julia
with_bound_statistics(f, enabled::Bool = true)

Run f() with every preparation it makes, nested ones included, using (true) or not using (false) bound least-squares statistics for summed Gaussian plates, whatever the bound_statistics preference says. It is the bound_statistics keyword of prepare for preparations made through an API that does not pass it on, such as a PPL's sampler preparation.

source
ReactiveKernels.with_plate_reverse Function
julia
with_plate_reverse(f, enabled::Bool = true)

Run f() with the generated summed-plate reverse enabled (or disabled) for every AD preparation f makes, whatever the plate_reverse preference says. A prepared gradient differentiates each eligible summed plate program with a reverse generated from its own code; every other plate is differentiated by the backend as before. This also applies to non-allocating kernels after their cache activity and ownership rewrite. plate_reverse_report reports static eligibility; backend operand annotations can still require the ordinary reverse at execution.

Include kernel preparation in this scope as well as AD preparation. Native optimizations chosen while the rule is disabled can produce forms outside the generated reverse's current coverage; enabling it only for AD can then retain the backend's ordinary reverse for those regions.

source

Macros ​

ReactiveKernels.@kernel Macro
julia
@kernel model(f, x) = begin
    y = f(x)
end

kernel = prepare(model)
kernel(sin, 1.0)

@kernel affine(x, scale = 2; offset = scale - 1) = begin
    y = scale * x + offset
end

prepare(affine)(3; offset = 4)

@kernel square(x) = x * x

prepare(square)(3)

@kernel begin
    x::Float64
    y::Float64 = f(x)
    return y
end

Build a named KernelSpec without executing any recipe RHS. The primary form mirrors an ordinary Julia function definition: its signature names the default have ports, including function-valued inputs. The macro binds the function name to the resulting KernelSpec; prepare turns it into the callable straight-line kernel. Both short and long definitions are supported. Trailing positional defaults and fixed keyword arguments use ordinary Julia call syntax. Defaults are evaluated at call time, from left to right, and may refer to earlier positional or keyword arguments. A keyword without a default is required. Defaulted and keyword arguments remain exposed have ports; the signature adapter only fills their values before entering the same generated positional kernel. Variadic positional and keyword splats are not supported.

Type annotations are optional metadata. Omitting them does not add dynamic dispatch to a prepared kernel: Julia specializes the generated function on the concrete operation and input types at the call site. An assignment creates one recipe; tuple assignment creates a multi-output recipe, and assigning an output again creates an alternative producer. Declarations and producers may be forward-referenced: the complete named-port namespace is collected before dependencies are inferred. When a caller global has the same name as a port, qualify the global with its module name.

Every signature argument and assignment is exposed by name. return is optional: without one, derived sink ports form the default want boundary; with one, the returned port names replace that default. Either way, every port remains selectable through spec[:name] or want = :name.

A direct call to another stateless KernelSpec on a recipe RHS splices that kernel's recipes into this graph during construction. Pass existing typed ports positionally and destructure the nested default output boundary exactly. Every call site receives fresh internal value identities, so repeated calls remain independent while the outer planner can prune or CSE their recipes. No nested runtime call remains in a prepared kernel.

Calling a spec itself with positional values, spec(args...), runs its default boundary, as prepare(spec)(args...) does. The graph keeps that prepared kernel, so only the first call per graph version prepares it (and the first under another preparation setting, such as simplify); later calls cost a cache lookup on top of the kernel's own call. A hot loop that holds prepare(spec) skips the lookup as well.

A short expression body is a compact single-result kernel. Its value is exposed as a port named after the kernel, and that port is the default want boundary: @kernel square(x) = x * x creates ports :x and :square. A bare identity such as @kernel passthrough(x) = x aliases the result port directly to the input without an identity recipe or an additional physical slot. Block bodies retain the graph-oriented sink/explicit-return behavior described above.

Recipe metadata uses the compact form

@recipe (cost = 1.2, cse_key = :combined) (a::T, b::T) = combined(u)

All recipe bodies resolve and capture names in the caller's scope. The macro only constructs closures and graph metadata; recipe bodies run only when a prepared kernel is invoked.

@kernel supports two authoring modes, discriminated by the body. A methodless recipe body authors a stateless graph KernelSpec — this docstring's primary form. A body with nested method definitions authors an OBJECT kernel with an IMPLICIT synthesized receiver: pure straight-line methods are transparent named endpoints. Nested methods declare no self/__self__ formal, bare unshadowed names are the owner's fields, and __self__ appears only as a sibling object-pass actual (flip!(__self__, depth)). ReactiveKernels compiles pure kernels only: a methodless body that mutates a field of its first positional subject, or any !! name (a strong same-object update such as nuts!!(state; rng)), is a stateful free method and raises an ArgumentError. Reactive mutation of a compiled stateless kernel remains available through prepare_reactive, set!, mutate!, and touch!.

source
ReactiveKernels.@node Macro
julia
@node(expr)

Anonymous-node promoter. Inside a @kernel recipe, @node(expr) is PORT-LIFTED into a distinct named recipe node (a schedulable graph node/port) — the ONLY way an anonymous subexpression becomes an independent node (named recipe assignments auto-node; no arbitrary AST extraction, no cost heuristics). It adds NO second object-definition surface. Outside a @kernel (or if it survives to runtime) it is a harmless identity.

source
ReactiveKernels.@plate Macro
julia
@plate for i in R
    …
    out[i] = expr
end

Loop syntax for an authored plate inside a @kernel body: each iteration is one cell, X[i] at the loop index zips X, other values are read as closures, and out[i] = … names the plate's output out. It prepares the same kernel as the equivalent out = plate(...) do … end. It is recognized only as a statement of a @kernel body.

source
ReactiveKernels.@scan Macro
julia
@scan begin
    a[1] = seed
    for t in 2:T
        a[t] = f(a[t - 1], x[t], t)
    end
end

Loop syntax for an authored scan inside a @kernel body. Every array the loop writes at t is carried: it is seeded at 1..m before the loop (the same depth for every carried array), each step writes it once, and the step reads earlier values through literal lags a[t - k] (1 ≤ k ≤ m), the current value a[t] after its write, and any earlier entry whose index provably lies in 1:(t - 1): a[s] or a[t - s] under a generator for s in 1:(t - 1), or a window a[(t - k):(t - 1)]. Other values are read as closures. The result a is the whole trajectory [a[1], …, a[T]]. One carried array with one seed prepares the same kernel as a = scan(2:T; init = seed, include_init = true) do a_prev, t … end; several carried arrays share one scan and expose named output columns. History reads use seed-prefixed buffers, one per carried array, so mutually dependent earlier entries are supported in the same scan (docs/src/scan.md, "Reading earlier entries").

source
ReactiveKernels.@traceable Macro
julia
@traceable f(args...) = body
@traceable function f(args...) ... end

Define an ordinary method of f whose generator folds over a data-length iterator, sum(term for i in iter [if condition]; init = x) with iter an eachindex, axes, range or a:b call, run as their explicit-accumulator loop: Base's value, bitwise, without the Any that Julia 1.10 infers for a nested Base fold (the compiler page, "Lowering and emitted ABI"). The method's source is recorded for source-reading compilers (jax_source), and an on_error = :ignore preparation calls its throw-stripped twin.

Supported: positional arguments with optional defaults, a trailing Vararg argument (args..., args::T..., args::Vararg{T,N}, whose name the recorded source reads as the tuple of the trailing arguments, as the method does), where clauses, and a return-type annotation. A docstring before @traceable documents the method, as it does a plain definition. A @traceable method of a function from Base, Core or ReactiveKernels is rejected, as is a return inside a loop. Body-level early returns are recorded as lazy conditional expressions; the ordinary method keeps its authored control flow. Keyword arguments keep Julia's defaults, required arguments and type checks.

source

Constants and modules ​

ReactiveKernels.ReactiveKernels Module
julia
ReactiveKernels

A have/want computational-graph kernel layer. Build a graph of pure computations, declare what values you have and what you want, and get a specialized straight-line Julia kernel containing only the cheapest necessary computation — with no graph traversal, dynamic dispatch, or planner overhead on the hot path.

The core (Value, Recipe, Graph, plan, prepare) is stateless. The ReactiveState layer on top adds incremental/reactive execution with provenance-aware invalidation and frozen/checkpoint cut points, without changing planner semantics.

See the design brief this package implements for the full rationale.

source

Additional exports ​

These exported bindings have no separate docstring. Their definitions are linked below.

NameKindSource
has_reverse_branchFunctiondefinition