diff --git a/README.md b/README.md index 5dc9cd997..54972aab6 100644 --- a/README.md +++ b/README.md @@ -25,21 +25,39 @@ This is called strong gravitational lensing and **PyAutoLens** makes it **simple ## Getting Started -### Human-Readable Documentation and Examples +### Natural Language or Python -The following human-readable documentation and examples are useful for new starters: +You can use **PyAutoLens** by describing what you want in natural language, through the +[**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant), or by writing Python yourself. Both +routes use the same software. To start in natural language, paste this prompt into Claude Code, Codex or another AI +coding agent: + +Starting prompt for Claude Code, Codex or other AI coding agent + +```text +I want to do strong lensing science with PyAutoLens (https://github.com/PyAutoLabs/PyAutoLens) and the +autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant). First clone that repository, +cd into it and follow its AGENTS.md. + +Begin the "start here" guide for a new user. +``` + +The assistant takes you through the [Start Here](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html) page as a conversation (grids, light and mass profiles, ray-tracing, then simulating and fitting a strong lens), one step at a time, then +helps you get started on your own lenses. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. +[Start Here](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html#natural-language-or-python) explains why **PyAutoLens** is designed to be used in natural +language, and why its Python API is not going anywhere. + +### Documentation and Examples + +All of the documentation and examples are written for people to read: - [The PyAutoLens readthedocs](https://pyautolens.readthedocs.io/en/latest): which includes [an overview of PyAutoLens's core features](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html). - [The introduction Jupyter Notebook on Google Colab](https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.10.29.1/start_here.ipynb): try **PyAutoLens** in a web browser (without installation). - [The autolens_workspace GitHub repository](https://github.com/PyAutoLabs/autolens_workspace): example scripts covering every **PyAutoLens** use case. - [The HowToLens GitHub repository](https://github.com/PyAutoLabs/HowToLens): a Jupyter notebook lecture series teaching strong lensing and lens modeling from the ground up. -### PyAutoLens AI Assistant - -The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) lets you do gravitational lensing science in natural language from inside an AI coding agent. You can get started simply by asking it a question about gravitational lensing or describing the task you would like to perform with **PyAutoLens**. See the [autolens_assistant GitHub page](https://github.com/PyAutoLabs/autolens_assistant) for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** - ## Community & Contributing **PyAutoLens** is built in the open by its users: everyone is welcome to ask questions, diff --git a/docs/_static/pyautolens.css b/docs/_static/pyautolens.css new file mode 100644 index 000000000..636c09dcd --- /dev/null +++ b/docs/_static/pyautolens.css @@ -0,0 +1,59 @@ +/* PyAutoLens-only docs layer. The shared brand file `pyauto.css` is byte-identical + across PyAutoFit / PyAutoGalaxy / PyAutoLens, so repo-specific rules live here + instead of diverging it. The natural-language prompt block below is copied + from PyAutoFit's `pyautofit.css` so prompts look the same in all three docs. */ + +/* Natural-language prompt blocks. A prompt is written as a blockquote wrapped in + `:::{container} nl-prompt`, which gives it two things a plain blockquote has + not got: a label saying what the block is, and a copy button so the prompt can + be pasted straight into an AI coding agent. The label text lives here in + `content:` so every prompt on every overview page picks it up simply by being + wrapped in the same container — nothing is repeated in the Markdown. + + The container is the positioning context for the copy button, which + sphinx-copybutton inserts as a sibling of the blockquote (see + `copybutton_selector` in conf.py). */ +.nl-prompt { + position: relative; + margin: 1.2rem 0; +} + +.nl-prompt::before { + content: "Example Natural Language Prompt for Claude Code, Codex or other AI coding agent"; + display: block; + /* Keeps the label clear of the copy button when it wraps on narrow screens. */ + padding-right: 2.5rem; + margin-bottom: 0.35rem; + font-size: 0.7rem; + font-weight: 600; + letter-spacing: 0.06em; + text-transform: uppercase; + line-height: 1.4; + color: var(--color-foreground-muted); +} + +/* sphinx-copybutton's own stylesheet positions the button against `.highlight` + code blocks and hard-codes GitHub's light-mode colours; both are re-stated + here in Furo's theme variables so the button sits in the prompt container and + follows light/dark mode. Idle at low opacity (like a code block's button), + full opacity on hover or after a successful copy. */ +.nl-prompt button.copybtn { + position: absolute; + top: 0; + right: 0; + opacity: 0.35; + border: 1px solid var(--color-background-border); + background-color: var(--color-background-secondary); + color: var(--color-foreground-muted); +} + +.nl-prompt:hover button.copybtn, +.nl-prompt button.copybtn:focus-visible, +.nl-prompt button.copybtn.success { + opacity: 1; +} + +.nl-prompt button.copybtn:hover { + background-color: var(--color-background-hover); + color: var(--color-brand-content); +} diff --git a/docs/conf.py b/docs/conf.py index 9a6492d22..d32762d80 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -75,6 +75,16 @@ todo_include_todos = True +# -- Options for copybutton -------------------------------------------------- + +# The default selector is "div.highlight pre" (code blocks only). The second +# entry adds the natural-language prompt blocks: any blockquote wrapped in a +# `:::{container} nl-prompt` aside gets its own copy button, so a reader can +# lift the prompt straight into an AI coding agent. The button is inserted as a +# sibling of the blockquote, inside the container, and copies the blockquote's +# innerText (the plain prompt, without the Markdown "> " markers). +copybutton_selector = "div.highlight pre, .nl-prompt blockquote" + # -- Options for Markdown files ---------------------------------------------- myst_enable_extensions = ["colon_fence", "deflist"] @@ -128,7 +138,7 @@ language = "en" html_static_path = ["_static"] -html_css_files = ["pyauto.css"] +html_css_files = ["pyauto.css", "pyautolens.css"] html_theme_options = { "light_css_variables": { diff --git a/docs/index.md b/docs/index.md index 21e35f4e5..c7c37c02e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,21 +10,37 @@ This is called strong gravitational lensing and **PyAutoLens** makes it simple t # Getting Started -## Human-Readable Documentation and Examples +## Natural Language or Python -The following human-readable documentation and examples are useful for new starters: +You can use **PyAutoLens** by describing what you want in natural language, through the +[**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant), or by writing Python yourself. Both +routes use the same software. To start in natural language, paste this prompt into Claude Code, Codex or another AI +coding agent: + +:::{container} nl-prompt +> I want to do strong lensing science with PyAutoLens (https://github.com/PyAutoLabs/PyAutoLens) and the +> autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant). First clone that repository, +> cd into it and follow its AGENTS.md. +> +> Begin the "start here" guide for a new user. +::: + +The assistant takes you through the [Start Here](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html) page as a conversation (grids, light and mass profiles, ray-tracing, then simulating and fitting a strong lens), one step at a time, then +helps you get started on your own lenses. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. +[Start Here](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html#natural-language-or-python) explains why **PyAutoLens** is designed to be used in natural +language, and why its Python API is not going anywhere. + +## Documentation and Examples + +All of the documentation and examples are written for people to read: - [The PyAutoLens readthedocs](https://pyautolens.readthedocs.io/en/latest): which includes [an overview of PyAutoLens's core features](https://pyautolens.readthedocs.io/en/latest/overview/overview_1_start_here.html), [a new user starting guide](https://pyautolens.readthedocs.io/en/latest/overview/overview_2_new_user_guide.html) and [an installation guide](https://pyautolens.readthedocs.io/en/latest/installation/overview.html). - [The introduction Jupyter Notebook on Colab](https://colab.research.google.com/github/PyAutoLabs/autolens_workspace/blob/2026.10.29.1/start_here.ipynb), where you can try **PyAutoLens** in a web browser (without installation). - [The autolens_workspace GitHub repository](https://github.com/PyAutoLabs/autolens_workspace), which includes example scripts covering every **PyAutoLens** use case. - [The HowToLens GitHub repository](https://github.com/PyAutoLabs/HowToLens): a Jupyter notebook lecture series teaching strong lensing and lens modeling from the ground up. -## PyAutoLens AI Assistant - -The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) lets you do gravitational lensing science in natural language from inside an AI coding agent. You can get started simply by asking it a question about gravitational lensing or describing the task you would like to perform with **PyAutoLens**. See the [autolens_assistant GitHub page](https://github.com/PyAutoLabs/autolens_assistant) for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** - # Strong Gravitational Lensing When two galaxies are aligned down the line-of-sight to Earth, light rays from the background galaxy are deflected by the diff --git a/docs/overview/overview_1_start_here.md b/docs/overview/overview_1_start_here.md index bce3ce6de..083cbf401 100644 --- a/docs/overview/overview_1_start_here.md +++ b/docs/overview/overview_1_start_here.md @@ -2,8 +2,6 @@ # Start Here -## Human-Readable Overview - **PyAutoLens** is software for analysing strong gravitational lenses, an astrophysical phenomenon where a galaxy appears multiple times because its light is bent by the gravitational field of an intervening foreground lens galaxy. @@ -19,13 +17,44 @@ Here is a schematic of a strong gravitational lens: **Credit: F. Courbin, S. G. Djorgovski, G. Meylan, et al., Caltech / EPFL / WMKO** -This notebook gives an overview of **PyAutoLens**'s features and API. - -## PyAutoLens AI Assistant - -The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) lets you do gravitational lensing science in natural language from inside an AI coding agent. You can get started simply by asking it a question about gravitational lensing or describing the task you would like to perform with **PyAutoLens**. See the [autolens_assistant GitHub page](https://github.com/PyAutoLabs/autolens_assistant) for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** +This page gives an overview of **PyAutoLens**'s features and API. + +## Natural Language or Python + +You can use **PyAutoLens** by describing what you want in **natural language**, or by writing **Python** yourself. +Both routes use the same software and everything on this page can be done either way. + +To use natural language, open Claude Code, Codex or another AI coding agent and paste in the prompt below. The +[PyAutoLens AI Assistant](https://github.com/PyAutoLabs/autolens_assistant) then takes you through this page as a +conversation (grids, light and mass profiles, ray-tracing, then simulating and fitting a strong lens), with you typing +each request in plain English. Afterwards it helps you get started on your own lenses: + +:::{container} nl-prompt +> I want to do strong lensing science with PyAutoLens (https://github.com/PyAutoLabs/PyAutoLens) and the +> autolens_assistant (https://github.com/PyAutoLabs/autolens_assistant). First clone that repository, +> cd into it and follow its AGENTS.md. +> +> Begin the "start here" guide for a new user. +::: + +The assistant runs inside an AI coding agent. Claude Code and Codex are recommended, and sustained scientific use +normally needs paid access to one of them. Free options are listed on the +[AI Options](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_OPTIONS.md) page. + +**Why natural language?** Turning a scientific idea into an analysis has always meant expressing it through the syntax +of a programming language. That syntax was never the science: it is the interface between your ideas and the +computer. **PyAutoLens** is designed so you can describe a lensing analysis in the language you use to think and write +about it, while you supply the understanding, direction and judgement. The +[PyAuto AI Policy](https://github.com/PyAutoLabs/PyAutoScientist/blob/main/AI_POLICY.md) explains this approach in +more detail. + +**Python is not going anywhere.** Every **PyAutoLens** feature remains available through its Python API, and the +assistant writes ordinary **PyAutoLens** code that you can read, run and change. All the documentation is written for +people to read. The rest of this page is the Python overview, the +[autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace) holds runnable examples for every use case, and +the [HowToLens](https://github.com/PyAutoLabs/HowToLens) lectures teach strong lensing and lens modeling from first +principles. That understanding is what lets you direct an analysis with expertise, whether you do it in natural +language or in Python. ## Imports diff --git a/docs/overview/overview_2_new_user_guide.md b/docs/overview/overview_2_new_user_guide.md index b9ff80412..73db78ac3 100644 --- a/docs/overview/overview_2_new_user_guide.md +++ b/docs/overview/overview_2_new_user_guide.md @@ -2,8 +2,6 @@ # New User Guide -## Human-Readable Guide - **PyAutoLens** can analyse strong lens systems across a range of physical scales (e.g. galaxy, multi-galaxy, group, and cluster) and for different types of data (e.g. imaging, interferometer, and point-source observations). Depending on the scientific questions you are interested in, the analysis you perform may differ significantly. @@ -11,11 +9,10 @@ The autolens_workspace contains a suite of example Jupyter Notebooks, organised This guide begins with two simple questions to help you find the most appropriate example notebook for your science case. -## PyAutoLens AI Assistant - -The [**PyAutoLens AI Assistant**](https://github.com/PyAutoLabs/autolens_assistant) lets you do gravitational lensing science in natural language from inside an AI coding agent. You can get started simply by asking it a question about gravitational lensing or describing the task you would like to perform with **PyAutoLens**. See the [autolens_assistant GitHub page](https://github.com/PyAutoLabs/autolens_assistant) for its full scope and instructions. - -**The assistant runs inside an AI coding agent: Claude Code or Codex are recommended. Sustained scientific use normally needs paid access to one of them (a personal subscription, institutional access or API billing). OpenCode is an experimental alternative whose client is free but whose model access, cost and capability depend on the provider. Browser chat routes (ChatGPT or Claude with a GitHub connector) are no longer supported.** +**In natural language:** if you are using the [PyAutoLens AI Assistant](https://github.com/PyAutoLabs/autolens_assistant), you can skip the +questions below: describe the scale of your lens and your data type to the assistant and it will pick the matching +example and work through it with you. The examples below are what the assistant uses, and they remain the best place +to see the Python. ## What Scale Lens?