JAX translations
Companion to JAX source: host preparation and package mappings.
Host preparation
Host findfirst(predicate, vector) returns the first matching one-based index or nothing. Captured predicates (isequal(label), Base.Fix1, Base.Fix2) work in positional kernels too: plate(values) do value; Int(findfirst(isequal(value), levels)); end. Labels and vector lengths remain runtime inputs.
RK 0.1.286 adds findall(vector)/findall(predicate, vector): every matching one-based position, possibly empty. Predicates run in order and return Bool. Dict(zip(keys, values)), including eachindex(rows) values, supports indexing, get and haskey in host plates. Zip is reusable and stops at its shortest input. Repeated keys keep their last value; equality follows isequal (NaNs, signed zero). These operations also translate in data-only definitions.
Host preparation also orders vectors of numbers or strings as Julia's isless does (-0.0 before 0.0, every NaN last): sort, unique (and sort!, unique! of a list built with push!), searchsortedfirst and searchsortedlast (one-based), and sortperm(v), whose one-based positions keep equal values in ascending position. invperm(p) of a vector of integers is the inverse permutation and raises ArgumentError: argument is not a permutation as Julia does. A data-only definition such as pos = invperm(vcat(rows_a, rows_b)) therefore runs in prepare_data. Keyword orders (rev, by, lt) have no translation. In the JAX functions these calls have none either: a recipe that also reads a parameter (theta[sortperm(rows)]) raises JAXEmissionError naming the function, so give the permutation a definition of its own that reads data alone.
Host preparation keeps ordinary data-only Julia as written (RK 0.1.278). Typed comprehensions convert each element as convert does, so Int[findfirst(==(k), levels) for k in keys] raises when a key is absent; nested generators keep Julia's clause order. push! and append! grow any local vector, which becomes a fresh Python list, so an input is never written. sizehint!, view, @view and @views read as Julia's. An index that is findfirst's result raises ArgumentError: invalid index: nothing of type Nothing when it is nothing. issorted and a scalar isless follow the isless order of sort. A Set holds isequal keys and is never iterated (Julia's hash order). (; a, b) = nt binds fields by name; an anonymous function is called where host code calls it (filter!).
repeat(A, counts...) tiles A counts[d] times along axis d, as Julia's repeat(A; outer = counts) does, and repeat(A; inner, outer) first repeats each entry inner[d] times along axis d; each keyword takes an integer or a tuple of them. Counts past A's rank add trailing axes, as Julia's do (repeat(v, 1, k) of a vector is a matrix with k columns). Shapes are static while JAX traces, so the JAX functions need static counts (literals, or integers static to jax.jit); a count of data is computed in prepare_data when the recipe reads data alone. A categorical model's prior scale per coefficient term, repeated once per non-reference category (repeat([intercept_scale, slope_scale], 1, k)), therefore runs in prepare_data, and one module serves every category count. Julia's argument checks hold: a negative count, or with inner a count list shorter than A's rank, raises with Julia's ArgumentError message. A recipe that repeats by a count the functions trace raises JAXEmissionError naming the recipe; a padded (ragged) value has no repeat translation.
A Bool array index (a BitVector or Vector{Bool}, such as table[table[:, 2] .!= 1, 4] or values[present]) selects the entries where it is true, as Julia's logical indexing does; it is not shifted as one-based positions. A mask of the array's whole shape (A[A .> 0]) selects in column-major order. prepare_data and other host code use a NumPy boolean mask, which fails on a mask of another length as Julia's BoundsError does; a list built with push! keeps the entries whose mask entry is true. In device code the count of selected entries depends on data, so the gather is padded to the mask's length: the selected entries come first, padding repeats the last of them, and reductions, length and broadcasts mask the padding as they do for a ragged row. A write through a mask writes only the selected entries. A device mask beside another kept dimension (A[mask, :]) and a mask of the groups of a ragged value raise JAXEmissionError, as does a single Bool index into an array, which Julia refuses.
Statistics reductions
With Statistics loaded (ReactiveKernelsStatisticsExt, RK 0.1.262), mean(x), mean(f, x), var(x) and std(x) translate, with the keywords dims (one integer known while JAX traces, or :), and for var and std also corrected (a literal true or false) and mean. Each is the core sum, length and size translation it composes, sum(x) / length(x) and sum(abs2.(x .- m)) / (n - corrected), so a padded row or a dims reduction reads only its valid entries and prepare_data takes NumPy's spelling. Over dims the reduced axis keeps length one, as in Julia. An empty argument, or one entry with corrected, gives Julia's NaN. Before, Statistics' own methods, which branch, were refused as "the function _mean has loops or branches".
Package translations
A package extension can map its own callable during source emission. Julia execution is unchanged; ordinary jax.grad differentiates the emitted primal without a registered derivative rule.
Use ReactiveKernels._jax_elementwise(::typeof(f)) for scalar calls and f.(xs). Return a Python callable name, name => source defining a module-level helper, or nothing for fallback translation. This does not register ordinary array calls: Julia's exp(A) is a matrix exponential; exp.(A) applies scalar exponentials.
For a positional whole-function call, including an array-valued helper, define _jax_function_call(ctx::_JaxContext, ::typeof(my_function), args::Vector{_PyVal}). Qualify RK names with ReactiveKernels, as in the executable example below.
These underscored names form the package extension interface. The context and vector annotations make the method more specific than RK's generic method. Selection precedes recorded/provider source and lowered-code translation, but follows applicable scalar/elementwise mappings. This hook registers positional calls, not keyword handling.
Each args[i] describes an argument: code is its Python expression, T its Julia type. Parenthesize expressions when composing operators. Return a _PyVal, not a string or nothing; call _jax_traceable_or_lowered(ctx, f, args) for the generic hook's source fallback.
_jax_result(f, args, expression) infers the native result type from f and the argument types, preserving matrix rank for subsequent multiplication. The expression must implement that native result and shape. Shapes and numerical inputs remain runtime expressions, not sampled data. For elementwise whole-array calls preserving the arrays' axes, _jax_elementwise_result(f, args, expression) additionally carries padded-axis metadata.
For changed shape or ragged structure, the full constructor is _PyVal(code, T, static, extent, limit, padded). Short constructors default static=false, extent="", limit="", and padded=0.
| Field | Meaning |
|---|---|
static::Bool | Known as a Python value while JAX traces; it can decide Python control flow. A JAX array is not static merely because its inputs are constants. |
extent::String | Valid length of a padded row, or lengths of a ragged collection; empty for an unpadded value. |
limit::String | Static upper-bound expression of a data-dependent integer, for loops and allocation; empty when absent. |
padded::Int | Bitmask of padded axes (bit k-1 for axis k), implicit for a vector; for a tuple, of its fields with a length. |
_jax_result carries an input extent to an array result without deriving new lengths or padding axes. Operations must account for padding and return their actual result metadata: copying input metadata cannot describe arbitrary reductions, reshapes or matrix functions. The matrix-exponential example takes an ordinary dense matrix, not a padded ragged row.
Host preparation and helpers
The hook also serves prepare_data, where ctx.host !== nothing. RK rewrites jnp.* to np.*, jsp.* to ssp.* (SciPy special functions), and jax.scipy.linalg.* to scipy.linalg.*. _jax_result uses these host spellings for all-static operands too, keeping shape/literal arithmetic usable in Python guards. Branch on ctx.host if different host mathematics is needed. Leftover device-only constructs (jax.lax, .at[...]) cannot form host preparation: the recipe stays on device or is reported untranslated, according to the preparation boundary.
Define Python helpers with _jax_helper!(ctx, name, source) and use its returned name. It emits each name once; host mode emits a NumPy twin with an _np suffix. Names must be unique across the module. For all-static operands in device mode, use _host_helper!(ctx, name, source) when a host spelling exists: _jax_result cannot discover JAX calls inside separate helper bodies. _jax_elementwise pairs select automatically. Custom helpers must not mutate inputs; RK cannot enforce ownership on arbitrary Python text or translate independently written derivatives.
Executable scalar and matrix example
This file defines owned helpers, mappings and kernels. The loop in triple requires its mapping for translation; matrix exponential demonstrates whole-array mathematics distinct from elementwise mapping.
module JAXTranslationExample
using ReactiveKernels
using LinearAlgebra
const RK = ReactiveKernels
# A package owns these Julia functions; its RK extension owns the mappings.
function triple(x)
result = zero(x)
for _ in 1:3
result += x
end
result
end
RK._jax_elementwise(::typeof(triple)) = "_example_triple" => """
def _example_triple(x):
return 3 * x
"""
# An ordinary call on an array has its own translation. Here its mathematics
# happens to be elementwise too, so preserve the input's padded axes as well.
function RK._jax_function_call(ctx::RK._JaxContext, ::typeof(triple),
args::Vector{RK._PyVal})
RK._jax_elementwise_result(triple, args, "3 * (" * only(args).code * ")")
end
matrix_exponential(A::AbstractMatrix) = exp(A)
function RK._jax_function_call(ctx::RK._JaxContext, ::typeof(matrix_exponential),
args::Vector{RK._PyVal})
RK._jax_result(matrix_exponential, args,
"jax.scipy.linalg.expm(" * only(args).code * ")")
end
# Types supplied to jax_source select scalar, vector, or matrix inputs.
@kernel mapped(x) = begin
y = triple(x)
total = sum(y)
return y, total
end
# The matrix result must keep its rank for the following matrix-vector product.
@kernel mapped_product(A::Matrix{Float64}, v::Vector{Float64}) = begin
B = triple(A)
total = sum(B * v)
return total
end
@kernel prepared(scale::Float64, x) = begin
y = triple(x)
total = scale * sum(y)
return total
end
@kernel exponential(scale::Float64, A::Matrix{Float64}) = begin
E = matrix_exponential(A)
total = scale * sum(E)
return total
end
end # module
Emit scalar and matrix device calls, and a data-only matrix exponential in host preparation:
ex = JAXTranslationExample
scalar_source = jax_source(ex.mapped; have=(:x,), want=:total, types=(x=Float64,))
matrix_source = jax_source(ex.mapped_product; have=(:A, :v), want=:total)
host_source = jax_source(ex.exponential; have=(:scale, :A), want=:total, data=(:A,))
print(host_source)"""Generated by ReactiveKernels.jax_source; do not edit."""
import scipy.linalg
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)
INPUTS = ("scale", "E")
PREPARED = {"E": {"dtype": "float64", "ndim": 2, "ragged": False}}
def prepare_data(A: 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)`.
"""
A = np.asarray(A, dtype=np.float64)
E = scipy.linalg.expm(A)
return {"E": np.asarray(E, dtype=np.float64)}
def kernel(scale: ArrayLike, **prepared: ArrayLike) -> jax.Array:
"""Compute `total` from the inputs."""
E = prepared["E"]
E = jnp.asarray(E)
total = scale * jnp.sum(E)
return jnp.asarray(total, dtype=jnp.float64)After write("matrix_model.py", host_source), run python examples/jax_translations.py matrix_model.py with a Python that has JAX and SciPy. This consumer checks the result and gradient against SciPy and that preparation returns NumPy arrays:
"""Run with: python examples/jax_translations.py matrix_model.py"""
import importlib.util
import sys
import jax
import numpy as np
from scipy.linalg import expm
spec = importlib.util.spec_from_file_location("matrix_model", sys.argv[1])
model = importlib.util.module_from_spec(spec)
spec.loader.exec_module(model)
A = np.array([[0.0, 0.2], [-0.3, 0.1]])
before = A.copy()
prepared = model.prepare_data(A=A)
assert prepared and all(isinstance(v, np.ndarray) for v in prepared.values())
np.testing.assert_array_equal(A, before)
value = jax.jit(model.kernel)(0.7, **prepared)
gradient = jax.grad(lambda scale: model.kernel(scale, **prepared))(0.7)
np.testing.assert_allclose(value, 0.7 * expm(A).sum(), rtol=1e-12)
np.testing.assert_allclose(gradient, expm(A).sum(), rtol=1e-12)
print("Host preparation and device value/gradient agree with SciPy.")
The repository's JAX tests execute these examples with RK_JAX_PYTHON enabled: direct and wrapped calls, matrix rank, changed sizes, host preparation, and ordinary gradients against native Julia. The documentation build executes the Julia examples; it displays the Python consumer's source.