expanding examples a bit more

notebooks/simple_light_curve.jl

@@ -1,5 +1,5 @@
 ### A Pluto.jl notebook ###
-# v0.12.20
+# v0.12.21
 
 using Markdown
 using InteractiveUtils
@@ -19,6 +19,7 @@ begin
 	Pkg.activate("..")
 	Pkg.instantiate()
 	using PlutoUI, Transits, Unitful, UnitfulRecipes, StatsPlots, LaTeXStrings
+	default(palette=:seaborn_colorblind)
 end
 
 # ╔═╡ 8e62dabc-70c4-11eb-07b3-d7ef7471240b
@@ -35,34 +36,70 @@ md"""
 In this notebook we will explore basic usage of [`Transits.jl`](https://juliaastro.github.io/Transits.jl/stable) by creating some simple light curves. Let's start by first setting up the notebook environment:
 """
 
-# ╔═╡ 9deb2688-70ba-11eb-0222-a7899e86523b
-default(palette=:seaborn_colorblind)
+# ╔═╡ a24d5b2a-754e-11eb-2bf5-3d5b7f4a0ec6
+md"""
+Now we need to gather the ingredients that make up a transit: 1) an orbit, and 2) a limb-darkening law. Let's start with describing the orbit of our exoplanetary system.
+"""
 
 # ╔═╡ b4d183f6-70c4-11eb-33be-cd86c368ae35
 md"## Orbit definition"
 
 # ╔═╡ 13e902e0-70bd-11eb-00a2-698092b29b2c
 md"""
-We will now create a `SimpleOrbit` object, which is a subtype of `AbstractOrbit`. This type accepts the following fields:
+We need to specify the parameters that define our orbital system. These parameters are stored in instances of the `AbstractOrbit` supertype. The most straightforward example of this is the `SimpleOrbit` subtype, so we will focus on using this subtype for the rest of this learning notebook. Let's see how to create this object next.
 """
 
-# ╔═╡ db44287e-70bd-11eb-31ea-a1130ca7077f
-fieldnames(SimpleOrbit)
-
 # ╔═╡ f80ed7c2-70bf-11eb-074a-e94f706e5c3b
 md"""
-Each field is already defined with default values, so we will go ahead and create our `SimpleOrbit` object with a period of 3 days and transit duration of 1 hour, which can be specified seamlessly with the external `Unitful.jl` package: 
+From the live docs, we see that `SimpleOrbit` accepts the following parameters:
+
+* `period` - The orbital period of the planets, nominally in days
+
+* `duration` - The duration of the transit, same units as period
+
+* `t0` - The midpoint time of the reference transit, same units as period
+
+* `b` - The impact parameter of the orbit
+
+* `r_star` - The radius of the star, nominally in solar radii
+
+Likewise, we see that `t0`, `b`, and `r_star` already have default values defined. The `;` in the function signature `SimpleOrbit(; period, duration, t0=0, b=0, r_star=1)` means that everything to the right is a keyword argument that we can define by name, so let's go ahead and do that to define an orbit with the following parameters:
+
+* `period` = 3 days
+* `duration` = 1 hour
+* `t0` = 0 days
+* `b` = 0
+* `r_star` = 1 (in units of solar radii)
 """
 
 # ╔═╡ a0bcc3c4-70b7-11eb-2a20-77644ebb50c1
 orbit = SimpleOrbit(period=3u"d", duration=1u"hr")
 
+# ╔═╡ 3086d2ae-7554-11eb-3638-2f94c1011bab
+md"""
+With our orbit defined, we now turn to our second and last ingredient: the limb darkening law.
+"""
+
 # ╔═╡ c63edf1e-70c4-11eb-0b86-b17548325707
 md"## Limb darkening definition"
 
-# ╔═╡ 65a7b174-70c4-11eb-12bb-1fbc53ee1764
+# ╔═╡ a9f8fa38-7554-11eb-36ad-a76d087d95c6
 md"""
-We can now use this as input into a limb darkening law, which we define next:
+Limb darkening is the natural phenomenon where a star's surface brightness appears to fall off as we look from its center to off-angle towards its limbs. The rate at which it falls off is described by a given limb darkening law. For this example, we are using a polynomial limb darkening law from [Agol, Luger, Foreman-Mackey (2020)](https://ui.adsabs.harvard.edu/abs/2020AJ....159..123A/abstract). This law uses analytically derived integrals, which makes it very fast and numerically accurate. There are other limb darkening laws which share a similar `AbstractLimbDark` interface. This interface lets us create composite laws like `IntegratedLimbDark` or `SecondaryLimbDark` with almost no effort. We will explore these laws and more in further notebooks.
+
+Pulling up the documentation for our particular law, `PolynomialLimbDark`, we see that it just accepts a single parameter `u`, the vector of limb darkening coefficients. These are defined such that:
+
+```math
+I(\mu) \propto -\sum_{i=0}^N u_i(1 - \mu)^i, \quad u_0 \equiv -1\quad,
+```
+
+where ``μ`` is a dimensionless parameter that varies from ``1`` to ``0`` as we move from the center to the edge of the star, as seen projected on the sky, ``N`` is the order of the polynomial, ``I`` is the intensity of the star, and ``u_i`` are the components of `u`.
+
+For this example, we will use a quadratic limb darkening law (N = 2):
+
+```math
+I(\mu) \propto -\sum_{i=0}^N u_i(1 - \mu)^i, \quad u_0 \equiv -1\quad,
+```
 """
 
 # ╔═╡ e7223d2a-70c7-11eb-24e4-af0ff49d42db
@@ -71,13 +108,8 @@ u = [0.4, 0.26] # Quadratic limb darkening
 # ╔═╡ 570e5624-70b8-11eb-1767-6911283302f5
 ld = PolynomialLimbDark(u)
 
-# ╔═╡ 40820d3a-70c5-11eb-04d1-3f32d0d453fe
-md"""
-For this example, we are using a Polynomial limb darkening law from [Agol, Luger, Foreman-Mackey (2020)](https://ui.adsabs.harvard.edu/abs/2020AJ....159..123A/abstract). This law is part of the `AbstractLimbDark` supertype, which includes the following laws as well that we will explore in other notebooks:
-"""
-
-# ╔═╡ 832cd21e-70c5-11eb-05b5-cd9a588751fc
-subtypes(Transits.AbstractLimbDark)
+# ╔═╡ 20a9e3fa-754f-11eb-0cb9-a5633210dd98
+@which PolynomialLimbDark(u)
 
 # ╔═╡ d0863d52-70c5-11eb-22f6-2fb13f25751c
 md"""
@@ -92,9 +124,30 @@ md"""
 With the orbit and limb darkening law defined, we can now compute light curves over time `t` for a range of different planet-to-star ratios `rprs`, which can be controlled with the slider below. We perform the computation of each light curve by directly passing our `AbstractOrbit` object to `ld`:
 """
 
+# ╔═╡ 0d935990-70c7-11eb-227a-274d8776916d
+note(
+md"""
+Technically we are passing this to the `compute` function, which is aliased to `ld` for convenience. A row-vector of planet-to-star ratios can be passed as well, and the required light curve computations will be automatically broadcasted:
+	
+```julia
+rprs = [0.0 0.05 0.1 0.15 0.2]
+fluxes = @. ld(orbit, t, rprs)
+```
+"""
+)
+
+# ╔═╡ b6a523e6-754b-11eb-112c-d3b1787d9818
+begin
+	rprs_range = 0:0.05:0.2
+	cs = Dict()
+	for (i ,rprs) in enumerate(rprs_range)
+		cs[rprs] = i
+	end
+end
+
 # ╔═╡ 6514b6ea-1374-4852-a4a7-ab8fa496d5d0
 md"""
-``R_\text{p}/R_* =`` $(@bind rprs Slider(0:0.05:0.2, show_value=true))
+``R_\text{p}/R_* =`` $(@bind rprs Slider(rprs_range, show_value=true))
 """
 
 # ╔═╡ 8be23852-70b8-11eb-30d3-b315246efe02
@@ -120,7 +173,7 @@ begin
 
 	# Show current model
 	fluxes = @. ld(orbit, t, rprs)
-	plot!(t, fluxes, c=1, label=rprs, legend=:bottomleft)
+	plot!(t, fluxes, c=cs[rprs], label=rprs, legend=:bottomleft)
 end
 
 # ╔═╡ a5989098-70c7-11eb-24d3-fb1c85b6f770
@@ -129,24 +182,19 @@ Not too bad!
 """
 
 # ╔═╡ af07537e-70bf-11eb-3c0a-592a55780281
-note(text) = Markdown.MD(Markdown.Admonition("note", "Note", [text]))
+tip(text) = Markdown.MD(Markdown.Admonition("tip", "Tip", [text]))
 
 # ╔═╡ ee993496-70bd-11eb-3374-83209e8150de
-note(
+tip(
 md"""
-These fields are described in the documentation, which can be readily pulled up in the Pluto notebook by selecting the `Live docs` tab below and then clicking on `SimpleOrbit` in the cell above. The `AbstractOrbit` supertype also inlcludes a `KeplerianOrbit` subtype that we will explore in the next notebook.
+Information about functions/types/etc. can be pulled up directly in Pluto by selecting the `Live docs` tab in the bottom right corner and then clicking on the item that you would like to explore. These live docs can also automatically be called by typing `?` in a cell, followed directly by what you would like to search for.
 """
 )
 
-# ╔═╡ 0d935990-70c7-11eb-227a-274d8776916d
-note(
+# ╔═╡ 9bb70f6a-7553-11eb-3ba2-5f70e3e63c11
+tip(
 md"""
-Technically we are passing this to the `compute` function, which is aliased to `ld` for convenience. A row-vector of planet-to-star ratios can be passed as well, and the required light curve computations will be automatically broadcasted:
-	
-```julia
-rprs = [0.0 0.05 0.1 0.15 0.2]
-fluxes = @. ld(orbit, t, rprs)
-```
+Parameters with units can be specified seamlessly with external [`Unitful.jl`](https://painterqubits.github.io/Unitful.jl/stable/) package using the `u"<unit here>"` string macro, and everything should just work™.
 """
 )
 
@@ -156,24 +204,25 @@ fluxes = @. ld(orbit, t, rprs)
 # ╟─8035d886-70c4-11eb-3212-fd9a6cc8de7e
 # ╟─b32ef55e-70bc-11eb-0c8e-f9f51a88a134
 # ╠═68a4138e-70b7-11eb-1ca7-399ee2f63a0e
-# ╠═9deb2688-70ba-11eb-0222-a7899e86523b
+# ╟─a24d5b2a-754e-11eb-2bf5-3d5b7f4a0ec6
 # ╟─b4d183f6-70c4-11eb-33be-cd86c368ae35
 # ╟─13e902e0-70bd-11eb-00a2-698092b29b2c
-# ╠═db44287e-70bd-11eb-31ea-a1130ca7077f
 # ╟─ee993496-70bd-11eb-3374-83209e8150de
 # ╟─f80ed7c2-70bf-11eb-074a-e94f706e5c3b
+# ╟─9bb70f6a-7553-11eb-3ba2-5f70e3e63c11
 # ╠═a0bcc3c4-70b7-11eb-2a20-77644ebb50c1
+# ╟─3086d2ae-7554-11eb-3638-2f94c1011bab
 # ╟─c63edf1e-70c4-11eb-0b86-b17548325707
-# ╟─65a7b174-70c4-11eb-12bb-1fbc53ee1764
+# ╠═a9f8fa38-7554-11eb-36ad-a76d087d95c6
 # ╠═e7223d2a-70c7-11eb-24e4-af0ff49d42db
 # ╠═570e5624-70b8-11eb-1767-6911283302f5
-# ╟─40820d3a-70c5-11eb-04d1-3f32d0d453fe
-# ╠═832cd21e-70c5-11eb-05b5-cd9a588751fc
+# ╠═20a9e3fa-754f-11eb-0cb9-a5633210dd98
 # ╟─d0863d52-70c5-11eb-22f6-2fb13f25751c
 # ╟─10065930-70c6-11eb-1fa7-551fd12f8e75
 # ╟─1fff2420-70c6-11eb-1bc0-9d35bd83a36a
 # ╟─0d935990-70c7-11eb-227a-274d8776916d
 # ╟─6514b6ea-1374-4852-a4a7-ab8fa496d5d0
-# ╠═8be23852-70b8-11eb-30d3-b315246efe02
+# ╟─b6a523e6-754b-11eb-112c-d3b1787d9818
+# ╟─8be23852-70b8-11eb-30d3-b315246efe02
 # ╟─a5989098-70c7-11eb-24d3-fb1c85b6f770
-# ╟─af07537e-70bf-11eb-3c0a-592a55780281
+# ╠═af07537e-70bf-11eb-3c0a-592a55780281