Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 40 ยท Getting Started

JAX vs NumPy

Compare jax.numpy with NumPy: shared API, immutability, float32 defaults, asynchronous dispatch, random numbers, and when to convert between the two libraries.

If you know NumPy you already know most of jax.numpy. Functions such as jnp.sum, jnp.dot, jnp.linspace and jnp.where behave as you expect, and the usual broadcasting rules apply. That familiarity is deliberate, and it means you can start being productive quickly.

But JAX is not NumPy with a faster engine. A handful of differences exist because JAX must be able to differentiate, compile and vectorize your code. Learn these differences now and the rest of the course will feel natural. As always, runnable editors here are NumPy-only stand-ins; real JAX code is read-only (see What Is JAX?).

What stays the same

Python
import numpy as np
import jax.numpy as jnp

a = np.linspace(0, 1, 5)
b = jnp.linspace(0, 1, 5)       # same call, same values (as float32)

print(jnp.sum(b ** 2))          # element-wise ops, reductions, broadcasting
print(jnp.dot(b, b))            # linear algebra
print(b[1:4])                   # slicing

Most NumPy functions have a counterpart, and a few conventions are identical: shape, ndim, dtype, reshape, T, boolean masks in reads, axis arguments and so on.

Difference 1: arrays are immutable

In NumPy you can write x[0] = 5. In JAX that raises a TypeError, because a compiler and an automatic differentiator are much happier when values never change underneath them. You build a new array instead, using the .at syntax (covered in Immutability and .at updates):

Python
x = jnp.array([1, 2, 3])
# x[0] = 5            -> TypeError: JAX arrays are immutable
y = x.at[0].set(5)    # returns a new array [5, 2, 3]; x is unchanged

The stand-in below shows the NumPy behavior that JAX takes away, and the functional replacement.

Python Stand-in: mutation vs functional update

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.

Difference 2: 32-bit by default

NumPy defaults to float64 and int64. JAX defaults to float32 and int32, because accelerators are optimized for 32-bit (or even 16-bit) math.

Python
print(np.arange(3.0).dtype)     # float64
print(jnp.arange(3.0).dtype)    # float32

Enable 64-bit mode only if you need it (see Installing JAX). This difference matters when you compare results: a NumPy float64 computation and the same JAX float32 computation agree only to about seven decimal digits.

Python Stand-in: what 32-bit precision looks like

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.

Difference 3: functions must be pure

JAX transformations assume that a function's output depends only on its inputs and that it changes nothing outside itself. A function that appends to a global list or reads a global counter may work the first time and silently misbehave later. Functional Programming in JAX explores this in depth.

Difference 4: randomness is explicit

np.random.rand() uses hidden global state. JAX has no hidden state: you create a key, split it, and pass keys to each random function. The reasons (reproducibility, parallel safety) are explained in the chapter on random numbers.

Python
import jax
key = jax.random.key(0)
key, sub = jax.random.split(key)
noise = jax.random.normal(sub, (3,))

Difference 5: asynchronous dispatch

When you call a JAX function, Python returns immediately with an array whose result may still be computing on the device. Work happens in the background; Python only waits when you actually need the value (printing, converting to NumPy, or calling .block_until_ready()).

This explains a classic benchmarking mistake: timing a JAX call without waiting measures only the time to dispatch the work.

Python
import time
t0 = time.perf_counter()
y = jnp.dot(a_big, a_big)            # returns almost instantly
y.block_until_ready()                # wait for the real result
print(time.perf_counter() - t0)

Difference 6: out-of-bounds indexing does not raise

Raising an exception from inside compiled code on an accelerator is hard, so JAX handles bad indexes by rule: reads clamp to the nearest valid index, and updates with out-of-range indices are dropped. NumPy would raise IndexError instead. Keep this in mind when debugging "wrong but no error" results.

Difference 7: some operations are not allowed or behave differently

  • Functions whose output shape depends on data values (such as jnp.nonzero or boolean-mask selection x[x > 0]) do not work under jit unless you supply a fixed size. We cover this in jit pitfalls.
  • Python if on a traced value fails under jit; use jnp.where or lax.cond.
  • Some in-place functions (np.put, out= parameters) do not exist.
flowchart LR
    N["NumPy array"] -->|"jnp.asarray(x)"| J["JAX array"]
    J -->|"np.asarray(y)"| N

Conversion between the two is cheap on the CPU. On a GPU, np.asarray copies data back to host memory and waits for the result.

Moving between the two libraries

  • NumPy to JAX: jnp.asarray(np_array) (note the dtype may become float32).
  • JAX to NumPy: np.asarray(jax_array).
  • Mixing is allowed in many expressions (np_array + jax_array gives a JAX array), but avoid ping-ponging inside hot loops: transfers cost time.

A common pattern is to load and preprocess data with NumPy or pandas, convert once with jnp.asarray, then keep everything in JAX until you need to plot or save results.

When to use which

Use NumPy for I/O, quick scripts, and anything involving mutation or irregular shapes. Use JAX when you need gradients, GPU/TPU acceleration, or heavy compiled numerical loops.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What happens when you run x[0] = 5 on a JAX array?

    JAX arrays cannot be modified; use x.at[0].set(5), which returns a new array.
  2. 2. What is the default floating-point dtype in JAX?

    JAX defaults to 32-bit values for speed on accelerators; x64 mode must be enabled explicitly.
  3. 3. Why can timing a JAX call without block_until_ready() be misleading?

    The function returns as soon as work is queued; block_until_ready() waits for the real result.
  4. 4. What does JAX do for an out-of-bounds read such as x[10] on a length-3 array?

    Errors cannot be raised from compiled accelerator code, so reads clamp and out-of-range updates are dropped.

Summary

  • jax.numpy mirrors NumPy, so slicing, broadcasting and reductions feel familiar.
  • Differences: immutable arrays, 32-bit defaults, pure functions, explicit random keys, asynchronous dispatch, clamped out-of-bounds indexing.
  • Convert with jnp.asarray and np.asarray; avoid shuttling data in loops.
  • Time JAX code with block_until_ready().

Next: Functional Programming in JAX