uki(ddlmZmZddlZddlmZddlZddlm Z ddlm Z ddlm Z ddlm Z ddlm Z dd lmZdd lmZdd lmZdd lmZddlm Zej*d Zeej.Zeej0Zeej2Zddddddeddedededzdeeefdzdef dZe j@dZ!de!_"e jFe!Gdde jHZ%e%Z&e jNjQe%e jRjQe%e!jTde+e jXdfdefdZ-dZ.e.ej^e!<d Z0e0ejbe!<ejde jfe!ejhe!<d!ejjd"ed#ed$ededee+eefdefd%Z6ejne!e6y)&)CallableSequenceN)Any)core)dispatch)effects)ffi) tree_util)util)ad)batching)mlirz jax.experimental.buffer_callbackF)has_side_effect vmap_methodinput_output_aliasescommand_buffer_compatiblecallback).Nresult_shape_dtypesrrrrc~ tj|\} td|D fd}|S)aAn experimental callback that operates in place on device buffers. Only supported on CPU and GPU backends. Note that the plan is for this to eventually be replaced by a consolidated callback API built using JAX mutable arrays, but for now this provides a mechanism for prototyping computational kernels using other Python libraries including Numpy, PyTorch, Cupy, and others. Let's start with a simple example: >>> def py_add_one_inplace(ctx, out, x): ... np.asarray(out)[...] = np.asarray(x) + 1 ... >>> x = jnp.array(41, dtype=jnp.int32) >>> out_type = jax.ShapeDtypeStruct(x.shape, x.dtype) >>> add_one = buffer_callback(py_add_one_inplace, out_type) >>> add_one(x) # doctest: +SKIP Array(42, dtype=int32) In this example, we're executing a numpy computation via JAX, and this could have been implemented using :func:`jax.pure_callback`, but in this case, the output is being populated in-place. This means that JAX doesn't need to copy the output arrays upon returning from the callback. Note that even though the callback function operates on mutable buffers, JAX still sees this as an operation that consumes and produces regular immutable JAX arrays. Unlike the other JAX callback APIs, ``buffer_callback`` requires that the user-defined Python function have the following signature: .. code-block:: python def callback(ctx: ExecutionContext, out, *args) -> None: ... where ``ctx`` is an instance of :class:`~jax.experimental.buffer_callback.ExecutionContext`, which mainly provides access to XLA's computation stream when running on GPU, ``out`` is a pytree of mutable :class:`~jax.experimental.buffer_callback.Buffer` objects, and the ``args`` arguments have the same pytree structure as the inputs, but each leaf is :class:`~jax.experimental.buffer_callback.Buffer`. This callback should not return any values, and it should overwrite the ``out`` buffers in place to output values back to JAX. It's important to note that this Python function can't really be called except via ```buffer_callback`` itself, because it's not (yet!) possible to construct mutable JAX buffers directly in Python. The bespoke :class:`~jax.experimental.buffer_callback.Buffer` type is an array-like object that supports the ``__array__`` protocol on CPU, the ``__cuda_array_interface__`` protocol on GPU, and the ``__dlpack__`` protocol on both CPU and GPU. Args: callback: A Python function with the signature and behavior described above. result_shape_dtypes: A pytree whose leaves have ``shape`` and ``dtype`` attributes, with a structure that matches the expected output of the callback function at runtime. :class:`jax.ShapeDtypeStruct` is often used to define leaf values. has_side_effect: Whether the callback has side effects. vmap_method: A string specifying how the callback transforms under :func:`~jax.vmap` as described in the docs for :func:`~jax.pure_callback`. input_output_aliases: a dictionary mapping the index of some inputs to the index of the output that aliases them. These indices are in the flattened inputs and outputs. command_buffer_compatible: if ``True``, the callback will be traced into the command buffer. This means that the Python code should only be executed once, and then the operations will be replayed for every subsequent call. Returns: A new callable that accepts :class:`jax.Array` inputs (and pytrees thereof), and pytree of :class:`jax.Array` objects whose structure matches that of ``result_shape_dtypes``. See Also: - :func:`jax.pure_callback`: callback designed for pure host functions. - :func:`jax.experimental.io_callback`: callback designed for impure host functions. - :func:`jax.debug.callback`: callback designed for general-purpose debugging. - :func:`jax.debug.print`: callback designed for printing. c3pK|].}tj|j|j0ywN)r ShapedArrayshapedtype).0xs S/home/cdr/jupyterlab/.venv/lib/python3.12/site-packages/jax/_src/buffer_callback.py z"buffer_callback..s*-.dqww(s46c tj||f\}}|Dcgc]}tj|}}d}t j D]\}}t |t |}}|t|k\r!td|d|d|dt|d |tk\r!td|d|d|dtd ||} |} tj| | std|d|d| d | d |||ffz }tj| || d } tj| Scc}w) Nz+input_output_aliases contains the mapping ':z' with input index z outside the range [0, z).z' with output index z,' referring to an input with abstract value z/ and an output with a different abstract value .)r result_avalsin_treeout_treerrrr)r tree_flattenrget_avalsorteditemsintlen ValueErrorr _check_compatible_avalsbuffer_callback_pbindtree_unflatten)argskwargs flat_argsr$rin_avalsstatic_input_output_aliasesi_idxo_idxin_avalout_avalout_flatrrflat_result_avalsrrr%rs rwrapped_callbackz)buffer_callback..wrapped_callbacks"//v?Iw*34Q a 4H4?A' !5!;!;!=>9,%5z3u:u CI ;E7!E7K""'(?T 2   C)* *;E7!E7K##(')@&'(,- -5/$U+**7H=;E7!E7K;;B)D88@zDE E $'88#'9*!%% &'8"; H  # #Hh 77G5sE )r r&tuple) rrrrrrflat_shape_dtypesr<r;r%s ` ```` @@rbuffer_callbackr?&sHx!* 6 67J KX2C&8&8P r?TceZdZdZy)BufferCallbackEffectcy)NBufferCallbackr )selfs r__str__zBufferCallbackEffect.__str__s r@N)__name__ __module__ __qualname__rFr r@rrBrBsr@rBr#.c>~|rthntj}||fSr)_BufferCallbackEffectr no_effects)r#rr1_rs r_buffer_callback_abstract_evalrNs# '6 " #DOO' w r@c~~td)NziBuffer callbacks do not support JVP. Please use `jax.custom_jvp` to use callbacks while taking gradients.r,r1r2s r_buffer_callback_jvp_rulerR FM NNr@c~~td)NzoBuffer callbacks do not support transpose. Please use `jax.custom_vjp` to use callbacks while taking gradients.rPrQs r_buffer_callback_transpose_rulerUrSr@ctxr1r$r%c t|jjdkDr td|jjd} ddddj | } | t d| d|r | d vr| d z } d t ffd } |jj| tjt|jjdz } tj| |t| } | |g|d| iS)Nz+multi-platform lowering for buffer_callbackrxla_buffer_python_cpu_callbackxla_buffer_python_gpu_callback)cpucudarocmz#`buffer_callback` not supported on z backend.)r\r] _cmd_bufferr1ctj|jg\}}tj|\}}tj |}||g|i| t dy)Nz4buffer_callback callback must not return any values.r )r split_list num_leavesr r0r,) exec_ctxr1args_inargs_out py_args_in py_kwargs_in py_args_outrr$r%s rr<z3_buffer_callback_lowering..wrapped_callbackspw/A/A.BCGX(77IJ **8X>K+C ClCO M NN r@)roperand_output_aliasesindex)r+module_context platformsNotImplementedErrorgetr,radd_host_callbacknpuint64host_callbacksr ffi_loweringdict)rVrr$r%rrrr1rMplatform target_namer<rirules ``` r_buffer_callback_loweringrws     % %&* K LL    ) )! ,( -..CM   :8*IN OO8/?#?= K&&'78 ))C**99:Q> ?%  %!"67 $ c &D & &&r@)8collections.abcrr functoolstypingrnumpyrojax._srcrrrr r r jax._src.interpretersr r r jax._src.libffi_lib set_moduleexportBufferExecutionStageExecutionContextobjectboolstrrsr*r? Primitiver.multiple_results simple_implEffectrBrKlowerable_effectsadd_typecontrol_flow_allowed_effectsdef_effectful_abstract_evalr=rrNrRprimitive_jvpsrUprimitive_transposespartialffi_batching_ruleprimitive_batchersLoweringRuleContextrwregister_loweringr r@rrsX/$*&' ; <  ../'223""26&+Iy!II I t I sCx.4/ I $IX#DNN#45%)"&'7>>-.""#78$$--.BC..((#-./N (A#$N .M)*1B1B1B,2-. )' ! !)' )' )'  )'  )'#5c?3)' $)'T(*CDr@