How jax-ml/jax works
Project type and purpose
• JAX is an open-source Python library for high-performance numerical computing.
• It provides composable transformations (grad, jit, vmap) on NumPy-style array code and compiles to XLA for execution on CPU, GPU, and TPU.
Top-level components (from file tree & README)
• Python-level interface (“jax” package)
– jax/api.py, jax/_src/api.py for user-facing functions (grad, jit, vmap)
– jax.numpy, jax.scipy, jax.lax, jax.experimental subpackages
• Core transformation engine
– interpreters (ad.py, batching.py, mlir.py, pxla.py under jax/_src/interpreters)
– jaxpr IR representation and passes (jax/core.py, jax/_src/jaxpr_util.py)
• XLA integration
– translation to XLA HLO (mlir bridge under jax/_src/compilation_cache, compiler.py, custom_partitioning)
• Runtime support (jaxlib C++ extensions)
– jaxlib/python entry points (py_array.cc, py_client.cc)
– device-specific kernels in jaxlib/cpu, jaxlib/gpu, jaxlib/rocm, jaxlib/triton
• Hardware backends
– CPU via Eigen/LAPACK
– NVIDIA GPU via CUDA/cuBLAS/cuDNN
– Google TPU via XLA TPU runtime
– AMD GPU via ROCm plugin
– Apple/Intel GPUs via community plugins
• Build & packaging
– Bazel and pyproject.toml / setup.py for source builds
– build_wheel.py, build/rocm Dockerfiles, jax_plugins for cuda/rocm
– CI/CD workflows (.github/workflows, ci/, build/rocm/)
• Examples, benchmarks, tutorials, docs, tests
– examples/ and benchmarks/ for usage patterns
– docs/, cloud_tpu_colabs/ for guidance
– tests/ and benchmarks/ for quality & performance
Relationships & data flow
3. Transformation engine converts functions to jaxpr IR, applies autodiff and vectorization passes
4. Transformed IR is lowered to XLA HLO via the MLIR bridge
5. XLA HLO is compiled just-in-time into device-specific machine code
6. jaxlib runtime loads and executes compiled binaries on target hardware (CPU/GPU/TPU)
7. Results are returned to Python and wrapped as DeviceArray objects
Architectural patterns & principles
• Layered architecture:
• Python frontend → transformation core → compiler → runtime → hardware
• Pluggable backends:
• Abstract dispatch in jax/_src/dispatch.py → concrete plugin in jaxlib
• Separation of concerns:
• Pure Python transformations and IR manipulation
• Low-level kernels and memory management in C++
• Build isolation:
• Bazel for C++ and Python integration
• Docker/rocm/CI scripts for multi-platform support