Skip to content

Commit 6ad7363

Browse files
Jammy2211claude
authored and
Jammy2211
committed
docs: add canonical AGENTS.md, reduce CLAUDE.md to import stub
Migrate the agent docs to one agent-agnostic AGENTS.md (uniform skeleton) with CLAUDE.md as a 4-line @AGENTS.md stub. Document the real CI gates (smoke_tests + navigator_check + url_check on Python 3.12 & 3.13, PyAutoBuild as sibling, same-named library branches), the navigator catalogue, and the full-resolution dataset policy (no PYAUTO_SMALL_DATASETS). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent f8d1bf5 commit 6ad7363

2 files changed

Lines changed: 112 additions & 120 deletions

File tree

‎AGENTS.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# HowToLens — Agent Instructions
2+
3+
This is the **HowToLens** tutorial lecture series for **PyAutoLens**, a Python library for strong
4+
gravitational lens modeling. Tutorials teach new users what strong lensing is and how to model it
5+
from first principles. It is the teaching companion to `../autolens_workspace`. These are the
6+
canonical, agent-agnostic instructions for this repo.
7+
8+
## Repository Structure
9+
10+
- `scripts/` — Runnable Python tutorial scripts:
11+
- `chapter_1_introduction/` — Grids, profiles, galaxies, ray-tracing, data, fitting
12+
- `chapter_2_lens_modeling/` — Non-linear searches, Bayesian inference, lens modeling
13+
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
14+
- `chapter_4_pixelizations/` — Pixelized source reconstruction, inversions, regularization
15+
- `chapter_optional/` — Alternative searches and advanced topics
16+
- `simulator/` — Simulator scripts that generate the tutorial datasets at runtime
17+
- `notebooks/` — Jupyter versions, generated from `scripts/` (do not edit directly)
18+
- `config/` — PyAutoLens configuration YAML
19+
- `dataset/` — Empty in the repo; written at runtime by the simulator scripts
20+
- `output/` — Model-fit results (generated at runtime, not committed)
21+
22+
## Running Scripts
23+
24+
Scripts are run **from the repo root** so relative paths to `dataset/` and `output/` resolve. A
25+
tutorial that needs a dataset invokes the matching `scripts/simulator/` script via `subprocess` if
26+
the dataset folder is absent — no manual simulate-then-run step.
27+
28+
```bash
29+
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
30+
```
31+
32+
Fast mode for integration: `PYAUTO_TEST_MODE=1` skips sampling (`=2` also bypasses; combine with
33+
`PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1` for a
34+
fast smoke run). **Dataset realism:** `PYAUTO_SMALL_DATASETS` is deliberately **not** used in
35+
HowToLens — tutorials assume the full-resolution simulated datasets (unlike the workspaces, which
36+
cap grids/masks).
37+
38+
## Testing
39+
40+
On CI, every PR is gated on Python **3.12 and 3.13** by `smoke_tests.yml` (runs
41+
`python .github/scripts/run_smoke.py`, driven by `smoke_tests.txt` + `config/build/env_vars.yaml` —
42+
the definition of green), `navigator_check.yml` (PyAutoBuild's reusable navigator-catalogue check;
43+
see *Notebooks vs Scripts*), and `url_check.yml` (link checking). The smoke and navigator jobs check
44+
out **PyAutoBuild** as a sibling and run the PyAuto* libraries from the **same-named branch** of each
45+
source repo, so a HowToLens PR is validated against matching library branches.
46+
47+
## Sandboxed / restricted runs
48+
49+
If `numba` or `matplotlib` cannot write to the default cache locations, point them at writable dirs:
50+
51+
```bash
52+
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
53+
```
54+
55+
## Notebooks vs Scripts
56+
57+
Notebooks in `notebooks/` are **generated** from the `.py` scripts via PyAutoBuild. **Always edit the
58+
`.py` scripts, never the `.ipynb` directly.** The `# %%` marker alternates code and markdown cells.
59+
Regenerate from the repo root:
60+
61+
```bash
62+
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtolens
63+
```
64+
65+
The `howtolens` project target is registered in PyAutoBuild (`run_all.py`, `navigator.py`,
66+
`config/`). The navigator catalogue — `llms-full.txt` + `workspace_index.json` — is what
67+
`navigator_check.yml` gates; it is rebuilt by the same PyAutoBuild generate/merge flow that builds
68+
the notebooks. Commit regenerated notebooks and catalogue alongside the script changes.
69+
70+
## Bulk-edit safety
71+
72+
When editing the same region across many scripts in one pass, only rewrite the targeted region.
73+
**Never produce a whole-file write unless you have read the entire current file** — a whole-file
74+
write from a header skim silently deletes every section below the header.
75+
76+
## Scientific Context
77+
78+
When a tutorial benefits from broader framing — landmark surveys, named lenses, degeneracies, or the
79+
literature behind a mass-model or source-reconstruction choice — pull from the `autolens_assistant`
80+
literature wiki at https://github.com/PyAutoLabs/autolens_assistant (`wiki/literature/` — concepts,
81+
entities, sources). If cloned as a sibling, read it locally at `../autolens_assistant/wiki/literature/`.
82+
83+
## Related Repos
84+
85+
- `../PyAutoLens`, `../PyAutoGalaxy` — source libraries.
86+
- `../autolens_workspace` — the user-facing workspace (tutorials point here as the next destination).
87+
- `../PyAutoBuild` — notebook generation + CI tooling.
88+
- `../autolens_assistant` — science-assistant workspace (literature wiki; see *Scientific Context*).
89+
90+
## Task Workflows
91+
92+
**`[API Update]` issues:** find every renamed/moved/removed/changed public API, update each tutorial
93+
script (preserving the teaching prose), run `python .github/scripts/run_smoke.py`, and fix `[FAIL]`
94+
entries until the summary passes; regenerate notebooks + catalogue after. **General issues:** edit
95+
only files in `scripts/` (never `notebooks/`), preserve docstrings and explanations, test, then
96+
regenerate. Flag any change that affects `autolens_workspace` or the source libraries in your PR.
97+
98+
## Clean state
99+
100+
Never rewrite history on a repo with a remote (no `git init` over a tracked tree, no force-push to
101+
`main`, no rebasing pushed shared branches). To reset a dirty tree the only correct sequence is:
102+
103+
```bash
104+
git fetch origin
105+
git reset --hard origin/main
106+
git clean -fd
107+
```

‎CLAUDE.md‎

Lines changed: 5 additions & 120 deletions
Original file line numberDiff line numberDiff line change
@@ -1,120 +1,5 @@
1-
# HowToLens
2-
3-
This is the **HowToLens** tutorial lecture series for `PyAutoLens`, a Python library for strong gravitational lens modeling. Tutorials teach new users what strong lensing is and how to model it from first principles.
4-
5-
## Scientific Context
6-
7-
When a tutorial benefits from broader scientific framing — references to
8-
landmark surveys, named lenses, degeneracies, or the literature behind a
9-
mass model or source-reconstruction choice — pull from the lensing
10-
sub-wiki at
11-
[`PyAutoLabs/PyAutoPaper`](https://github.com/PyAutoLabs/PyAutoPaper),
12-
locally at `../PyAutoPaper/lensing_wiki/`. It has topical concept pages
13-
(`concepts/`), named-entity pages (`entities/`, including SLACS, H0liCOW,
14-
Euclid Q1, Abell 1201, the Cosmic Horseshoe), and a per-topic
15-
bibliography (`sources/`, ~190 papers — most stubs are `status: stub`
16-
until verified against the PDF). Start at
17-
`../PyAutoPaper/lensing_wiki/index.md`. Use it especially for the
18-
science-narrative tutorials that Opus authors.
19-
20-
## Repository Structure
21-
22-
- `scripts/` — Runnable Python tutorial scripts
23-
- `chapter_1_introduction/` — Grids, profiles, galaxies, ray-tracing, data, fitting
24-
- `chapter_2_lens_modeling/` — Non-linear searches, Bayesian inference, lens modeling
25-
- `chapter_3_search_chaining/` — Search chaining, prior passing, automated pipelines
26-
- `chapter_4_pixelizations/` — Pixelized source reconstruction, inversions, regularization
27-
- `chapter_optional/` — Alternative non-linear searches and advanced topics
28-
- `simulator/` — Simulator scripts that generate the tutorial datasets at runtime
29-
- `notebooks/` — Jupyter notebook versions of scripts (generated from `scripts/`, do not edit directly)
30-
- `config/` — `PyAutoLens` configuration YAML files
31-
- `dataset/` — Empty in the repo; tutorial datasets are written here at runtime by the simulator scripts
32-
- `output/` — Model-fit results (generated at runtime, not committed)
33-
34-
## Running Scripts
35-
36-
Scripts are run from the repository root so relative paths to `dataset/` and `output/` resolve correctly:
37-
38-
```bash
39-
python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
40-
```
41-
42-
Tutorials in chapters 1 and 2 that need a dataset invoke the relevant script in `scripts/simulator/` via `subprocess` if the dataset folder does not already exist — there is no manual simulate-then-run step.
43-
44-
**Integration testing / fast mode**: set `PYAUTO_TEST_MODE=1` to skip non-linear search sampling:
45-
46-
```bash
47-
PYAUTO_TEST_MODE=1 python scripts/chapter_2_lens_modeling/tutorial_1_non_linear_search.py
48-
```
49-
50-
**Fast smoke tests**: combine test mode with the skip flags:
51-
52-
```bash
53-
PYAUTO_TEST_MODE=2 PYAUTO_SKIP_FIT_OUTPUT=1 PYAUTO_SKIP_VISUALIZATION=1 PYAUTO_SKIP_CHECKS=1 PYAUTO_FAST_PLOTS=1 python scripts/chapter_1_introduction/tutorial_7_fitting.py
54-
```
55-
56-
Note: `PYAUTO_SMALL_DATASETS` is deliberately **not** used in HowToLens. Tutorials assume the full-resolution simulated datasets that the simulator scripts produce.
57-
58-
**Codex / sandboxed runs**: set writable cache directories so `numba` and `matplotlib` do not fail on unwritable home paths:
59-
60-
```bash
61-
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/chapter_1_introduction/tutorial_1_grids_and_galaxies.py
62-
```
63-
64-
## Core API Patterns
65-
66-
Imports used throughout the tutorials:
67-
68-
```python
69-
import autofit as af
70-
import autolens as al
71-
import autolens.plot as aplt
72-
```
73-
74-
## Notebooks vs Scripts
75-
76-
Notebooks in `notebooks/` are generated from the `.py` files in `scripts/` using `generate.py` from the `PyAutoBuild` repo. **Always edit the `.py` scripts**, never the notebooks directly. The `# %%` marker alternates between code and markdown cells.
77-
78-
### Building Notebooks
79-
80-
Run from the workspace root:
81-
82-
```bash
83-
PYTHONPATH=../PyAutoBuild/autobuild python3 ../PyAutoBuild/autobuild/generate.py howtolens
84-
```
85-
86-
The `howtolens` project target in `PyAutoBuild/autobuild/config.yaml` is what drives this.
87-
88-
## Relationship to autolens_workspace
89-
90-
HowToLens is the teaching companion to `autolens_workspace`. Many tutorials (particularly in chapters 2–4) point users to `autolens_workspace` scripts (e.g. `scripts/imaging/modeling.py`, `scripts/guides/...`) as the next destination after the relevant concept has been introduced. Those cross-references use absolute paths like `autolens_workspace/scripts/...` and refer to the separate `autolens_workspace` repository — not to anything inside HowToLens.
91-
92-
## Related Repos
93-
94-
- **PyAutoLens** source: `../PyAutoLens`
95-
- **PyAutoGalaxy** source: `../PyAutoGalaxy`
96-
- **autolens_workspace**: `../autolens_workspace` — main user-facing workspace
97-
- **PyAutoBuild**: `../PyAutoBuild` — notebook generation and CI/CD tooling
98-
## Never rewrite history
99-
100-
NEVER perform these operations on any repo with a remote:
101-
102-
- `git init` in a directory already tracked by git
103-
- `rm -rf .git && git init`
104-
- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
105-
for AI workflow", or any equivalent message on a branch with a remote
106-
- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
107-
- `git filter-repo` / `git filter-branch` on shared branches
108-
- `git rebase -i` rewriting commits already pushed to a shared branch
109-
110-
If the working tree needs a clean state, the **only** correct sequence is:
111-
112-
git fetch origin
113-
git reset --hard origin/main
114-
git clean -fd
115-
116-
This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
117-
and any other agent. The "Initial commit — fresh start for AI workflow" pattern
118-
that appeared independently on origin and local for three workspace repos is
119-
exactly what this rule prevents — it costs ~40 commits of redundant local work
120-
every time it happens.
1+
# HowToLens — agent instructions
2+
The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them
3+
via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in
4+
this directory and read it directly.
5+
@AGENTS.md

0 commit comments

Comments
 (0)