Skip to content

refactor: merge adjacent docstring blocks so tutorial sections render as one cell #129

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Nov 4, 2026
Merged

refactor: merge adjacent docstring blocks so tutorial sections render as one cell #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 2 additions & 7 deletions notebooks/chapter_1_introduction/tutorial_0_visualization.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -275,13 +275,8 @@
"`subplot_shape_to_figsize_factor` controls subplot sizes. The per-call options above are enough for this lesson.\n",
"\n",
"**\ud83e\udd16 Ask AI:** Why can logarithmic colour scaling make faint structure easier to see without increasing its\n",
"signal-to-noise ratio?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"signal-to-noise ratio?\n",
"\n",
"__Overlays__\n",
"\n",
"Overlays place reference curves or positions on an image. The `lines=` argument draws curves, while\n",
Expand Down
9 changes: 2 additions & 7 deletions notebooks/chapter_1_introduction/tutorial_2_ray_tracing.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1049,13 +1049,8 @@
"physical units when needed.\n",
"\n",
"Tutorial 3 explains the cosmological distances behind this\n",
"conversion, as part of its optional mathematical discussion."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"conversion, as part of its optional mathematical discussion.\n",
"\n",
"__More Complexity__\n",
"\n",
"Our tracer currently contains one spherical lens and one source.\n",
Expand Down
72 changes: 16 additions & 56 deletions notebooks/chapter_1_introduction/tutorial_3_more_ray_tracing.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -260,13 +260,8 @@
"expressed in arcseconds. They are the displacement we subtract\n",
"from an image-plane position to obtain its source-plane position,\n",
"as we did in tutorial 2. We will continue to call them\n",
"\"deflection angles\" throughout this tutorial."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"\"deflection angles\" throughout this tutorial.\n",
"\n",
"__Convergence__\n",
"\n",
"Imagine adding up the lens galaxy's mass along our line of sight.\n",
Expand Down Expand Up @@ -348,13 +343,8 @@
"\n",
"This is an average over the enclosed area, rather than the\n",
"convergence at its edge. We will return to this connection\n",
"when we use the Einstein radius to measure the lens's mass."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"when we use the Einstein radius to measure the lens's mass.\n",
"\n",
"__Deflection Angles__\n",
"\n",
"The convergence describes the projected mass distribution.\n",
Expand Down Expand Up @@ -417,13 +407,8 @@
"source": [
"Each component changes sign across the lens centre. Together,\n",
"they describe the displacement we subtract from each\n",
"image-plane coordinate when tracing it to the source plane."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"image-plane coordinate when tracing it to the source plane.\n",
"\n",
"__The Lensing Potential__\n",
"\n",
"We can describe the same lens using a single scalar field:\n",
Expand Down Expand Up @@ -485,13 +470,8 @@
"source": [
"For this spherical lens, the potential has circular contours.\n",
"Its slope points radially outwards, matching the direction\n",
"of the deflection vectors used in our lens equation."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"of the deflection vectors used in our lens equation.\n",
"\n",
"We can check $\\boldsymbol{\\alpha} = \\nabla\\psi$ directly.\n",
"\n",
"First, we calculate the deflections using the mass profile's\n",
Expand Down Expand Up @@ -1037,13 +1017,8 @@
"The recovered angular radius should be close to the\n",
"1.6 arcseconds specified in our spherical mass profile.\n",
"Small differences arise from locating the critical curve\n",
"on a finite grid."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"on a finite grid.\n",
"\n",
"Two simple mass distributions have useful expressions\n",
"for the Einstein radius.\n",
"\n",
Expand Down Expand Up @@ -1075,13 +1050,8 @@
"They show how the Einstein radius connects the lens's mass\n",
"or velocity dispersion to the observer\u2013lens\u2013source geometry.\n",
"Our `IsothermalSph` profile specifies this angular scale\n",
"directly through its `einstein_radius` parameter."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"directly through its `einstein_radius` parameter.\n",
"\n",
"For a circular lens, the mean convergence inside the Einstein\n",
"radius equals one. Its enclosed projected mass is therefore\n",
"\n",
Expand Down Expand Up @@ -1125,13 +1095,8 @@
"For non-circular lenses, the effective Einstein radius remains\n",
"a useful summary of the lensing scale, but the circular\n",
"enclosed-mass relation is not generally exact. The detailed\n",
"mass model and surrounding matter still matter."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"mass model and surrounding matter still matter.\n",
"\n",
"__Time Delays__\n",
"\n",
"Different images of the same source follow different paths\n",
Expand Down Expand Up @@ -1206,13 +1171,8 @@
"same brightness variation can appear in different images\n",
"at different times. Measuring those delays provides\n",
"information about cosmological distances as well as\n",
"the lens's mass distribution."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"the lens's mass distribution.\n",
"\n",
"__Wrap Up__\n",
"\n",
"The quantities in this tutorial describe different aspects\n",
Expand Down
45 changes: 10 additions & 35 deletions notebooks/chapter_1_introduction/tutorial_4_point_sources.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -187,13 +187,8 @@
"between the appearances of the same variation in different images.\n",
"\n",
"A quasar or supernova can also sit inside a visible host galaxy. Such a lens may therefore contain both\n",
"unresolved point images and extended arcs."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"unresolved point images and extended arcs.\n",
"\n",
"__Point Source Tracer__\n",
"\n",
"PyAutoLens represents a point source using the `Point` profile in `al.ps`. This profile specifies its\n",
Expand Down Expand Up @@ -228,13 +223,8 @@
"contains several background sources.\n",
"\n",
"This tracer now contains the lens mass and the point-source position. Next, we will find the multiple image\n",
"positions that this combination predicts."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"positions that this combination predicts.\n",
"\n",
"__The Lens Equation__\n",
"\n",
"In Tutorial 2, we used the lens equation to map an image-plane coordinate $\\theta$ to a source-plane coordinate\n",
Expand All @@ -252,13 +242,8 @@
"\n",
"Finding these solutions is harder than evaluating the equation at a known coordinate. The deflection\n",
"$\\alpha(\\theta)$ changes with position, and several different coordinates can map to the same source. Simple\n",
"mass profiles have analytic solutions, but more general models require a numerical search."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"mass profiles have analytic solutions, but more general models require a numerical search.\n",
"\n",
"__Point Solver__\n",
"\n",
"The `PointSolver` divides the image-plane into triangles and ray-traces their corners to the source-plane. It\n",
Expand Down Expand Up @@ -330,13 +315,8 @@
"\n",
"Some mass profiles also produce a faint image near the lens centre. Our singular isothermal profile does not\n",
"produce a finite central image, so we should not interpret the magnification threshold as removing a fifth\n",
"image in this example."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"image in this example.\n",
"\n",
"__Multiple Images and Critical Curves__\n",
"\n",
"Let's overlay the solved positions on the compact extended source's image. The markers show where a point\n",
Expand Down Expand Up @@ -374,13 +354,8 @@
"image positions of a point source.\n",
"\n",
"**\ud83e\udd16 Ask AI:** For a fixed elliptical lens mass profile, why can moving a point source across a caustic change\n",
"the number of its multiple images?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"the number of its multiple images?\n",
"\n",
"__Magnifications__\n",
"\n",
"Each multiple image has its own magnification. For an unresolved image, we measure this through its total\n",
Expand Down
45 changes: 10 additions & 35 deletions notebooks/chapter_1_introduction/tutorial_5_data.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -331,13 +331,8 @@
"metadata": {},
"source": [
"**\ud83e\udd16 Ask AI:** How does blurring by a telescope's PSF affect our ability to\n",
"distinguish two nearby features in a gravitationally lensed arc?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"distinguish two nearby features in a gravitationally lensed arc?\n",
"\n",
"__Poisson Noise__\n",
"\n",
"Even if a galaxy's brightness remains constant, repeated observations do not\n",
Expand Down Expand Up @@ -591,13 +586,8 @@
"metadata": {},
"source": [
"**\ud83e\udd16 Ask AI:** Why does subtracting the mean background sky from an astronomical\n",
"image leave the sky's Poisson noise behind?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"image leave the sky's Poisson noise behind?\n",
"\n",
"The dataset also stores the PSF used to simulate the observation.\n",
"\n",
"For real observations, we need an estimate of the PSF, which can come from\n",
Expand Down Expand Up @@ -841,13 +831,8 @@
"Fluxes and time delays are optional: a dataset can contain only positions\n",
"and their uncertainties. For further examples of working with these data,\n",
"see the workspace's\n",
"[point-source examples](https://github.com/PyAutoLabs/autolens_workspace/blob/main/scripts/point_source/start_here.py)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[point-source examples](https://github.com/PyAutoLabs/autolens_workspace/blob/main/scripts/point_source/start_here.py).\n",
"\n",
"__Interferometer Data__\n",
"\n",
"We can also observe strong lenses at radio and submillimetre wavelengths using\n",
Expand Down Expand Up @@ -916,13 +901,8 @@
"\n",
"The dataset retains the visibilities for analysis. For further examples of\n",
"working with these data, see the workspace's\n",
"[interferometer examples](https://github.com/PyAutoLabs/autolens_workspace/tree/main/scripts/interferometer)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[interferometer examples](https://github.com/PyAutoLabs/autolens_workspace/tree/main/scripts/interferometer).\n",
"\n",
"__Weak Lensing Data__\n",
"\n",
"Away from the prominent arcs and rings, gravitational lensing can produce\n",
Expand Down Expand Up @@ -973,13 +953,8 @@
"\n",
"Chapter 4 returns to weak lensing in more detail. For further examples of\n",
"working with these data, see the workspace's\n",
"[weak-lensing examples](https://github.com/PyAutoLabs/autolens_workspace/blob/main/scripts/weak/start_here.py)."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"[weak-lensing examples](https://github.com/PyAutoLabs/autolens_workspace/blob/main/scripts/weak/start_here.py).\n",
"\n",
"__Group and Cluster Lenses__\n",
"\n",
"Strong lensing also occurs around groups and clusters of galaxies. Their\n",
Expand Down
36 changes: 8 additions & 28 deletions notebooks/chapter_1_introduction/tutorial_6_fitting.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -624,13 +624,8 @@
"the noise expected in that pixel. This is our next step.\n",
"\n",
"**\ud83e\udd16 Ask AI:** Why can a correct lens model leave larger absolute residuals\n",
"in bright arcs than in the faint background?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"in bright arcs than in the faint background?\n",
"\n",
"The size of a residual only becomes informative when compared with the\n",
"uncertainty in that pixel. A difference of 0.1 electrons per second could\n",
"be small in a noisy pixel but substantial in a precisely measured one.\n",
Expand Down Expand Up @@ -1060,13 +1055,8 @@
"cells in the Fitting section.\n",
"\n",
"**\ud83e\udd16 Ask AI:** Why might the parameters that maximise the likelihood of a\n",
"noisy simulated image differ slightly from those used to generate it?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"noisy simulated image differ slightly from those used to generate it?\n",
"\n",
"__Model Fitting__\n",
"\n",
"So far, we have compared parameter choices with a known reference model.\n",
Expand Down Expand Up @@ -1192,13 +1182,8 @@
"\n",
"To restore the original starting point, set both centres to `(1.0, 1.0)`,\n",
"and set `einstein_radius`, `effective_radius` and `intensity` to 1.0, then\n",
"rerun the cell."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"rerun the cell.\n",
"\n",
"You have now performed a simple manual search: choose parameters, predict\n",
"an image, compare it with the data, then use that comparison to choose\n",
"another set of parameters.\n",
Expand All @@ -1216,13 +1201,8 @@
"and quantify what we can infer from the data.\n",
"\n",
"**\ud83e\udd16 Ask AI:** How could changing both the source size and its intensity\n",
"make it difficult to determine either parameter by adjusting them manually?"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"make it difficult to determine either parameter by adjusting them manually?\n",
"\n",
"__Likelihood Function__\n",
"\n",
"Everything we have learned can now be put into a single sequence:\n",
Expand Down
Loading
Loading