Skip to content

docs: correct false simulator-JAX claims (registration, eager-on-JAX, TransformerNUFFT) - #380

Merged
Jammy2211 merged 2 commits into
mainfrom
feature/correct-simulator-jax-claims
Jul 30, 2026
Merged

docs: correct false simulator-JAX claims (registration, eager-on-JAX, TransformerNUFFT)#380
Jammy2211 merged 2 commits into
mainfrom
feature/correct-simulator-jax-claims

Conversation

@Jammy2211

Copy link
Copy Markdown
Collaborator

Summary

Corrects four false JAX claims in this workspace's docs. All measured against the
installed stack — nothing here is a style change.

Closes #379 (in part; the autogalaxy half is PyAutoLabs/autogalaxy_workspace).

1. "The simulator handles pytree registration internally" — false

No simulator anywhere registers pytrees: grep -rn register over both autolens
simulators, both autogalaxy simulators and both autoarray bases returns zero
hits
. The documented @jax.jit wrap fails immediately with
TypeError ... value is of type Tracer.

It is also unimplementable as worded, and PointSolver.solve_triangles
already says why at its own call site:

Auto-registering inside solve() doesn't help because JAX flattens function
arguments at trace time — before entering this method — so registration must
run before the first jitted call.

2. "eager via_tracer_from(...) already runs on JAX" — false

Eager with use_jax=True succeeds but returns dataset.data.array of type
numpy.ndarray, not jax.Array.

3. The @jax.jit simulator recipe does not work at all

Even with correct registration it dies inside autoarray
(preprocess.py:153, then array_2d_util.py) on sites that do not thread xp.
That is a separate library bug, filed separately. The docs now say so and point
readers at the eager call, instead of presenting a recipe that cannot run.

4. TransformerNUFFT is not the un-traceable one — this repo shipped it backwards today

#375 (merged this morning) put "TransformerDFT (the default).
TransformerNUFFT is not JAX-traceable." into guides/using_jax.py. Inherited
from the old __JAX__ blocks and wrong. Per autoarray's own error text
TransformerNUFFT is "the default JAX-native" transformer (nufftax-backed;
nufftax 0.3.1 installed) and TransformerNUFFTPyNUFFT is "the legacy pynufft
backend". Defaults also differ by class: SimulatorInterferometer
TransformerDFT; Interferometer, which a fit uses → TransformerNUFFT.
scripts/interferometer/simulator.py already had this right, so #375 contradicted
a sibling script.

Approach

The wording is mirrored from the two scripts that already get this right
scripts/point_source/simulator.py __JAX Variant (Advanced)__ and
scripts/cluster/simulator.py __JAX JIT__ — both of which state the one-time
setup, call register_tracer_classes(tracer), and give the trace-time reason.
Those two files are deliberately untouched.

In imaging/ and interferometer/simulator.py the dead @jax.jit def simulate(...)
cells are removed rather than corrected: they defined a function that was never
called (# dataset_jax = simulate(tracer) was commented out), which is exactly
why the claim survived so long. The use_jax=True constructor stays as a live
cell, since that part works.

Scripts Changed

  • scripts/guides/using_jax.py — rewrote __Writing @jax.jit Yourself__ item 1 (claims 1-3); fixed the NUFFT sentence in __Custom Likelihood Functions__ (claim 4)
  • scripts/guides/tracer.py — split the "implicit path" section: registration-as-side-effect is true for Analysis.fit_from, false for Simulator.via_tracer_from
  • scripts/imaging/simulator.py — claims 1-3; removed the never-called jitted cell
  • scripts/interferometer/simulator.py — claims 1-3; removed the never-called jitted cell; its already-correct nufftax paragraph kept
  • scripts/group/simulator.py — claim 1 (stub pointing at imaging)
  • scripts/multi_galaxy/simulator.py — claim 1 (stub pointing at imaging)

Notebooks, llms-full.txt and workspace_index.json regenerated via
PyAutoHands/autohands/generate.py.

Not touched: point_source/simulator.py, cluster/simulator.py — already correct.

Upstream PR

PyAutoLabs/PyAutoLens#665 — the same stale auto-call claim
in autolens/jax/registration.py's module docstring. Docstring-only with zero API
surface, so nothing here imports new API; merge order does not actually matter,
but the library PR is trivial and can go first.

Test Plan

  • All four edited simulator scripts run end-to-end
  • py_compile on every touched file
  • scripts/check_sizes.sh clean
  • Post-edit grep: zero surviving hits for pytree registration internally, already runs on JAX, and the reversed NUFFT claim
  • Smoke tests: 17/17 passed

Generated by the PyAutoLabs agent workflow.

… NUFFT)

Four claims in this workspace's JAX docs were false. All measured against the
installed stack.

1. "The simulator handles pytree registration internally" — no simulator
   anywhere registers pytrees (autolens, autogalaxy and autoarray bases: zero
   `register` hits), so the documented @jax.jit wrap fails with
   `TypeError ... value is of type Tracer`. It is also unimplementable as
   worded: JAX flattens a jitted function's arguments at trace time, before
   entering the callee, so registration must precede the first jitted call.
   PointSolver.solve_triangles already documents exactly this.

2. "eager via_tracer_from(...) already runs on JAX" — eager with use_jax=True
   returns dataset.data.array of type numpy.ndarray, not jax.Array.

3. The @jax.jit simulator recipe does not work even WITH correct registration:
   it dies inside autoarray (preprocess.py:153, then array_2d_util.py) on sites
   that do not thread xp. Separate library bug, filed separately. The docs now
   say so and point at the eager call.

4. `TransformerNUFFT is not JAX-traceable` — shipped backwards in #375 this
   morning, inherited from the old __JAX__ blocks. Per autoarray's own error
   text TransformerNUFFT IS the default JAX-native (nufftax-backed) transformer;
   TransformerNUFFTPyNUFFT is the legacy pynufft one. Defaults differ by class:
   SimulatorInterferometer -> TransformerDFT, Interferometer -> TransformerNUFFT.
   scripts/interferometer/simulator.py already had this right, so #375
   contradicted a sibling script.

Wording is mirrored from the two scripts that already get this right —
point_source/simulator.py and cluster/simulator.py — which are left untouched.

In imaging/ and interferometer/simulator.py the dead `@jax.jit def simulate(...)`
cells are removed rather than corrected: they defined a function that was never
called (the call was commented out), which is why the claim survived unnoticed.
The use_jax=True constructor stays a live cell, since that part works.

Closes #379

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CWqjHGXUut25TEB8octU8H
…ator-jax-claims

# Conflicts:
#	workspace_index.json
@Jammy2211
Jammy2211 merged commit 5ebc159 into main Jul 30, 2026
7 of 8 checks passed
@Jammy2211
Jammy2211 deleted the feature/correct-simulator-jax-claims branch July 30, 2026 09:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pending-release PR queued for the next release build

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: correct false simulator-JAX claims (registration, eager-on-JAX, TransformerNUFFT)

1 participant