How to use Chex assertions in a jitted function?

Decorate your jitted function with @chex.chexify to enable value-based assertions like assert_tree_all_finite. This wrapper ensures checks work during JAX tracing and execution, though it adds an extra layer.

Chex dataclasses or standard Python dataclasses for JAX?

Chex dataclasses are essential for JAX projects because they register as PyTree nodes and integrate with dm-tree, while standard dataclasses lack this compatibility. However, Chex dataclasses have stricter constructor rules.

How to test JAX code on both CPU and GPU with Chex?

Use the @chex.variants decorator with with_device and without_device options in your tests. Ensure your test class inherits from chex.TestCase to handle variant unrolling automatically.

Can Chex debug pmap without multiple devices?

Yes, wrap your code with chex.fake_pmap() context manager to replace pmap with vmap, allowing you to simulate and debug parallel execution on a single device like a CPU or GPU.

How to prevent too many traces in JAX using Chex?

Apply the @chex.assert_max_traces decorator to your jitted functions to set a limit on re-tracing. This helps catch performance issues from frequent argument structure changes, but requires manual trace counter management in tests.

Does Chex work with TPUs for debugging?

Chex supports TPU environments through assertions like assert_tpu_available and can restrict backends, but faking multi-device tests on TPUs is limited as it primarily relies on CPU threading for simulation.

Chex — JAX Testing & Debugging Utilities

What is Chex?

Chex is a Python library developed by DeepMind that provides utilities for writing and testing reliable JAX code. It solves problems like debugging JAX-transformed functions, ensuring comprehensive test coverage across different JAX execution modes, and adding runtime checks for array properties. It helps developers catch errors early and maintain code quality in JAX projects.

Target Audience

JAX developers and researchers who need to write robust, production-ready code and ensure their implementations behave correctly across JAX's various transformations (e.g., jit, pmap, vmap).

Value Proposition

Chex offers a specialized, integrated toolkit for JAX reliability that isn't available in generic testing libraries. Its deep integration with JAX's execution model, support for test variants, and JAX-aware assertions make it uniquely valuable for catching subtle bugs in transformed code.

Overview

Chex is a utility library designed to help developers write and test reliable JAX code. It addresses common challenges in JAX development, such as debugging transformed code and ensuring comprehensive test coverage across different execution environments.

Key Features

JAX-friendly Dataclasses — Provides dataclass implementations compatible with JAX's PyTree and dm-tree, enabling easy definition of typed data structures.
Flexible Assertions — Offers a wide range of assertions for checking array shapes, ranks, dtypes, and numerical properties, with support for both static and runtime checks in jitted code.
Test Variants — Simplifies testing across different JAX transformations (e.g., jitted vs. non-jitted, with/without device placement) via a decorator-based system.
Debugging Utilities — Includes tools like fake_pmap to replace pmap with vmap for easier single-device debugging and restrict_backends to enforce backend usage.
Tracing Assertions — Provides assert_max_traces to detect and prevent excessive re-tracing in JIT-compiled functions, aiding performance optimization.

Philosophy

Chex emphasizes reliability and debuggability in JAX codebases by providing practical tools that integrate seamlessly with JAX's functional and transformation-based paradigm, helping developers catch errors early and ensure consistent behavior across different execution modes.

Chex

What is Chex?

Overview

Key Features

Philosophy

Related Projects

Found a gem we're missing?

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions