docs

Author: Jammy2211

docs/overview/overview_1_start_here.rst

@@ -6,7 +6,7 @@ Start Here
 **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.
 
-It uses JAX to accelerate lensing calculations, with the example code below all running significantly faster on GPU.
+It uses **JAX** to **accelerate lensing calculations**, with the example code below all running **significantly faster on GPU**.
 
 Here is a schematic of a strong gravitational lens:
 
@@ -342,93 +342,46 @@ the stellar components use a ``LightAndMassProfile`` via the ``lmp`` module.
   :width: 600
   :alt: Alternative text
 
-
-Simulator
----------
-
-Let’s now switch gears and simulate our own strong lens imaging. This is a great way to:
-
-- Practice lens modeling before using real data.
-- Build large training sets (e.g. for machine learning).
-- Test lensing theory in a controlled environment.
-
-In this example. we simulate “perfect” images without telescope effects. This means no blurring
-from a PSF and no noise — just the raw light from galaxies and deflections from gravity.
-
-In fact, this exactly what the image above is: a perfect image of a double Einstein ring system. The only
-thing we need to do then, is output it to a .fits file so we can load it elsewhere.
-
-.. code:: python
-
-    al.output_to_fits(
-        values=image.native,
-        file_path=Path("image.fits"),
-        overwrite=True,
-    )
-
-Samples
--------
-
-Often we want to simulate *many* strong lenses — for example, to train a neural network
-or to explore population-level statistics.
-
-This uses the model composition API to define the distribution of the light and mass profiles
-of the lens and source galaxies we draw from. The model composition is a little too complex for
-the first example, thus we use a helper function to create a simple lens and source model.
-
-We then generate 3 lenses for speed, and plot their images so you can see the variety of lenses
-we create.
-
-If you want to simulate lenses yourself (e.g. for training a neural network), checkout the
-`autolens_workspace/simulators` package for a full description of how to do this and customize
-the simulated lenses to your science.
-
-The images below are perfect lenses of strong lenses, the next examples will show us how to
-instead output realistic observations of strong lenses (e.g. CCD imaging, interferometer data, etc).
-
-.. code:: python
-
-    lens_model, source_model = al.model_util.simulator_start_here_model_from()
-
-    total_datasets = 3
-
-    for sample_index in range(total_datasets):
-
-        lens_galaxy = lens_model.random_instance()
-        source_galaxy = source_model.random_instance()
-
-        tracer = al.Tracer(galaxies=[lens_galaxy, source_galaxy])
-
-        tracer_plotter = aplt.TracerPlotter(tracer=tracer, grid=grid)
-        tracer_plotter.figures_2d(image=True)
-
 Lens Modeling
 -------------
 
-Lens modeling is the process where given data on a strong lens, we fit the data with a model to infer the properties
-of the lens and source galaxies.
+Lens modeling is the process of fitting a physical model to strong-lensing data in order to infer the properties of
+the lens and source galaxies.
 
-The animation below shows a slide-show of the lens modeling procedure. Many lens models are fitted to the data over
-and over, gradually improving the quality of the fit to the data and looking more and more like the observed image.
+The primary goal of **PyAutoLens** is to make lens modeling **simple, scalable to large datasets, and fast**, with
+GPU acceleration provided via JAX.
 
-We can see that initial models give a poor fit to the data but gradually improve (increasing the likelihood) as more
-iterations are performed.
+The animation below illustrates the lens modeling workflow. Many models are fitted to the data iteratively,
+progressively improving the quality of the fit until the model closely reproduces the observed image.
 
 .. image:: https://github.com/Jammy2211/auto_files/blob/main/lensmodel.gif?raw=true
   :width: 600
 
-![Lens Modeling Animation](https://github.com/Jammy2211/auto_files/blob/main/lensmodel.gif?raw=true "model")
-
 **Credit: Amy Etherington**
 
-**PyAutoLens**'s main goal is to make lens modeling **simple** for everyone, **scale** to large datasets
-and **run very fast** thanks to GPU acceleration via JAX.
+The next documentation page guides you through lens modeling for a variety of lensing regimes (e.g. galaxy–galaxy lenses,
+cluster-scale lenses) and data types (e.g. CCD imaging, interferometer data).
+
+Simulations
+-----------
+
+Simulating strong lenses is often essential, for example to:
+
+- Practice lens modeling before working with real data.
+- Generate large training sets (e.g. for machine learning).
+- Test lensing theory in a fully controlled environment.
+
+The next documentation page guides you through how to simulate lenses for different types of strong
+lenses (e.g. galaxy–galaxy lenses, cluster-scale lenses) and different types of data (e.g. CCD imaging, interferometer data).
 
 Wrap Up
 -------
 
-We have now completed the API overview of **PyAutoLens**, including a brief introduction to the core API for
-creating galaxies, simulating data and performing lens modeling.
+This completes the introduction to **PyAutoLens**, including a brief overview of the core API for lensing calculations,
+lens modeling, and data simulation.
+
+Different users will be interested in strong lenses across different lensing regimes (e.g. galaxy-scale or
+cluster-scale lenses) and using different data types (e.g. CCD imaging or interferometer data).
 
-The next overview describes how a new user should navigate the **PyAutoLens** workspace, which contains many examples
-and tutorials, in order to get up and running with the software.
+The autolens_workspace repository contains a wide range of examples and tutorials covering these use cases. The
+next documentation page helps new users identify the most appropriate starting point based on their scientific goals.

docs/overview/overview_2_new_user_guide.rst

@@ -3,22 +3,11 @@
 New User Guide
 ==============
 
-**PyAutoLens** is an extensive piece of software with functionality for doing many different analysis tasks, fitting
-different data types and it is used for a variety of different science cases. This means the documentation is quite
-extensive, and it may initially be difficult to find the example script you need.
+**PyAutoLens** can analyse strong lens systems across a range of physical scales (e.g. 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.
 
-The ``autolens_workspace`` has five ``start_here.ipynb`` notebooks, and you need to determine which is most relevant
-to your scientific interests.
-
-You can access the notebooks by clicking on the embedded links below:
-
- - `imaging/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/imaging/start_here.ipynb>`_: Galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, James Webb).
- - `interferometer/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/interferometer/start_here.ipynb>`_: Galaxy scale strong lenses observed with interferometer data (e.g. ALMA).
- - `point_source/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/point_source/start_here.ipynb>`_: Galaxy scale strong lenses with a lensed point source (e.g. lensed quasars).
- - `group/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/group/start_here.ipynb>`_: Group scale strong lenses where there are 2-10 lens galaxies.
- - `cluster/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/cluster/start_here.ipynb>`_: Cluster scale strong lenses with 2+ lenses and 5+ source galaxies.
-
-If you are unsure based on the brief descriptions above, answer the following two questions to work out where to start.
+The autolens_workspace contains a suite of example Jupyter Notebooks, organised by lens scale and dataset type.
+To help you find the most appropriate starting point, we begin by answering two simple questions.
 
 What Scale Lens?
 ----------------
@@ -31,22 +20,40 @@ There are three scales to choose from:
   If you're interested in galaxy scale lenses, go to the question below called "What Data Type?".
 
 - **Group Scale**: Strong Lens Groups contains 2-10 lens galaxies, normally with one main large galaxy responsible for the majority of lensing.
-  They also typically lens just one source galaxy. If you are interested in groups, go to the ``group/start_here.ipynb`` notebook.
+  They also typically lens just one source galaxy. If you are interested in groups, go to the `group/start_here.ipynb <https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/group/start_here.ipynb>`_ notebook.
 
 - **Cluster Scale**: Strong Lens Galaxy clusters often contained 20-50, or more, lens galaxies, lensing 10, or more, sources galaxies.
-  If you are interested in clusters, go to the ``cluster/start_here.ipynb`` notebook.
+  If you are interested in clusters, go to the `cluster/start_here.ipynb <https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/cluster/start_here.ipynb>`_ notebook.
 
 What Dataset Type?
 ------------------
 
 If you are interested in galaxy-scale strong lenses, you now need to decide what type of strong lens data you are
 interested in:
 
-- **CDD Imaging**: For image data from telescopes like Hubble and James Webb, go to ``imaging/start_here.ipynb``.
+- **CDD Imaging**: For image data from telescopes like Hubble and James Webb, go to `imaging/start_here.ipynb <https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/imaging/start_here.ipynb>`_.
+
+- **Interferometer**: For radio / sub-mm interferometer from instruments like ALMA, go to `interferometer/start_here.ipynb <https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/interferometer/start_here.ipynb>`_.
+
+- **Point Sources**: For strongly lensed point sources (e.g. lensed quasars, supernovae), go to `point_source/start_here.ipynb <hhttps://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/point_source/start_here.ipynb>`_.
 
-- **Interferometer**: For radio / sub-mm interferometer from instruments like ALMA, go to ``interferometer/start_here.ipynb``.
+Google Colab
+------------
 
-- **Point Sources**: For strongly lensed point sources (e.g. lensed quasars, supernovae), go to ``point_source/start_here.ipynb``.
+The links above take you to the GitHub page of each notebook, and if you've cloned the workspace you can open them
+locally on your machine.
+
+However, you can also open and run each notebook directly in Google Colab, which provides a free cloud computing
+environment with all the required dependencies already installed.
+
+This is a great way to get started quickly without needing to install **PyAutoLens** on your own machine,
+so you can check its the right software for you before going through the installation process:
+
+ - `imaging/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/imaging/start_here.ipynb>`_: Galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, James Webb).
+ - `interferometer/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/interferometer/start_here.ipynb>`_: Galaxy scale strong lenses observed with interferometer data (e.g. ALMA).
+ - `point_source/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/point_source/start_here.ipynb>`_: Galaxy scale strong lenses with a lensed point source (e.g. lensed quasars).
+ - `group/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/group/start_here.ipynb>`_: Group scale strong lenses where there are 2-10 lens galaxies.
+ - `cluster/start_here.ipynb <https://colab.research.google.com/github/Jammy2211/autolens_workspace/blob/release/notebooks/cluster/start_here.ipynb>`_: Cluster scale strong lenses with 2+ lenses and 5+ source galaxies.
 
 Still Unsure?
 -------------
@@ -71,11 +78,7 @@ used in modeling and ultimately will allow you to undertake scientific research
 To complete thoroughly, they'll probably take 2-4 days, so you may want try moving ahead to the examples but can
 go back to these lectures if you find them hard to follow.
 
-If this sounds like it suits you, checkout the ``autolens_workspace/notebooks/howtolens`` package now.
-
-GitHub Links:
-
-https://github.com/Jammy2211/autolens_workspace/tree/release/notebooks/howtolens
+If this sounds like it suits you, checkout the `HowToLens <https://github.com/Jammy2211/autolens_workspace/tree/release/notebooks/howtolens>`_ package now.
 
 Wrap Up
 -------