Skip to main content

JAX-Tqdm

Add a tqdm progress bar to your JAX scans and loops.

PyPI - Version PyPI - Downloads

Installation

Install with pip:

pip install jax-tqdm

Example Usage

In jax.lax.scan

from jax_tqdm import scan_tqdm
from jax import lax
import jax.numpy as jnp

n = 10_000


@scan_tqdm(n)
def step(carry, x):
    return carry + 1, carry + 1


last_number, all_numbers = lax.scan(step, 0, jnp.arange(n))

Where the range argument must start at 0. A tuple can be used to pass data to the scan, as long as the first entry is a range, e.g.:

from jax_tqdm import scan_tqdm
from jax import lax
import jax.numpy as jnp

n = 10
scan_data = jnp.zeros((n, 200, 100))


@scan_tqdm(n)
def step(carry, x):
    _, d = x
    return carry + 1, d


last_number, output_data = lax.scan(step, 0, (jnp.arange(n), scan_data))

In jax.lax.fori_loop

from jax_tqdm import loop_tqdm
from jax import lax

n = 10_000


@loop_tqdm(n)
def step(i, val):
    return val + 1


last_number = lax.fori_loop(0, n, step, 0)

where the initial loop value should start at 0.

Scans & Loops Inside Vmap

For scans and loops inside a map, jax-tqdm can print stacked progress bars showing the individual progress of each process. To do this you can wrap the initial value of the loop or scan inside a PBar class, along with the index of the progress bar. For example

from jax_tqdm import PBar, scan_tqdm
import jax

n = 10_000


@scan_tqdm(n)
def step(carry, _):
    return carry + 1, carry + 1


def map_func(i):
    # Wrap the initial value and pass the
    # progress bar index
    init = PBar(id=i, carry=0)
    final_value, _all_numbers = jax.lax.scan(step, init, jax.numpy.arange(n))
    return (
        final_value.carry,
        _all_numbers,
    )


last_numbers, all_numbers = jax.vmap(map_func)(jax.numpy.arange(10))

The indices of the progress bars should be contiguous integers starting from 0.

Print Rate

By default, the progress bar is updated 20 times over the course of the scan/loop (for performance purposes, see below). This update rate can be manually controlled with the print_rate keyword argument. For example:

from jax_tqdm import scan_tqdm
from jax import lax
import jax.numpy as jnp

n = 10_000


@scan_tqdm(n, print_rate=2)
def step(carry, x):
    return carry + 1, carry + 1


last_number, all_numbers = lax.scan(step, 0, jnp.arange(n))

will update every other step.

Progress Bar Type

You can select the tqdm submodule manually with the tqdm_type option. The options are 'std', 'notebook', or 'auto'.

from jax_tqdm import scan_tqdm
from jax import lax
import jax.numpy as jnp

n = 10_000


@scan_tqdm(n, print_rate=1, tqdm_type="std")  # tqdm_type='std' or 'notebook' or 'auto'
def step(carry, x):
    return carry + 1, carry + 1


last_number, all_numbers = lax.scan(step, 0, jnp.arange(n))

Progress Bar Options

Any additional keyword arguments are passed to the tqdm progress bar constructor. For example:

from jax_tqdm import scan_tqdm
from jax import lax
import jax.numpy as jnp

n = 10_000


@scan_tqdm(n, print_rate=1, desc="progress bar", position=0, leave=False)
def step(carry, x):
    return carry + 1, carry + 1


last_number, all_numbers = lax.scan(step, 0, jnp.arange(n))

Why JAX-Tqdm?

JAX functions are pure, so side effects such as printing progress when running scans and loops are not allowed. However, the debug module has primitives for calling Python functions on the host from JAX code. This can be used to update a Python tqdm progress bar regularly during the computation. JAX-tqdm implements this for JAX scans and loops and is used by simply adding a decorator to the body of your update function.

Note that as the tqdm progress bar is only updated 20 times during the scan or loop, there is no performance penalty.

The code is explained in more detail in this blog post.

Developers

Dependencies are managed using uv.

Pre-Commit Hooks

Pre-commit checks can then be run using

uv run task lint

Tests

Tests can be run with

uv run task test

Metadata

Release files for jax-tqdm 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jax-tqdm 0.4.1
File Size Uploaded Provenance Actions
jax_tqdm-0.4.1.tar.gz 6.0 kB Without provenance Details for jax_tqdm-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jax-tqdm 0.4.1
File Interpreter ABI Platform Actions
jax_tqdm-0.4.1-py3-none-any.whl Python 3 none any Details for jax_tqdm-0.4.1-py3-none-any.whl

Total release size: 13.7 kB

Release files / jax_tqdm-0.4.1.tar.gz

Download URL jax_tqdm-0.4.1.tar.gz
Size 6.0 kB
Tags Source
SHA-256 checksum
How to use checksums
942af4c5acc9de6d1db3ee744014acb7ed32c333c852906c0d1b82f70def6443
BLAKE2b-256 checksum
How to use checksums
2fc8a0502a922689e1d83c53d5a77e62f26de12144ba6601bb9e4c03e426cce4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Freedesktop SDK","version":"25.08","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / jax_tqdm-0.4.1-py3-none-any.whl

Download URL jax_tqdm-0.4.1-py3-none-any.whl
Size 7.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
193a077409dbc23adf0a75c15bfb3bc379d8187dff20276873de7f5821d37193
BLAKE2b-256 checksum
How to use checksums
965b4c60db7b0012bd22c8733430353387b66e9a71bd90db4b677c00cbbba4e7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Freedesktop SDK","version":"25.08","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for jax-tqdm 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page