From d820cfc9dbf566743f9564fd82c2fbc74d6884ea Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Thu, 30 Apr 2026 21:45:28 +0100 Subject: [PATCH] docs: convert 23 prose .rst files to MyST .md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keeps docs/api/*.rst and docs/_templates/*.rst as RST — autosummary-driven pages don't gain readability from a MyST conversion. Existing myst_enable_extensions (colon_fence, deflist) cover all converted content. Part of PyAutoLabs/PyAutoFit#1245. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/general/citations.md | 58 +++ docs/general/citations.rst | 65 --- docs/general/configs.md | 24 + docs/general/configs.rst | 27 - docs/general/credits.md | 33 ++ docs/general/credits.rst | 35 -- docs/general/demagnified_solutions.md | 200 ++++++++ docs/general/demagnified_solutions.rst | 201 -------- ...od_function.rst => likelihood_function.md} | 41 +- docs/general/model_cookbook.md | 416 ++++++++++++++++ docs/general/model_cookbook.rst | 432 ---------------- docs/general/papers.md | 101 ++++ docs/general/papers.rst | 104 ---- docs/general/workspace.md | 59 +++ docs/general/workspace.rst | 66 --- docs/howtolens/chapter_1_introduction.md | 34 ++ docs/howtolens/chapter_1_introduction.rst | 35 -- docs/howtolens/chapter_2_lens_modeling.md | 29 ++ docs/howtolens/chapter_2_lens_modeling.rst | 30 -- docs/howtolens/chapter_3_search_chaining.md | 24 + docs/howtolens/chapter_3_search_chaining.rst | 25 - docs/howtolens/chapter_4_pixelizations.md | 38 ++ docs/howtolens/chapter_4_pixelizations.rst | 39 -- docs/howtolens/chapter_optional.md | 11 + docs/howtolens/chapter_optional.rst | 13 - .../howtolens/{howtolens.rst => howtolens.md} | 144 +++--- docs/index.md | 266 ++++++++++ docs/index.rst | 269 ---------- docs/installation/{conda.rst => conda.md} | 232 +++++---- docs/installation/overview.md | 43 ++ docs/installation/overview.rst | 48 -- docs/installation/{pip.rst => pip.md} | 239 +++++---- docs/installation/source.md | 173 +++++++ docs/installation/source.rst | 179 ------- docs/installation/troubleshooting.md | 69 +++ docs/installation/troubleshooting.rst | 75 --- docs/overview/overview_1_start_here.md | 372 ++++++++++++++ docs/overview/overview_1_start_here.rst | 373 -------------- ...guide.rst => overview_2_new_user_guide.md} | 167 +++---- ..._3_features.rst => overview_3_features.md} | 462 +++++++++--------- 40 files changed, 2573 insertions(+), 2678 deletions(-) create mode 100644 docs/general/citations.md delete mode 100644 docs/general/citations.rst create mode 100644 docs/general/configs.md delete mode 100644 docs/general/configs.rst create mode 100644 docs/general/credits.md delete mode 100644 docs/general/credits.rst create mode 100644 docs/general/demagnified_solutions.md delete mode 100644 docs/general/demagnified_solutions.rst rename docs/general/{likelihood_function.rst => likelihood_function.md} (68%) create mode 100644 docs/general/model_cookbook.md delete mode 100644 docs/general/model_cookbook.rst create mode 100644 docs/general/papers.md delete mode 100644 docs/general/papers.rst create mode 100644 docs/general/workspace.md delete mode 100644 docs/general/workspace.rst create mode 100644 docs/howtolens/chapter_1_introduction.md delete mode 100644 docs/howtolens/chapter_1_introduction.rst create mode 100644 docs/howtolens/chapter_2_lens_modeling.md delete mode 100644 docs/howtolens/chapter_2_lens_modeling.rst create mode 100644 docs/howtolens/chapter_3_search_chaining.md delete mode 100644 docs/howtolens/chapter_3_search_chaining.rst create mode 100644 docs/howtolens/chapter_4_pixelizations.md delete mode 100644 docs/howtolens/chapter_4_pixelizations.rst create mode 100644 docs/howtolens/chapter_optional.md delete mode 100644 docs/howtolens/chapter_optional.rst rename docs/howtolens/{howtolens.rst => howtolens.md} (78%) create mode 100644 docs/index.md delete mode 100644 docs/index.rst rename docs/installation/{conda.rst => conda.md} (53%) create mode 100644 docs/installation/overview.md delete mode 100644 docs/installation/overview.rst rename docs/installation/{pip.rst => pip.md} (50%) create mode 100644 docs/installation/source.md delete mode 100644 docs/installation/source.rst create mode 100644 docs/installation/troubleshooting.md delete mode 100644 docs/installation/troubleshooting.rst create mode 100644 docs/overview/overview_1_start_here.md delete mode 100644 docs/overview/overview_1_start_here.rst rename docs/overview/{overview_2_new_user_guide.rst => overview_2_new_user_guide.md} (63%) rename docs/overview/{overview_3_features.rst => overview_3_features.md} (63%) diff --git a/docs/general/citations.md b/docs/general/citations.md new file mode 100644 index 000000000..240ba12a2 --- /dev/null +++ b/docs/general/citations.md @@ -0,0 +1,58 @@ +(references)= + +# Citations & References + +The bibtex entries for **PyAutoLens** and its affiliated software packages can be found +[here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.bib), with example text for citing **PyAutoLens** +in [.tex format here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.tex) format here and +[.md format here](https://github.com/Jammy2211/PyAutoLens/blob/main/files/citations.md). As shown in the examples, we +would greatly appreciate it if you mention **PyAutoLens** by name and include a link to our GitHub page! + +**PyAutoLens** is published in the [Journal of Open Source Software](https://joss.theoj.org/papers/10.21105/joss.02825#) and its +entry in the above .bib file is under the citation key `pyautolens`. Please also cite the MNRAS AutoLens +papers ( and ) which are included +under the citation keys `Nightingale2015` and `Nightingale2018`. + +You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, etc) in +the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes +the citation key for all of these projects. + +## Jax-Zero-Contour + +If you use the zero-contour method for critical curve and caustic computation (the default in +`visualize/general.yaml` via `critical_curves_method: zero_contour`), please cite the +`Jax-Zero-Contour` package by Coleman Krawczyk: + +```bibtex +@software{coleman_krawczyk_2025_15730415, + author = {Coleman Krawczyk}, + title = {CKrawczyk/Jax-Zero-Contour: Version 2.0.0}, + month = jun, + year = 2025, + publisher = {Zenodo}, + version = {v2.0.0}, + doi = {10.5281/zenodo.15730415}, + url = {https://doi.org/10.5281/zenodo.15730415}, +} +``` + +The package is available at and archived at +. + +## Dynesty + +If you used the nested sampling algorithm Dynesty, please follow the citation instructions [on the dynesty readthedocs](https://dynesty.readthedocs.io/en/latest/references.html). + +## Mass Models + +If you use decomposed mass models (e.g. stellar mass models like an `Sersic` or dark matter models like +an `NFW`) please cite the following paper under +citation key `Oguri2021`. Our deflection angle calculations are based on this method. + +If you specifically use a decomposed mass model with the `gNFW` please cite the following paper under +citation key `Anowar2019`. + +## Science Papers + +The citations.bib file above also includes my work on [using strong lensing to study galaxy structure](https://ui.adsabs.harvard.edu/abs/2019MNRAS.489.2049N/abstract). If you're feeling kind, please go ahead and stick +a citation in your introduction using citep\{Nightingale2019} or [@Nightingale2019] ;). diff --git a/docs/general/citations.rst b/docs/general/citations.rst deleted file mode 100644 index ec795df30..000000000 --- a/docs/general/citations.rst +++ /dev/null @@ -1,65 +0,0 @@ -.. _references: - -Citations & References -====================== - -The bibtex entries for **PyAutoLens** and its affiliated software packages can be found -`here `_, with example text for citing **PyAutoLens** -in `.tex format here `_ format here and -`.md format here `_. As shown in the examples, we -would greatly appreciate it if you mention **PyAutoLens** by name and include a link to our GitHub page! - -**PyAutoLens** is published in the `Journal of Open Source Software `_ and its -entry in the above .bib file is under the citation key ``pyautolens``. Please also cite the MNRAS AutoLens -papers (https://academic.oup.com/mnras/article/452/3/2940/1749640 and https://academic.oup.com/mnras/article-abstract/478/4/4738/5001434?redirectedFrom=fulltext) which are included -under the citation keys ``Nightingale2015`` and ``Nightingale2018``. - -You should also specify the non-linear search(es) you use in your analysis (e.g. Dynesty, Emcee, PySwarms, etc) in -the main body of text, and delete as appropriate any packages your analysis did not use. The citations.bib file includes -the citation key for all of these projects. - -Jax-Zero-Contour ----------------- - -If you use the zero-contour method for critical curve and caustic computation (the default in -``visualize/general.yaml`` via ``critical_curves_method: zero_contour``), please cite the -``Jax-Zero-Contour`` package by Coleman Krawczyk: - -.. code-block:: bibtex - - @software{coleman_krawczyk_2025_15730415, - author = {Coleman Krawczyk}, - title = {CKrawczyk/Jax-Zero-Contour: Version 2.0.0}, - month = jun, - year = 2025, - publisher = {Zenodo}, - version = {v2.0.0}, - doi = {10.5281/zenodo.15730415}, - url = {https://doi.org/10.5281/zenodo.15730415}, - } - -The package is available at https://github.com/CKrawczyk/Jax-Zero-Contour and archived at -https://doi.org/10.5281/zenodo.15730415. - -Dynesty -------- - -If you used the nested sampling algorithm Dynesty, please follow the citation instructions `on the dynesty readthedocs `_. - -Mass Models ------------ - -If you use decomposed mass models (e.g. stellar mass models like an ``Sersic`` or dark matter models like -an ``NFW``) please cite the following paper https://arxiv.org/abs/2106.11464 under -citation key ``Oguri2021``. Our deflection angle calculations are based on this method. - -If you specifically use a decomposed mass model with the ``gNFW`` please cite the following paper https://academic.oup.com/mnras/article/488/1/1387/5526256 under -citation key ``Anowar2019``. - -Science Papers --------------- - -The citations.bib file above also includes my work on `using strong lensing to study galaxy structure -`_. If you're feeling kind, please go ahead and stick -a citation in your introduction using \citep{Nightingale2019} or [@Nightingale2019] ;). - diff --git a/docs/general/configs.md b/docs/general/configs.md new file mode 100644 index 000000000..5d0bfc589 --- /dev/null +++ b/docs/general/configs.md @@ -0,0 +1,24 @@ +# Configs + +**PyAutoLens** uses a number of configuration files that customize the default behaviour of the non-linear searches, +visualization and other aspects of **PyAutoLens**. + +Descriptions of every configuration file and their input parameters are provided in the `README.rst` in +the [config directory of the workspace](https://github.com/Jammy2211/autolens_workspace/tree/release/config) + +## Setup + +By default, **PyAutoLens** looks for the config files in a `config` folder in the current working directory, which is +why we run autolens scripts from the `autolens_workspace` directory. + +The configuration path can also be set manually in a script using the project **PyAutoConf** and the following +command (the path to the `output` folder where the results of a non-linear search are stored is also set below): + +```bash +from autoconf import conf + +conf.instance.push( + config_path="path/to/config", + output_path=f"path/to/output" +) +``` diff --git a/docs/general/configs.rst b/docs/general/configs.rst deleted file mode 100644 index f7eea17a6..000000000 --- a/docs/general/configs.rst +++ /dev/null @@ -1,27 +0,0 @@ -Configs -======= - -**PyAutoLens** uses a number of configuration files that customize the default behaviour of the non-linear searches, -visualization and other aspects of **PyAutoLens**. - -Descriptions of every configuration file and their input parameters are provided in the ``README.rst`` in -the `config directory of the workspace `_ - - -Setup ------ - -By default, **PyAutoLens** looks for the config files in a ``config`` folder in the current working directory, which is -why we run autolens scripts from the ``autolens_workspace`` directory. - -The configuration path can also be set manually in a script using the project **PyAutoConf** and the following -command (the path to the ``output`` folder where the results of a non-linear search are stored is also set below): - -.. code-block:: bash - - from autoconf import conf - - conf.instance.push( - config_path="path/to/config", - output_path=f"path/to/output" - ) diff --git a/docs/general/credits.md b/docs/general/credits.md new file mode 100644 index 000000000..474cbab1f --- /dev/null +++ b/docs/general/credits.md @@ -0,0 +1,33 @@ +(credits)= + +# Credits + +**Developers**: + +[James Nightingale](https://github.com/Jammy2211): Lead developer & PyAutoLens guru. + +[Richard Hayes](https://github.com/rhayes777): Lead developer & [PyAutoFit](https://github.com/rhayes777/PyAutoFit) guru. + +[Aristeidis Amvrosiadis](https://github.com/Sketos): Interferometer Analysis. + +[Amy Etherington](https://github.com/amyetherington) : Magnification, Critical Curves and Caustic Calculations. + +Qiuhan He: NFW Profile Lensing Calculations. + +[Johnathan Frawley](https://github.com/jonathanfrawley): Profiling, optimization and build server tools. + +[Ashley Kelly](https://github.com/AshKelly): Developer of [pyquad](https://github.com/AshKelly/pyquad) for fast deflections computations. + +[Xiaoyue Cao](https://github.com/caoxiaoyue): Analytic Ellipitcal Power-Law Deflection Angle Calculations. + +[Nan Li](https://github.com/linan7788626): Docker integration & support. + +**Code Donors**: + +[Andrew Robertson](https://github.com/Andrew-Robertson): Critical curve & caustic calculations. + +Mattia Negrello: Visibility models in the uv-plane via direct Fourier transforms. + +[Andrea Enia](https://github.com/AndreaEnia): Voronoi source-plane plotting tools. + +Conor O'Riordan : Broken Power-Law mass profile. diff --git a/docs/general/credits.rst b/docs/general/credits.rst deleted file mode 100644 index b20418aac..000000000 --- a/docs/general/credits.rst +++ /dev/null @@ -1,35 +0,0 @@ -.. _credits: - - -Credits -------- - -**Developers**: - -`James Nightingale `_: Lead developer & PyAutoLens guru. - -`Richard Hayes `_: Lead developer & `PyAutoFit `_ guru. - -`Aristeidis Amvrosiadis `_: Interferometer Analysis. - -`Amy Etherington `_ : Magnification, Critical Curves and Caustic Calculations. - -Qiuhan He: NFW Profile Lensing Calculations. - -`Johnathan Frawley `_: Profiling, optimization and build server tools. - -`Ashley Kelly `_: Developer of `pyquad `_ for fast deflections computations. - -`Xiaoyue Cao `_: Analytic Ellipitcal Power-Law Deflection Angle Calculations. - -`Nan Li `_: Docker integration & support. - -**Code Donors**: - -`Andrew Robertson `_: Critical curve & caustic calculations. - -Mattia Negrello: Visibility models in the uv-plane via direct Fourier transforms. - -`Andrea Enia `_: Voronoi source-plane plotting tools. - -Conor O'Riordan : Broken Power-Law mass profile. diff --git a/docs/general/demagnified_solutions.md b/docs/general/demagnified_solutions.md new file mode 100644 index 000000000..edb83984e --- /dev/null +++ b/docs/general/demagnified_solutions.md @@ -0,0 +1,200 @@ +(demagnified-solutions)= + +# Demagnified Solutions + +## Overview + +When fitting a lens model using a pixelized source reconstruction, it is common for unphysical and inaccurate lens +models to be estimated. + +This is due to demagnified source reconstructions, where the source is reconstructed as the lensed source galaxy +(without any lensing): + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/data.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/model_image.png +:alt: Alternative text +:width: 400 +``` + +What has happened above is that the mass model has gone to an extremely low mass solution, such that essentially no +ray-tracing occurs. The best source reconstruction to fit the data is therefore one where the source is reconstructed +to look exactly like the observed lensed source. + +In fact, there are two variants of these unwanted systematic solutions, with the second variant corresponding to mass +models with **too much mass**, such that the ray-tracing inverts in on itself. + +The following schematic is from the paper Maresca et al 2021 () and illustrates +this beautifully: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/maresca_fig1.png +:alt: Alternative text +:width: 400 +``` + +The source reconstructions and model-fits of these solutions are also illustrated by Maresca et al 2021: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/maresca_fig2.png +:alt: Alternative text +:width: 400 +``` + +The demagnified solutions are not as high likelihood as the physical and accurate mass model shown in the central +row of the figure above. However, the demagnified solutions **occupy a much greater volume of non-linear parameter space**. + +This means that when we fit a lens model, it is highly probable that all solutions correspond to demagnified solutions, +such that the non-linear search converges on these solutions and never samples the accurate physical mass model. + +## Solution + +To prevent a non-linear search from inferring these unwanted solutions **PyAutoLens** penalizes the likelihood +via a position thresholding term. + +First, we specify the locations of the lensed source's multiple images, which the example code below does: + +```python +positions = al.Grid2DIrregular( + grid=[(0.4, 1.6), (1.58, -0.35), (-0.43, -1.59), (-1.45, 0.2)] +) +``` + +Here is where the multiple images appear for an example strong lens, where multiple images are drawn on with black +stars: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/lensed_source.png +:alt: Alternative text +:width: 400 +``` + +The `autolens_workspace` also includes a Graphical User Interface for drawing lensed source positions via +mouse click (). + +Next, we create `PositionsLH` object, which has an input `threshold`. + +This requires that a mass model traces the multiple image `positions` specified above within the `threshold` +value (e.g. 0.5") of one another in the source-plane. If this criteria is not met, a large penalty term is +applied to likelihood that massively reduces the overall likelihood. This penalty is larger if the `positions` +trace further from one another. + +This ensures the unphysical solutions that produce demagnified solutions have a much lower likelihood that the +physical solutions we desire. Furthermore, the penalty term reduces as the image-plane multiple image `positions` +trace closer in the source-plane, ensuring the non-linear search (e.g. Dynesty) converges towards an accurate mass +model. It does this very fast, as ray-tracing just a few multiple image positions is computationally cheap. + +If the `positions` do trace within the `threshold` no penalty is applied. + +The penalty term is created and passed to an `Analysis` object as follows: + +```python +positions_likelihood = al.PositionsLH(positions=positions, threshold=0.3) + +analysis = al.AnalysisImaging( + dataset=dataset, positions_likelihood_list=[positions_likelihood] +) +``` + +The threshold of 0.5" is large. For an accurate lens model we would anticipate the positions trace within < 0.01" of +one another. However, we only want the threshold to aid the non-linear with the choice of mass model in the initial fit +and remove demagnified solutions. + +## Auto Position Updates + +There are a number of downsides to having to input the multiple images positions manually: + +> - For large lens samples this could take a lot of time. +> - For complex sources, it can be unclear which brightness peaks in the image-plane lensed source correspond to the same emission in the source-plane. + +**PyAutoLens** allows the `positions` and `threshold` to be computed if a model for the lens mass is available. + +This is the case for lens modeling pipelines which use **PyAutoLens**'s search chaining functionality, because the +early fits in these pipelines fit a parametric source model which does not suffer these demagnified solutions. + +If we have a `result` from a previous search, which contains a mass model for the lens galaxy and a light model +for the source (the centre of which is used to compute the multiple image `positions`) we can compute a new +set of multiple image positions from this result: + +```python +result.image_plane_multiple_image_positions +``` + +We can also compute a `threshold` from the result, where this threshold value corresponds to the maximum separation +of the `result.image_plane_multiple_image_positions` computed above but ray traced to the source-plane using +the `result`'s maximum likelihood mass model. + +```python +result.positions_threshold_from(factor=2.0, minimum_threshold=0.3) +``` + +The `factor` input is a value that the computed `threshold` is multiplied by. For example, if a `threshold` of +0.1" is computed, the returned value above for `factor=2.0` will be 0.2". + +The `minimum_threshold` is the lowest number the function return will reutnr. Above, if a `threshold` of 0.1" +is computed, the function will return 0.3" because `minimum_threshold==0.3`. + +These inputs are useful when using function to set the `threshold` in a new fit of a search chaining pipeline, as +it allows us to make sure we do set too small a threshold that we remove genuinely physically mass models. + +For writing search chaining pipelines, a convenience method is available in the `result` which returns directly a +`PositionsLH` object: + +```python +result_1.positions_likelihood_from( + factor=3.0, minimum_threshold=0.2 +) +``` + +This is often used to set up new `Analysis` objects with a positions penalty concisely: + +```python +analysis = al.AnalysisImaging( + dataset=dataset, + positions_likelihood_list=[result_1.positions_likelihood_from( + factor=3.0, minimum_threshold=0.2 + )], +) +``` + +## Multiple Source Plane Systems + +A double source plane system is a lens system where there are multiple source-planes at different redshifts, meaning that +incuding the image-plane there are at least 3 planes. + +The `PositionsLH` class can have a `plane_redshift` input, which specifies the redshift of the source-plane +the positions are ray-traced to. + +Multiple `PositionsLH` objects can be passed to the `Analysis` object, which then applies the penalty term to +both source-planes independently such that a double source-plane system can be fitted with the penalty based likelihood +functionality. + +```python +positions_likelihood_source_plane_0 = al.PositionsLH(positions=positions, threshold=0.3, plane_redshift=1.0) +positions_likelihood_source_plane_1 = al.PositionsLH(positions=positions, threshold=0.3, plane_redshift=2.0) + +analysis = al.AnalysisImaging( + dataset=dataset, positions_likelihood_list= + [ + positions_likelihood_source_plane_0, + positions_likelihood_source_plane_1 + ] +) +``` + +To set up an `Analysis` object with multiple `PositionsLH` objects from a result, each positions likelihood is +computed from the result for each `plane_redshift`: + +``` +analysis = al.AnalysisImaging( + dataset=dataset, + positions_likelihood_list=[ + source_lp_result.positions_likelihood_from( + factor=3.0, minimum_threshold=0.2, plane_redshift=source_lp_result.instance.galaxies.source_1.redshift, + ), + source_lp_result.positions_likelihood_from( + factor=3.0, minimum_threshold=0.2, plane_redshift=source_lp_result.instance.galaxies.source_2.redshift, + ) + ], +) +``` diff --git a/docs/general/demagnified_solutions.rst b/docs/general/demagnified_solutions.rst deleted file mode 100644 index b9800a3fc..000000000 --- a/docs/general/demagnified_solutions.rst +++ /dev/null @@ -1,201 +0,0 @@ -.. _demagnified_solutions: - -Demagnified Solutions -===================== - -Overview --------- - -When fitting a lens model using a pixelized source reconstruction, it is common for unphysical and inaccurate lens -models to be estimated. - -This is due to demagnified source reconstructions, where the source is reconstructed as the lensed source galaxy -(without any lensing): - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/data.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/model_image.png - :width: 400 - :alt: Alternative text - -What has happened above is that the mass model has gone to an extremely low mass solution, such that essentially no -ray-tracing occurs. The best source reconstruction to fit the data is therefore one where the source is reconstructed -to look exactly like the observed lensed source. - -In fact, there are two variants of these unwanted systematic solutions, with the second variant corresponding to mass -models with **too much mass**, such that the ray-tracing inverts in on itself. - -The following schematic is from the paper Maresca et al 2021 (https://arxiv.org/abs/2012.04665) and illustrates -this beautifully: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/maresca_fig1.png - :width: 400 - :alt: Alternative text - -The source reconstructions and model-fits of these solutions are also illustrated by Maresca et al 2021: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/maresca_fig2.png - :width: 400 - :alt: Alternative text - -The demagnified solutions are not as high likelihood as the physical and accurate mass model shown in the central -row of the figure above. However, the demagnified solutions **occupy a much greater volume of non-linear parameter space**. - -This means that when we fit a lens model, it is highly probable that all solutions correspond to demagnified solutions, -such that the non-linear search converges on these solutions and never samples the accurate physical mass model. - -Solution --------- - -To prevent a non-linear search from inferring these unwanted solutions **PyAutoLens** penalizes the likelihood -via a position thresholding term. - -First, we specify the locations of the lensed source's multiple images, which the example code below does: - -.. code-block:: python - - positions = al.Grid2DIrregular( - grid=[(0.4, 1.6), (1.58, -0.35), (-0.43, -1.59), (-1.45, 0.2)] - ) - -Here is where the multiple images appear for an example strong lens, where multiple images are drawn on with black -stars: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/general/images/lensed_source.png - :width: 400 - :alt: Alternative text - -The ``autolens_workspace`` also includes a Graphical User Interface for drawing lensed source positions via -mouse click (https://github.com/Jammy2211/autolens_workspace/blob/release/scripts/imaging/preprocess/gui/positions.py). - -Next, we create ``PositionsLH`` object, which has an input ``threshold``. - -This requires that a mass model traces the multiple image ``positions`` specified above within the ``threshold`` -value (e.g. 0.5") of one another in the source-plane. If this criteria is not met, a large penalty term is -applied to likelihood that massively reduces the overall likelihood. This penalty is larger if the ``positions`` -trace further from one another. - -This ensures the unphysical solutions that produce demagnified solutions have a much lower likelihood that the -physical solutions we desire. Furthermore, the penalty term reduces as the image-plane multiple image ``positions`` -trace closer in the source-plane, ensuring the non-linear search (e.g. Dynesty) converges towards an accurate mass -model. It does this very fast, as ray-tracing just a few multiple image positions is computationally cheap. - -If the ``positions`` do trace within the ``threshold`` no penalty is applied. - -The penalty term is created and passed to an ``Analysis`` object as follows: - -.. code-block:: python - - positions_likelihood = al.PositionsLH(positions=positions, threshold=0.3) - - analysis = al.AnalysisImaging( - dataset=dataset, positions_likelihood_list=[positions_likelihood] - ) - -The threshold of 0.5" is large. For an accurate lens model we would anticipate the positions trace within < 0.01" of -one another. However, we only want the threshold to aid the non-linear with the choice of mass model in the initial fit -and remove demagnified solutions. - -Auto Position Updates ---------------------- - -There are a number of downsides to having to input the multiple images positions manually: - - - For large lens samples this could take a lot of time. - - - For complex sources, it can be unclear which brightness peaks in the image-plane lensed source correspond to the same emission in the source-plane. - -**PyAutoLens** allows the ``positions`` and ``threshold`` to be computed if a model for the lens mass is available. - -This is the case for lens modeling pipelines which use **PyAutoLens**'s search chaining functionality, because the -early fits in these pipelines fit a parametric source model which does not suffer these demagnified solutions. - -If we have a ``result`` from a previous search, which contains a mass model for the lens galaxy and a light model -for the source (the centre of which is used to compute the multiple image ``positions``) we can compute a new -set of multiple image positions from this result: - -.. code-block:: python - - result.image_plane_multiple_image_positions - -We can also compute a ``threshold`` from the result, where this threshold value corresponds to the maximum separation -of the ``result.image_plane_multiple_image_positions`` computed above but ray traced to the source-plane using -the ``result``'s maximum likelihood mass model. - -.. code-block:: python - - result.positions_threshold_from(factor=2.0, minimum_threshold=0.3) - -The ``factor`` input is a value that the computed ``threshold`` is multiplied by. For example, if a ``threshold`` of -0.1" is computed, the returned value above for ``factor=2.0`` will be 0.2". - -The ``minimum_threshold`` is the lowest number the function return will reutnr. Above, if a ``threshold`` of 0.1" -is computed, the function will return 0.3" because ``minimum_threshold==0.3``. - -These inputs are useful when using function to set the ``threshold`` in a new fit of a search chaining pipeline, as -it allows us to make sure we do set too small a threshold that we remove genuinely physically mass models. - -For writing search chaining pipelines, a convenience method is available in the ``result`` which returns directly a -``PositionsLH`` object: - -.. code-block:: python - - result_1.positions_likelihood_from( - factor=3.0, minimum_threshold=0.2 - ) - -This is often used to set up new ``Analysis`` objects with a positions penalty concisely: - -.. code-block:: python - - analysis = al.AnalysisImaging( - dataset=dataset, - positions_likelihood_list=[result_1.positions_likelihood_from( - factor=3.0, minimum_threshold=0.2 - )], - ) - -Multiple Source Plane Systems ------------------------------ - -A double source plane system is a lens system where there are multiple source-planes at different redshifts, meaning that -incuding the image-plane there are at least 3 planes. - -The ``PositionsLH`` class can have a `plane_redshift` input, which specifies the redshift of the source-plane -the positions are ray-traced to. - -Multiple ``PositionsLH`` objects can be passed to the ``Analysis`` object, which then applies the penalty term to -both source-planes independently such that a double source-plane system can be fitted with the penalty based likelihood -functionality. - -.. code-block:: python - - positions_likelihood_source_plane_0 = al.PositionsLH(positions=positions, threshold=0.3, plane_redshift=1.0) - positions_likelihood_source_plane_1 = al.PositionsLH(positions=positions, threshold=0.3, plane_redshift=2.0) - - analysis = al.AnalysisImaging( - dataset=dataset, positions_likelihood_list= - [ - positions_likelihood_source_plane_0, - positions_likelihood_source_plane_1 - ] - ) - -To set up an ``Analysis`` object with multiple ``PositionsLH`` objects from a result, each positions likelihood is -computed from the result for each ``plane_redshift``: - -.. code-block:: - - analysis = al.AnalysisImaging( - dataset=dataset, - positions_likelihood_list=[ - source_lp_result.positions_likelihood_from( - factor=3.0, minimum_threshold=0.2, plane_redshift=source_lp_result.instance.galaxies.source_1.redshift, - ), - source_lp_result.positions_likelihood_from( - factor=3.0, minimum_threshold=0.2, plane_redshift=source_lp_result.instance.galaxies.source_2.redshift, - ) - ], - ) \ No newline at end of file diff --git a/docs/general/likelihood_function.rst b/docs/general/likelihood_function.md similarity index 68% rename from docs/general/likelihood_function.rst rename to docs/general/likelihood_function.md index 6fbfd6d7e..847c8802d 100644 --- a/docs/general/likelihood_function.rst +++ b/docs/general/likelihood_function.md @@ -1,21 +1,20 @@ -.. _likelihood_function: - -Likelihood Function -=================== - -The ``autolens_workspace`` contains Jupyter notebooks describing the (log) likelihood functions used by **PyAutoLens**. - -The notebooks provide a step-by-step guide of how **PyAutoLens** fits strong lens data, with the aim to make -the analysis clear to readers without background experience in strong lens modeling and make the modeling less -of a "black box". - -We recommend that when writing a paper using **PyAutoLens** the author links to this GitHub repository when describing -their likelihood function. - -Links to every notebook are provided at the GitHub repository linked to below. We recommend authors link to this -GitHub repository (as opposed to direct links to each) because the URLs to notebooks on the ``autolens_workspace`` -may change after papers are published. - -By linking to this repository a permanent URL is provided. - -https://github.com/Jammy2211/autolens_likelihood_function \ No newline at end of file +(likelihood-function)= + +# Likelihood Function + +The `autolens_workspace` contains Jupyter notebooks describing the (log) likelihood functions used by **PyAutoLens**. + +The notebooks provide a step-by-step guide of how **PyAutoLens** fits strong lens data, with the aim to make +the analysis clear to readers without background experience in strong lens modeling and make the modeling less +of a "black box". + +We recommend that when writing a paper using **PyAutoLens** the author links to this GitHub repository when describing +their likelihood function. + +Links to every notebook are provided at the GitHub repository linked to below. We recommend authors link to this +GitHub repository (as opposed to direct links to each) because the URLs to notebooks on the `autolens_workspace` +may change after papers are published. + +By linking to this repository a permanent URL is provided. + + diff --git a/docs/general/model_cookbook.md b/docs/general/model_cookbook.md new file mode 100644 index 000000000..31f05aace --- /dev/null +++ b/docs/general/model_cookbook.md @@ -0,0 +1,416 @@ +(model-cookbook)= + +# Model Cookbook + +The model cookbook provides a concise reference to lens model composition tools, specifically the `Model` +and `Collection` objects. + +Examples using different **PyAutoLens** API’s for model composition are provided, which produce more concise and +readable code for different use-cases. + +## Simple Lens Model + +A simple lens model has a lens galaxy with a Sersic light profile, Isothermal mass profile and +source galaxy with a Sersic light profile: + +```python +# Lens: + +bulge = af.Model(al.lp.Sersic) +mass = af.Model(al.mp.Isothermal) + +lens = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + mass=mass, +) + +# Source: + +bulge = af.Model(al.lp.SersicCore) + +source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) + +# Overall Lens Model: + +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) +``` + +The redshifts in the above model are used to determine which galaxy is the lens and which is the source. + +The model `total_free_parameters` attribute which tells us the total number of free parameters (which are fitted for +via a non-linear search), which in this case is 19 (7 from the lens Sersic, 5 from the lens Isothermal and 7 from the +source Sersic). + +```python +print(f"Model Total Free Parameters = {model.total_free_parameters}") +``` + +If we print the `info` attribute of the model we get information on all of the parameters and their priors. + +```python +print(model.info) +``` + +This gives the following output: + +```bash +galaxies + lens + redshift 0.5 + bulge + centre + centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 + centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 + ell_comps + ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 + ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 + intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 + effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 + mass + centre + centre_0 GaussianPrior, mean = 0.0, sigma = 0.1 + centre_1 GaussianPrior, mean = 0.0, sigma = 0.1 + ell_comps + ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.3 + ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.3 + einstein_radius UniformPrior, lower_limit = 0.0, upper_limit = 8.0 + source + redshift 1.0 + disk + centre + centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 + centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 + ell_comps + ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 + ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 + intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 + effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 +``` + +## More Complex Lens Models + +The API above can be easily extended to compose lens models where each galaxy has multiple light or mass profiles: + +```python +# Lens: + +bulge = af.Model(al.lp.Sersic) +disk = af.Model(al.lp.Exponential) + +mass = af.Model(al.mp.Isothermal) +shear = af.Model(al.mp.ExternalShear) + +lens = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + disk=disk, + mass=mass, + shear=shear, +) + +# Source: + +bulge = af.Model(al.lp.SersicCore) +disk = af.Model(al.lp.Exponential) + +source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge, disk=disk) + +# Overall Lens Model: + +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) +``` + +The use of the words `bulge`, `disk`, `mass` and `shear` above are arbitrary. They can be replaced with any name you +like, e.g. `bulge_0`, `bulge_1`, `mass_0`, `mass_1`, and the model will still behave in the same way. + +The API can also be extended to compose lens models where there are multiple galaxies: + +```python +bulge = af.Model(al.lp.Sersic) +mass = af.Model(al.mp.Isothermal) + +lens_0 = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + mass=mass, +) + +bulge = af.Model(al.lp.Sersic) +mass = af.Model(al.mp.Isothermal) + +lens_1 = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + mass=mass, +) + +# Source 0: + +bulge = af.Model(al.lp.SersicCore) + +source_0 = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) + +# Source 1 : + +bulge = af.Model(al.lp.SersicCore) + +source_1 = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) + +# Overall Lens Model: + +model = af.Collection( + galaxies=af.Collection( + lens_0=lens_0, + lens_1=lens_1, + source_0=source_0, + source_1=source_1 + ) +) +``` + +The above lens model consists of only two planes (an image-plane and source-plane), but has four galaxies in total. +This is because the lens galaxies have the same redshift and the souece galaxies have the same redshift. + +If we gave one of the lens galaxies a different redshift, it would be included in a third plane, and the model would +perform multi-plane ray tracing when the model-fit is performed. + +## Concise API + +If a light or mass profile is passed directly to the `af.Model` of a galaxy, it is automatically assigned to be a +`af.Model` component of the galaxy. + +This means we can write the model above comprising multiple light and mass profiles more concisely as follows (also +removing the comments reading Lens / Source / Overall Lens Model to make the code more readable): + +```python +lens = af.Model( + al.Galaxy, + redshift=0.5, + bulge=al.lp.Sersic, + disk=al.lp.Sersic, + mass=al.mp.Isothermal, + shear=al.mp.ExternalShear, +) + +source = af.Model( + al.Galaxy, + redshift=1.0, + bulge=al.lp.SersicCore, + disk=al.lp.Exponential +) + +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) +``` + +## Prior Customization + +We can customize the priors of the lens model component individual parameters as follows: + +```python +# Lens: + +bulge = af.Model(al.lp.Sersic) +bulge.intensity = af.LogUniformPrior(lower_limit=1e-4, upper_limit=1e4) +bulge.sersic_index = af.GaussianPrior(mean=4.0, sigma=1.0, lower_limit=1.0, upper_limit=8.0) + +mass = af.Model(al.mp.Isothermal) +mass.centre.centre_0 = af.GaussianPrior(mean=0.0, sigma=0.1, lower_limit=-0.5, upper_limit=0.5) +mass.centre.centre_1 = af.GaussianPrior(mean=0.0, sigma=0.1, lower_limit=-0.5, upper_limit=0.5) +mass.einstein_radius = af.UniformPrior(lower_limit=0.0, upper_limit=8.0) + +lens = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + mass=mass, +) + +# Source + +bulge = af.Model(al.lp.Sersic) + +source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) +source.effective_radius = af.GaussianPrior(mean=0.1, sigma=0.05, lower_limit=0.0, upper_limit=1.0) + +# Overall Lens Model: + +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) +``` + +## Model Customization + +We can customize the lens model parameters in a number of different ways, as shown below: + +```python +# Lens: + +bulge = af.Model(al.lp.Sersic) +disk = af.Model(al.lp.Exponential) + +# Parameter Pairing: Pair the centre of the bulge and disk together, reducing +# the complexity of non-linear parameter space by N = 2 + +bulge.centre = disk.centre + +# Parameter Fixing: Fix the sersic_index of the bulge to a value of 4, reducing +# the complexity of non-linear parameter space by N = 1 + +bulge.sersic_index = 4.0 + +mass = af.Model(al.mp.Isothermal) + +# Parameter Offsets: Make the mass model centre parameters the same value as +# the bulge / disk but with an offset. + +mass.centre.centre_0 = bulge.centre.centre_0 + 0.1 +mass.centre.centre_1 = bulge.centre.centre_1 + 0.1 + +shear = af.Model(al.mp.ExternalShear) + +lens = af.Model( + al.Galaxy, + redshift=0.5, + bulge=bulge, + disk=disk, + mass=mass, + shear=shear, +) + +# Source: + +bulge = af.Model(al.lp.SersicCore) +disk = af.Model(al.lp.Exponential) + +source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge, disk=disk) + +# Overall Lens Model: + +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) + +# Assert that the effective radius of the bulge is larger than that of the disk. +# (Assertions can only be added at the end of model composition, after all components +# have been bright together in a `Collection`. +model.add_assertion(model.galaxies.lens.bulge.effective_radius > model.galaxies.lens.disk.effective_radius) + +# Assert that the Einstein Radius is below 3.0": +model.add_assertion(model.galaxies.lens.mass.einstein_radius < 3.0) +``` + +## Redshift Free + +The redshift of a galaxy can be treated as a free parameter in the model-fit by using the following API: + +```python +redshift = af.Model(al.Redshift) +redshift.redshift = af.UniformPrior(lower_limit=0.0, upper_limit=2.0) + +lens = af.Model( + al.Galaxy, + redshift=redshift, + mass=al.mp.Isothermal +) +``` + +The model-fit will automatically enable multi-plane ray tracing and alter the ordering of the planes depending on the +redshifts of the galaxies. + +NOTE: For strong lenses with just two planes (an image-plane and source-plane) the redshifts of the galaxies do not +impact the model-fit. You should therefore never make the redshifts free if you are only modeling a two-plane lens +system. This is because lensing calculations can be defined in arc-second coordinates, which do not change as a +function of redshift. + +Redshifts should be made free when modeling three or more planes, as the mulit-plane ray-tracing calculations have an +obvious dependence on the redshifts of the galaxies which could be inferred by the model-fit. + +## Available Model Components + +The light profiles, mass profiles and other components that can be used for lens modeling are given at the following +API documentation pages: + +> - +> - +> - + +## JSon Outputs + +After a model is composed, it can easily be output to a .json file on hard-disk in a readable structure: + +```python +import os +import json + +model_path = path.join("path", "to", "model", "json") + +os.makedirs(model_path, exist_ok=True) + +model_file = path.join(model_path, "model.json") + +with open(model_file, "w+") as f: + json.dump(model.dict(), f, indent=4) +``` + +We can load the model from its `.json` file. + +```python +model = af.Model.from_json(file=model_file) +``` + +This means in **PyAutoLens** one can write a model in a script, save it to hard disk and load it elsewhere, as well +as manually customize it in the .json file directory. + +This is used for composing complex models of group scale lenses. + +## Many Profile Models (Advanced) + +Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light +profiles. + +The following example notebooks show how to compose and fit these models: + + + + +## Model Linking (Advanced) + +When performing non-linear search chaining, the inferred model of one phase can be linked to the model. + +The following example notebooks show how to compose and fit these models: + + + +## Across Datasets (Advanced) + +When fitting multiple datasets, model can be composed where the same model component are used across the datasets +but certain parameters are free to vary across the datasets. + +The following example notebooks show how to compose and fit these models: + + + +## Relations (Advanced) + +We can compose models where the free parameter(s) vary according to a user-specified function +(e.g. y = mx +c -> intensity = (m * wavelength) + c across the datasets. + +The following example notebooks show how to compose and fit these models: + + + +## PyAutoFit API + +**PyAutoFit** is a general model composition library which offers even more ways to compose lens models not +detailed in this cookbook. + +The **PyAutoFit** model composition cookbooks detail this API in more detail: + + + + +## Wrap Up + +This cookbook shows how to compose simple lens models using the `af.Model()` and `af.Collection()` objects. diff --git a/docs/general/model_cookbook.rst b/docs/general/model_cookbook.rst deleted file mode 100644 index 873fc962c..000000000 --- a/docs/general/model_cookbook.rst +++ /dev/null @@ -1,432 +0,0 @@ -.. _model_cookbook: - -Model Cookbook -============== - -The model cookbook provides a concise reference to lens model composition tools, specifically the ``Model`` -and ``Collection`` objects. - -Examples using different **PyAutoLens** API’s for model composition are provided, which produce more concise and -readable code for different use-cases. - -Simple Lens Model ------------------ - -A simple lens model has a lens galaxy with a Sersic light profile, Isothermal mass profile and -source galaxy with a Sersic light profile: - -.. code-block:: python - - # Lens: - - bulge = af.Model(al.lp.Sersic) - mass = af.Model(al.mp.Isothermal) - - lens = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - mass=mass, - ) - - # Source: - - bulge = af.Model(al.lp.SersicCore) - - source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) - - # Overall Lens Model: - - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - -The redshifts in the above model are used to determine which galaxy is the lens and which is the source. - -The model ``total_free_parameters`` attribute which tells us the total number of free parameters (which are fitted for -via a non-linear search), which in this case is 19 (7 from the lens Sersic, 5 from the lens Isothermal and 7 from the -source Sersic). - -.. code-block:: python - - print(f"Model Total Free Parameters = {model.total_free_parameters}") - -If we print the ``info`` attribute of the model we get information on all of the parameters and their priors. - -.. code-block:: python - - print(model.info) - -This gives the following output: - -.. code-block:: bash - - galaxies - lens - redshift 0.5 - bulge - centre - centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 - centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 - ell_comps - ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 - ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 - intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 - effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 - mass - centre - centre_0 GaussianPrior, mean = 0.0, sigma = 0.1 - centre_1 GaussianPrior, mean = 0.0, sigma = 0.1 - ell_comps - ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.3 - ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.3 - einstein_radius UniformPrior, lower_limit = 0.0, upper_limit = 8.0 - source - redshift 1.0 - disk - centre - centre_0 GaussianPrior, mean = 0.0, sigma = 0.3 - centre_1 GaussianPrior, mean = 0.0, sigma = 0.3 - ell_comps - ell_comps_0 GaussianPrior, mean = 0.0, sigma = 0.5 - ell_comps_1 GaussianPrior, mean = 0.0, sigma = 0.5 - intensity LogUniformPrior, lower_limit = 1e-06, upper_limit = 1000000.0 - effective_radius UniformPrior, lower_limit = 0.0, upper_limit = 30.0 - -More Complex Lens Models ------------------------- - -The API above can be easily extended to compose lens models where each galaxy has multiple light or mass profiles: - -.. code-block:: python - - # Lens: - - bulge = af.Model(al.lp.Sersic) - disk = af.Model(al.lp.Exponential) - - mass = af.Model(al.mp.Isothermal) - shear = af.Model(al.mp.ExternalShear) - - lens = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - disk=disk, - mass=mass, - shear=shear, - ) - - # Source: - - bulge = af.Model(al.lp.SersicCore) - disk = af.Model(al.lp.Exponential) - - source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge, disk=disk) - - # Overall Lens Model: - - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - -The use of the words `bulge`, `disk`, `mass` and `shear` above are arbitrary. They can be replaced with any name you -like, e.g. `bulge_0`, `bulge_1`, `mass_0`, `mass_1`, and the model will still behave in the same way. - -The API can also be extended to compose lens models where there are multiple galaxies: - -.. code-block:: python - - bulge = af.Model(al.lp.Sersic) - mass = af.Model(al.mp.Isothermal) - - lens_0 = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - mass=mass, - ) - - bulge = af.Model(al.lp.Sersic) - mass = af.Model(al.mp.Isothermal) - - lens_1 = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - mass=mass, - ) - - # Source 0: - - bulge = af.Model(al.lp.SersicCore) - - source_0 = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) - - # Source 1 : - - bulge = af.Model(al.lp.SersicCore) - - source_1 = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) - - # Overall Lens Model: - - model = af.Collection( - galaxies=af.Collection( - lens_0=lens_0, - lens_1=lens_1, - source_0=source_0, - source_1=source_1 - ) - ) - -The above lens model consists of only two planes (an image-plane and source-plane), but has four galaxies in total. -This is because the lens galaxies have the same redshift and the souece galaxies have the same redshift. - -If we gave one of the lens galaxies a different redshift, it would be included in a third plane, and the model would -perform multi-plane ray tracing when the model-fit is performed. - -Concise API ------------ - -If a light or mass profile is passed directly to the `af.Model` of a galaxy, it is automatically assigned to be a -`af.Model` component of the galaxy. - -This means we can write the model above comprising multiple light and mass profiles more concisely as follows (also -removing the comments reading Lens / Source / Overall Lens Model to make the code more readable): - -.. code-block:: python - - lens = af.Model( - al.Galaxy, - redshift=0.5, - bulge=al.lp.Sersic, - disk=al.lp.Sersic, - mass=al.mp.Isothermal, - shear=al.mp.ExternalShear, - ) - - source = af.Model( - al.Galaxy, - redshift=1.0, - bulge=al.lp.SersicCore, - disk=al.lp.Exponential - ) - - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - - -Prior Customization -------------------- - -We can customize the priors of the lens model component individual parameters as follows: - -.. code-block:: python - - # Lens: - - bulge = af.Model(al.lp.Sersic) - bulge.intensity = af.LogUniformPrior(lower_limit=1e-4, upper_limit=1e4) - bulge.sersic_index = af.GaussianPrior(mean=4.0, sigma=1.0, lower_limit=1.0, upper_limit=8.0) - - mass = af.Model(al.mp.Isothermal) - mass.centre.centre_0 = af.GaussianPrior(mean=0.0, sigma=0.1, lower_limit=-0.5, upper_limit=0.5) - mass.centre.centre_1 = af.GaussianPrior(mean=0.0, sigma=0.1, lower_limit=-0.5, upper_limit=0.5) - mass.einstein_radius = af.UniformPrior(lower_limit=0.0, upper_limit=8.0) - - lens = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - mass=mass, - ) - - # Source - - bulge = af.Model(al.lp.Sersic) - - source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge) - source.effective_radius = af.GaussianPrior(mean=0.1, sigma=0.05, lower_limit=0.0, upper_limit=1.0) - - # Overall Lens Model: - - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - -Model Customization -------------------- - -We can customize the lens model parameters in a number of different ways, as shown below: - -.. code-block:: python - - # Lens: - - bulge = af.Model(al.lp.Sersic) - disk = af.Model(al.lp.Exponential) - - # Parameter Pairing: Pair the centre of the bulge and disk together, reducing - # the complexity of non-linear parameter space by N = 2 - - bulge.centre = disk.centre - - # Parameter Fixing: Fix the sersic_index of the bulge to a value of 4, reducing - # the complexity of non-linear parameter space by N = 1 - - bulge.sersic_index = 4.0 - - mass = af.Model(al.mp.Isothermal) - - # Parameter Offsets: Make the mass model centre parameters the same value as - # the bulge / disk but with an offset. - - mass.centre.centre_0 = bulge.centre.centre_0 + 0.1 - mass.centre.centre_1 = bulge.centre.centre_1 + 0.1 - - shear = af.Model(al.mp.ExternalShear) - - lens = af.Model( - al.Galaxy, - redshift=0.5, - bulge=bulge, - disk=disk, - mass=mass, - shear=shear, - ) - - # Source: - - bulge = af.Model(al.lp.SersicCore) - disk = af.Model(al.lp.Exponential) - - source = af.Model(al.Galaxy, redshift=1.0, bulge=bulge, disk=disk) - - # Overall Lens Model: - - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - - # Assert that the effective radius of the bulge is larger than that of the disk. - # (Assertions can only be added at the end of model composition, after all components - # have been bright together in a `Collection`. - model.add_assertion(model.galaxies.lens.bulge.effective_radius > model.galaxies.lens.disk.effective_radius) - - # Assert that the Einstein Radius is below 3.0": - model.add_assertion(model.galaxies.lens.mass.einstein_radius < 3.0) - -Redshift Free -------------- - -The redshift of a galaxy can be treated as a free parameter in the model-fit by using the following API: - -.. code-block:: python - - redshift = af.Model(al.Redshift) - redshift.redshift = af.UniformPrior(lower_limit=0.0, upper_limit=2.0) - - lens = af.Model( - al.Galaxy, - redshift=redshift, - mass=al.mp.Isothermal - ) - -The model-fit will automatically enable multi-plane ray tracing and alter the ordering of the planes depending on the -redshifts of the galaxies. - -NOTE: For strong lenses with just two planes (an image-plane and source-plane) the redshifts of the galaxies do not -impact the model-fit. You should therefore never make the redshifts free if you are only modeling a two-plane lens -system. This is because lensing calculations can be defined in arc-second coordinates, which do not change as a -function of redshift. - -Redshifts should be made free when modeling three or more planes, as the mulit-plane ray-tracing calculations have an -obvious dependence on the redshifts of the galaxies which could be inferred by the model-fit. - -Available Model Components --------------------------- - -The light profiles, mass profiles and other components that can be used for lens modeling are given at the following -API documentation pages: - - - https://pyautolens.readthedocs.io/en/latest/api/light.html - - https://pyautolens.readthedocs.io/en/latest/api/mass.html - - https://pyautolens.readthedocs.io/en/latest/api/pixelization.html - -JSon Outputs ------------- - -After a model is composed, it can easily be output to a .json file on hard-disk in a readable structure: - -.. code-block:: python - - import os - import json - - model_path = path.join("path", "to", "model", "json") - - os.makedirs(model_path, exist_ok=True) - - model_file = path.join(model_path, "model.json") - - with open(model_file, "w+") as f: - json.dump(model.dict(), f, indent=4) - -We can load the model from its ``.json`` file. - -.. code-block:: python - - model = af.Model.from_json(file=model_file) - -This means in **PyAutoLens** one can write a model in a script, save it to hard disk and load it elsewhere, as well -as manually customize it in the .json file directory. - -This is used for composing complex models of group scale lenses. - -Many Profile Models (Advanced) ------------------------------- - -Features such as the Multi Gaussian Expansion (MGE) and shapelets compose models consisting of 50 - 500+ light -profiles. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/modeling/imaging/features/multi_gaussian_expansion.ipynb -https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/modeling/imaging/features/shapelets.ipynb - -Model Linking (Advanced) ------------------------- - -When performing non-linear search chaining, the inferred model of one phase can be linked to the model. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/imaging/advanced/chaining/start_here.ipynb - -Across Datasets (Advanced) --------------------------- - -When fitting multiple datasets, model can be composed where the same model component are used across the datasets -but certain parameters are free to vary across the datasets. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/multi/modeling/start_here.ipynb - -Relations (Advanced) --------------------- - -We can compose models where the free parameter(s) vary according to a user-specified function -(e.g. y = mx +c -> intensity = (m * wavelength) + c across the datasets. - -The following example notebooks show how to compose and fit these models: - -https://github.com/Jammy2211/autolens_workspace/blob/release/notebooks/multi/modeling/features/wavelength_dependence.ipynb - -PyAutoFit API -------------- - -**PyAutoFit** is a general model composition library which offers even more ways to compose lens models not -detailed in this cookbook. - -The **PyAutoFit** model composition cookbooks detail this API in more detail: - -https://pyautofit.readthedocs.io/en/latest/cookbooks/model.html -https://pyautofit.readthedocs.io/en/latest/cookbooks/multi_level_model.html - -Wrap Up -------- - -This cookbook shows how to compose simple lens models using the ``af.Model()`` and ``af.Collection()`` objects. diff --git a/docs/general/papers.md b/docs/general/papers.md new file mode 100644 index 000000000..f397068b1 --- /dev/null +++ b/docs/general/papers.md @@ -0,0 +1,101 @@ +(papers)= + +# Papers + +The following papers use **PyAutoLens**: + +**Dark Matter** + +[A forward-modelling method to infer the dark matter particle mass from strong gravitational lenses](https://arxiv.org/abs/2010.13221) + +[Dark disk substructure and superfluid dark matter](https://arxiv.org/abs/1901.03694) + +[Galaxy-galaxy strong lens perturbations: line-of-sight haloes versus lens subhaloes](https://arxiv.org/abs/2110.04512) + +[Halo concentration strengthens dark matter constraints in galaxy–galaxy strong lensing analyses](https://arxiv.org/abs/2109.00018) + +[Novel Substructure & Superfluid Dark Matter](https://arxiv.org/abs/1901.03694) + +**Cosmology** + +[Kinematic cosmic dipole from a large sample of strong lenses](https://arxiv.org/abs/2603.11152) + +[Probing General Relativity in galactic scales at z ∼0.3](https://arxiv.org/abs/2212.08463) + +[Why weak lensing cluster shapes are insensitive to self-interacting dark matter](https://arxiv.org/abs/2210.13474) + +**Galaxy Formation & Evolution** + +[Two-dimensional kinematics and dynamical modelling of the 'Jackpot' gravitational lens from deep MUSE observations](https://arxiv.org/abs/2401.08771) + +[Beyond the bulge-halo conspiracy? Density profiles of Early-type galaxies from extended-source strong lensing](https://arxiv.org/abs/2207.04070) + +[Galaxy structure with strong gravitational lensing: decomposing the internal mass distribution of massive elliptical galaxies](https://arxiv.org/abs/1901.07801) + +[Microlensing and the type Ia supernova iPTF16geu](https://arxiv.org/abs/2112.04524) + +**Lens Modeling / Theory** + +[Spectroscopical Confirmation and Lens Modeling of a Complex Strong Lensing System Produced by a Close Galaxy Pair at z_d = 0.79](https://arxiv.org/abs/2603.12790) + +[Strong gravitational lensings external shear is not shear](https://arxiv.org/abs/2301.05244) + +[Automated galaxy-galaxy strong lens modelling: no lens left behind](https://arxiv.org/abs/2202.09201) + +[Systematic Errors Induced by the Elliptical Power-law model in Galaxy–Galaxy Strong Lens Modeling](https://arxiv.org/abs/2110.14554) + +[Testing strong lensing subhalo detection with a cosmological simulation](https://arxiv.org/abs/2202.10191) + +**Statistics / Machine Learning** + +[A machine learning based approach to gravitational lens identification with the International LOFAR Telescope](https://arxiv.org/abs/2207.10698) + +[Auto-identification of unphysical source reconstructions in strong gravitational lens modelling](https://arxiv.org/abs/2012.04665) + +[Decoding Dark Matter Substructure without Supervision](https://arxiv.org/abs/2008.12731) + +[Deep Learning the Morphology of Dark Matter Substructure](https://arxiv.org/abs/1909.07346) + +[Domain Adaptation for Simulation-Based Dark Matter Searches Using Strong Gravitational Lensing](https://arxiv.org/abs/2112.12121) + +[Likelihood-free MCMC with Amortized Approximate Likelihood Ratios](https://arxiv.org/abs/1903.04057) + +[On machine learning search for gravitational lenses](https://arxiv.org/abs/2104.01014) + +[Strong lens modelling: comparing and combining Bayesian neural networks and parametric profile fitting](https://arxiv.org/abs/2103.03257) + +[Streamlined Lensed Quasar Identification in Multiband Images via Ensemble Networks](https://arxiv.org/abs/2307.01090) + +**Source Science** + +[A Glimpse of the Stellar Populations and Elemental Abundances of Gravitationally Lensed, Quiescent Galaxies at z≳1 with Keck Deep Spectroscopy](https://arxiv.org/abs/2212.04731) + +[Discovery of a radio lobe in the Cloverleaf Quasar at z = 2.56](https://arxiv.org/abs/2212.07027) + +[ALMA [\{N} \{II}] 205 μm Imaging Spectroscopy of the Lensed Submillimeter Galaxy ID 141 at Redshift 4.24](https://arxiv.org/abs/2006.01147) + +[CO, H2O, H2O+ line & dust emission in a z = 3.63 strongly lensed starburst merger at sub-kiloparsec scales](https://arxiv.org/abs/1903.00273) + +[The molecular-gas properties in the gravitationally lensed merger HATLAS J142935.3-002836](https://arxiv.org/abs/1904.00307) + +[Modelling high-resolution ALMA observations of strongly lensed dusty star forming galaxies detected by Herschel](https://arxiv.org/abs/2111.09680) + +[ALMA resolves the first strongly-lensed Optical/NIR-dark galaxy](https://arxiv.org/abs/2207.00466) + +[The Two 𝑧 ∼ 13 Galaxy Candidates HD1 and HD2 Are Likely Not Lensed](https://arxiv.org/abs/2209.06830) + +[The Way of Water: ALMA resolves H2O emission lines in a strongly lensed dusty star-forming galaxy at z ∼ 3.1](https://arxiv.org/abs/2304.08563) + +[Characterisation of Herschel-selected strong lens candidates through HST and sub-mm/mm observations](https://arxiv.org/abs/2311.01158) + +**Surveys** + +[Gaia GraL X.: The GraL catalogue of gravitationally lensed quasars Matched with Gaia data, redshifts, and time delays](https://arxiv.org/abs/2603.12810) + +[When Spectral Modeling Meets Convolutional Networks: A Method for Discovering Reionization-era Lensed Quasars in Multi-band Imaging Data](https://arxiv.org/abs/2211.14543) + +[Modeling Strong Lenses from Wide-Field Ground-Based Observations in KiDS and GAMA](https://arxiv.org/abs/2301.05320) + +[MNELLS: The MUSE Nearby Early-Type Galaxy Lens Locator Survey](https://arxiv.org/abs/2002.07191) + +[Subaru FOCAS IFU observations of two z=0.12 strong-lensing elliptical galaxies from SDSS MaNGA](https://arxiv.org/abs/1911.06338) diff --git a/docs/general/papers.rst b/docs/general/papers.rst deleted file mode 100644 index 632d18b7d..000000000 --- a/docs/general/papers.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. _papers: - -Papers ------- - -The following papers use **PyAutoLens**: - -**Dark Matter** - -`A forward-modelling method to infer the dark matter particle mass from strong gravitational lenses `_ - -`Dark disk substructure and superfluid dark matter `_ - -`Galaxy-galaxy strong lens perturbations: line-of-sight haloes versus lens subhaloes `_ - -`Halo concentration strengthens dark matter constraints in galaxy–galaxy strong lensing analyses `_ - -`Novel Substructure & Superfluid Dark Matter `_ - -**Cosmology** - -`Kinematic cosmic dipole from a large sample of strong lenses `_ - -`Probing General Relativity in galactic scales at z ∼0.3 `_ - -`Why weak lensing cluster shapes are insensitive to self-interacting dark matter `_ - -**Galaxy Formation & Evolution** - -`Two-dimensional kinematics and dynamical modelling of the 'Jackpot' gravitational lens from deep MUSE observations `_ - -`Beyond the bulge-halo conspiracy? Density profiles of Early-type galaxies from extended-source strong lensing `_ - -`Galaxy structure with strong gravitational lensing: decomposing the internal mass distribution of massive elliptical galaxies `_ - -`Microlensing and the type Ia supernova iPTF16geu `_ - -**Lens Modeling / Theory** - -`Spectroscopical Confirmation and Lens Modeling of a Complex Strong Lensing System Produced by a Close Galaxy Pair at z_d = 0.79 `_ - -`Strong gravitational lensings external shear is not shear `_ - -`Automated galaxy-galaxy strong lens modelling: no lens left behind `_ - -`Systematic Errors Induced by the Elliptical Power-law model in Galaxy–Galaxy Strong Lens Modeling `_ - -`Testing strong lensing subhalo detection with a cosmological simulation `_ - -**Statistics / Machine Learning** - -`A machine learning based approach to gravitational lens identification with the International LOFAR Telescope `_ - -`Auto-identification of unphysical source reconstructions in strong gravitational lens modelling `_ - -`Decoding Dark Matter Substructure without Supervision `_ - -`Deep Learning the Morphology of Dark Matter Substructure `_ - -`Domain Adaptation for Simulation-Based Dark Matter Searches Using Strong Gravitational Lensing `_ - -`Likelihood-free MCMC with Amortized Approximate Likelihood Ratios `_ - -`On machine learning search for gravitational lenses `_ - -`Strong lens modelling: comparing and combining Bayesian neural networks and parametric profile fitting `_ - -`Streamlined Lensed Quasar Identification in Multiband Images via Ensemble Networks `_ - - -**Source Science** - -`A Glimpse of the Stellar Populations and Elemental Abundances of Gravitationally Lensed, Quiescent Galaxies at z≳1 with Keck Deep Spectroscopy `_ - -`Discovery of a radio lobe in the Cloverleaf Quasar at z = 2.56 `_ - -`ALMA [{N} {II}] 205 μm Imaging Spectroscopy of the Lensed Submillimeter Galaxy ID 141 at Redshift 4.24 `_ - -`CO, H2O, H2O+ line & dust emission in a z = 3.63 strongly lensed starburst merger at sub-kiloparsec scales `_ - -`The molecular-gas properties in the gravitationally lensed merger HATLAS J142935.3-002836 `_ - -`Modelling high-resolution ALMA observations of strongly lensed dusty star forming galaxies detected by Herschel `_ - -`ALMA resolves the first strongly-lensed Optical/NIR-dark galaxy `_ - -`The Two 𝑧 ∼ 13 Galaxy Candidates HD1 and HD2 Are Likely Not Lensed `_ - -`The Way of Water: ALMA resolves H2O emission lines in a strongly lensed dusty star-forming galaxy at z ∼ 3.1 `_ - -`Characterisation of Herschel-selected strong lens candidates through HST and sub-mm/mm observations `_ - -**Surveys** - -`Gaia GraL X.: The GraL catalogue of gravitationally lensed quasars Matched with Gaia data, redshifts, and time delays `_ - -`When Spectral Modeling Meets Convolutional Networks: A Method for Discovering Reionization-era Lensed Quasars in Multi-band Imaging Data `_ - -`Modeling Strong Lenses from Wide-Field Ground-Based Observations in KiDS and GAMA `_ - -`MNELLS: The MUSE Nearby Early-Type Galaxy Lens Locator Survey `_ - -`Subaru FOCAS IFU observations of two z=0.12 strong-lensing elliptical galaxies from SDSS MaNGA `_ - diff --git a/docs/general/workspace.md b/docs/general/workspace.md new file mode 100644 index 000000000..f18e2e231 --- /dev/null +++ b/docs/general/workspace.md @@ -0,0 +1,59 @@ +(workspace)= + +# Workspace Tour + +You should have downloaded and configured the [autolens workspace](https://github.com/Jammy2211/autolens_workspace) +when you installed **PyAutoLens**. If you didn't, checkout the +[installation instructions](https://pyautolens.readthedocs.io/en/latest/general/installation.html#installation-with-pip) +for how to downloaded and configure the workspace. + +The `README.rst` files distributed throughout the workspace describe every folder and file, and specify if +examples are for beginner or advanced users. + +New users should begin by checking out the following parts of the workspace. + +## Scripts / Notebooks + +There are numerous example describing how to perform lensing calculations, lens modeling, and many other +**PyAutoLens** features. All examples are provided as Python scripts and Jupyter notebooks. + +Descriptions of every configuration file and their input parameters are provided in the `README.rst` in +the [config directory of the workspace](https://github.com/Jammy2211/autolens_workspace/tree/release/config) + +## Config + +Here, you'll find the configuration files which customize: + +> - The default settings used by every non-linear search. +> - Visualization, including the backend used by *matplotlib*. +> - The priors and notation configs associated with the light and mass profiles used for lens modeling. +> - The behaviour of different (y,x) Cartesian grids used to perform lens calculations. +> - The general.yaml config which customizes other aspects of **PyAutoLens**. + +Checkout the [configuration](https://pyautolens.readthedocs.io/en/latest/general/installation.html#installation-with-pip) +section of the readthedocs for a complete description of every configuration file. + +## Dataset + +Contains the dataset's used to perform lens modeling. Example datasets using simulators included with the workspace +are included here by default. + +## Output + +The folder where modeling results are stored. + +## SLaM + +Advanced lens modeling pipelines that use the Source, Light and Mass (SLaM) approach to lens modeling. + +See [here](https://pyautolens.readthedocs.io/en/latest/advanced/slam.html) for an overview. + +## HowToLens + +The **HowToLens** lecture series is a collection of Jupyter notebooks describing how to build a **PyAutoLens** model +fitting project and giving illustrations of different statistical methods and techniques. It ships as a standalone +repository at [PyAutoLabs/HowToLens](https://github.com/PyAutoLabs/HowToLens) (separate from the workspace). + +Checkout the +[tutorials section](https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html) for a +full description of the lectures and online examples of every notebook. diff --git a/docs/general/workspace.rst b/docs/general/workspace.rst deleted file mode 100644 index d682863e6..000000000 --- a/docs/general/workspace.rst +++ /dev/null @@ -1,66 +0,0 @@ -.. _workspace: - -Workspace Tour -============== - -You should have downloaded and configured the `autolens workspace `_ -when you installed **PyAutoLens**. If you didn't, checkout the -`installation instructions `_ -for how to downloaded and configure the workspace. - -The ``README.rst`` files distributed throughout the workspace describe every folder and file, and specify if -examples are for beginner or advanced users. - -New users should begin by checking out the following parts of the workspace. - -Scripts / Notebooks -------------------- - -There are numerous example describing how to perform lensing calculations, lens modeling, and many other -**PyAutoLens** features. All examples are provided as Python scripts and Jupyter notebooks. - -Descriptions of every configuration file and their input parameters are provided in the ``README.rst`` in -the `config directory of the workspace `_ - -Config ------- - -Here, you'll find the configuration files which customize: - - - The default settings used by every non-linear search. - - Visualization, including the backend used by *matplotlib*. - - The priors and notation configs associated with the light and mass profiles used for lens modeling. - - The behaviour of different (y,x) Cartesian grids used to perform lens calculations. - - The general.yaml config which customizes other aspects of **PyAutoLens**. - -Checkout the `configuration `_ -section of the readthedocs for a complete description of every configuration file. - -Dataset -------- - -Contains the dataset's used to perform lens modeling. Example datasets using simulators included with the workspace -are included here by default. - -Output ------- - -The folder where modeling results are stored. - -SLaM ----- - -Advanced lens modeling pipelines that use the Source, Light and Mass (SLaM) approach to lens modeling. - -See `here `_ for an overview. - -HowToLens ---------- - -The **HowToLens** lecture series is a collection of Jupyter notebooks describing how to build a **PyAutoLens** model -fitting project and giving illustrations of different statistical methods and techniques. It ships as a standalone -repository at `PyAutoLabs/HowToLens `_ (separate from the workspace). - -Checkout the -`tutorials section `_ for a -full description of the lectures and online examples of every notebook. \ No newline at end of file diff --git a/docs/howtolens/chapter_1_introduction.md b/docs/howtolens/chapter_1_introduction.md new file mode 100644 index 000000000..538a07aa3 --- /dev/null +++ b/docs/howtolens/chapter_1_introduction.md @@ -0,0 +1,34 @@ +# Chapter 1: Strong Lensing + +In chapter 1, we introduce you to strong gravitational lensing and the core **PyAutoLens** API. + +**Colab** links to every tutorial are included. + +The chapter contains the following tutorials: + +[Tutorial 0: Visualization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb) +\- Setting up **PyAutoLens**'s visualization library. + +[Tutorial 1: Grids And Galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_1_grids_and_galaxies.ipynb) +\- Using grids of (y,x) coordinates with galaxies made up of light profiles. + +[Tutorial 2: Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb) +\- Using grids, galaxies and mass profiles to perform strong lens ray-tracing. + +[Tutorial 3: More Ray Tracing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_3_more_ray_tracing.ipynb) +\- Advanced strong lens ray-tracing. + +[Tutorial 4: Point Sources](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_4_point_sources.ipynb) +\- How lensing calculations when the source galaxy is a point-source (e.g. a quasar). + +[Tutorial 5: Lensing Formalism](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_5_lensing_formalism.ipynb) +\- The algebraic lensing formalism used to describe strong lensing. + +[Tutorial 6: Data](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_6_data.ipynb) +\- Loading and inspecting telescope imaging data of a strong lens. + +[Tutorial 7: Fitting](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_7_fitting.ipynb) +\- Fitting data with a strong lens model. + +[Tutorial 8: Summary](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_1_introduction/tutorial_8_summary.ipynb) +\- A summary of the chapter. diff --git a/docs/howtolens/chapter_1_introduction.rst b/docs/howtolens/chapter_1_introduction.rst deleted file mode 100644 index 687442223..000000000 --- a/docs/howtolens/chapter_1_introduction.rst +++ /dev/null @@ -1,35 +0,0 @@ -Chapter 1: Strong Lensing -========================= - -In chapter 1, we introduce you to strong gravitational lensing and the core **PyAutoLens** API. - -**Colab** links to every tutorial are included. - -The chapter contains the following tutorials: - -`Tutorial 0: Visualization `_ -- Setting up **PyAutoLens**'s visualization library. - -`Tutorial 1: Grids And Galaxies `_ -- Using grids of (y,x) coordinates with galaxies made up of light profiles. - -`Tutorial 2: Ray Tracing `_ -- Using grids, galaxies and mass profiles to perform strong lens ray-tracing. - -`Tutorial 3: More Ray Tracing `_ -- Advanced strong lens ray-tracing. - -`Tutorial 4: Point Sources `_ -- How lensing calculations when the source galaxy is a point-source (e.g. a quasar). - -`Tutorial 5: Lensing Formalism `_ -- The algebraic lensing formalism used to describe strong lensing. - -`Tutorial 6: Data `_ -- Loading and inspecting telescope imaging data of a strong lens. - -`Tutorial 7: Fitting `_ -- Fitting data with a strong lens model. - -`Tutorial 8: Summary `_ -- A summary of the chapter. \ No newline at end of file diff --git a/docs/howtolens/chapter_2_lens_modeling.md b/docs/howtolens/chapter_2_lens_modeling.md new file mode 100644 index 000000000..c38bc028a --- /dev/null +++ b/docs/howtolens/chapter_2_lens_modeling.md @@ -0,0 +1,29 @@ +# Chapter 2: Lens Modeling + +In chapter 2, we'll take you through how to model strong lenses using a non-linear search. + +The chapter contains the following tutorials: + +[Tutorial 1: Non-linear Search](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_1_non_linear_search.ipynb) +\- How a non-linear search is used to fit a lens model and the concepts of a parameter space and priors. + +[Tutorial 2: Practicalities](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_2_practicalities.ipynb) +\- Practicalities of performing model-fitting, like how to inspect the results on your hard-disk. + +[Tutorial 3: Realism and Complexity](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_3_realism_and_complexity.ipynb) +\- Finding a balance between realism and complexity when composing and fitting a lens model. + +[Tutorial 4: Dealing with Failure](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_4_dealing_with_failure.ipynb) +\- What to do when PyAutoLens finds an inaccurate lens model. + +[Tutorial 5: Linear Profiles](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_5_linear_profiles.ipynb) +\- Light profiles which capture complex morphologies in a reduced number of non-linear parameters. + +[Tutorial 6: Masking and Positions](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_6_masking_and_positions.ipynb) +\- How to mask and mark positions on your data to improve the lens model. + +[Tutorial 7: Results](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_7_results.ipynb) +\- Overview of the results available after successfully fitting a lens model. + +[Tutorial 8: Need for Speed](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_2_lens_modeling/tutorial_8_need_for_speed.ipynb) +\- How to fit complex models whilst balancing efficiency and run-time. diff --git a/docs/howtolens/chapter_2_lens_modeling.rst b/docs/howtolens/chapter_2_lens_modeling.rst deleted file mode 100644 index 78b91829b..000000000 --- a/docs/howtolens/chapter_2_lens_modeling.rst +++ /dev/null @@ -1,30 +0,0 @@ -Chapter 2: Lens Modeling -======================== - -In chapter 2, we'll take you through how to model strong lenses using a non-linear search. - -The chapter contains the following tutorials: - -`Tutorial 1: Non-linear Search `_ -- How a non-linear search is used to fit a lens model and the concepts of a parameter space and priors. - -`Tutorial 2: Practicalities `_ -- Practicalities of performing model-fitting, like how to inspect the results on your hard-disk. - -`Tutorial 3: Realism and Complexity `_ -- Finding a balance between realism and complexity when composing and fitting a lens model. - -`Tutorial 4: Dealing with Failure `_ -- What to do when PyAutoLens finds an inaccurate lens model. - -`Tutorial 5: Linear Profiles `_ -- Light profiles which capture complex morphologies in a reduced number of non-linear parameters. - -`Tutorial 6: Masking and Positions `_ -- How to mask and mark positions on your data to improve the lens model. - -`Tutorial 7: Results `_ -- Overview of the results available after successfully fitting a lens model. - -`Tutorial 8: Need for Speed `_ -- How to fit complex models whilst balancing efficiency and run-time. diff --git a/docs/howtolens/chapter_3_search_chaining.md b/docs/howtolens/chapter_3_search_chaining.md new file mode 100644 index 000000000..51ae4d77f --- /dev/null +++ b/docs/howtolens/chapter_3_search_chaining.md @@ -0,0 +1,24 @@ +# Chapter 3: Search Chaining + +In chapter 3, we introduce non-linear search chaining, whereby model-fits are chained together to enable efficient and +robust modeling of large strong lens samples. + +The chapter contains the following tutorials: + +[Tutorial 1: Search Chaining](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_1_search_chaining.ipynb) +\- Breaking the lens modeling procedure into a chained sequence of model-fits. + +[Tutorial 2: Prior Passing](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_2_prior_passing.ipynb) +\- How the results of earlier searches are passed to later searches. + +[Tutorial 3: Lens and Source](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_3_lens_and_source.ipynb) +\- Fitting the lens's light followed by its mass using chained searches. + +[Tutorial 4: Two Lens galaxies](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_4_x2_lens_galaxies.ipynb) +\- Modeling a strong lens with two lens galaxies using chained searches. + +[Tutorial 5: Complex Source](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_4_complex_source.ipynb) +\- Using multiple light profiles to fit a complex and irregular source using chained searches. + +[Tutorial 6: SLaM](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_3_search_chaining/tutorial_6_slam.ipynb) +\- Template pipelines for fitting lens model is standardized ways. diff --git a/docs/howtolens/chapter_3_search_chaining.rst b/docs/howtolens/chapter_3_search_chaining.rst deleted file mode 100644 index b896a12e2..000000000 --- a/docs/howtolens/chapter_3_search_chaining.rst +++ /dev/null @@ -1,25 +0,0 @@ -Chapter 3: Search Chaining -========================== - -In chapter 3, we introduce non-linear search chaining, whereby model-fits are chained together to enable efficient and -robust modeling of large strong lens samples. - -The chapter contains the following tutorials: - -`Tutorial 1: Search Chaining `_ -- Breaking the lens modeling procedure into a chained sequence of model-fits. - -`Tutorial 2: Prior Passing `_ -- How the results of earlier searches are passed to later searches. - -`Tutorial 3: Lens and Source `_ -- Fitting the lens's light followed by its mass using chained searches. - -`Tutorial 4: Two Lens galaxies `_ -- Modeling a strong lens with two lens galaxies using chained searches. - -`Tutorial 5: Complex Source `_ -- Using multiple light profiles to fit a complex and irregular source using chained searches. - -`Tutorial 6: SLaM `_ -- Template pipelines for fitting lens model is standardized ways. \ No newline at end of file diff --git a/docs/howtolens/chapter_4_pixelizations.md b/docs/howtolens/chapter_4_pixelizations.md new file mode 100644 index 000000000..f3d5c7e8b --- /dev/null +++ b/docs/howtolens/chapter_4_pixelizations.md @@ -0,0 +1,38 @@ +# Chapter 4: Pixelizations + +In chapter 4, we use **Pixelizations** to reconstruct complex source galaxies on pixelized grids. + +The chapter contains the following tutorials: + +[Tutorial 1: Pixelizations](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_1_pixelizations.ipynb) +\- Creating a pixel-grid in the source-plane. + +[Tutorial 2: Mappers](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_2_mappers.ipynb) +\- How a pixelization maps source-pixels to image-pixels. + +[Tutorial 3: Inversions](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_3_inversions.ipynb) +\- Inverting the mappings to reconstruct the source's light. + +[Tutorial 4: Bayesian Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_4_bayesian_regularization.ipynb) +\- Smoothing the source within a Bayesian framework. + +[Tutorial 5: Borders](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_5_borders.ipynb) +\- Preventing highly demagnified image-pixels ruining the inversion. + +[Tutorial 6: Lens Modeling](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_6_lens_modeling.ipynb) +\- How to use inversions to fit a lens model. + +[Tutorial 7: Adaptive Pixelization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_7_adaptive_pixelization.ipynb) +\- A Voronoi mesh which adapts to the mass model's magnification. + +[Tutorial 8: Model Fit](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_8_model_fit.ipynb) +\- An example lens modeling pipeline which uses an inversion. + +[Tutorial 9: Fit Problems](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_9_fit_problems.ipynb) +\- The shortcomings of our lens models and inversions. + +[Tutorial 10: Brightness Adaption](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_10_brightness_adaption.ipynb) +\- Adapting the pixelization to the source's morphology. + +[Tutorial 11: Adaptive Regularization](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_4_pixelizations/tutorial_11_adapt_regularization.py.ipynb) +\- Adapting the regularization to the source's morphology. diff --git a/docs/howtolens/chapter_4_pixelizations.rst b/docs/howtolens/chapter_4_pixelizations.rst deleted file mode 100644 index 6ab734440..000000000 --- a/docs/howtolens/chapter_4_pixelizations.rst +++ /dev/null @@ -1,39 +0,0 @@ -Chapter 4: Pixelizations -======================== - -In chapter 4, we use **Pixelizations** to reconstruct complex source galaxies on pixelized grids. - -The chapter contains the following tutorials: - -`Tutorial 1: Pixelizations `_ -- Creating a pixel-grid in the source-plane. - -`Tutorial 2: Mappers `_ -- How a pixelization maps source-pixels to image-pixels. - -`Tutorial 3: Inversions `_ -- Inverting the mappings to reconstruct the source's light. - -`Tutorial 4: Bayesian Regularization `_ -- Smoothing the source within a Bayesian framework. - -`Tutorial 5: Borders `_ -- Preventing highly demagnified image-pixels ruining the inversion. - -`Tutorial 6: Lens Modeling `_ -- How to use inversions to fit a lens model. - -`Tutorial 7: Adaptive Pixelization `_ -- A Voronoi mesh which adapts to the mass model's magnification. - -`Tutorial 8: Model Fit `_ -- An example lens modeling pipeline which uses an inversion. - -`Tutorial 9: Fit Problems `_ -- The shortcomings of our lens models and inversions. - -`Tutorial 10: Brightness Adaption `_ -- Adapting the pixelization to the source's morphology. - -`Tutorial 11: Adaptive Regularization `_ -- Adapting the regularization to the source's morphology. \ No newline at end of file diff --git a/docs/howtolens/chapter_optional.md b/docs/howtolens/chapter_optional.md new file mode 100644 index 000000000..2dc7d8632 --- /dev/null +++ b/docs/howtolens/chapter_optional.md @@ -0,0 +1,11 @@ +# Chapter: Optional + +This chapter contains optional tutorials expanding on different aspects of how **PyAutoLens** work. + +The chapter contains the following tutorials: + +[Tutorial: Sub-grids](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_optional/tutorial_sub_grids.ipynb) +\- Use sub-grids to perform more accuratee and precise lensing calculations. + +[Tutorial: Searches](https://colab.research.google.com/github/PyAutoLabs/HowToLens/blob/2026.4.13.6/notebooks/chapter_optional/tutorial_searches.ipynb) +\- Alternative non-linear searches to sample parameter space. diff --git a/docs/howtolens/chapter_optional.rst b/docs/howtolens/chapter_optional.rst deleted file mode 100644 index 64b722b2b..000000000 --- a/docs/howtolens/chapter_optional.rst +++ /dev/null @@ -1,13 +0,0 @@ -Chapter: Optional -================= - -This chapter contains optional tutorials expanding on different aspects of how **PyAutoLens** work. - -The chapter contains the following tutorials: - -`Tutorial: Sub-grids `_ -- Use sub-grids to perform more accuratee and precise lensing calculations. - -`Tutorial: Searches `_ -- Alternative non-linear searches to sample parameter space. - diff --git a/docs/howtolens/howtolens.rst b/docs/howtolens/howtolens.md similarity index 78% rename from docs/howtolens/howtolens.rst rename to docs/howtolens/howtolens.md index 310f7f92d..53a4ca213 100644 --- a/docs/howtolens/howtolens.rst +++ b/docs/howtolens/howtolens.md @@ -1,75 +1,69 @@ -.. _howtolens: - -HowToLens Lectures -================== - -The best way to learn **PyAutoLens** is by going through the **HowToLens** lecture series, which lives in its own -repository at `PyAutoLabs/HowToLens `_. - -The lectures are provided as Jupyter notebooks (and Python scripts), and they are linked to via this readthedocs. The -lectures are composed of five chapters - -- **Introduction** - An introduction to strong gravitational lensing and **PyAutolens**. -- **Lens Modeling** - How to model strong lenses, including a primer on Bayesian non-linear analysis. -- **Search Chaining** - How to fit complex lens models using non-linear search chaining. -- **Pixelizations** - How to perform pixelized reconstructions of the source-galaxy. - -How to Tackle HowToLens ------------------------ - -The HowToLens lecture series currently sits at 5 chapters, and each will take around 3-6 hours to go through thoroughly. -You probably want to be modeling lenses faster than that! Furthermore, the concepts in the -later chapters are pretty challenging, and familiarity and lens modeling is desirable before you -tackle them. - -Therefore, we recommend that you complete chapters 1 & 2 and then apply what you've learnt to the modeling of simulated -and real strong lenses imaging, using the scripts found in the -`autolens_workspace `_ ``modeling`` packages. Once you're -confident with your use of **PyAutoLens**, you can then begin to cover the advanced functionality covered in chapters -3, 4 & 5. - -Lensing Theory --------------- - -**HowToLens** assumes minimal previous knowledge of gravitational lensing and astronomy. However, it is beneficial to -give yourself a basic theoretical grounding as you go through the lectures. I heartily recommend you have open the -lecture course on gravitational lensing by Massimo Meneghetti below as you go through the tutorials, and refer to it -for anything that isn't clear in **HowToLens**. - -http://www.ita.uni-heidelberg.de/~massimo/sub/Lectures/gl_all.pdf - -Visualization -------------- - -Before beginning the **HowToLens** lecture series, in chapter 1 you should do 'tutorial_0_visualization'. This will -take you through how **PyAutoLens** interfaces with matplotlib to perform visualization and will get you setup such -that images and figures display correctly in your Jupyter notebooks. - -Jupyter Notebooks ------------------ - -The tutorials are supplied as Jupyter Notebooks, which come with a '.ipynb' suffix. For those new to Python, Jupyter -Notebooks are a different way to write, view and use Python code. Compared to the traditional Python scripts, they allow: - -- Small blocks of code to be viewed and run at a time -- Images and visualization from a code to be displayed directly underneath it. -- Text script to appear between the blocks of code. - -This makes them an ideal way for us to present the HowToFit lecture series, therefore I recommend you get yourself -a Jupyter notebook viewer (https://jupyter.org/) if you haven't done so already. - -If you *really* want to use Python scripts, all tutorials are also supplied as ``.py`` files in the ``scripts`` folder -of the `HowToLens repository `_. - -Code Style and Formatting -------------------------- - -You may notice the style and formatting of our Python code looks different to what you are used to. For example, it -is common for brackets to be placed on their own line at the end of function calls, the inputs of a function or -class may be listed over many separate lines and the code in general takes up a lot more space then you are used to. - -This is intentional, because we believe it makes the cleanest, most readable code possible. In fact, lots of people do, -which is why we use an auto-formatter to produce the code in a standardized format. If you're interested in the style -and would like to adapt it to your own code, check out the Python auto-code formatter 'black'. - -https://github.com/python/black +(howtolens)= + +# HowToLens Lectures + +The best way to learn **PyAutoLens** is by going through the **HowToLens** lecture series, which lives in its own +repository at [PyAutoLabs/HowToLens](https://github.com/PyAutoLabs/HowToLens). + +The lectures are provided as Jupyter notebooks (and Python scripts), and they are linked to via this readthedocs. The +lectures are composed of five chapters + +- **Introduction** - An introduction to strong gravitational lensing and **PyAutolens**. +- **Lens Modeling** - How to model strong lenses, including a primer on Bayesian non-linear analysis. +- **Search Chaining** - How to fit complex lens models using non-linear search chaining. +- **Pixelizations** - How to perform pixelized reconstructions of the source-galaxy. + +## How to Tackle HowToLens + +The HowToLens lecture series currently sits at 5 chapters, and each will take around 3-6 hours to go through thoroughly. +You probably want to be modeling lenses faster than that! Furthermore, the concepts in the +later chapters are pretty challenging, and familiarity and lens modeling is desirable before you +tackle them. + +Therefore, we recommend that you complete chapters 1 & 2 and then apply what you've learnt to the modeling of simulated +and real strong lenses imaging, using the scripts found in the +[autolens_workspace](https://github.com/PyAutoLabs/autolens_workspace) `modeling` packages. Once you're +confident with your use of **PyAutoLens**, you can then begin to cover the advanced functionality covered in chapters +3, 4 & 5. + +## Lensing Theory + +**HowToLens** assumes minimal previous knowledge of gravitational lensing and astronomy. However, it is beneficial to +give yourself a basic theoretical grounding as you go through the lectures. I heartily recommend you have open the +lecture course on gravitational lensing by Massimo Meneghetti below as you go through the tutorials, and refer to it +for anything that isn't clear in **HowToLens**. + + + +## Visualization + +Before beginning the **HowToLens** lecture series, in chapter 1 you should do 'tutorial_0_visualization'. This will +take you through how **PyAutoLens** interfaces with matplotlib to perform visualization and will get you setup such +that images and figures display correctly in your Jupyter notebooks. + +## Jupyter Notebooks + +The tutorials are supplied as Jupyter Notebooks, which come with a '.ipynb' suffix. For those new to Python, Jupyter +Notebooks are a different way to write, view and use Python code. Compared to the traditional Python scripts, they allow: + +- Small blocks of code to be viewed and run at a time +- Images and visualization from a code to be displayed directly underneath it. +- Text script to appear between the blocks of code. + +This makes them an ideal way for us to present the HowToFit lecture series, therefore I recommend you get yourself +a Jupyter notebook viewer () if you haven't done so already. + +If you *really* want to use Python scripts, all tutorials are also supplied as `.py` files in the `scripts` folder +of the [HowToLens repository](https://github.com/PyAutoLabs/HowToLens). + +## Code Style and Formatting + +You may notice the style and formatting of our Python code looks different to what you are used to. For example, it +is common for brackets to be placed on their own line at the end of function calls, the inputs of a function or +class may be listed over many separate lines and the code in general takes up a lot more space then you are used to. + +This is intentional, because we believe it makes the cleanest, most readable code possible. In fact, lots of people do, +which is why we use an auto-formatter to produce the code in a standardized format. If you're interested in the style +and would like to adapt it to your own code, check out the Python auto-code formatter 'black'. + + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..cc88ea83f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,266 @@ +```{image} https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true +:width: 900 +``` + +# What is PyAutoLens? + +When two or more galaxies are aligned perfectly down our line-of-sight, the background galaxy appears multiple times. + +This is called strong gravitational lensing and **PyAutoLens** makes it simple to model strong gravitational lenses, using JAX to **accelerate lens modeling on GPUs**. + +# Getting Started + +The following links are useful for new starters: + +- [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.4.13.6/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. + +# 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 +intervening mass of one or more foreground galaxies. Sometimes its light is fully deflected around the foreground galaxies, +traversing multiple paths to the Earth, meaning that the background galaxy is observed multiple times. This alignment +of galaxies is called a strong gravitational lens, an example of which, SLACS1430+4105, is shown in the image +below. The massive elliptical lens galaxy can be seen in the centre of the left panel, surrounded by a multiply +imaged source galaxy whose light has been distorted into an 'Einstein ring'. The central and right panels shows +reconstructions of the source's lensed and unlensed light distributions, which are created using a model of the lens +galaxy's mass to trace backwards how the source's light is gravitationally lensed. + +```{image} https://github.com/Jammy2211/PyAutoLens/blob/main/files/imageaxis.png?raw=true +``` + +Strong lensing provides astronomers with an invaluable tool to study a diverse range of topics, including the +[structure of galaxies](https://academic.oup.com/mnras/article-abstract/489/2/2049/5550746), +[dark matter](https://academic.oup.com/mnras/article/442/3/2017/1048278) and the +[expansion of the Universe](https://academic.oup.com/mnras/article/468/3/2590/3055701). + +The past decade has seen the discovery of many hundreds of new strong lenses, however the modeling of a strong lens is +historically a time-intensive process that requires significant human intervention to perform, restricting the scope of +any scientific analysis. In the next decade of order of `one hundred thousand` strong lenses will be discovered by +surveys such as Euclid, the Vera Rubin Observatory and Square Kilometer Array. + +The goal of **PyAutoLens** is to enable fully automated strong lens analysis, such that these large samples of strong +lenses can be exploited to their fullest. + +# How does PyAutoLens Work? + +A strong lens system can be quickly assembled from abstracted objects. A `Galaxy` object contains one or +more `LightProfile`'s and `MassProfile`'s, which represent its two dimensional distribution of starlight and mass. +`Galaxy`’s lie at a particular distance (redshift) from the observer, and are grouped into planes. Ray tracing +through multiple planess is achieved by passing them to a `Tracer` with an `astropy` Cosmology. By passing +these objects a `Grid2D` strong lens sightlines are computed, including multi-plane ray-tracing. All of these +objects are extensible, making it straightforward to compose highly customized lensing system. The example code +below shows this in action: + +```python +import autolens as al +import autolens.plot as aplt +from astropy import cosmology as cosmo + +""" +To describe the deflection of light by mass, two-dimensional grids of (y,x) Cartesian +coordinates are used. +""" +grid = al.Grid2D.uniform( + shape_native=(50, 50), + pixel_scales=0.05, # <- Conversion from pixel units to arc-seconds. +) + +""" +The lens galaxy has an elliptical isothermal mass profile and is at redshift 0.5. +""" +mass = al.mp.Isothermal( + centre=(0.0, 0.0), + ell_comps=(0.1, 0.05), + einstein_radius=1.6 +) + +lens_galaxy = al.Galaxy(redshift=0.5, mass=mass) + +""" +The source galaxy has an elliptical exponential light profile and is at redshift 1.0. +""" +disk = al.lp.Exponential( + centre=(0.3, 0.2), + ell_comps=(0.05, 0.25), + intensity=0.05, + effective_radius=0.5, +) + +source_galaxy = al.Galaxy(redshift=1.0, disk=disk) + +""" +We create the strong lens using a Tracer, which uses the galaxies, their redshifts +and an input cosmology to determine how light is deflected on its path to Earth. +""" +tracer = al.Tracer( + galaxies=[lens_galaxy, source_galaxy], + cosmology = al.cosmo.Planck15() +) + +""" +We can use the Grid2D and Tracer to perform many lensing calculations, for example +plotting the image of the lensed source. +""" +tracer_plotter = aplt.Tracer(tracer=tracer, grid=grid) +tracer_plotter.figures_2d(image=True) +``` + +To perform lens modeling, **PyAutoLens** adopts the probabilistic programming +language [PyAutoFit](https://github.com/rhayes777/PyAutoFit). **PyAutoFit** allows users to compose a +lens model from `LightProfile`, `MassProfile` and `Galaxy` objects, customize the model parameterization and +fit it to data via a non-linear search (e.g. [dynesty](https://github.com/joshspeagle/dynesty), +[emcee](https://github.com/dfm/emcee) or [PySwarms](https://pyswarms.readthedocs.io/en/latest/)). The example +code below shows how to setup and fit a lens model to a dataset: + +```python +import autofit as af +import autolens as al +import autolens.plot as aplt + +""" +Load Imaging data of the strong lens from the dataset folder of the workspace. +""" +dataset = al.Imaging.from_fits( + data_path="/path/to/dataset/image.fits", + noise_map_path="/path/to/dataset/noise_map.fits", + psf_path="/path/to/dataset/psf.fits", + pixel_scales=0.1, +) + +""" +Create a mask for the imaging data, which we setup as a 3.0" circle, and apply it. +""" +mask = al.Mask2D.circular( + shape_native=dataset.shape_native, + pixel_scales=dataset.pixel_scales, + radius=3.0 +) +dataset = dataset.apply_mask(mask=mask) + +""" +We model the lens galaxy using an elliptical isothermal mass profile and +the source galaxy using an elliptical sersic light profile. + +To setup these profiles as model components whose parameters are free & fitted for +we set up each Galaxy as a `Model` and define the model as a `Collection` of all galaxies. +""" +# Lens: + +mass = af.Model(al.mp.Isothermal) +lens = af.Model(al.Galaxy, redshift=0.5, mass=lens_mass_profile) + +# Source: + +disk = af.Model(al.lp.SersicCore) +source = af.Model(al.Galaxy, redshift=1.0, disk=disk) + +# Overall Lens Model: +model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) + +""" +We define the non-linear search used to fit the model to the data (in this case, Dynesty). +""" +search = af.Nautilus(name="search[example]", n_live=50) + +""" +We next set up the `Analysis`, which contains the `log likelihood function` that the +non-linear search calls to fit the lens model to the data. +""" +analysis = al.AnalysisImaging(dataset=dataset) + +""" +To perform the model-fit we pass the model and analysis to the search's fit method. This will +output results (e.g., dynesty samples, model parameters, visualization) to hard-disk. +""" +result = search.fit(model=model, analysis=analysis) + +""" +The results contain information on the fit, for example the maximum likelihood +model from the Dynesty parameter space search. +""" +print(result.samples.max_log_likelihood()) +``` + +# Getting Started + +To get started, users can check-out the **PyAutoLens**'s rich feature-set by going through the `overview` section +of our readthedocs. This illustrates the API for all of **PyAutoLens**'s core features, including how to simulate +strong lens datasets, reconstructing the lensed source galaxy on adaptive pixel-grids and fitting interferometer +datasets. + +For new **PyAutoLens** users, we recommend they start by +[installing PyAutoLens](https://pyautolens.readthedocs.io/en/latest/installation/overview.html) (if you haven't +already!), read through the `start_here.ipynb` notebook on +the [autolens_workspace](https://github.com/Jammy2211/autolens_workspace) and take the +[HowToLens Jupyter notebook lecture series](https://pyautolens.readthedocs.io/en/latest/howtolens/howtolens.html) on +strong gravitational lensing. + +```{toctree} +:caption: 'Overview:' +:hidden: true +:maxdepth: 1 + +overview/overview_1_start_here +overview/overview_2_new_user_guide +overview/overview_3_features +``` + +```{toctree} +:caption: 'Installation:' +:hidden: true +:maxdepth: 1 + +installation/overview +installation/conda +installation/pip +installation/source +installation/troubleshooting +``` + +```{toctree} +:caption: 'General:' +:hidden: true +:maxdepth: 1 + +general/workspace +general/configs +general/model_cookbook +general/likelihood_function +general/demagnified_solutions +general/citations +general/papers +general/credits +``` + +```{toctree} +:caption: 'Tutorials:' +:hidden: true +:maxdepth: 1 + +howtolens/howtolens +howtolens/chapter_1_introduction +howtolens/chapter_2_lens_modeling +howtolens/chapter_3_search_chaining +howtolens/chapter_4_pixelizations +howtolens/chapter_optional +``` + +```{toctree} +:caption: 'API Reference:' +:hidden: true +:maxdepth: 1 + +api/data +api/light +api/mass +api/galaxy +api/fitting +api/modeling +api/pixelization +api/point +api/plot +api/source +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 344cbf29d..000000000 --- a/docs/index.rst +++ /dev/null @@ -1,269 +0,0 @@ -.. image:: https://github.com/Jammy2211/PyAutoLogo/blob/main/gifs/pyautolens.gif?raw=true - :width: 900 - - -What is PyAutoLens? -=================== - -When two or more galaxies are aligned perfectly down our line-of-sight, the background galaxy appears multiple times. - -This is called strong gravitational lensing and **PyAutoLens** makes it simple to model strong gravitational lenses, using JAX to **accelerate lens modeling on GPUs**. - -Getting Started -=============== - -The following links are useful for new starters: - -- `The PyAutoLens readthedocs `_: which includes `an overview of PyAutoLens's core features `_, `a new user starting guide `_ and `an installation guide `_. - -- `The introduction Jupyter Notebook on Colab `_, where you can try **PyAutoLens** in a web browser (without installation). - -- `The autolens_workspace GitHub repository `_, which includes example scripts covering every **PyAutoLens** use case. - -- `The HowToLens GitHub repository `_: a Jupyter notebook lecture series teaching strong lensing and lens modeling from the ground up. - -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 -intervening mass of one or more foreground galaxies. Sometimes its light is fully deflected around the foreground galaxies, -traversing multiple paths to the Earth, meaning that the background galaxy is observed multiple times. This alignment -of galaxies is called a strong gravitational lens, an example of which, SLACS1430+4105, is shown in the image -below. The massive elliptical lens galaxy can be seen in the centre of the left panel, surrounded by a multiply -imaged source galaxy whose light has been distorted into an 'Einstein ring'. The central and right panels shows -reconstructions of the source's lensed and unlensed light distributions, which are created using a model of the lens -galaxy's mass to trace backwards how the source's light is gravitationally lensed. - -.. image:: https://github.com/Jammy2211/PyAutoLens/blob/main/files/imageaxis.png?raw=true - -Strong lensing provides astronomers with an invaluable tool to study a diverse range of topics, including the -`structure of galaxies `_, -`dark matter `_ and the -`expansion of the Universe `_. - -The past decade has seen the discovery of many hundreds of new strong lenses, however the modeling of a strong lens is -historically a time-intensive process that requires significant human intervention to perform, restricting the scope of -any scientific analysis. In the next decade of order of `one hundred thousand` strong lenses will be discovered by -surveys such as Euclid, the Vera Rubin Observatory and Square Kilometer Array. - -The goal of **PyAutoLens** is to enable fully automated strong lens analysis, such that these large samples of strong -lenses can be exploited to their fullest. - -How does PyAutoLens Work? -========================= - -A strong lens system can be quickly assembled from abstracted objects. A ``Galaxy`` object contains one or -more ``LightProfile``'s and ``MassProfile``'s, which represent its two dimensional distribution of starlight and mass. -``Galaxy``’s lie at a particular distance (redshift) from the observer, and are grouped into planes. Ray tracing -through multiple planess is achieved by passing them to a ``Tracer`` with an ``astropy`` Cosmology. By passing -these objects a ``Grid2D`` strong lens sightlines are computed, including multi-plane ray-tracing. All of these -objects are extensible, making it straightforward to compose highly customized lensing system. The example code -below shows this in action: - -.. code-block:: python - - import autolens as al - import autolens.plot as aplt - from astropy import cosmology as cosmo - - """ - To describe the deflection of light by mass, two-dimensional grids of (y,x) Cartesian - coordinates are used. - """ - grid = al.Grid2D.uniform( - shape_native=(50, 50), - pixel_scales=0.05, # <- Conversion from pixel units to arc-seconds. - ) - - """ - The lens galaxy has an elliptical isothermal mass profile and is at redshift 0.5. - """ - mass = al.mp.Isothermal( - centre=(0.0, 0.0), - ell_comps=(0.1, 0.05), - einstein_radius=1.6 - ) - - lens_galaxy = al.Galaxy(redshift=0.5, mass=mass) - - """ - The source galaxy has an elliptical exponential light profile and is at redshift 1.0. - """ - disk = al.lp.Exponential( - centre=(0.3, 0.2), - ell_comps=(0.05, 0.25), - intensity=0.05, - effective_radius=0.5, - ) - - source_galaxy = al.Galaxy(redshift=1.0, disk=disk) - - """ - We create the strong lens using a Tracer, which uses the galaxies, their redshifts - and an input cosmology to determine how light is deflected on its path to Earth. - """ - tracer = al.Tracer( - galaxies=[lens_galaxy, source_galaxy], - cosmology = al.cosmo.Planck15() - ) - - """ - We can use the Grid2D and Tracer to perform many lensing calculations, for example - plotting the image of the lensed source. - """ - tracer_plotter = aplt.Tracer(tracer=tracer, grid=grid) - tracer_plotter.figures_2d(image=True) - -To perform lens modeling, **PyAutoLens** adopts the probabilistic programming -language `PyAutoFit `_. **PyAutoFit** allows users to compose a -lens model from ``LightProfile``, ``MassProfile`` and ``Galaxy`` objects, customize the model parameterization and -fit it to data via a non-linear search (e.g. `dynesty `_, -`emcee `_ or `PySwarms `_). The example -code below shows how to setup and fit a lens model to a dataset: - - -.. code-block:: python - - import autofit as af - import autolens as al - import autolens.plot as aplt - - """ - Load Imaging data of the strong lens from the dataset folder of the workspace. - """ - dataset = al.Imaging.from_fits( - data_path="/path/to/dataset/image.fits", - noise_map_path="/path/to/dataset/noise_map.fits", - psf_path="/path/to/dataset/psf.fits", - pixel_scales=0.1, - ) - - """ - Create a mask for the imaging data, which we setup as a 3.0" circle, and apply it. - """ - mask = al.Mask2D.circular( - shape_native=dataset.shape_native, - pixel_scales=dataset.pixel_scales, - radius=3.0 - ) - dataset = dataset.apply_mask(mask=mask) - - """ - We model the lens galaxy using an elliptical isothermal mass profile and - the source galaxy using an elliptical sersic light profile. - - To setup these profiles as model components whose parameters are free & fitted for - we set up each Galaxy as a `Model` and define the model as a `Collection` of all galaxies. - """ - # Lens: - - mass = af.Model(al.mp.Isothermal) - lens = af.Model(al.Galaxy, redshift=0.5, mass=lens_mass_profile) - - # Source: - - disk = af.Model(al.lp.SersicCore) - source = af.Model(al.Galaxy, redshift=1.0, disk=disk) - - # Overall Lens Model: - model = af.Collection(galaxies=af.Collection(lens=lens, source=source)) - - """ - We define the non-linear search used to fit the model to the data (in this case, Dynesty). - """ - search = af.Nautilus(name="search[example]", n_live=50) - - """ - We next set up the `Analysis`, which contains the `log likelihood function` that the - non-linear search calls to fit the lens model to the data. - """ - analysis = al.AnalysisImaging(dataset=dataset) - - """ - To perform the model-fit we pass the model and analysis to the search's fit method. This will - output results (e.g., dynesty samples, model parameters, visualization) to hard-disk. - """ - result = search.fit(model=model, analysis=analysis) - - """ - The results contain information on the fit, for example the maximum likelihood - model from the Dynesty parameter space search. - """ - print(result.samples.max_log_likelihood()) - -Getting Started -=============== - -To get started, users can check-out the **PyAutoLens**'s rich feature-set by going through the ``overview`` section -of our readthedocs. This illustrates the API for all of **PyAutoLens**'s core features, including how to simulate -strong lens datasets, reconstructing the lensed source galaxy on adaptive pixel-grids and fitting interferometer -datasets. - -For new **PyAutoLens** users, we recommend they start by -`installing PyAutoLens `_ (if you haven't -already!), read through the ``start_here.ipynb`` notebook on -the `autolens_workspace `_ and take the -`HowToLens Jupyter notebook lecture series `_ on -strong gravitational lensing. - -.. toctree:: - :caption: Overview: - :maxdepth: 1 - :hidden: - - overview/overview_1_start_here - overview/overview_2_new_user_guide - overview/overview_3_features - -.. toctree:: - :caption: Installation: - :maxdepth: 1 - :hidden: - - installation/overview - installation/conda - installation/pip - installation/source - installation/troubleshooting - -.. toctree:: - :caption: General: - :maxdepth: 1 - :hidden: - - general/workspace - general/configs - general/model_cookbook - general/likelihood_function - general/demagnified_solutions - general/citations - general/papers - general/credits - -.. toctree:: - :caption: Tutorials: - :maxdepth: 1 - :hidden: - - howtolens/howtolens - howtolens/chapter_1_introduction - howtolens/chapter_2_lens_modeling - howtolens/chapter_3_search_chaining - howtolens/chapter_4_pixelizations - howtolens/chapter_optional - -.. toctree:: - :caption: API Reference: - :maxdepth: 1 - :hidden: - - api/data - api/light - api/mass - api/galaxy - api/fitting - api/modeling - api/pixelization - api/point - api/plot - api/source diff --git a/docs/installation/conda.rst b/docs/installation/conda.md similarity index 53% rename from docs/installation/conda.rst rename to docs/installation/conda.md index 0ad8895b7..340f6d0bc 100644 --- a/docs/installation/conda.rst +++ b/docs/installation/conda.md @@ -1,119 +1,113 @@ -.. _conda: - -Installation with conda -======================= - -JAX & GPU ---------- - -**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. - -This acceleration is achieved through [**JAX**](https://docs.jax.dev/en/latest/notebooks/thinking_in_jax.html), which provides GPU and TPU support. - -When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. - -To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official [JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html). - -If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. - -Install -------- - -Installation via a conda environment circumvents compatibility issues when installing certain libraries. This guide -assumes you have a working installation of `conda `_. - -First, update conda: - -.. code-block:: bash - - conda update -n base -c defaults conda - -Next, create a conda environment (we name this ``autolens`` to signify it is for the **PyAutoLens** install): - -The command below creates this environment with Python 3.12: - -.. code-block:: bash - - conda create -n autolens python=3.12 - -Activate the conda environment (you will have to do this every time you want to run **PyAutoLens**): - -.. code-block:: bash - - conda activate autolens - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -The latest version of **PyAutoLens** is installed via pip as follows (the command ``--no-cache-dir`` prevents -caching issues impacting the installation): - -.. code-block:: bash - - pip install autolens --no-cache-dir - -If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below -will identify clearly if the installation is a success. - -If there are no errors **PyAutoLens** is installed! - -If there is an error check out the `troubleshooting section `_. - -Workspace ---------- - -Next, clone the ``autolens workspace`` (the line ``--depth 1`` clones only the most recent branch on -the ``autolens_workspace``, reducing the download size): - -.. code-block:: bash - - cd /path/on/your/computer/you/want/to/put/the/autolens_workspace - git clone https://github.com/Jammy2211/autolens_workspace --depth 1 - cd autolens_workspace - -Run the ``welcome.py`` script to get started! - -.. code-block:: bash - - python3 welcome.py - -It should be clear that **PyAutoLens** runs without issue. - -If there is an error check out the `troubleshooting section `_. - -Numba ------ - -Numba (https://numba.pydata.org) is an optional library which makes **PyAutoLens** run a lot faster, which we -strongly recommend users have installed. - -You can install numba via the following command: - -.. code-block:: bash - - pip install numba --no-cache-dir - -Some users have experienced difficulties installing numba, which is why it is an optional library. If your -installation is not successful, you can use **PyAutoLens** without it installed for now, to familiarize yourself -with the software and determine if it is the right software for you. - -If you decide that **PyAutoLens** is the right software, then I recommend you commit the time to getting a -successful numba install working, with more information provided `at this readthedocs page `_ - -Optional --------- - -For interferometer analysis there are two optional dependencies that must be installed via the commands: - -.. code-block:: bash - - pip install pynufft - -**PyAutoLens** will run without these libraries and it is recommended that you only install them if you intend to -do interferometer analysis. - -If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore -it is safe not to install them initially. \ No newline at end of file +(conda)= + +# Installation with conda + +## JAX & GPU + +**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. + +This acceleration is achieved through \[**JAX**\](), which provides GPU and TPU support. + +When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. + +To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official \[JAX installation guide\](). + +If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. + +## Install + +Installation via a conda environment circumvents compatibility issues when installing certain libraries. This guide +assumes you have a working installation of [conda](https://conda.io/miniconda.html). + +First, update conda: + +```bash +conda update -n base -c defaults conda +``` + +Next, create a conda environment (we name this `autolens` to signify it is for the **PyAutoLens** install): + +The command below creates this environment with Python 3.12: + +```bash +conda create -n autolens python=3.12 +``` + +Activate the conda environment (you will have to do this every time you want to run **PyAutoLens**): + +```bash +conda activate autolens +``` + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +The latest version of **PyAutoLens** is installed via pip as follows (the command `--no-cache-dir` prevents +caching issues impacting the installation): + +```bash +pip install autolens --no-cache-dir +``` + +If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below +will identify clearly if the installation is a success. + +If there are no errors **PyAutoLens** is installed! + +If there is an error check out the [troubleshooting section](https://pyautolens.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Workspace + +Next, clone the `autolens workspace` (the line `--depth 1` clones only the most recent branch on +the `autolens_workspace`, reducing the download size): + +```bash +cd /path/on/your/computer/you/want/to/put/the/autolens_workspace +git clone https://github.com/Jammy2211/autolens_workspace --depth 1 +cd autolens_workspace +``` + +Run the `welcome.py` script to get started! + +```bash +python3 welcome.py +``` + +It should be clear that **PyAutoLens** runs without issue. + +If there is an error check out the [troubleshooting section](https://pyautolens.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Numba + +Numba () is an optional library which makes **PyAutoLens** run a lot faster, which we +strongly recommend users have installed. + +You can install numba via the following command: + +```bash +pip install numba --no-cache-dir +``` + +Some users have experienced difficulties installing numba, which is why it is an optional library. If your +installation is not successful, you can use **PyAutoLens** without it installed for now, to familiarize yourself +with the software and determine if it is the right software for you. + +If you decide that **PyAutoLens** is the right software, then I recommend you commit the time to getting a +successful numba install working, with more information provided [at this readthedocs page](https://pyautolens.readthedocs.io/en/latest/installation/numba.html) + +## Optional + +For interferometer analysis there are two optional dependencies that must be installed via the commands: + +```bash +pip install pynufft +``` + +**PyAutoLens** will run without these libraries and it is recommended that you only install them if you intend to +do interferometer analysis. + +If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore +it is safe not to install them initially. diff --git a/docs/installation/overview.md b/docs/installation/overview.md new file mode 100644 index 000000000..a97155486 --- /dev/null +++ b/docs/installation/overview.md @@ -0,0 +1,43 @@ +(overview)= + +# Overview + +**PyAutoLens** requires Python 3.12 - 3.13 and supports the Linux, MacOS and Windows operating systems. + +**PyAutoLens** can be installed via the Python distribution [Anaconda](https://www.anaconda.com/) or using +[Pypi](https://pypi.org/) to `pip install autolens` into your Python distribution. + +We recommend Anaconda as it manages the installation of many major libraries (e.g. numpy, scipy, +matplotlib, etc.) making installation more straight forward. Windows users must use Anaconda. + +The installation guide for both approaches can be found at: + +- [Anaconda installation guide](https://pyautolens.readthedocs.io/en/latest/installation/conda.html) +- [PyPI installation guide](https://pyautolens.readthedocs.io/en/latest/installation/pip.html) + +Users who wish to build **PyAutoLens** from source (e.g. via a `git clone`) should follow +our [building from source installation guide](https://pyautolens.readthedocs.io/en/latest/installation/source.html). + +## JAX & GPU + +**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. + +This acceleration is achieved through \[**JAX**\](), which provides GPU and TPU support. + +When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. + +To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official \[JAX installation guide\](). + +If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. + +## Dependencies + +**PyAutoLens** uses the following parent packages: + +**PyAutoConf** + +**PyAutoFit** + +**PyAutoArray** + +**PyAutoGalaxy** diff --git a/docs/installation/overview.rst b/docs/installation/overview.rst deleted file mode 100644 index 489e8797b..000000000 --- a/docs/installation/overview.rst +++ /dev/null @@ -1,48 +0,0 @@ -.. _overview: - -Overview -======== - -**PyAutoLens** requires Python 3.12 - 3.13 and supports the Linux, MacOS and Windows operating systems. - -**PyAutoLens** can be installed via the Python distribution `Anaconda `_ or using -`Pypi `_ to ``pip install autolens`` into your Python distribution. - -We recommend Anaconda as it manages the installation of many major libraries (e.g. numpy, scipy, -matplotlib, etc.) making installation more straight forward. Windows users must use Anaconda. - -The installation guide for both approaches can be found at: - -- `Anaconda installation guide `_ - -- `PyPI installation guide `_ - -Users who wish to build **PyAutoLens** from source (e.g. via a ``git clone``) should follow -our `building from source installation guide `_. - -JAX & GPU ---------- - -**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. - -This acceleration is achieved through [**JAX**](https://docs.jax.dev/en/latest/notebooks/thinking_in_jax.html), which provides GPU and TPU support. - -When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. - -To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official [JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html). - -If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. - -Dependencies ------------- - -**PyAutoLens** uses the following parent packages: - -**PyAutoConf** https://github.com/rhayes777/PyAutoConf - -**PyAutoFit** https://github.com/rhayes777/PyAutoFit - -**PyAutoArray** https://github.com/Jammy2211/PyAutoArray - -**PyAutoGalaxy** https://github.com/Jammy2211/PyAutoGalaxy - diff --git a/docs/installation/pip.rst b/docs/installation/pip.md similarity index 50% rename from docs/installation/pip.rst rename to docs/installation/pip.md index 336fb6ad1..cc706e202 100644 --- a/docs/installation/pip.rst +++ b/docs/installation/pip.md @@ -1,123 +1,116 @@ -.. _pip: - -Installation with pip -===================== - -.. note:: - **PyAutoLens** requires **Python 3.12 or later**. If you are on Python - 3.9, 3.10, or 3.11, ``pip install autolens`` will fail with a "no matching - distribution" error. Upgrade Python to 3.12+ before installing. - -JAX & GPU ---------- - -**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. - -This acceleration is achieved through [**JAX**](https://docs.jax.dev/en/latest/notebooks/thinking_in_jax.html), which provides GPU and TPU support. - -When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. - -To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official [JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html). - -If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. - - -Install -------- - -We strongly recommend that you install **PyAutoLens** in a -`Python virtual environment `_, with the link attached -describing what a virtual environment is and how to create one. - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -The latest version of **PyAutoLens** is installed via pip as follows (specifying the version as shown below ensures -the installation has clean dependencies): - -.. code-block:: bash - - pip install autolens - -If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below -will identify clearly if the installation is a success. - -If there are no errors **PyAutoLens** is installed! - -If there is an error check out the `troubleshooting section `_. - -Workspace ---------- - -Next, clone the ``autolens workspace`` (the line ``--depth 1`` clones only the most recent branch on -the ``autolens_workspace``, reducing the download size): - -.. code-block:: bash - - cd /path/on/your/computer/you/want/to/put/the/autolens_workspace - git clone https://github.com/Jammy2211/autolens_workspace --depth 1 - cd autolens_workspace - -Run the ``welcome.py`` script to get started! - -.. code-block:: bash - - python3 welcome.py - -It should be clear that **PyAutoLens** runs without issue. - -If there is an error check out the `troubleshooting section `_. - -Numba ------ - -Numba (https://numba.pydata.org) is an optional library which makes **PyAutoLens** run a lot faster, which we -strongly recommend users have installed. - -You can install numba via the following command: - -.. code-block:: bash - - pip install numba - -Some users have experienced difficulties installing numba, which is why it is an optional library. If your -installation is not successful, you can use **PyAutoLens** without it installed for now, to familiarize yourself -with the software and determine if it is the right software for you. - -If you decide that **PyAutoLens** is the right software, then I recommend you commit the time to getting a -successful numba install working, with more information provided `at this readthedocs page `_ - -Optional --------- - -For interferometer analysis there are two optional dependencies that must be installed via the commands: - -.. code-block:: bash - - pip install pynufft - -**PyAutoLens** will run without these libraries and it is recommended that you only install them if you intend to -do interferometer analysis. - -If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore -it is safe not to install them initially. - -Legacy Python versions ----------------------- - -We dropped support for Python 3.9, 3.10, and 3.11 in release ``2026.4.5.3`` -(April 2026). Pre-``2026.4.5.3`` releases on PyPI have been yanked, so they -will not install via the standard ``pip install autolens`` command. - -If you have an existing project that requires a pre-``2026.4.5.3`` version, -you can still install it explicitly by pinning the version, e.g.: - -.. code-block:: bash - - pip install autolens==2025.10.6.1 - -Yanked releases remain available for explicit pins; only resolver-driven -fallback is blocked. \ No newline at end of file +(pip)= + +# Installation with pip + +:::{note} +**PyAutoLens** requires **Python 3.12 or later**. If you are on Python +3.9, 3.10, or 3.11, `pip install autolens` will fail with a "no matching +distribution" error. Upgrade Python to 3.12+ before installing. +::: + +## JAX & GPU + +**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. + +This acceleration is achieved through \[**JAX**\](), which provides GPU and TPU support. + +When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. + +To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official \[JAX installation guide\](). + +If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. + +## Install + +We strongly recommend that you install **PyAutoLens** in a +[Python virtual environment](https://www.geeksforgeeks.org/python-virtual-environment/), with the link attached +describing what a virtual environment is and how to create one. + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +The latest version of **PyAutoLens** is installed via pip as follows (specifying the version as shown below ensures +the installation has clean dependencies): + +```bash +pip install autolens +``` + +If pip prints warnings about dependency version conflicts, these can usually be ignored — the instructions below +will identify clearly if the installation is a success. + +If there are no errors **PyAutoLens** is installed! + +If there is an error check out the [troubleshooting section](https://pyautolens.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Workspace + +Next, clone the `autolens workspace` (the line `--depth 1` clones only the most recent branch on +the `autolens_workspace`, reducing the download size): + +```bash +cd /path/on/your/computer/you/want/to/put/the/autolens_workspace +git clone https://github.com/Jammy2211/autolens_workspace --depth 1 +cd autolens_workspace +``` + +Run the `welcome.py` script to get started! + +```bash +python3 welcome.py +``` + +It should be clear that **PyAutoLens** runs without issue. + +If there is an error check out the [troubleshooting section](https://pyautolens.readthedocs.io/en/latest/installation/troubleshooting.html). + +## Numba + +Numba () is an optional library which makes **PyAutoLens** run a lot faster, which we +strongly recommend users have installed. + +You can install numba via the following command: + +```bash +pip install numba +``` + +Some users have experienced difficulties installing numba, which is why it is an optional library. If your +installation is not successful, you can use **PyAutoLens** without it installed for now, to familiarize yourself +with the software and determine if it is the right software for you. + +If you decide that **PyAutoLens** is the right software, then I recommend you commit the time to getting a +successful numba install working, with more information provided [at this readthedocs page](https://pyautolens.readthedocs.io/en/latest/installation/numba.html) + +## Optional + +For interferometer analysis there are two optional dependencies that must be installed via the commands: + +```bash +pip install pynufft +``` + +**PyAutoLens** will run without these libraries and it is recommended that you only install them if you intend to +do interferometer analysis. + +If you run interferometer code a message explaining that you need to install these libraries will be printed, therefore +it is safe not to install them initially. + +## Legacy Python versions + +We dropped support for Python 3.9, 3.10, and 3.11 in release `2026.4.5.3` +(April 2026). Pre-`2026.4.5.3` releases on PyPI have been yanked, so they +will not install via the standard `pip install autolens` command. + +If you have an existing project that requires a pre-`2026.4.5.3` version, +you can still install it explicitly by pinning the version, e.g.: + +```bash +pip install autolens==2025.10.6.1 +``` + +Yanked releases remain available for explicit pins; only resolver-driven +fallback is blocked. diff --git a/docs/installation/source.md b/docs/installation/source.md new file mode 100644 index 000000000..014a8de0f --- /dev/null +++ b/docs/installation/source.md @@ -0,0 +1,173 @@ +(source)= + +# Building From Source + +## JAX & GPU + +**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. + +This acceleration is achieved through \[**JAX**\](), which provides GPU and TPU support. + +When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. + +To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official \[JAX installation guide\](). + +If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. + +## Packages + +Building from source means that you clone (or fork) the **PyAutoLens** GitHub repository and run **PyAutoLens** from +there. Unlike `conda` and `pip` this provides a build of the source code that you can edit and change, to +contribute the development **PyAutoLens** or experiment with yourself! + +A large amount of **PyAutoLens** functionality is contained in its parent projects: + +**PyAutoFit** + +**PyAutoArray** + +**PyAutoGalaxy** + +If you wish to build from source all code you may need to build from source these 3 additional +projects. We include below instructions for building just **PyAutoLens** from source or building all projects. + +## Building Only PyAutoLens + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +First, clone (or fork) the **PyAutoLens** GitHub repository: + +```bash +git clone https://github.com/Jammy2211/PyAutoLens +``` + +Next, install the **PyAuto** parent projects via pip: + +```bash +pip install autoconf +pip install autofit +pip install autoarray +pip install autogalaxy +``` + +Next, install the **PyAutoLens** dependencies via pip: + +```bash +pip install -r PyAutoLens/requirements.txt +``` + +Next, install the optional dependency numba via pip (see [this link](https://pyautolens.readthedocs.io/en/latest/installation/numba.html) for a description of numba): + +```bash +pip install numba +``` + +For unit tests to pass you will also need the following optional requirements: + +```bash +pip install pynufft +``` + +If you are using a `conda` environment, add the source repository as follows: + +\[NOTE: Certain versions of conda use the command `conda develop` (without a dash) instead of those shown below.\] + +```bash +conda-develop PyAutoLens +``` + +Alternatively, if you are using a Python environment include the **PyAutoLens** source repository in your PYTHONPATH +(noting that you must replace the text `/path/to` with the path to the **PyAutoLens** directory on your computer): + +```bash +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoLens +``` + +Finally, check the **PyAutoLens** unit tests run and pass (you may need to install pytest via `pip install pytest`): + +```bash +cd /path/to/PyAutoLens +python3 -m pytest +``` + +## Building All Projects + +We upgrade pip to ensure certain libraries install: + +```bash +pip install --upgrade pip +``` + +First, clone (or fork) all 4 GitHub repositories: + +```bash +git clone https://github.com/rhayes777/PyAutoFit +git clone https://github.com/Jammy2211/PyAutoArray +git clone https://github.com/Jammy2211/PyAutoGalaxy +git clone https://github.com/Jammy2211/PyAutoLens +``` + +Next, install **PyAutoConf** via pip: + +```bash +pip install autoconf +``` + +Next, install the source build dependencies of each project via pip: + +```bash +pip install -r PyAutoFit/requirements.txt +pip install -r PyAutoArray/requirements.txt +pip install -r PyAutoGalaxy/requirements.txt +pip install -r PyAutoLens/requirements.txt +``` + +Next, install the optional dependency numba via pip (see [this link](https://pyautolens.readthedocs.io/en/latest/installation/numba.html) for a description of numba): + +```bash +pip install numba +``` + +For unit tests to pass you will also need the following optional requirements: + +```bash +pip install -r PyAutoArray/optional_requirements.txt +``` + +If you are using a `conda` environment, add each source repository as follows: + +\[NOTE: Certain versions of conda use the command `conda develop` (without a dash) instead of those shown below.\] + +```bash +conda-develop PyAutoFit +conda-develop PyAutoArray +conda-develop PyAutoGalaxy +conda-develop PyAutoLens +``` + +Alternatively, if you are using a Python environment include each source repository in your PYTHONPATH +(noting that you must replace the text `/path/to` with the path to the each directory on your computer): + +```bash +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoFit +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoArray +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy +export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoLens +``` + +Finally, check the unit tests run and pass for each project (you may need to install pytest via `pip install pytest`): + +```bash +cd /path/to/PyAutoFit +python3 -m pytest +cd ../PyAutoArray +python3 -m pytest +cd ../PyAutoGalaxy +python3 -m pytest +cd ../PyAutoLens +python3 -m pytest +``` diff --git a/docs/installation/source.rst b/docs/installation/source.rst deleted file mode 100644 index 6cc1e677d..000000000 --- a/docs/installation/source.rst +++ /dev/null @@ -1,179 +0,0 @@ -.. _source: - -Building From Source -==================== - -JAX & GPU ---------- - -**PyAutoLens** runs significantly faster on GPUs — often **50x or more** compared to CPUs. - -This acceleration is achieved through [**JAX**](https://docs.jax.dev/en/latest/notebooks/thinking_in_jax.html), which provides GPU and TPU support. - -When you install **PyAutoLens** (see instructions below), JAX will also be installed. However, the default installation may not include GPU support. - -To ensure GPU acceleration, it is recommended that you install JAX with GPU support **before** installing **PyAutoLens**, by following the official [JAX installation guide](https://jax.readthedocs.io/en/latest/installation.html). - -If you install **PyAutoLens** without a proper GPU setup, a warning will be displayed. - -Packages --------- - -Building from source means that you clone (or fork) the **PyAutoLens** GitHub repository and run **PyAutoLens** from -there. Unlike ``conda`` and ``pip`` this provides a build of the source code that you can edit and change, to -contribute the development **PyAutoLens** or experiment with yourself! - -A large amount of **PyAutoLens** functionality is contained in its parent projects: - -**PyAutoFit** https://github.com/rhayes777/PyAutoFit - -**PyAutoArray** https://github.com/Jammy2211/PyAutoArray - -**PyAutoGalaxy** https://github.com/Jammy2211/PyAutoGalaxy - -If you wish to build from source all code you may need to build from source these 3 additional -projects. We include below instructions for building just **PyAutoLens** from source or building all projects. - -Building Only PyAutoLens ------------------------- - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -First, clone (or fork) the **PyAutoLens** GitHub repository: - -.. code-block:: bash - - git clone https://github.com/Jammy2211/PyAutoLens - -Next, install the **PyAuto** parent projects via pip: - -.. code-block:: bash - - pip install autoconf - pip install autofit - pip install autoarray - pip install autogalaxy - -Next, install the **PyAutoLens** dependencies via pip: - -.. code-block:: bash - - pip install -r PyAutoLens/requirements.txt - -Next, install the optional dependency numba via pip (see `this link `_ for a description of numba): - -.. code-block:: bash - - pip install numba - -For unit tests to pass you will also need the following optional requirements: - -.. code-block:: bash - - pip install pynufft - -If you are using a ``conda`` environment, add the source repository as follows: - -[NOTE: Certain versions of conda use the command ``conda develop`` (without a dash) instead of those shown below.] - -.. code-block:: bash - - conda-develop PyAutoLens - -Alternatively, if you are using a Python environment include the **PyAutoLens** source repository in your PYTHONPATH -(noting that you must replace the text ``/path/to`` with the path to the **PyAutoLens** directory on your computer): - -.. code-block:: bash - - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoLens - -Finally, check the **PyAutoLens** unit tests run and pass (you may need to install pytest via ``pip install pytest``): - -.. code-block:: bash - - cd /path/to/PyAutoLens - python3 -m pytest - - -Building All Projects ---------------------- - -We upgrade pip to ensure certain libraries install: - -.. code-block:: bash - - pip install --upgrade pip - -First, clone (or fork) all 4 GitHub repositories: - -.. code-block:: bash - - git clone https://github.com/rhayes777/PyAutoFit - git clone https://github.com/Jammy2211/PyAutoArray - git clone https://github.com/Jammy2211/PyAutoGalaxy - git clone https://github.com/Jammy2211/PyAutoLens - -Next, install **PyAutoConf** via pip: - -.. code-block:: bash - - pip install autoconf - -Next, install the source build dependencies of each project via pip: - -.. code-block:: bash - - pip install -r PyAutoFit/requirements.txt - pip install -r PyAutoArray/requirements.txt - pip install -r PyAutoGalaxy/requirements.txt - pip install -r PyAutoLens/requirements.txt - -Next, install the optional dependency numba via pip (see `this link `_ for a description of numba): - -.. code-block:: bash - - pip install numba - -For unit tests to pass you will also need the following optional requirements: - -.. code-block:: bash - - pip install -r PyAutoArray/optional_requirements.txt - -If you are using a ``conda`` environment, add each source repository as follows: - -[NOTE: Certain versions of conda use the command ``conda develop`` (without a dash) instead of those shown below.] - -.. code-block:: bash - - conda-develop PyAutoFit - conda-develop PyAutoArray - conda-develop PyAutoGalaxy - conda-develop PyAutoLens - -Alternatively, if you are using a Python environment include each source repository in your PYTHONPATH -(noting that you must replace the text ``/path/to`` with the path to the each directory on your computer): - -.. code-block:: bash - - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoFit - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoArray - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoGalaxy - export PYTHONPATH=$PYTHONPATH:/path/to/PyAutoLens - -Finally, check the unit tests run and pass for each project (you may need to install pytest via ``pip install pytest``): - -.. code-block:: bash - - cd /path/to/PyAutoFit - python3 -m pytest - cd ../PyAutoArray - python3 -m pytest - cd ../PyAutoGalaxy - python3 -m pytest - cd ../PyAutoLens - python3 -m pytest \ No newline at end of file diff --git a/docs/installation/troubleshooting.md b/docs/installation/troubleshooting.md new file mode 100644 index 000000000..496565c48 --- /dev/null +++ b/docs/installation/troubleshooting.md @@ -0,0 +1,69 @@ +(troubleshooting)= + +# Troubleshooting + +## Pip Version + +If an error message appears after trying to run `pip install autolens` first make sure you are using +the latest version of pip. + +```bash +pip install --upgrade pip +pip3 install --upgrade pip +``` + +## Pip / Conda + +If you are trying to [install via pip](https://pyautolens.readthedocs.io/en/latest/installation/pip.html) but +still having issues, we recommend you try to [install via conda](https://pyautogalaxy.readthedocs.io/en/latest/installation/conda.html) +instead, or visa versa. + +## Support + +If you are still having issues with installation, please raise an issue on the +[autolens_workspace issues page](https://github.com/Jammy2211/autolens_workspace/issues) with a description of the +problem and your system setup (operating system, Python version, etc.). + +## Current Working Directory + +**PyAutoLens** scripts assume that the `autolens_workspace` directory is the Python working directory. This means +that, when you run an example script, you should run it from the `autolens_workspace` as follows: + +```bash +cd path/to/autolens_workspace (if you are not already in the autolens_workspace). +python3 examples/model/beginner/mass_total__source_lp.py +``` + +The reasons for this are so that **PyAutoLens** can: + +> - Load configuration settings from config files in the `autolens_workspace/config` folder. +> - Load example data from the `autolens_workspace/dataset` folder. +> - Output the results of models fits to your hard-disk to the `autolens/output` folder. + +If you have any errors relating to importing modules, loading data or outputting results it is likely because you +are not running the script with the `autolens_workspace` as the working directory! + +## Matplotlib Backend + +Matplotlib uses the default backend on your computer, as set in the config file: + +```bash +autolens_workspace/config/visualize/general.yaml +``` + +If unchanged, the backend is set to 'default', meaning it will use the backend automatically set up for Python on +your system. + +```bash +general: + backend: default +``` + +There have been reports that using the default backend causes crashes when running the test script below (either the +code crashes without a error or your computer restarts). If this happens, change the config's backend until the test +works (TKAgg has worked on Linux machines, Qt5Agg has worked on new MACs). For example: + +```bash +general: + backend: TKAgg +``` diff --git a/docs/installation/troubleshooting.rst b/docs/installation/troubleshooting.rst deleted file mode 100644 index f6b46d312..000000000 --- a/docs/installation/troubleshooting.rst +++ /dev/null @@ -1,75 +0,0 @@ -.. _troubleshooting: - -Troubleshooting -=============== - -Pip Version ------------ - -If an error message appears after trying to run ``pip install autolens`` first make sure you are using -the latest version of pip. - -.. code-block:: bash - - pip install --upgrade pip - pip3 install --upgrade pip - -Pip / Conda ------------ - -If you are trying to `install via pip `_ but -still having issues, we recommend you try to `install via conda `_ -instead, or visa versa. - -Support -------- - -If you are still having issues with installation, please raise an issue on the -`autolens_workspace issues page `_ with a description of the -problem and your system setup (operating system, Python version, etc.). - -Current Working Directory -------------------------- - -**PyAutoLens** scripts assume that the ``autolens_workspace`` directory is the Python working directory. This means -that, when you run an example script, you should run it from the ``autolens_workspace`` as follows: - -.. code-block:: bash - - cd path/to/autolens_workspace (if you are not already in the autolens_workspace). - python3 examples/model/beginner/mass_total__source_lp.py - -The reasons for this are so that **PyAutoLens** can: - - - Load configuration settings from config files in the ``autolens_workspace/config`` folder. - - Load example data from the ``autolens_workspace/dataset`` folder. - - Output the results of models fits to your hard-disk to the ``autolens/output`` folder. - -If you have any errors relating to importing modules, loading data or outputting results it is likely because you -are not running the script with the ``autolens_workspace`` as the working directory! - -Matplotlib Backend ------------------- - -Matplotlib uses the default backend on your computer, as set in the config file: - -.. code-block:: bash - - autolens_workspace/config/visualize/general.yaml - -If unchanged, the backend is set to 'default', meaning it will use the backend automatically set up for Python on -your system. - -.. code-block:: bash - - general: - backend: default - -There have been reports that using the default backend causes crashes when running the test script below (either the -code crashes without a error or your computer restarts). If this happens, change the config's backend until the test -works (TKAgg has worked on Linux machines, Qt5Agg has worked on new MACs). For example: - -.. code-block:: bash - - general: - backend: TKAgg \ No newline at end of file diff --git a/docs/overview/overview_1_start_here.md b/docs/overview/overview_1_start_here.md new file mode 100644 index 000000000..baaaf97c0 --- /dev/null +++ b/docs/overview/overview_1_start_here.md @@ -0,0 +1,372 @@ +(overview-1-start-here)= + +# 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**. + +Here is a schematic of a strong gravitational lens: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/schematic.jpg +:alt: Alternative text +:width: 600 +``` + +**Credit: F. Courbin, S. G. Djorgovski, G. Meylan, et al., Caltech / EPFL / WMKO** + + +This notebook gives an overview of **PyAutoLens**'s features and API. + +## Imports + +Lets first import autolens, its plotting module and the other libraries we'll need. + +You'll see these imports in the majority of workspace examples. + +```python +import autolens as al +import autoarray as aa +import autolens.plot as aplt +``` + +Lets illustrate a simple gravitational lensing calculation, creating an an image of a lensed galaxy using a +light profile and mass profile. + +## Grid + +The emission of light from a source galaxy, which is gravitationally lensed around the lens galaxy, is described +using the `Grid2D` data structure, which is two-dimensional Cartesian grids of (y,x) coordinates. + +We make and plot a uniform Cartesian grid: + +```python +grid = al.Grid2D.uniform( + shape_native=(150, 150), # The [pixels x pixels] shape of the grid in 2D. + pixel_scales=0.05, # The pixel-scale describes the conversion from pixel units to arc-seconds. +) + +aplt.plot_grid(grid=grid, title="") +``` + +The `Grid2D` looks like this: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/0_grid.png +:alt: Alternative text +:width: 600 +``` + +## Light Profiles + +Our aim is to create an image of the source galaxy after its light has been deflected by the mass of the foreground +lens galaxy. We therefore need to ray-trace the `Grid2D`'s coordinates from the 'image-plane' to the 'source-plane'. + +This uses analytic functions representing a galaxy's light and mass distributions, referred to as `LightProfile` and +`MassProfile` objects. + +A common light profile in Astronomy is the elliptical Sersic, which we create an instance of below: + +```python +sersic_light_profile = al.lp.Sersic( + centre=(0.0, 0.0), # The light profile centre [units of arc-seconds]. + ell_comps=( + 0.2, + 0.1, + ), # The light profile elliptical components [can be converted to axis-ratio and position angle]. + intensity=0.005, # The overall intensity normalisation [units arbitrary and are matched to the data]. + effective_radius=2.0, # The effective radius containing half the profile's total luminosity [units of arc-seconds]. + sersic_index=4.0, # Describes the profile's shape [higher value -> more concentrated profile]. +) +``` + +By passing the light profile the `grid`, we evaluate the light emitted at every (y,x) coordinate and therefore create +an image of the Sersic light profile. + +```python +image = sersic_light_profile.image_2d_from(grid=grid) +``` + +## Plotting + +In-built plotting methods are provided for plotting objects and their properties, like the image of +a light profile we just created. + +By using `aplt.plot_array` to plot the light profile's image, the figure is improved. + +Its axis units are scaled to arc-seconds, a color-bar is added, descriptive labels are included, etc. + +The plot module is highly customizable and designed to make it straight forward to create clean and informative figures +for fits to large datasets. + +```python +aplt.plot_array(array=sersic_light_profile.image_2d_from(grid=grid), title="Image") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/1_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Mass Profiles + +PyAutoLens uses MassProfile objects to represent a galaxy’s mass distribution and perform ray-tracing calculations. + +Below we create an elliptical isothermal MassProfile and compute its deflection angles on our Cartesian grid, where +the deflection angles describe how the lens galaxy’s mass bends the source’s light: + +```python +isothermal_mass_profile = al.mp.Isothermal( + centre=(0.0, 0.0), # The mass profile centre [units of arc-seconds]. + ell_comps=( + 0.1, + 0.0, + ), # The mass profile elliptical components [can be converted to axis-ratio and position angle]. + einstein_radius=1.6, # The Einstein radius [units of arc-seconds]. +) + +deflections = isothermal_mass_profile.deflections_yx_2d_from(grid=grid) +``` + +The deflection angles are easily plotted using the **PyAutoLens** plot module. + +Many other lensing quantities are also easily plotted, for example the `convergence` and `potential`. + +```python +deflections_y = aa.Array2D(values=deflections.slim[:, 0], mask=grid.mask) +aplt.plot_array(array=deflections_y, title="Deflections Y") + +deflections = isothermal_mass_profile.deflections_yx_2d_from(grid=grid) +deflections_x = aa.Array2D(values=deflections.slim[:, 1], mask=grid.mask) +aplt.plot_array(array=deflections_x, title="Deflections X") + +aplt.plot_array(array=isothermal_mass_profile.convergence_2d_from(grid=grid), title="Convergence") +aplt.plot_array(array=isothermal_mass_profile.potential_2d_from(grid=grid), title="Potential") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/2_deflections_y_2d.png +:alt: Alternative text +:width: 600 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/3_deflections_x_2d.png +:alt: Alternative text +:width: 600 +``` + +## Galaxy + +A `Galaxy` object is a collection of light profiles at a specific redshift. + +This object is highly extensible and is what ultimately allows us to fit complex models to strong lens images. + +We create two galaxies representing the lens and source galaxies shown in the strong lensing diagram above. + +```python +lens_galaxy = al.Galaxy( + redshift=0.5, + light=sersic_light_profile, # The foreground lens's light is typically observed in a strong lens. + mass=isothermal_mass_profile, # Its mass is what causes the strong lensing effect. +) + +source_light_profile = al.lp.Exponential( + centre=( + 0.3, + 0.2, + ), # The source galaxy's light is observed, appearing as multiple images around the lens galaxy. + ell_comps=( + 0.1, + 0.0, + ), # However, the mass of the source does not impact the strong lensing effect. + intensity=0.1, # and is not included. + effective_radius=0.5, +) + +source_galaxy = al.Galaxy(redshift=1.0, light=source_light_profile) +``` + +We can plot properties of the lens and source galaxies using `aplt.plot_array`: + +```python +aplt.plot_array(array=lens_galaxy.image_2d_from(grid=grid), title="Lens Galaxy Image") +aplt.plot_array(array=source_galaxy.image_2d_from(grid=grid), title="Source Galaxy Image") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/4_image_2d.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/7_image_2d.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/5_deflections_y_2d.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/6_deflections_x_2d.png +:alt: Alternative text +:width: 400 +``` + +The individual light profiles of the galaxy can be plotted on a subplot: + +```python +aplt.subplot_galaxy_light_profiles(galaxy=lens_galaxy, grid=grid) +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/8_subplot_image.png +:alt: Alternative text +:width: 600 +``` + +## Tracer + +The `Tracer` object is the most important object in **PyAutoLens**. + +It is a collection of galaxies at different redshifts (often referred to as planes). + +It uses these galaxies to perform ray-tracing, using the mass profiles of the galaxies to bend the light of the source +galaxy(s) into the multiple images we observe in a strong lens system. + +This is shown below, where the image of the tracer shows a distinct Einstein ring of the source galaxy. + +```python +tracer = al.Tracer(galaxies=[lens_galaxy, source_galaxy], cosmology=al.cosmo.Planck15()) + +aplt.plot_array(array=tracer.image_2d_from(grid=grid), title="Image") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/9_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Units + +The units used throughout the strong lensing literature vary, therefore lets quickly describe the units used in +**PyAutoLens**. + +The `Tracer` object and all mass profiles describe their quantities in terms of angles, which are defined in units +of arc-seconds. To convert these to physical units (e.g. kiloparsecs), we use the redshift of the lens and source +galaxies and an input cosmology. A run through of all normal unit conversions is given in guides in the workspace +that are discussed later. + +The use of angles in arc-seconds has an important property, it means that for a two-plane strong lens system +(e.g. a lens galaxy at one redshift and source galaxy at another redshift) lensing calculations are independent of +the galaxies' redshifts and the input cosmology. This has a number of benefits, for example it makes it straight +forward to compare the lensing properties of different strong lens systems even when the redshifts of the galaxies +are unknown. + +Multi-plane lensing is when there are more than two planes. The tracer fully supports this, if you input 3+ galaxies +with different redshifts into the tracer it will use their redshifts and its cosmology to perform multi-plane lensing +calculations that depend on them. + +## Extensibility + +All of the objects we've introduced so far are highly extensible, for example a tracer can be made of many galaxies, a +galaxy can be made up of any number of light profiles and many galaxy objects can be combined into a galaxies object. + +Below, wecreate a `Tracer` with 3 galaxies at 3 different redshifts, forming a system with two distinct Einstein +rings! The mass distribution of the first galaxy has separate components for its stellar mass and dark matter, where +the stellar components use a `LightAndMassProfile` via the `lmp` module. + +```python +lens_galaxy_0 = al.Galaxy( + redshift=0.5, + bulge=al.lmp.Sersic( + centre=(0.0, 0.0), + ell_comps=(0.0, 0.05), + intensity=0.5, + effective_radius=0.3, + sersic_index=3.5, + mass_to_light_ratio=0.6, + ), + disk=al.lmp.Exponential( + centre=(0.0, 0.0), + ell_comps=(0.0, 0.1), + intensity=1.0, + effective_radius=2.0, + mass_to_light_ratio=0.2, + ), + dark=al.mp.NFWSph(centre=(0.0, 0.0), kappa_s=0.08, scale_radius=30.0), +) + +lens_galaxy_1 = al.Galaxy( + redshift=1.0, + bulge=al.lp.Exponential( + centre=(0.00, 0.00), + ell_comps=(0.05, 0.05), + intensity=1.2, + effective_radius=0.1, + ), + mass=al.mp.Isothermal( + centre=(0.0, 0.0), ell_comps=(0.05, 0.05), einstein_radius=0.6 + ), +) + +source_galaxy = al.Galaxy( + redshift=2.0, + bulge=al.lp.Sersic( + centre=(0.0, 0.0), + ell_comps=(0.0, 0.111111), + intensity=0.7, + effective_radius=0.1, + sersic_index=1.5, + ), +) + +tracer = al.Tracer(galaxies=[lens_galaxy_0, lens_galaxy_1, source_galaxy]) + +aplt.plot_array(array=tracer.image_2d_from(grid=grid), title="Image") +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/10_image_2d.png +:alt: Alternative text +:width: 600 +``` + +## Lens Modeling + +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 primary goal of **PyAutoLens** is to make lens modeling **simple, scalable to large datasets, and fast**, with +GPU acceleration provided via JAX. + +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 +``` + +**Credit: Amy Etherington** + +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 + +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 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. diff --git a/docs/overview/overview_1_start_here.rst b/docs/overview/overview_1_start_here.rst deleted file mode 100644 index 4d3c187da..000000000 --- a/docs/overview/overview_1_start_here.rst +++ /dev/null @@ -1,373 +0,0 @@ -.. _overview_1_start_here: - -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**. - -Here is a schematic of a strong gravitational lens: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/schematic.jpg - :width: 600 - :alt: Alternative text - -**Credit: F. Courbin, S. G. Djorgovski, G. Meylan, et al., Caltech / EPFL / WMKO** -https://www.astro.caltech.edu/~george/qsolens/ - -This notebook gives an overview of **PyAutoLens**'s features and API. - -Imports -------- - -Lets first import autolens, its plotting module and the other libraries we'll need. - -You'll see these imports in the majority of workspace examples. - -.. code:: python - - import autolens as al - import autoarray as aa - import autolens.plot as aplt - -Lets illustrate a simple gravitational lensing calculation, creating an an image of a lensed galaxy using a -light profile and mass profile. - -Grid ----- - -The emission of light from a source galaxy, which is gravitationally lensed around the lens galaxy, is described -using the ``Grid2D`` data structure, which is two-dimensional Cartesian grids of (y,x) coordinates. - -We make and plot a uniform Cartesian grid: - -.. code:: python - - grid = al.Grid2D.uniform( - shape_native=(150, 150), # The [pixels x pixels] shape of the grid in 2D. - pixel_scales=0.05, # The pixel-scale describes the conversion from pixel units to arc-seconds. - ) - - aplt.plot_grid(grid=grid, title="") - -The ``Grid2D`` looks like this: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/0_grid.png - :width: 600 - :alt: Alternative text - -Light Profiles --------------- - -Our aim is to create an image of the source galaxy after its light has been deflected by the mass of the foreground -lens galaxy. We therefore need to ray-trace the ``Grid2D``'s coordinates from the 'image-plane' to the 'source-plane'. - -This uses analytic functions representing a galaxy's light and mass distributions, referred to as ``LightProfile`` and -``MassProfile`` objects. - -A common light profile in Astronomy is the elliptical Sersic, which we create an instance of below: - -.. code:: python - - sersic_light_profile = al.lp.Sersic( - centre=(0.0, 0.0), # The light profile centre [units of arc-seconds]. - ell_comps=( - 0.2, - 0.1, - ), # The light profile elliptical components [can be converted to axis-ratio and position angle]. - intensity=0.005, # The overall intensity normalisation [units arbitrary and are matched to the data]. - effective_radius=2.0, # The effective radius containing half the profile's total luminosity [units of arc-seconds]. - sersic_index=4.0, # Describes the profile's shape [higher value -> more concentrated profile]. - ) - - -By passing the light profile the ``grid``, we evaluate the light emitted at every (y,x) coordinate and therefore create -an image of the Sersic light profile. - -.. code:: python - - image = sersic_light_profile.image_2d_from(grid=grid) - -Plotting --------- - -In-built plotting methods are provided for plotting objects and their properties, like the image of -a light profile we just created. - -By using ``aplt.plot_array`` to plot the light profile's image, the figure is improved. - -Its axis units are scaled to arc-seconds, a color-bar is added, descriptive labels are included, etc. - -The plot module is highly customizable and designed to make it straight forward to create clean and informative figures -for fits to large datasets. - -.. code:: python - - aplt.plot_array(array=sersic_light_profile.image_2d_from(grid=grid), title="Image") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/1_image_2d.png - :width: 600 - :alt: Alternative text - -Mass Profiles -------------- - -PyAutoLens uses MassProfile objects to represent a galaxy’s mass distribution and perform ray-tracing calculations. - -Below we create an elliptical isothermal MassProfile and compute its deflection angles on our Cartesian grid, where -the deflection angles describe how the lens galaxy’s mass bends the source’s light: - -.. code:: python - - isothermal_mass_profile = al.mp.Isothermal( - centre=(0.0, 0.0), # The mass profile centre [units of arc-seconds]. - ell_comps=( - 0.1, - 0.0, - ), # The mass profile elliptical components [can be converted to axis-ratio and position angle]. - einstein_radius=1.6, # The Einstein radius [units of arc-seconds]. - ) - - deflections = isothermal_mass_profile.deflections_yx_2d_from(grid=grid) - -The deflection angles are easily plotted using the **PyAutoLens** plot module. - -Many other lensing quantities are also easily plotted, for example the ``convergence`` and ``potential``. - -.. code:: python - - deflections_y = aa.Array2D(values=deflections.slim[:, 0], mask=grid.mask) - aplt.plot_array(array=deflections_y, title="Deflections Y") - - deflections = isothermal_mass_profile.deflections_yx_2d_from(grid=grid) - deflections_x = aa.Array2D(values=deflections.slim[:, 1], mask=grid.mask) - aplt.plot_array(array=deflections_x, title="Deflections X") - - aplt.plot_array(array=isothermal_mass_profile.convergence_2d_from(grid=grid), title="Convergence") - aplt.plot_array(array=isothermal_mass_profile.potential_2d_from(grid=grid), title="Potential") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/2_deflections_y_2d.png - :width: 600 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/3_deflections_x_2d.png - :width: 600 - :alt: Alternative text - -Galaxy ------- - -A ``Galaxy`` object is a collection of light profiles at a specific redshift. - -This object is highly extensible and is what ultimately allows us to fit complex models to strong lens images. - -We create two galaxies representing the lens and source galaxies shown in the strong lensing diagram above. - -.. code:: python - - lens_galaxy = al.Galaxy( - redshift=0.5, - light=sersic_light_profile, # The foreground lens's light is typically observed in a strong lens. - mass=isothermal_mass_profile, # Its mass is what causes the strong lensing effect. - ) - - source_light_profile = al.lp.Exponential( - centre=( - 0.3, - 0.2, - ), # The source galaxy's light is observed, appearing as multiple images around the lens galaxy. - ell_comps=( - 0.1, - 0.0, - ), # However, the mass of the source does not impact the strong lensing effect. - intensity=0.1, # and is not included. - effective_radius=0.5, - ) - - source_galaxy = al.Galaxy(redshift=1.0, light=source_light_profile) - -We can plot properties of the lens and source galaxies using ``aplt.plot_array``: - -.. code:: python - - aplt.plot_array(array=lens_galaxy.image_2d_from(grid=grid), title="Lens Galaxy Image") - aplt.plot_array(array=source_galaxy.image_2d_from(grid=grid), title="Source Galaxy Image") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/4_image_2d.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/7_image_2d.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/5_deflections_y_2d.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/6_deflections_x_2d.png - :width: 400 - :alt: Alternative text - -The individual light profiles of the galaxy can be plotted on a subplot: - -.. code:: python - - aplt.subplot_galaxy_light_profiles(galaxy=lens_galaxy, grid=grid) - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/8_subplot_image.png - :width: 600 - :alt: Alternative text - -Tracer ------- - -The ``Tracer`` object is the most important object in **PyAutoLens**. - -It is a collection of galaxies at different redshifts (often referred to as planes). - -It uses these galaxies to perform ray-tracing, using the mass profiles of the galaxies to bend the light of the source -galaxy(s) into the multiple images we observe in a strong lens system. - -This is shown below, where the image of the tracer shows a distinct Einstein ring of the source galaxy. - -.. code:: python - - tracer = al.Tracer(galaxies=[lens_galaxy, source_galaxy], cosmology=al.cosmo.Planck15()) - - aplt.plot_array(array=tracer.image_2d_from(grid=grid), title="Image") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/9_image_2d.png - :width: 600 - :alt: Alternative text - -Units ------ - -The units used throughout the strong lensing literature vary, therefore lets quickly describe the units used in -**PyAutoLens**. - -The ``Tracer`` object and all mass profiles describe their quantities in terms of angles, which are defined in units -of arc-seconds. To convert these to physical units (e.g. kiloparsecs), we use the redshift of the lens and source -galaxies and an input cosmology. A run through of all normal unit conversions is given in guides in the workspace -that are discussed later. - -The use of angles in arc-seconds has an important property, it means that for a two-plane strong lens system -(e.g. a lens galaxy at one redshift and source galaxy at another redshift) lensing calculations are independent of -the galaxies' redshifts and the input cosmology. This has a number of benefits, for example it makes it straight -forward to compare the lensing properties of different strong lens systems even when the redshifts of the galaxies -are unknown. - -Multi-plane lensing is when there are more than two planes. The tracer fully supports this, if you input 3+ galaxies -with different redshifts into the tracer it will use their redshifts and its cosmology to perform multi-plane lensing -calculations that depend on them. - -Extensibility -------------- - -All of the objects we've introduced so far are highly extensible, for example a tracer can be made of many galaxies, a -galaxy can be made up of any number of light profiles and many galaxy objects can be combined into a galaxies object. - -Below, wecreate a ``Tracer`` with 3 galaxies at 3 different redshifts, forming a system with two distinct Einstein -rings! The mass distribution of the first galaxy has separate components for its stellar mass and dark matter, where -the stellar components use a ``LightAndMassProfile`` via the ``lmp`` module. - -.. code:: python - - lens_galaxy_0 = al.Galaxy( - redshift=0.5, - bulge=al.lmp.Sersic( - centre=(0.0, 0.0), - ell_comps=(0.0, 0.05), - intensity=0.5, - effective_radius=0.3, - sersic_index=3.5, - mass_to_light_ratio=0.6, - ), - disk=al.lmp.Exponential( - centre=(0.0, 0.0), - ell_comps=(0.0, 0.1), - intensity=1.0, - effective_radius=2.0, - mass_to_light_ratio=0.2, - ), - dark=al.mp.NFWSph(centre=(0.0, 0.0), kappa_s=0.08, scale_radius=30.0), - ) - - lens_galaxy_1 = al.Galaxy( - redshift=1.0, - bulge=al.lp.Exponential( - centre=(0.00, 0.00), - ell_comps=(0.05, 0.05), - intensity=1.2, - effective_radius=0.1, - ), - mass=al.mp.Isothermal( - centre=(0.0, 0.0), ell_comps=(0.05, 0.05), einstein_radius=0.6 - ), - ) - - source_galaxy = al.Galaxy( - redshift=2.0, - bulge=al.lp.Sersic( - centre=(0.0, 0.0), - ell_comps=(0.0, 0.111111), - intensity=0.7, - effective_radius=0.1, - sersic_index=1.5, - ), - ) - - tracer = al.Tracer(galaxies=[lens_galaxy_0, lens_galaxy_1, source_galaxy]) - - aplt.plot_array(array=tracer.image_2d_from(grid=grid), title="Image") - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_1/10_image_2d.png - :width: 600 - :alt: Alternative text - -Lens Modeling -------------- - -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 primary goal of **PyAutoLens** is to make lens modeling **simple, scalable to large datasets, and fast**, with -GPU acceleration provided via JAX. - -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 - -**Credit: Amy Etherington** - -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 -------- - -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 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. \ No newline at end of file diff --git a/docs/overview/overview_2_new_user_guide.rst b/docs/overview/overview_2_new_user_guide.md similarity index 63% rename from docs/overview/overview_2_new_user_guide.rst rename to docs/overview/overview_2_new_user_guide.md index a2beb2bec..462de4adc 100644 --- a/docs/overview/overview_2_new_user_guide.rst +++ b/docs/overview/overview_2_new_user_guide.md @@ -1,89 +1,78 @@ -.. _overview_2_new_user_guide: - -New User Guide -============== - -**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 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? ----------------- - -What size and scale of strong lens system are you expecting to work with? - -There are three scales to choose from: - -- **Galaxy Scale**: Made up of a single lens galaxy lensing a single source galaxy, the simplest strong lens you can get! - 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. - -- **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. - -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 `_. - -- **Interferometer**: For radio / sub-mm interferometer from instruments like ALMA, go to `interferometer/start_here.ipynb `_. - -- **Point Sources**: For strongly lensed point sources (e.g. lensed quasars, supernovae), go to `point_source/start_here.ipynb `_. - -Google Colab ------------- - -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 `_: Galaxy scale strong lenses observed with CCD imaging (e.g. Hubble, James Webb). - - `interferometer/start_here.ipynb `_: Galaxy scale strong lenses observed with interferometer data (e.g. ALMA). - - `point_source/start_here.ipynb `_: Galaxy scale strong lenses with a lensed point source (e.g. lensed quasars). - - `group/start_here.ipynb `_: Group scale strong lenses where there are 2-10 lens galaxies. - - `cluster/start_here.ipynb `_: Cluster scale strong lenses with 2+ lenses and 5+ source galaxies. - -Still Unsure? -------------- - -Each notebook is short and self-contained, and can be completed and adapted quickly to your particular task. -Therefore, if you're unsure exactly which scale of lensing applies to you, or quite what data you want to use, you -should just read through a few different notebooks and go from there. - -HowToLens ---------- - -For experienced scientists, the **PyAutoLens** examples will be simple to follow. Concepts surrounding strong lensing may -already be familiar and the statistical techniques used for fitting and modeling already understood. - -For those less familiar with these concepts (e.g. undergraduate students, new PhD students or interested members of the -public), things may have been less clear and a slower more detailed explanation of each concept would be beneficial. - -The **HowToLens** Jupyter Notebook lectures provide exactly this. They are a 3+ chapter guide which thoroughly -take you through the core concepts of strong lensing, teach you the principles of the statistical techniques -used in modeling and ultimately will allow you to undertake scientific research like a professional astronomer. - -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 `HowToLens `_ repository now. - -Wrap Up -------- - -After completing this guide, you should be able to use **PyAutoLens** for your science research. - -The biggest decisions you'll need to make are what features and functionality your specific science case requires, -which the next readthedocs page gives an overview of to help you decide. \ No newline at end of file +(overview-2-new-user-guide)= + +# New User Guide + +**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 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? + +What size and scale of strong lens system are you expecting to work with? + +There are three scales to choose from: + +- **Galaxy Scale**: Made up of a single lens galaxy lensing a single source galaxy, the simplest strong lens you can get! + 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](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](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](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). + +## Google Colab + +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/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/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/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/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/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/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/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/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/PyAutoLabs/autolens_workspace/blob/2026.4.13.6/notebooks/cluster/start_here.ipynb): Cluster scale strong lenses with 2+ lenses and 5+ source galaxies. + +## Still Unsure? + +Each notebook is short and self-contained, and can be completed and adapted quickly to your particular task. +Therefore, if you're unsure exactly which scale of lensing applies to you, or quite what data you want to use, you +should just read through a few different notebooks and go from there. + +## HowToLens + +For experienced scientists, the **PyAutoLens** examples will be simple to follow. Concepts surrounding strong lensing may +already be familiar and the statistical techniques used for fitting and modeling already understood. + +For those less familiar with these concepts (e.g. undergraduate students, new PhD students or interested members of the +public), things may have been less clear and a slower more detailed explanation of each concept would be beneficial. + +The **HowToLens** Jupyter Notebook lectures provide exactly this. They are a 3+ chapter guide which thoroughly +take you through the core concepts of strong lensing, teach you the principles of the statistical techniques +used in modeling and ultimately will allow you to undertake scientific research like a professional astronomer. + +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 [HowToLens](https://github.com/PyAutoLabs/HowToLens) repository now. + +## Wrap Up + +After completing this guide, you should be able to use **PyAutoLens** for your science research. + +The biggest decisions you'll need to make are what features and functionality your specific science case requires, +which the next readthedocs page gives an overview of to help you decide. diff --git a/docs/overview/overview_3_features.rst b/docs/overview/overview_3_features.md similarity index 63% rename from docs/overview/overview_3_features.rst rename to docs/overview/overview_3_features.md index 16d6ef608..fbee87ce3 100644 --- a/docs/overview/overview_3_features.rst +++ b/docs/overview/overview_3_features.md @@ -1,235 +1,227 @@ -.. _overview_3_features: - -Features -======== - -This page provides an overview of the advanced features of **PyAutoLens**. - -Firstly, brief one sentence descriptions of each feature are given, with more detailed descriptions below including -links to the relevant workspace examples. - -**Pixelizations**: Reconstructing the source galaxy on a mesh of pixels, to capture extremely irregular structures like spiral arms. - -**Point Sources**: Modeling point sources (e.g. quasars) observed in the strong lens imaging data. - -**Interferometry**: Modeling of interferometer data (e.g. ALMA, LOFAR) directly in the uv-plane. - -**Multi Gaussian Expansion (MGE)**: Decomposing the lens galaxy into hundreds of Gaussians, for a clean lens subtraction. - -**Groups**: Modeling group-scale strong lenses with multiple lens galaxies and multiple source galaxies. - -**Multi-Wavelength**: Simultaneous analysis of imaging and / or interferometer datasets observed at different wavelengths. - -**Ellipse Fitting**: Fitting ellipses to determine a lens galaxy's ellipticity, position angle and centre. - -**Shapelets**: Decomposing a galaxy into a set of shapelet orthogonal basis functions, capturing more complex structures than simple light profiles. - -**Operated Light Profiles**: Assuming a light profile has already been convolved with the PSF, for when the PSF is a significant effect. - -**Sky Background**: Including the background sky in the model to ensure robust fits to the outskirts of galaxies. - -Pixelizations -------------- - -Pixelizations reconstruct the source galaxy's light on a pixel-grid. Unlike ``LightProfile``'s, they are able to -reconstruct the light of non-symmetric, irregular and clumpy sources. - -The image below shows a pixelized source reconstruction of the strong lens SLACS1430+4105, where the source is -reconstructed on a Voronoi mesh adapted to the source morphology, revealing it to be a grand-design face on spiral -galaxy: - -.. image:: https://github.com/Jammy2211/PyAutoLens/blob/main/files/imageaxis.png?raw=true - :width: 600 - :alt: Alternative text - -A complete overview of pixelized source reconstructions can be found -at ``notebooks/overview/overview_5_pixelizations.ipynb``. - -Chapter 4 of lectures describes pixelizations in detail and teaches users how they can be used to -perform lens modeling. - - -Point Sources -------------- - -There are many lenses where the background source is not extended but is instead a point-source, for example strongly -lensed quasars and supernovae. - -For these objects, we do not want to model the source using a light profile, which implicitly assumes an extended -surface brightness distribution. - -Instead, we assume that our source is a point source with a centre (y,x), and ray-trace triangles at iteratively -higher resolutions to determine the source's exact locations in the image-plane: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_0.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_1.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_2.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_3.png - :width: 400 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_4.png - :width: 400 - :alt: Alternative text - -Note that the image positions above include the fifth central image of the strong lens, which is often not seen in -strong lens imaging data. It is easy to disable this image in the point source modeling. - -Checkout the ``autolens_workspace/*/point_source`` package to get started. - - -Interferometry --------------- - -Modeling of interferometer data from submillimeter (e.g. ALMA) and radio (e.g. LOFAR) observatories: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/almacombined.png - :width: 600 - :alt: Alternative text - -Visibilities data is fitted directly in the uv-plane, circumventing issues that arise when fitting a dirty image -such as correlated noise. This uses the non-uniform fast fourier transform algorithm -[PyNUFFT](https://github.com/jyhmiinlin/pynufft) to efficiently map the galaxy model images to the uv-plane. - -Checkout the ``autolens_workspace/*/interferometer`` package to get started. - - -Multi Gaussian Expansion (MGE) ------------------------------- - -An MGE decomposes the light of a galaxy into tens or hundreds of two dimensional Gaussians: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/mge.png - :width: 600 - :alt: Alternative text - -In the image above, 30 Gaussians are shown, where their sizes go from below the pixel scale (in order to resolve -point emission) to beyond the size of the galaxy (to capture its extended emission). - -An MGE is an extremely powerful way to model and subtract the light of the foreground lens galaxy in strong lens imaging, -and makes it possible to model the stellar mass of the lens galaxy in a way that is tied to its light. - -Scientific Applications include capturing departures from elliptical symmetry in the light of galaxies, providing a -flexible model to deblend the emission of point sources (e.g. quasars) from the emission of their host galaxy and -deprojecting the light of a galaxy from 2D to 3D. - -The following paper gives a detailed overview of MGEs and their applications in strong lensing: https://arxiv.org/abs/2403.16253 - -Checkout ``autolens_workspace/notebooks/features/multi_gaussian_expansion.ipynb`` to learn how to use an MGE. - - -Groups ------- - -The strong lenses we've discussed so far have just a single lens galaxy responsible for the lensing. Group-scale -strong lenses are systems where there two or more lens galaxies deflecting one or more background sources: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/group.png - :width: 600 - :alt: Alternative text - -**PyAutoLens** has built in tools for modeling group-scale lenses, with no limit on the number of -lens and source galaxies! - -Overviews of group and analysis are given in ``notebooks/overview/overview_9_groups.ipynb`` -The ``autolens_workspace/*/group`` package has example scripts for simulating datasets and lens modeling. - - -Multi-Wavelength ----------------- - -Modeling imaging datasets observed at different wavelengths (e.g. HST F814W and F150W) simultaneously or simultaneously -analysing imaging and interferometer data: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/g_image.png - :width: 600 - :alt: Alternative text - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/r_image.png - :width: 600 - :alt: Alternative text - -The appearance of the strong changes as a function of wavelength, therefore multi-wavelength analysis means we can learn -more about the different components in a galaxy (e.g a redder bulge and bluer disk) or when imaging and interferometer -data are combined, we can compare the emission from stars and dust. - -Checkout the ``autolens_workspace/*/multi`` package to get started, however combining datasets is a more advanced -feature and it is recommended you first get to grips with the core API. - - -Ellipse Fitting -_______________ - -Ellipse fitting is a technique which fits many ellipses to a galaxy's emission to determine its ellipticity, position -angle and centre, without assuming a parametric form for its light (e.g. like a Seisc profile): - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/ellipse.png - :width: 600 - :alt: Alternative text - -This provides complementary information to parametric light profile fitting, for example giving insights on whether -the ellipticity and position angle are constant with radius or if the galaxy's emission is lopsided. - -There are also multipole moment extensions to ellipse fitting, which determine higher order deviations from elliptical -symmetry providing even more information on the galaxy's structure. - -The following paper describes the technique in detail: https://arxiv.org/html/2407.12983v1 - -Checkout ``autolens_workspace/notebooks/features/ellipse_fitting.ipynb`` to learn how to use ellipse fitting. - - -Shapelets ---------- - -Shapelets are a set of orthogonal basis functions that can be combined the represent galaxy structures: - -.. image:: https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/shapelets.png - :width: 600 - :alt: Alternative text - -Scientific Applications include capturing symmetric structures in a galaxy which are more complex than a Sersic profile, -irregular and asymmetric structures in a galaxy like spiral arms and providing a flexible model to deblend the emission -of point sources (e.g. quasars) from the emission of their host galaxy. - -Checkout ``autolens_workspace/notebooks/features/shapelets.ipynb`` to learn how to use shapelets. - - -Operated Light Profiles ------------------------ - -An operated light profile is one where it is assumed to already be convolved with the PSF of the data, with the -``Moffat`` and ``Gaussian`` profiles common choices: - -They are used for certain scientific applications where the PSF convolution is known to be a significant effect and -the knowledge of the PSF allows for detailed modeling abd deblending of the galaxy's light. - -Checkout ``autogalaxy_workspace/notebooks/features/operated_light_profiles.ipynb`` to learn how to use operated profiles. - - -Sky Background --------------- - -When an image of a galaxy is observed, the background sky contributes light to the image and adds noise: - -For detailed studies of the outskirts of galaxies (e.g. stellar halos, faint extended disks), the sky background must be -accounted for in the model to ensure robust and accurate fits. - -Checkout ``autogalaxy_workspace/notebooks/features/sky_background.ipynb`` to learn how to use include the sky -background in your model. - -Other ------ - -- mass models (aris paper) -- Automated pipelines / SLaM. -- Dark matter subhalos. -- Graphical models. \ No newline at end of file +(overview-3-features)= + +# Features + +This page provides an overview of the advanced features of **PyAutoLens**. + +Firstly, brief one sentence descriptions of each feature are given, with more detailed descriptions below including +links to the relevant workspace examples. + +**Pixelizations**: Reconstructing the source galaxy on a mesh of pixels, to capture extremely irregular structures like spiral arms. + +**Point Sources**: Modeling point sources (e.g. quasars) observed in the strong lens imaging data. + +**Interferometry**: Modeling of interferometer data (e.g. ALMA, LOFAR) directly in the uv-plane. + +**Multi Gaussian Expansion (MGE)**: Decomposing the lens galaxy into hundreds of Gaussians, for a clean lens subtraction. + +**Groups**: Modeling group-scale strong lenses with multiple lens galaxies and multiple source galaxies. + +**Multi-Wavelength**: Simultaneous analysis of imaging and / or interferometer datasets observed at different wavelengths. + +**Ellipse Fitting**: Fitting ellipses to determine a lens galaxy's ellipticity, position angle and centre. + +**Shapelets**: Decomposing a galaxy into a set of shapelet orthogonal basis functions, capturing more complex structures than simple light profiles. + +**Operated Light Profiles**: Assuming a light profile has already been convolved with the PSF, for when the PSF is a significant effect. + +**Sky Background**: Including the background sky in the model to ensure robust fits to the outskirts of galaxies. + +## Pixelizations + +Pixelizations reconstruct the source galaxy's light on a pixel-grid. Unlike `LightProfile`'s, they are able to +reconstruct the light of non-symmetric, irregular and clumpy sources. + +The image below shows a pixelized source reconstruction of the strong lens SLACS1430+4105, where the source is +reconstructed on a Voronoi mesh adapted to the source morphology, revealing it to be a grand-design face on spiral +galaxy: + +```{image} https://github.com/Jammy2211/PyAutoLens/blob/main/files/imageaxis.png?raw=true +:alt: Alternative text +:width: 600 +``` + +A complete overview of pixelized source reconstructions can be found +at `notebooks/overview/overview_5_pixelizations.ipynb`. + +Chapter 4 of lectures describes pixelizations in detail and teaches users how they can be used to +perform lens modeling. + +## Point Sources + +There are many lenses where the background source is not extended but is instead a point-source, for example strongly +lensed quasars and supernovae. + +For these objects, we do not want to model the source using a light profile, which implicitly assumes an extended +surface brightness distribution. + +Instead, we assume that our source is a point source with a centre (y,x), and ray-trace triangles at iteratively +higher resolutions to determine the source's exact locations in the image-plane: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_0.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_1.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_2.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_3.png +:alt: Alternative text +:width: 400 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/point_4.png +:alt: Alternative text +:width: 400 +``` + +Note that the image positions above include the fifth central image of the strong lens, which is often not seen in +strong lens imaging data. It is easy to disable this image in the point source modeling. + +Checkout the `autolens_workspace/*/point_source` package to get started. + +## Interferometry + +Modeling of interferometer data from submillimeter (e.g. ALMA) and radio (e.g. LOFAR) observatories: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoGalaxy/main/paper/almacombined.png +:alt: Alternative text +:width: 600 +``` + +Visibilities data is fitted directly in the uv-plane, circumventing issues that arise when fitting a dirty image +such as correlated noise. This uses the non-uniform fast fourier transform algorithm +\[PyNUFFT\]() to efficiently map the galaxy model images to the uv-plane. + +Checkout the `autolens_workspace/*/interferometer` package to get started. + +## Multi Gaussian Expansion (MGE) + +An MGE decomposes the light of a galaxy into tens or hundreds of two dimensional Gaussians: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/mge.png +:alt: Alternative text +:width: 600 +``` + +In the image above, 30 Gaussians are shown, where their sizes go from below the pixel scale (in order to resolve +point emission) to beyond the size of the galaxy (to capture its extended emission). + +An MGE is an extremely powerful way to model and subtract the light of the foreground lens galaxy in strong lens imaging, +and makes it possible to model the stellar mass of the lens galaxy in a way that is tied to its light. + +Scientific Applications include capturing departures from elliptical symmetry in the light of galaxies, providing a +flexible model to deblend the emission of point sources (e.g. quasars) from the emission of their host galaxy and +deprojecting the light of a galaxy from 2D to 3D. + +The following paper gives a detailed overview of MGEs and their applications in strong lensing: + +Checkout `autolens_workspace/notebooks/features/multi_gaussian_expansion.ipynb` to learn how to use an MGE. + +## Groups + +The strong lenses we've discussed so far have just a single lens galaxy responsible for the lensing. Group-scale +strong lenses are systems where there two or more lens galaxies deflecting one or more background sources: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/group.png +:alt: Alternative text +:width: 600 +``` + +**PyAutoLens** has built in tools for modeling group-scale lenses, with no limit on the number of +lens and source galaxies! + +Overviews of group and analysis are given in `notebooks/overview/overview_9_groups.ipynb` +The `autolens_workspace/*/group` package has example scripts for simulating datasets and lens modeling. + +## Multi-Wavelength + +Modeling imaging datasets observed at different wavelengths (e.g. HST F814W and F150W) simultaneously or simultaneously +analysing imaging and interferometer data: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/g_image.png +:alt: Alternative text +:width: 600 +``` + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/r_image.png +:alt: Alternative text +:width: 600 +``` + +The appearance of the strong changes as a function of wavelength, therefore multi-wavelength analysis means we can learn +more about the different components in a galaxy (e.g a redder bulge and bluer disk) or when imaging and interferometer +data are combined, we can compare the emission from stars and dust. + +Checkout the `autolens_workspace/*/multi` package to get started, however combining datasets is a more advanced +feature and it is recommended you first get to grips with the core API. + +### Ellipse Fitting + +Ellipse fitting is a technique which fits many ellipses to a galaxy's emission to determine its ellipticity, position +angle and centre, without assuming a parametric form for its light (e.g. like a Seisc profile): + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/ellipse.png +:alt: Alternative text +:width: 600 +``` + +This provides complementary information to parametric light profile fitting, for example giving insights on whether +the ellipticity and position angle are constant with radius or if the galaxy's emission is lopsided. + +There are also multipole moment extensions to ellipse fitting, which determine higher order deviations from elliptical +symmetry providing even more information on the galaxy's structure. + +The following paper describes the technique in detail: + +Checkout `autolens_workspace/notebooks/features/ellipse_fitting.ipynb` to learn how to use ellipse fitting. + +## Shapelets + +Shapelets are a set of orthogonal basis functions that can be combined the represent galaxy structures: + +```{image} https://raw.githubusercontent.com/Jammy2211/PyAutoLens/main/docs/overview/images/overview_3/shapelets.png +:alt: Alternative text +:width: 600 +``` + +Scientific Applications include capturing symmetric structures in a galaxy which are more complex than a Sersic profile, +irregular and asymmetric structures in a galaxy like spiral arms and providing a flexible model to deblend the emission +of point sources (e.g. quasars) from the emission of their host galaxy. + +Checkout `autolens_workspace/notebooks/features/shapelets.ipynb` to learn how to use shapelets. + +## Operated Light Profiles + +An operated light profile is one where it is assumed to already be convolved with the PSF of the data, with the +`Moffat` and `Gaussian` profiles common choices: + +They are used for certain scientific applications where the PSF convolution is known to be a significant effect and +the knowledge of the PSF allows for detailed modeling abd deblending of the galaxy's light. + +Checkout `autogalaxy_workspace/notebooks/features/operated_light_profiles.ipynb` to learn how to use operated profiles. + +## Sky Background + +When an image of a galaxy is observed, the background sky contributes light to the image and adds noise: + +For detailed studies of the outskirts of galaxies (e.g. stellar halos, faint extended disks), the sky background must be +accounted for in the model to ensure robust and accurate fits. + +Checkout `autogalaxy_workspace/notebooks/features/sky_background.ipynb` to learn how to use include the sky +background in your model. + +## Other + +- mass models (aris paper) +- Automated pipelines / SLaM. +- Dark matter subhalos. +- Graphical models.