JAX helpers and submodels
This guide continues JAX source: how emitted modules share submodel functions, and which helpers with loops and branches translate.
Named submodels and shared entries
Repeated calls to an authored submodel share a Python function when their selected computations agree. A scoped rewrite that changes the computation gets a separate function. Each function carries the submodel's documentation. The native model retains its expanded graph, so individual locals remain queryable.
The public density functions and constrain call a shared model function. Their output selectors are fixed by the wrappers, allowing JAX to trace only the requested computation. Call them as before: log_density(u, **prepared). The submodel functions likewise take a static outputs selection; their arguments and array lengths remain runtime inputs. Consecutive statements that the same outputs need share one selection block (if _entry in (...):, or if any(name in outputs for name in (...)): in a submodel function), and the checks every public function runs, such as the packed-length check, run once before the per-function returns.
A plate may use separate functions for a scalar return value and a batched density. Combined computations, such as grouped scalar priors, retain their shared graph boundary. Interleaved dependencies split a submodel into named portions that execute in the original dependency order.
using ReactiveKernels, ReactiveKernelsPPL
@rkppl effect(loc, scale, spread_rate, n) = begin
"Mean of the effect."
mean ~ Normal(loc, scale)
"Spread of the members around the mean."
spread ~ Exponential(spread_rate)
"Standardised member deviations."
z[1:n] .~ Normal.(0, 1)
return mean .+ spread .* z
end
model = @rkppl begin
a ~ effect(a_loc, a_scale, a_rate, n)
b ~ effect(b_loc, b_scale, b_rate, n)
y .~ Normal.(a .+ b, noise)
end
bound = model(; n = 3, a_loc = 0.0, a_scale = 1.0, a_rate = 1.0,
b_loc = 0.0, b_scale = 1.0, b_rate = 1.0, noise = 1.0) |
(; y = [0.1, 0.2, 0.3])
built = build_kernel(bound)
print(jax_source(built, bound))"""Generated by ReactiveKernelsPPL.jax_source from a built @rkppl program; do not edit.
Data: a_loc, a_rate, a_scale, b_loc, b_rate, b_scale, n, noise, y.
Model documentation:
- `a.mean`: Mean of the effect.
- `a.spread`: Spread of the members around the mean.
- `a.z`: Standardised member deviations.
- `b.mean`: Mean of the effect.
- `b.spread`: Spread of the members around the mean.
- `b.z`: Standardised member deviations.
"""
import numpy as np
import scipy.special as ssp
from typing import Any
import jax
import jax.numpy as jnp
import jax.scipy.linalg
import jax.scipy.special as jsp
from jax.typing import ArrayLike
jax.config.update("jax_enable_x64", True)
DATA = {"a_loc": {"dtype": "float64", "ndim": 0, "ragged": False}, "a_rate": {"dtype": "float64", "ndim": 0, "ragged": False}, "a_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_loc": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_rate": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "n": {"dtype": "int64", "ndim": 0, "ragged": False}, "noise": {"dtype": "float64", "ndim": 0, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}}
INPUTS = ("unconstrained", "ppl_last_a_z", "ppl_first_b_z", "ppl_last_b_z", "y", "noise", "_ppl_pw_y_resp_lanes_1", "_ppl_pw_y_resp_lanes_2", "_ppl_pw_y_resp_lane_order", "a_loc", "a_scale", "ppl_prior_a_mean_log_scale", "ppl_prior_a_spread_log_scale", "a_rate", "b_loc", "b_scale", "ppl_prior_b_mean_log_scale", "ppl_prior_b_spread_log_scale", "b_rate", "n")
PREPARED = {"ppl_last_a_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_first_b_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "ppl_last_b_z": {"dtype": "int64", "ndim": 0, "ragged": False}, "y": {"dtype": "float64", "ndim": 1, "ragged": False}, "noise": {"dtype": "float64", "ndim": 0, "ragged": False}, "_ppl_pw_y_resp_lanes_1": {"dtype": "int64", "ndim": 1, "ragged": False}, "_ppl_pw_y_resp_lanes_2": {"dtype": "int64", "ndim": 1, "ragged": False}, "_ppl_pw_y_resp_lane_order": {"dtype": "int64", "ndim": 1, "ragged": False}, "a_loc": {"dtype": "float64", "ndim": 0, "ragged": False}, "a_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "ppl_prior_a_mean_log_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "ppl_prior_a_spread_log_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "a_rate": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_loc": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "ppl_prior_b_mean_log_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "ppl_prior_b_spread_log_scale": {"dtype": "float64", "ndim": 0, "ragged": False}, "b_rate": {"dtype": "float64", "ndim": 0, "ragged": False}, "n": {"dtype": "int64", "ndim": 0, "ragged": False}}
UNTRANSLATED = {}
class StaticInt(int):
"""An integer of the prepared data that sets a shape.
It is an `int` everywhere, and `jax.jit` treats it as static, so the
functions jit with the prepared data as arguments; a new value traces
them again.
"""
def __repr__(self):
return "StaticInt(%d)" % int(self)
jax.tree_util.register_pytree_node(StaticInt, lambda s: ((), int(s)), lambda v, _: StaticInt(v))
def effect(
loc: ArrayLike,
mean: ArrayLike,
ppl_prior_mean_log_scale: ArrayLike,
ppl_prior_spread_log_scale: ArrayLike,
scale: ArrayLike,
spread: ArrayLike,
spread_rate: ArrayLike,
z: ArrayLike,
*,
outputs: tuple[str, ...],
) -> dict:
"""`mean`: Mean of the effect.
`spread`: Spread of the members around the mean.
`z`: Standardised member deviations.
"""
results = {}
if any(name in outputs for name in ("value",)):
def value_cell(mean_2, spread_2, z_2):
plate_value = mean_2 + spread_2 * z_2
return plate_value
value = (jnp.zeros(z.shape[:1], dtype=jnp.float64) if 0 in z.shape[:1] else jax.vmap(value_cell, in_axes=(None, None, 0))(mean, spread, z))
if any(name in outputs for name in ("ppl_prior_mean", "ppl_prior_mean_standard_logpdf")):
ppl_prior_mean_logpdf_z = (mean - loc) / jnp.where(jnp.logical_and(scale == 0, mean == loc), 1.0, scale)
ppl_prior_mean_standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * ppl_prior_mean_logpdf_z ** 2
if any(name in outputs for name in ("ppl_prior_mean",)):
ppl_prior_mean = ppl_prior_mean_standard_logpdf - jnp.where(jnp.logical_and(scale == 0, mean != loc), 0.0, ppl_prior_mean_log_scale)
if any(name in outputs for name in ("ppl_prior_spread",)):
ppl_prior_spread = jax.lax.cond(spread < 0, lambda: -jnp.inf, lambda: -ppl_prior_spread_log_scale - spread / spread_rate)
if any(name in outputs for name in ("ppl_prior_z", "ppl_pw_prior_z")):
def ppl_pw_prior_z_cell(z_2):
log_scale = np.log(1.0)
standardized = (z_2 - 0.0) / jnp.where((z_2 == 0.0 if 1.0 == 0 else False), 1.0, 1.0)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
logpdf = standard_logpdf - jnp.where((z_2 != 0.0 if 1.0 == 0 else False), 0.0, log_scale)
return logpdf
ppl_pw_prior_z = (jnp.zeros(z.shape[:1], dtype=jnp.float64) if 0 in z.shape[:1] else jax.vmap(ppl_pw_prior_z_cell, in_axes=(0,))(z))
if any(name in outputs for name in ("ppl_prior_z",)):
ppl_prior_z = jnp.sum(ppl_pw_prior_z)
if "ppl_prior_mean" in outputs:
results["ppl_prior_mean"] = ppl_prior_mean
if "ppl_prior_spread" in outputs:
results["ppl_prior_spread"] = ppl_prior_spread
if "ppl_prior_z" in outputs:
results["ppl_prior_z"] = ppl_prior_z
if "ppl_pw_prior_z" in outputs:
results["ppl_pw_prior_z"] = ppl_pw_prior_z
if "ppl_prior_mean_standard_logpdf" in outputs:
results["ppl_prior_mean_standard_logpdf"] = ppl_prior_mean_standard_logpdf
if "value" in outputs:
results["value"] = value
return results
def prepare_data(a_loc: ArrayLike, a_rate: ArrayLike, a_scale: ArrayLike, b_loc: ArrayLike, b_rate: ArrayLike, b_scale: ArrayLike, n: ArrayLike, noise: ArrayLike, y: ArrayLike) -> dict:
"""The functions' data inputs, computed from the raw data once per dataset.
Pass the data by the names the model reads them; a list of arrays is a ragged
column. Call the other functions with the result: `f(u, **prepared)`.
"""
y = np.asarray(y, dtype=np.float64)
rkppl_value_a_loc = a_loc
rkppl_value_a_rate = a_rate
rkppl_value_a_scale = a_scale
rkppl_value_b_loc = b_loc
rkppl_value_b_rate = b_rate
rkppl_value_b_scale = b_scale
rkppl_value_n = n
rkppl_value_noise = noise
ppl_last_a_z = 4 + n
ppl_first_b_z = ppl_last_a_z + 1
ppl_last_b_z = ppl_first_b_z + (n - 1)
ppl_prior_a_mean_log_scale = np.log(a_scale)
ppl_prior_a_spread_log_scale = np.log(a_rate)
ppl_prior_b_mean_log_scale = np.log(b_scale)
ppl_prior_b_spread_log_scale = np.log(b_rate)
def lane_conditions(lane_input_1, lane_input_2):
return (bool(lane_input_2 > 0),)
lane_conditions_2 = np.asarray([lane_conditions(entry, noise) for entry in y], dtype=bool).reshape((-1, 1))
lanes = np.flatnonzero(lane_conditions_2[:, 0])
lanes_2 = np.flatnonzero(~lane_conditions_2[:, 0])
ppl_pw_y_resp_lanes_1 = lanes
ppl_pw_y_resp_lanes_2 = lanes_2
ppl_pw_y_resp_lane_order = np.argsort(np.concatenate((lanes, lanes_2,)), kind="stable")
return {"ppl_last_a_z": StaticInt(ppl_last_a_z), "ppl_first_b_z": StaticInt(ppl_first_b_z), "ppl_last_b_z": StaticInt(ppl_last_b_z), "y": np.asarray(y, dtype=np.float64), "noise": noise, "_ppl_pw_y_resp_lanes_1": np.asarray(ppl_pw_y_resp_lanes_1, dtype=np.int64), "_ppl_pw_y_resp_lanes_2": np.asarray(ppl_pw_y_resp_lanes_2, dtype=np.int64), "_ppl_pw_y_resp_lane_order": np.asarray(ppl_pw_y_resp_lane_order, dtype=np.int64), "a_loc": a_loc, "a_scale": a_scale, "ppl_prior_a_mean_log_scale": ppl_prior_a_mean_log_scale, "ppl_prior_a_spread_log_scale": ppl_prior_a_spread_log_scale, "a_rate": a_rate, "b_loc": b_loc, "b_scale": b_scale, "ppl_prior_b_mean_log_scale": ppl_prior_b_mean_log_scale, "ppl_prior_b_spread_log_scale": ppl_prior_b_spread_log_scale, "b_rate": b_rate, "n": StaticInt(n)}
def model(_entry: str, unconstrained: ArrayLike, **prepared: ArrayLike) -> Any:
"""Shared model computation. The generated entry wrappers select a static output."""
ppl_last_a_z = prepared["ppl_last_a_z"]
ppl_first_b_z = prepared["ppl_first_b_z"]
ppl_last_b_z = prepared["ppl_last_b_z"]
y = prepared["y"]
noise = prepared["noise"]
_ppl_pw_y_resp_lanes_1 = prepared["_ppl_pw_y_resp_lanes_1"]
_ppl_pw_y_resp_lanes_2 = prepared["_ppl_pw_y_resp_lanes_2"]
_ppl_pw_y_resp_lane_order = prepared["_ppl_pw_y_resp_lane_order"]
a_loc = prepared["a_loc"]
a_scale = prepared["a_scale"]
ppl_prior_a_mean_log_scale = prepared["ppl_prior_a_mean_log_scale"]
ppl_prior_a_spread_log_scale = prepared["ppl_prior_a_spread_log_scale"]
a_rate = prepared["a_rate"]
b_loc = prepared["b_loc"]
b_scale = prepared["b_scale"]
ppl_prior_b_mean_log_scale = prepared["ppl_prior_b_mean_log_scale"]
ppl_prior_b_spread_log_scale = prepared["ppl_prior_b_spread_log_scale"]
b_rate = prepared["b_rate"]
n = prepared["n"]
unconstrained = jnp.asarray(unconstrained)
y = jnp.asarray(y)
_ppl_pw_y_resp_lanes_1 = jnp.asarray(_ppl_pw_y_resp_lanes_1)
_ppl_pw_y_resp_lanes_2 = jnp.asarray(_ppl_pw_y_resp_lanes_2)
_ppl_pw_y_resp_lane_order = jnp.asarray(_ppl_pw_y_resp_lane_order)
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
a_mean = unconstrained[0]
u_argument = unconstrained[1]
constrain_2 = jnp.exp(u_argument)
b_mean = unconstrained[2]
u_argument_2 = unconstrained[3]
constrain_3 = jnp.exp(u_argument_2)
a_z = unconstrained[4:ppl_last_a_z]
if _entry in ("log_density", "log_prior", "log_likelihood"):
a = effect(
loc=(a_loc if _entry in ("log_density", "log_prior") else None),
mean=(a_mean if _entry in ("log_density", "log_prior", "log_likelihood") else None),
ppl_prior_mean_log_scale=(ppl_prior_a_mean_log_scale if _entry in ("log_density", "log_prior") else None),
ppl_prior_spread_log_scale=(ppl_prior_a_spread_log_scale if _entry in ("log_density", "log_prior") else None),
scale=(a_scale if _entry in ("log_density", "log_prior") else None),
spread=(constrain_2 if _entry in ("log_density", "log_prior", "log_likelihood") else None),
spread_rate=(a_rate if _entry in ("log_density", "log_prior") else None),
z=(a_z if _entry in ("log_density", "log_prior", "log_likelihood") else None),
outputs=tuple(
name for name, needed in (
("ppl_prior_mean", ("log_density", "log_prior")),
("ppl_prior_spread", ("log_density", "log_prior")),
("ppl_prior_z", ("log_density", "log_prior")),
("ppl_pw_prior_z", ("log_density", "log_prior")),
("ppl_prior_mean_standard_logpdf", ("log_density", "log_prior")),
("value", ("log_density", "log_likelihood")),
)
if _entry in needed
),
)
if _entry in ("log_density", "log_prior", "log_likelihood", "constrain"):
b_z = unconstrained[ppl_first_b_z - 1:ppl_last_b_z]
if _entry in ("log_density", "log_prior", "log_likelihood"):
b = effect(
loc=(b_loc if _entry in ("log_density", "log_prior") else None),
mean=(b_mean if _entry in ("log_density", "log_prior", "log_likelihood") else None),
ppl_prior_mean_log_scale=(ppl_prior_b_mean_log_scale if _entry in ("log_density", "log_prior") else None),
ppl_prior_spread_log_scale=(ppl_prior_b_spread_log_scale if _entry in ("log_density", "log_prior") else None),
scale=(b_scale if _entry in ("log_density", "log_prior") else None),
spread=(constrain_3 if _entry in ("log_density", "log_prior", "log_likelihood") else None),
spread_rate=(b_rate if _entry in ("log_density", "log_prior") else None),
z=(b_z if _entry in ("log_density", "log_prior", "log_likelihood") else None),
outputs=tuple(
name for name, needed in (
("ppl_prior_mean", ("log_density", "log_prior")),
("ppl_prior_spread", ("log_density", "log_prior")),
("ppl_prior_z", ("log_density", "log_prior")),
("ppl_pw_prior_z", ("log_density", "log_prior")),
("ppl_prior_mean_standard_logpdf", ("log_density", "log_prior")),
("value", ("log_density", "log_likelihood")),
)
if _entry in needed
),
)
if _entry in ("log_density", "log_likelihood"):
def y_eta_cell(rkppl_leaf_1, rkppl_leaf_2):
plate_value = rkppl_leaf_1 + rkppl_leaf_2
return plate_value
y_eta = (jnp.zeros(a["value"].shape[:1], dtype=jnp.float64) if 0 in a["value"].shape[:1] and b["value"].shape[:1] == a["value"].shape[:1] else jax.vmap(y_eta_cell, in_axes=(0, 0))(a["value"], b["value"]))
lane_entries = jnp.asarray(y)[_ppl_pw_y_resp_lanes_1]
lane_entries_2 = jnp.asarray(y_eta)[_ppl_pw_y_resp_lanes_1]
def ppl_pw_y_resp_cell(y_2, y_eta_2, noise_2):
log_scale = jnp.log(noise_2)
standardized = (y_2 - y_eta_2) / jnp.where(jnp.logical_and(noise_2 == 0, y_2 == y_eta_2), 1.0, noise_2)
standard_logpdf = -0.5 * np.log(2 * np.pi) - 0.5 * standardized ** 2
ppl_density = standard_logpdf - jnp.where(jnp.logical_and(noise_2 == 0, y_2 != y_eta_2), 0.0, log_scale)
return ppl_density
plate_part = (jnp.zeros(lane_entries.shape[:1], dtype=jnp.float64) if 0 in lane_entries.shape[:1] and lane_entries_2.shape[:1] == lane_entries.shape[:1] else jax.vmap(ppl_pw_y_resp_cell, in_axes=(0, 0, None))(lane_entries, lane_entries_2, noise))
lane_entries_3 = jnp.asarray(y)[_ppl_pw_y_resp_lanes_2]
lane_entries_4 = jnp.asarray(y_eta)[_ppl_pw_y_resp_lanes_2]
def ppl_pw_y_resp_cell_2(y_2, y_eta_2, noise_2):
ppl_density = -jnp.inf
return ppl_density
plate_part_2 = (jnp.zeros(lane_entries_3.shape[:1], dtype=jnp.float64) if 0 in lane_entries_3.shape[:1] and lane_entries_4.shape[:1] == lane_entries_3.shape[:1] else jax.vmap(ppl_pw_y_resp_cell_2, in_axes=(0, 0, None))(lane_entries_3, lane_entries_4, noise))
ppl_pw_y_resp = jnp.concatenate((plate_part, plate_part_2,))[_ppl_pw_y_resp_lane_order]
ppl_lik_y_resp = jnp.sum(ppl_pw_y_resp)
if _entry in ("log_density", "log_prior"):
prior = a["ppl_prior_mean"] + a["ppl_prior_spread"] + b["ppl_prior_mean"] + b["ppl_prior_spread"] + a["ppl_prior_z"] + b["ppl_prior_z"]
if _entry in ("log_density", "log_jacobian"):
u_argument_3 = unconstrained[1]
u_argument_4 = unconstrained[3]
log_jacobian_2 = u_argument_3 + u_argument_4
if _entry in ("log_density",):
posterior = prior + ppl_lik_y_resp + log_jacobian_2
if not (unconstrained.size == ppl_last_b_z):
raise ValueError("[layout] packed length ≠ layout total: a packed point holds the coordinates of the binding whose layout packed it")
if _entry == "log_density":
return jnp.asarray(posterior, dtype=jnp.float64)
if _entry == "log_prior":
return jnp.asarray(prior, dtype=jnp.float64)
if _entry == "log_likelihood":
return jnp.asarray(ppl_lik_y_resp, dtype=jnp.float64)
if _entry == "log_jacobian":
return jnp.asarray(log_jacobian_2, dtype=jnp.float64)
if _entry == "constrain":
return {"a": {"mean": jnp.asarray(a_mean, dtype=jnp.float64), "spread": jnp.asarray(constrain_2, dtype=jnp.float64), "z": jnp.asarray(a_z)}, "b": {"mean": jnp.asarray(b_mean, dtype=jnp.float64), "spread": jnp.asarray(constrain_3, dtype=jnp.float64), "z": jnp.asarray(b_z)}}
def log_density(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log density a sampler targets at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`.
The sum of `log_prior`, `log_likelihood` and `log_jacobian`.
"""
return model("log_density", unconstrained, **prepared)
def log_prior(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log prior density of the constrained parameters at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_prior", unconstrained, **prepared)
def log_likelihood(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log likelihood of the observations at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_likelihood", unconstrained, **prepared)
def log_jacobian(unconstrained: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""The log Jacobian of the constraining transforms at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`."""
return model("log_jacobian", unconstrained, **prepared)
def constrain(unconstrained: ArrayLike, **prepared: ArrayLike) -> dict:
"""The constrained value of each parameter, and of each requested value, at `unconstrained`, the packed unconstrained parameters (length `dimension(prepared)`), for the data `prepare_data` returned: `f(u, **prepared)`. Returns a dict, a submodel's values nested under its name:
- `a.mean`: Mean of the effect.
- `a.spread`: Spread of the members around the mean.
- `b.mean`: Mean of the effect.
- `b.spread`: Spread of the members around the mean.
- `a.z`: Standardised member deviations.
- `b.z`: Standardised member deviations.
"""
return model("constrain", unconstrained, **prepared)
def dimension(prepared: dict) -> int:
"""The length of `unconstrained` for the data `prepared` (what `prepare_data` returned)."""
return int(prepared["ppl_last_b_z"])
def parameters(prepared: dict) -> dict:
"""Each parameter's 0-based `start`/`stop` in `unconstrained`, its transform and dimensions,
for the data `prepared` (what `prepare_data` returned)."""
return {"a.mean": {"start": 0, "stop": 1, "transform": "identity", "dims": ()}, "a.spread": {"start": 1, "stop": 2, "transform": "exp", "dims": ()}, "b.mean": {"start": 2, "stop": 3, "transform": "identity", "dims": ()}, "b.spread": {"start": 3, "stop": 4, "transform": "exp", "dims": ()}, "a.z": {"start": 4, "stop": int(prepared["ppl_last_a_z"]), "transform": "identity", "dims": (int(prepared["n"]),)}, "b.z": {"start": int(prepared["ppl_first_b_z"]) - 1, "stop": int(prepared["ppl_last_b_z"]), "transform": "identity", "dims": (int(prepared["n"]),)}}Helpers with loops and branches
A helper becomes a named Python function with its method's argument names, reused by calls with the same argument representation: from recorded source, or, for a plain helper outside Julia and ReactiveKernels, from its lowered code. Its Julia docstring accompanies the body; a broadcast vectorizes the function itself. A leading underscore and ReactiveKernels' own helpers stay private (_name). Arrays, captured numerical values and padded lengths are normally explicit arguments. A helper that carries loop bounds or reads scan history stays nested in that scope, preserving the bounds and history access analysis. Nested plate cells and scan steps are named after the authored values they compute.
A helper translates from recorded source when available: @traceable records it, and a trailing Vararg argument (args..., args::Vararg{T,N}) reads as the tuple of the trailing arguments, as the method receives them, and sum(f, t; init) folds such a tuple over its fixed length; for becomes jax.lax.fori_loop, if becomes jax.lax.cond, and A[i] = v becomes A.at[i].set(v), converting v to A's element type as setindex! does. A jax.lax.cond arm that is one expression is a lambda, and a branch between two values already bound or literal (s == 0 && x == m ? 1.0 : s) is jnp.where, whose value and derivative are the conditional's; an arm that computes anything stays lazy. A condition decided while tracing (a shape or literal test) is Python's own if, so a guard n == k || throw(...) reads if not (n == k): raise ValueError(...). Plain lowered helpers support straight-line code and terminal forward branches, including size guards. They can create immutable closures and fold fixed argument lists with Base.afoldl. Broadcasting Ref(x) passes x whole to each call. Captures remain runtime inputs; host prepare_data uses the same translation.
@traceable methods also accept named keywords, including required and typed keywords. Calls such as weighted(xs; scale) bind by name. Omitted defaults are evaluated in the helper's module, in declaration order, and may read positional arguments and earlier keywords. Supplied keywords skip their defaults. Keyword values and data-derived sizes remain runtime arguments in both host preparation and JAX functions.
A captured NamedTuple of data can be read whole, for example passed to a helper (metadata = (; weights = w, indices = idx) captured by a kernel that calls weighted(x, metadata)). It is the Python tuple of its fields, as a named-tuple HAVE crosses, and the helper's field reads (metadata.weights[1]) index it by position. Each array field is a typed module constant named after the record and the field (METADATA_WEIGHTS = jnp.asarray(..., dtype=jnp.float64)), with Julia's shape and element type, so a matrix or a rank-3 integer array keeps its axes and one-based reads. A record holding an array is itself a module constant (METADATA = (METADATA_WEIGHTS, METADATA_INDICES)), so a call passes that one name; a record of numbers stays a static literal and can size an allocation. A field that is a function or a type raises JAXEmissionError.
Field names obtained from keys(record) or the names parameter of record::NamedTuple{names} remain structural through locals and helper calls. For example, getproperty(record, first(keys(record))) selects the first field in the record's declared order, in host preparation and JAX functions. The record's numerical fields and array lengths remain runtime values; this does not specialize a module to the data used when emitting it.
A host helper that writes its argument in place (rv[k] = x, push!(rv, x), sort!(rv), or a helper it calls doing so) writes the caller's vector, as Julia's does, whether or not the caller reads the helper's result (RK 0.1.278). The caller passes its own local: a copy of an input or a module constant first, and a list when the helper grows it. A slice or another expression in that position raises JAXEmissionError, because Julia's x[r] is a copy and view(x, r) is not, and the two have one NumPy spelling.
A method that a package generates, such as one its macro writes into the caller's module, cannot carry @traceable. The generating package keeps the method's source as a TraceableSource (argument names, body, and the module whose globals the body reads) and hands it over through a provider. It registers the provider with register_source_provider!, once, from the __init__ of the package extension that loads with ReactiveKernels. The emitter asks the provider for a call that has no other translation and no @traceable source, with the function and the Tuple type of the argument types. The provider answers nothing or the source of the method those arguments call natively.
The example below stands in for such a package. Its macro defines the method and keeps its source.
using ReactiveKernels
const GENERATED = Dict{Any,TraceableSource}()
macro generate(def)
call, body = def.args
names = Tuple(arg.args[1] for arg in call.args[2:end])
source = TraceableSource(names, body, __module__)
:($(esc(def)); GENERATED[$(esc(call.args[1]))] = $source)
end
@generate function decay_sum(x::Vector{Float64}, rate::Float64)
total = zero(rate)
for i in 1:3
total = total + x[i] * exp(-i * rate)
end
if rate > 0
total = total / rate
end
return total
end
provide_source(f, argument_types) = get(GENERATED, f, nothing)
register_source_provider!(provide_source)
@kernel decayed(x::Vector{Float64}, rate::Float64) = begin
value = decay_sum(x, rate)
return value
end
print(jax_source(decayed; have = (:x, :rate), want = :value))"""Generated by ReactiveKernels.jax_source; do not edit."""
from typing import Any
import jax
import jax.numpy as jnp
import jax.scipy.linalg
import jax.scipy.special as jsp
from jax.typing import ArrayLike
jax.config.update("jax_enable_x64", True)
def decay_sum(x: ArrayLike, rate: ArrayLike) -> jax.Array:
"""Compute `decay_sum` from its authored source."""
total = jnp.zeros_like(rate)
def loop_body(i, carry):
(total_2,) = carry
total_3 = total_2 + x[i - 1] * jnp.exp(-i * rate)
return (total_3,)
loop_carry = jax.lax.fori_loop(1, 4, loop_body, (jnp.asarray(total, dtype=jnp.float64),))
def then_arm():
total_2 = loop_carry[0] / rate
return (None, jnp.asarray(total_2, dtype=jnp.float64))
branch = jax.lax.cond(rate > 0, then_arm, lambda: (None, jnp.asarray(loop_carry[0], dtype=jnp.float64)))
return branch[1]
def kernel(x: ArrayLike, rate: ArrayLike) -> jax.Array:
"""Compute `value` from the inputs."""
x = jnp.asarray(x)
decay_sum_2 = decay_sum(x, rate)
value = decay_sum_2
return jnp.asarray(value, dtype=jnp.float64)Body-level early returns, including condition || return fallback(...), keep the continuation in the falling-through branch. The native method retains its original control flow. A return inside a loop remains unsupported. In device code, continue skips the remaining iteration statements and break exits the nearest loop. A bounded for carries a flag and skips later steps after an exit, preserving reverse differentiation. A loop without a static bound remains a runtime loop; JAX requires an authored derivative rule for reverse differentiation through it. Host prepare_data supports the same exits. A provider's source is read only by jax_source; native execution runs the method itself.
@inbounds and @simd preserve the source loop. Chained comparisons evaluate a shared middle operand once and reach later operands only when earlier comparisons succeed. Plain helpers accept acyclic forward joins and static Boolean Val parameters. Helpers can destructure numerical arrays and use firstindex, lastindex, integer parity predicates, and floating-point copysign.
A numerical helper may return a scalar or nothing; consume that result inside the program with something or isnothing. Device branches carry a presence flag and the scalar, while host preparation keeps ordinary Python values. A numerical vector prefix c[1:n] carries its runtime length and checks bounds. evalpoly(x, c) for real vectors retains Horner's loop over that logical length, including a runtime prefix; unused coefficients contribute neither values nor derivatives.
Conditional arrays and tuple fields retain their logical lengths, including when destructured. A bound such as min(n, length(row) - 1) keeps a runtime range bounded by the row's capacity. Numerical matrix allocation can use a bounded dimension, such as Matrix{Float64}(undef, length(row), 2), and several axes may share that logical extent. Independently padded dimensions remain unsupported. Array lengths and loop bodies are never copied from a sample dataset into emitted source.
A source ntuple(j -> expression, Val(N)) records the authored, fixed number of fields with runtime captures. A fixed tuple of numbers of one type supports computed integer reads, such as indexing that basis inside a loop. The device read checks bounds and uses a numerical array view of the tuple; the data-dependent loop remains a runtime loop.
A device helper can allocate Vector{Vector{Float64}}(undef, k), fill its slots with fixed-width numerical rows, and use isassigned(rows, i) to skip earlier assignments. A size such as isempty(ids) ? 0 : maximum(ids) uses bounds computed from prepared integer data, including ragged cells. Allocation and iteration remain runtime array operations; emitted source does not grow with the data. Assignment state travels with the numerical storage through loops and branches. Missing references and invalid indices raise when read; isassigned returns false for either.
This nested-buffer representation accepts fresh rows with an authored fixed shape, such as [a, b, c] or zeros(3). Different row shapes require a ragged representation, and mutation through stored row aliases or a helper's buffer or row argument requires reference writeback; these cases raise JAXEmissionError. Buffers are consumed inside the program by indexing or plates; direct public buffer outputs are not supported yet.