Skip to content

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

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)#183
Jammy2211 merged 2 commits into
mainfrom
feature/correct-simulator-jax-claims

Conversation

@Jammy2211

Copy link
Copy Markdown
Collaborator

Summary

Corrects the false JAX claims in this workspace's docs — the autogalaxy half of
PyAutoLabs/autolens_workspace#379. All measured against the installed stack.

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

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

It is also unimplementable as worded — JAX flattens a jitted function's
arguments at trace time, before entering the callee, so a simulator that
registered internally would already be too late. (PointSolver.solve_triangles
in autolens carries the same note at its own call site.)

The correct call is now named: autogalaxy.jax.register_galaxies_classes(galaxies),
added in PyAutoGalaxy#537 precisely because autogalaxy had no public counterpart to
autolens.jax.register_tracer_classes.

2. "eager via_galaxies_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.
Separate library bug, filed separately. The docs now say so and point at the eager
call rather than presenting a recipe that cannot run.

4. TransformerNUFFT — two separate stale claims

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 differ by
class: SimulatorInterferometerTransformerDFT; Interferometer, which a fit
uses → TransformerNUFFT.

Note on why this went unnoticed

Both __JAX Variant__ sections present their recipe inside a ```python
fence — prose, not executed cells — and neither simulator.py is in
smoke_tests.txt. So dataset_jax = simulate(galaxies) looked like a working
call while never running. Same failure mode as the six likelihood_function.py
__JAX__ blocks removed in #181.

Scripts Changed

  • scripts/guides/using_jax.py — rewrote __Writing @jax.jit Yourself__ (claims 1-3); fixed the NUFFT sentence in __Custom Likelihood Functions__ (claim 4)
  • scripts/imaging/simulator.py — claims 1-3 in __JAX Variant__
  • scripts/interferometer/simulator.py — claims 1-3 plus the stale nufftax-as-research-path paragraph

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

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; nothing here imports new API, so merge order does not actually matter.

The register_galaxies_classes function this PR now points readers at is already
merged (PyAutoGalaxy#537, 9594c00b).

Test Plan

  • Both edited simulator scripts run end-to-end
  • py_compile on every touched file
  • Post-edit grep: zero surviving hits for pytree registration internally, already runs on JAX, and both reversed NUFFT claims
  • Smoke tests: 12/12 passed

Generated by the PyAutoLabs agent workflow.

… NUFFT)

The autogalaxy half of PyAutoLabs/autolens_workspace#379. All measured against
the installed stack.

1. "The simulator handles pytree registration internally" — no simulator
   registers pytrees anywhere, so the documented @jax.jit wrap fails with
   `TypeError ... value is of type Galaxies`. Unimplementable as worded too:
   JAX flattens jitted arguments at trace time, before entering the callee.
   The correct call is now named — autogalaxy.jax.register_galaxies_classes,
   added in PyAutoGalaxy#537 for exactly this gap.

2. "eager via_galaxies_from(...) already runs on JAX" — returns a
   numpy.ndarray-backed dataset, not jax.Array.

3. The @jax.jit recipe fails even WITH registration, inside autoarray
   (preprocess.py:153, then array_2d_util.py). Separate library bug, filed
   separately; docs now point at the eager call instead.

4. Two separate stale NUFFT claims: guides/using_jax.py said TransformerNUFFT is
   not JAX-traceable (shipped backwards in #181 this morning), and
   interferometer/simulator.py said it is pynufft-backed with nufftax "a
   research path". Per autoarray's own error text TransformerNUFFT IS the
   default JAX-native nufftax-backed transformer (nufftax 0.3.1 installed);
   TransformerNUFFTPyNUFFT is the legacy pynufft one.

Why this went unnoticed: both __JAX Variant__ recipes live inside ```python
fences (prose, not executed cells) and neither simulator.py is in
smoke_tests.txt, so `dataset_jax = simulate(galaxies)` looked like a working call
while never running. Same failure mode as the six likelihood_function.py __JAX__
blocks removed in #181.

Refs PyAutoLabs/autolens_workspace#379

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CWqjHGXUut25TEB8octU8H
…igator gate)

PyAutoHands#213 ("gate relative folder references in README prose") merged at
08:28:46Z, seven minutes after this repo's main last passed Navigator Check
(1abfc8c, 08:21:38Z). navigator_check.yml is consumed @main, so this PR was the
first to run under the widened gate and it flagged 5 pre-existing references:

  scripts/README.md:1                                            -> autogalaxy_workspace/scripts
  scripts/README.md:4                                            -> autogalaxy_workspace/notebooks
  scripts/interferometer/features/linear_light_profiles/README.md -> autogalaxy_workspace/scripts/imaging/features/...
  scripts/interferometer/features/multi_gaussian_expansion/README.md -> ditto
  scripts/interferometer/features/shapelets/README.md             -> ditto

None were touched by this PR; all are unchanged on main, which will fail its next
run too. They are genuine drift rather than a checker false positive:
autolens_workspace words the same sentences repo-relative ("The `scripts`
folder") and passes the identical gate, while this repo used the
repo-name-prefixed form, which cannot resolve from the repo root because the root
IS autogalaxy_workspace.

Dropped the `autogalaxy_workspace/` prefix from those 5 folder references.
References to `autogalaxy_workspace/README.md` are left alone — the gate covers
folder refs only, and autolens_workspace keeps that form too.

The notebooks/ README mirrors are generated from scripts/, so generate.py
propagated the change.

Refs PyAutoLabs/autolens_workspace#379

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CWqjHGXUut25TEB8octU8H
@Jammy2211
Jammy2211 merged commit 21c17ce into main Jul 30, 2026
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.

1 participant