Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 40 ยท Arrays and NumPy API

Immutability and .at Updates

Why JAX arrays cannot be modified in place, how .at[idx].set/add/mul/min/max return updated copies, out-of-bounds modes, and how jit makes updates efficient.

In NumPy, x[2] = 10 changes the array. In JAX the same line fails with a TypeError, because JAX arrays are immutable. This restriction is what lets the compiler reorder and fuse operations safely, and what lets grad treat every array as a plain value.

Instead JAX gives you the .at property: an indexed functional update. x.at[idx].set(v) does not change x; it returns a new array equal to x with the update applied. Real JAX is read-only here, and the editors use a small NumPy stand-in that implements the same semantics (see What Is JAX? for why).

The .at syntax

Python
import jax.numpy as jnp

x = jnp.array([1.0, 2.0, 3.0, 4.0, 5.0])

y = x.at[0].set(10.0)          # [10.  2.  3.  4.  5.]
z = x.at[1:3].add(100.0)       # [  1. 102. 103.   4.   5.]
w = x.at[x > 3].set(0.0)       # boolean mask: [1. 2. 3. 0. 0.]
print(x)                       # unchanged: [1. 2. 3. 4. 5.]

The pattern is array.at[index].method(value), where method is one of:

Method Effect
set(v) replace with v
add(v) add v
multiply(v) multiply by v
divide(v) divide by v
power(v) raise to v
min(v) element-wise minimum
max(v) element-wise maximum
apply(fn) apply a function to the selected elements
get() read (same as normal indexing, with extra options)

The index can be anything normal NumPy indexing accepts: integers, slices, integer arrays, boolean masks and tuples for multi-dimensional arrays (m.at[1, :].set(0)).

Python Stand-in: building .at on NumPy

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Repeated indices

What if the same index appears more than once? With NumPy's x[[0, 0]] += 1 the increment happens once, because the right-hand side is computed first and then written back. JAX's .at[...].add follows scatter semantics: every update is applied, so duplicates accumulate. That makes .at[idx].add the tool for counting and histograms.

Python
counts = jnp.zeros(4).at[jnp.array([0, 1, 1, 3, 3, 3])].add(1)
print(counts)          # [1. 2. 0. 3.]
Python Stand-in: accumulating duplicate indices

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

np.add.at is the NumPy equivalent of JAX's .at[idx].add.

Out-of-bounds indices

Updates whose indices fall outside the array are dropped by default instead of raising an error; reads are clamped. You can choose the behavior with mode:

Python
x = jnp.arange(5)
x.at[10].set(99)                       # silently ignored
x.at[10].set(99, mode="drop")          # same, explicit
x.at[10].set(99, mode="clip")          # writes to the last element
x.at[-1].set(0)                        # negative indexes count from the end
x.at[10].get(mode="fill", fill_value=-1)   # -1 instead of a clamped read

Remember this when results look wrong without any error: an off-by-one index may have been silently dropped.

Is copying slow?

It looks like each .at[...].set copies the whole array. Outside jit, that is true: each call creates a fresh array, so building an array element by element in a Python loop is slow and should be avoided.

Inside a jit-compiled function, XLA can see the whole computation and perform the update in place when the old array is not needed afterwards. So in compiled code .at updates are cheap. Use jit for update-heavy code, or better, express the whole computation with vectorized operations, jnp.where, or lax loops.

flowchart LR
    X["x = [1,2,3]"] -->|".at[0].set(9)"| Y["y = [9,2,3] (new array)"]
    X --> X2["x is still [1,2,3]"]

The update returns a new value; the old one is untouched, which is exactly what makes grad and jit safe.

Common patterns

  • Set a border: img.at[0, :].set(0).at[-1, :].set(0); updates chain because each returns an array.
  • Conditional replace: prefer jnp.where(x < 0, 0.0, x) over .at[x < 0].set(0.0). The where form works under jit because its output shape never depends on the data.
  • Scatter-add / histogram: .at[labels].add(values) sums values per group, a building block for segment sums.
  • Running updates in a loop: keep the array as loop state (lax.fori_loop) rather than a Python list.

Boolean-mask updates with .at[mask].set(v) work under jit only when you set a scalar. Selecting values with a mask (x[mask]) produces a data-dependent shape and fails under jit. Use jnp.where instead. More in jit pitfalls.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does y = x.at[0].set(5) do to x?

    .at updates are functional: they return an updated copy and do not modify the original.
  2. 2. jnp.zeros(3).at[jnp.array([1, 1])].add(1) gives:

    .at[...].add has scatter semantics, so repeated indices all accumulate.
  3. 3. By default, what happens to an .at update with an out-of-bounds index?

    JAX cannot raise from compiled code, so out-of-range updates are dropped by default (mode='drop').
  4. 4. Why are .at updates cheap inside jit?

    The compiler sees the whole program and can reuse the buffer, avoiding a full copy.

Summary

  • JAX arrays are immutable; use x.at[idx].set/add/multiply/min/max/apply(...) to get an updated copy.
  • Repeated indices accumulate with .add, which makes histograms and segment sums easy.
  • Out-of-bounds updates are dropped by default; choose mode="clip" or "fill" if needed.
  • Under jit updates are efficient; outside it, avoid element-by-element loops.
  • Prefer jnp.where for conditional replacement.

Next: Indexing, Slicing and Broadcasting