feat: Phase 3 — mirror Nautilus profiling scripts

[Jammy2211]

Overview

Phase 3 of the autolens_profiling z_feature roadmap — stand up autolens_profiling/searches/ with sampler profiling for the Nautilus sampler only, mirrored from autolens_workspace_developer/searches_minimal/. Other samplers in _developer/searches_minimal/ (Dynesty, Emcee, BlackJAX, NumPyro, PocoMC, NSS variants, LBFGS, sweep scripts) are explicitly out of scope — Phase 3 designs the folder layout so they can slot in later under their own prompts.

_developer stays the source of truth — the originals do not move.

Plan

• Mirror 4 files into a new nested folder layout: nautilus_simple.py → searches/nautilus/simple.py, nautilus_jax.py → searches/nautilus/jax.py, and the shared _setup.py / _metrics.py → searches/{_setup,_metrics}.py. ~20K total source.
• Update the shared _setup.py path constants from Path("jax_profiling") / "dataset" / "imaging" / "hst" to Path("dataset") / "imaging" / "hst" so the Nautilus scripts find the HST dataset Phase 1 already mirrored at the top level.
• Rewrite the Nautilus scripts' imports: from searches_minimal._{setup,metrics} → from searches._{setup,metrics} (relative-from-nested-folder structure).
• Make sure run-time + sampler-stat JSON writes land at results/searches/nautilus/<script>_summary_v<al.__version__>.{json,png} using the same versioned-artifact convention as the rest of the repo.
• Write two READMEs: top-level searches/README.md (section overview + "supported samplers" table with Nautilus filled in, others marked "planned") and searches/nautilus/README.md (what the Nautilus scripts profile, how to read the result JSON, headline-run-times table placeholder for Phase 4).
• Smoke-check: python searches/nautilus/simple.py end-to-end with a small problem size; confirm JSON+PNG lands at the expected path.

Detailed implementation plan

Affected Repositories

• PyAutoLabs/autolens_profiling (primary, target) — currently at aa131a7 on main after F1 re-mirror.
• PyAutoLabs/autolens_workspace_developer (read-only source-of-truth, no changes).

Work Classification

Scripts mirroring (workspace-style). Same routing pattern as Phase 1 / Phase 2 — manual worktree setup.

Branch Survey

Repository	Current Branch	Dirty?
./autolens_profiling	main	clean (no overlap with Phase 2's queued simulators/ touches — Phase 3 touches searches/ only)

Suggested branch: feature/nautilus-mirror
Worktree root: ~/Code/PyAutoLabs-wt/nautilus-mirror/

Parallel-execution note

Phase 2 (simulators-mirror, autolens_profiling#4) is queued but not yet started (no worktree exists). Phase 3 touches disjoint directories (searches/ vs simulators/), so the two can run in parallel from separate worktrees if needed. The worktree_check_conflict helper currently treats two tasks claiming the same repo as a conflict regardless of whether their file scopes overlap — if both phases want to run simultaneously, decide how to manage that (e.g. start Phase 3 first or merge Phase 2 quickly).

Target folder layout

searches/
    README.md                # section overview + samplers table
    _setup.py                # shared dataset/model/analysis builder
    _metrics.py              # shared MLTracker
    nautilus/
        README.md            # Nautilus-specific narrative + run-times
        simple.py            # numpy path
        jax.py               # JAX path
    # future: dynesty/, emcee/, blackjax/, numpyro/, pocomc/, nss/, lbfgs/

Path-rewrite patterns

Pattern	Before	After	File(s)
Shared dataset path constant	Path("jax_profiling") / "dataset" / "imaging" / "hst"	Path("dataset") / "imaging" / "hst"	_setup.py
Workspace-root walk-up in _setup.py	Path(__file__).resolve().parent.parent (two up from searches_minimal/_setup.py)	Path(__file__).resolve().parent.parent (still two up, now from searches/_setup.py)	_setup.py — confirm no change needed since the new location is also one folder deep from repo root
Imports in Nautilus scripts	from searches_minimal._{setup,metrics} import ...	from searches._{setup,metrics} import ...	searches/nautilus/{simple,jax}.py
Results write path	(whatever the originals use)	_workspace_root / "results" / "searches" / "nautilus"	both Nautilus scripts

The artifact filename convention is unchanged: <script>_summary_v<al.__version__>.{json,png}.

Implementation Steps

1. Set up worktree manually:

   source admin_jammy/software/worktree.sh
   worktree_create nautilus-mirror autolens_profiling
   cd ~/Code/PyAutoLabs-wt/nautilus-mirror/autolens_profiling
   git checkout -b feature/nautilus-mirror

2. Create the section folder skeleton: searches/ already exists from Phase 0 with the placeholder README — create searches/nautilus/ subfolder.

3. Copy 4 files from ~/Code/PyAutoLabs-wt/nautilus-mirror/autolens_workspace_developer/searches_minimal/ (worktree's clean origin/main copy, F1 lesson applied):

   • _setup.py → searches/_setup.py
   • _metrics.py → searches/_metrics.py
   • nautilus_simple.py → searches/nautilus/simple.py
   • nautilus_jax.py → searches/nautilus/jax.py

4. Apply path rewrites above. The _setup.py walk-up should still resolve correctly (one folder deep, same depth as before).

5. Read _developer/searches_minimal/sweep_findings.md for the user's prior observations from sweep runs — use as context for the Nautilus README narrative (per the prompt's instruction). Do NOT mirror sweep_findings.md itself; it's a workspace note, not a public artifact.

6. Replace searches/README.md placeholder with the real section README — overview, what _setup.py / _metrics.py provide, "supported samplers" table (Nautilus filled, others "planned").

7. Write searches/nautilus/README.md — narrative on what the two scripts profile (chain time, n_live sensitivity, JIT vs NumPy comparison), how to read the result JSON, headline-run-times table placeholder for Phase 4.

8. JIT-placeholder audit: nautilus_jax.py may have caveats (per sweep_findings.md); if so, surface them in the Nautilus README and link the upstream issue.

9. Smoke searches/nautilus/simple.py end-to-end with a small n_live (the docstring already says it's a wiring test). Confirm JSON+PNG lands at results/searches/nautilus/simple_summary_v<al.__version__>.{json,png}.

10. Open PR against main of PyAutoLabs/autolens_profiling. PR body: link this issue + summary of which scripts moved + which JIT paths are stubbed.

Key Files

• Source (read-only): autolens_workspace_developer/searches_minimal/{_setup,_metrics,nautilus_simple,nautilus_jax}.py (~20K).
• Reference (read-only): autolens_workspace_developer/searches_minimal/sweep_findings.md — informs the README narrative; NOT mirrored.
• New: autolens_profiling/searches/{_setup,_metrics}.py (mirrored shared helpers).
• New: autolens_profiling/searches/nautilus/{simple,jax}.py (Nautilus scripts).
• New: autolens_profiling/searches/nautilus/README.md.
• Edit: autolens_profiling/searches/README.md — replace Phase 0 placeholder.

Decisions inherited from Phase 1

• Datasets live at top-level dataset/<type>/<name>/. Phase 3's _setup.py reads from dataset/imaging/hst/ which Phase 1 already mirrored. No new dataset work.
• Results folder structure mirrors source folder structure (results/searches/nautilus/ mirrors searches/nautilus/).

F1 lesson applied: copy from clean origin/main, not the canonical

Phase 1 inadvertently copied from the dirty _developer canonical checkout. F1 (autolens_workspace_developer#67) surfaced and fixed it via autolens_profiling#3. Phase 3 must copy from the worktree's _developer (clean origin/main).

Out of scope

• All non-Nautilus samplers in _developer/searches_minimal/ (Dynesty, Emcee, BlackJAX, NumPyro, PocoMC, NSS, LBFGS) — follow-up prompts will land each under its own folder using the layout this PR establishes.
• All sweep_*.py scripts and probe_grad.py.
• Mirroring sweep_findings.md.
• Phase 2 (simulators) and Phases 4–5 of the autolens_profiling z_feature.

Original Prompt

Click to expand starting prompt

The full prompt content is preserved at PyAutoPrompt/issued/searches_nautilus_mirror.md after this issue is created. See also the z_features tracker at PyAutoPrompt/z_features/autolens_profiling.md.