Work on understanding conventions

.gitignore

@@ -33,7 +33,7 @@ benchmark/results.md
 # Ignore my notes and settings
 /notes
 .vscode
-
+conventions.slides.json
 
 rotate.jl
 

Project.toml

@@ -26,6 +26,7 @@ Coverage = "1.6"
 DoubleFloats = "1"
 ForwardDiff = "0.10"
 FFTW = "1"
+FastDifferentiation = "0.3.17"
 FastTransforms = "0.12, 0.13, 0.14, 0.15, 0.16"
 Hwloc = "2, 3"
 LinearAlgebra = "1"
@@ -47,6 +48,7 @@ Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 Coverage = "a2441757-f6aa-5fb2-8edb-039e3f45d037"
 DoubleFloats = "497a8b3b-efae-58df-a0af-a86822472b78"
 FFTW = "7a1cc6ca-52ef-59f5-83cd-3a7055c09341"
+FastDifferentiation = "eb9bf01b-bf85-4b60-bf87-ee5de06c00be"
 FastTransforms = "057dd010-8810-581a-b7be-e3fc3b93f78c"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
 Hwloc = "0e44f5e4-bd66-52a0-8798-143a42290a1d"
@@ -61,4 +63,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestItemRunner = "f8b46487-2199-4994-9208-9a1283c18c0a"
 
 [targets]
-test = ["Aqua", "Coverage", "DoubleFloats", "FFTW", "FastTransforms", "ForwardDiff", "Hwloc", "LinearAlgebra", "Logging", "OffsetArrays", "ProgressMeter", "Quaternionic", "Random", "StaticArrays", "Test", "TestItemRunner"]
+test = ["Aqua", "Coverage", "DoubleFloats", "FFTW", "FastDifferentiation", "FastTransforms", "ForwardDiff", "Hwloc", "LinearAlgebra", "Logging", "OffsetArrays", "ProgressMeter", "Quaternionic", "Random", "StaticArrays", "Test", "TestItemRunner"]

docs/Project.toml

@@ -8,3 +8,4 @@ Quaternionic = "0756cd96-85bf-4b6f-a009-b5012ea7a443"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SphericalFunctions = "af6d55de-b1f7-4743-b797-0829a72cf84e"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+TestItems = "1c621080-faea-4a02-84b6-bbd5e436b8fe"

docs/make.jl

@@ -1,6 +1,6 @@
 # Run with
-#   time julia --project=. make.jl && julia --project=. -e 'using LiveServer; serve(dir="build")'
-# assuming you are in this `docs` directory (otherwise point the project argument here)
+#   julia -t 4 --project=. scripts/docs.jl
+# assuming you are in this top-level directory
 
 using SphericalFunctions
 using Documenter
@@ -21,7 +21,7 @@ makedocs(
         prettyurls = !("local" in ARGS),  # Use clean URLs, unless built as a "local" build
         edit_link = "main",  # Link out to "main" branch on github
         canonical = "https://moble.github.io/SphericalFunctions.jl/stable/",
-        assets = String["assets/citations.css"],
+        assets = String["assets/citations.css", "assets/extras.css"],
     ),
     pages = [
         "index.md",
@@ -34,6 +34,10 @@ makedocs(
             "internal.md",
             "functions.md",
         ],
+        "Conventions" => [
+            "conventions/conventions.md",
+            "conventions/comparisons.md",
+        ],
         "Notes" => map(
             s -> "notes/$(s)",
             sort(readdir(joinpath(@__DIR__, "src/notes")))

docs/notebooks/condon_shortley_expression.py

@@ -0,0 +1,108 @@
+import marimo
+
+__generated_with = "0.9.20"
+app = marimo.App(width="medium")
+
+
+@app.cell(hide_code=True)
+def __(mo):
+    mo.md(
+        r"""
+        Eq. (15) of Sec. 4³ (page 52) of Condon and Shortley (1935) defines the polar portion of the spherical harmonic function as
+
+        \begin{equation}
+        \Theta(\ell, m) = (-1)^\ell \sqrt{\frac{2\ell+1}{2} \frac{(\ell+m)!}{(\ell-m)!}}
+        \frac{1}{2^\ell \ell!} \frac{1}{\sin^m\theta}
+        \frac{d^{\ell-m}}{d(\cos\theta)^{\ell-m}} \sin^{2\ell}\theta.
+        \end{equation}
+
+        A footnote gives the first few values through $\ell=3$.  I explicitly test these explicit forms in [`SphericalFunctions.jl`](https://github.com/moble/SphericalFunctions.jl)`/test/conventions/condon_shortley.jl`.  Here, I want to verify that they are correct.
+
+        Visually comparing, and accounting for some minor differences in simplification, I find that the expressions in the book are correct.  I also use the explicit expressions — as implemented in the test code and translated by AI — to check that sympy can simplify the difference to 0.
+        """
+    )
+    return
+
+
+@app.cell
+def __():
+    from IPython.display import display
+    import marimo as mo
+    import sympy
+    from sympy import S
+
+    θ = sympy.symbols("θ", real=True)
+
+    def ϴ(ℓ, m):
+        cosθ = sympy.symbols("cosθ", real=True)
+        return (
+            (-1)**ℓ
+            * sympy.sqrt(
+                ((2*ℓ+1) / 2)
+                * (sympy.factorial(ℓ+m) / sympy.factorial(ℓ-m))
+            )
+            * (1 / (2**ℓ * sympy.factorial(ℓ)))
+            * (1 / sympy.sin(θ)**m)
+            #* sympy.diff(sympy.sin(θ)**(2*ℓ), sympy.cos(θ), ℓ-m)  # Can't differentiate wrt cos(θ), so we use a dummy and substitute
+            * sympy.diff((1 - cosθ**2)**ℓ, cosθ, ℓ-m).subs(cosθ, sympy.cos(θ))
+        ).simplify()
+    return S, display, mo, sympy, Θ, θ
+
+
+@app.cell
+def __(S, display, Θ):
+    for ℓ in range(4):
+        for m in range(-ℓ, ℓ+1):
+            display(ℓ, m, ϴ(S(ℓ), S(m)))
+    return l, m
+
+
+@app.cell
+def __(S, sympy, Θ, θ):
+    def compare_explicit_expression(ℓ, m):
+        if (ℓ, m) == (0, 0):
+            expression = sympy.sqrt(1/S(2))
+        elif (ℓ, m) == (1, 0):
+            expression = sympy.sqrt(3/S(2)) * sympy.cos(θ)
+        elif (ℓ, m) == (2, 0):
+            expression = sympy.sqrt(5/S(8)) * (2*sympy.cos(θ)**2 - sympy.sin(θ)**2)
+        elif (ℓ, m) == (3, 0):
+            expression = sympy.sqrt(7/S(8)) * (2*sympy.cos(θ)**3 - 3*sympy.cos(θ)*sympy.sin(θ)**2)
+        elif (ℓ, m) == (1, 1):
+            expression = -sympy.sqrt(3/S(4)) * sympy.sin(θ)
+        elif (ℓ, m) == (1, -1):
+            expression = sympy.sqrt(3/S(4)) * sympy.sin(θ)
+        elif (ℓ, m) == (2, 1):
+            expression = -sympy.sqrt(15/S(4)) * sympy.cos(θ) * sympy.sin(θ)
+        elif (ℓ, m) == (2, -1):
+            expression = sympy.sqrt(15/S(4)) * sympy.cos(θ) * sympy.sin(θ)
+        elif (ℓ, m) == (3, 1):
+            expression = -sympy.sqrt(21/S(32)) * (4*sympy.cos(θ)**2*sympy.sin(θ) - sympy.sin(θ)**3)
+        elif (ℓ, m) == (3, -1):
+            expression = sympy.sqrt(21/S(32)) * (4*sympy.cos(θ)**2*sympy.sin(θ) - sympy.sin(θ)**3)
+        elif (ℓ, m) == (2, 2):
+            expression = sympy.sqrt(15/S(16)) * sympy.sin(θ)**2
+        elif (ℓ, m) == (2, -2):
+            expression = sympy.sqrt(15/S(16)) * sympy.sin(θ)**2
+        elif (ℓ, m) == (3, 2):
+            expression = sympy.sqrt(105/S(16)) * sympy.cos(θ) * sympy.sin(θ)**2
+        elif (ℓ, m) == (3, -2):
+            expression = sympy.sqrt(105/S(16)) * sympy.cos(θ) * sympy.sin(θ)**2
+        elif (ℓ, m) == (3, 3):
+            expression = -sympy.sqrt(35/S(32)) * sympy.sin(θ)**3
+        elif (ℓ, m) == (3, -3):
+            expression = sympy.sqrt(35/S(32)) * sympy.sin(θ)**3
+        else:
+            raise ValueError(f"Unknown {ℓ=}, {m=}")
+        return sympy.simplify(ϴ(S(ℓ), S(m)) - expression) == 0
+
+
+    for _ℓ in range(4):
+        for _m in range(-_ℓ, _ℓ+1):
+            print((_ℓ, _m), "  \t", compare_explicit_expression(_ℓ, _m))
+
+    return (compare_explicit_expression,)
+
+
+if __name__ == "__main__":
+    app.run()