# legendre
连带 Legendre 函数
函数库: TyMath
# 语法
P = legendre(n,X)
P = legendre(n,X,normalization)
# 说明
Y = legendre(n,X) X中的每个元素计算阶数为n、级数为m=0,1,...,n 时的连带 Legendre 函数。示例
Y = legendre(n,X,normalization ) 计算连带 Legendre 函数的归一化版本。normalization 可以是 "unnorm"（默认值）、"sch" 或 "norm"。 示例
# 示例
向量的连带 Legendre 函数值
使用 legendre 函数对向量进行运算，然后检查输出的格式。
计算向量的二阶 Legendre 函数值。
using TyMath
deg = 2
x = [0,0.1,0.2]
P = legendre(deg,x)
P = 3×3 Matrix{Float64}:
-0.5 -0.485 -0.44
-0.0 -0.298496 -0.587878
3.0 2.97 2.88
输出的格式如下：
- 每行包含不同 m（连带 Legendre 函数的阶）值的函数值
- 每列包含不同 x 值的函数值
二阶连带 Legendre 函数
因此，
该结果与 P(1,1) = -0.5000 一致。
比较 Legendre 归一化
计算几种归一化情况下的连带 Legendre 函数值。
计算非归一化一阶 Legendre 函数值
using TyMath
x = 0:0.2:1
n = 1
P_unnorm = legendre(n,x)
P_unnorm = 2×6 Matrix{Float64}:
0.0 0.2 0.4 0.6 0.8 1.0
-1.0 -0.979796 -0.916515 -0.8 -0.6 -0.0
接下来，计算 Schmidt 半归一化函数值。与非归一化值相比，当 m>0 时，Schmidt 形式的值都乘以缩放因子：
对于第一行，这两个归一化是相同的，因为 m=0。对于第二行，每个值都乘以缩放常量 -1。
P_sch = legendre(n,x,"sch")
P_sch = 2×6 Matrix{Float64}:
0.0 0.2 0.4 0.6 0.8 1.0
1.0 0.979796 0.916515 0.8 0.6 0.0
C1 = (-1) * sqrt(2 * factorial(0) / factorial(2) )
C1 = -1.0
最后，计算完全归一化的函数值。与非归一化值相比，完全归一化形式的值都乘以缩放因子：
此缩放因子适用于 m 的所有值，因此第一行和第二行具有不同缩放因子。
P_norm = legendre(n,x,"norm")
P_norm = 2×6 Matrix{Float64}:
0.0 0.244949 0.489898 0.734847 0.979796 1.22474
0.866025 0.848528 0.793725 0.69282 0.519615 0.0
Cm0 = sqrt((3/2))
Cm0 = 1.224744871391589
Cm1 = (-1) * sqrt((3/2)/2)
Cm1 = -0.8660254037844386
计算球谐函数
球谐函数出现在拉普拉斯方程的解中，用于表示在球面上定义的函数。使用 legendre 来计算和可视化
球谐函数的方程包括 Legendre 函数的一个项以及一个复指数：
首先，创建一个由值组成的网格，以表示 0≤θ≤π （余纬度角）和 0≤ϕ≤2π（方位角）的所有组合。此处，余纬度 θ 的范围从 0 度（位于北极）到 π/2 度（位于赤道），到 π 度（位于南极）。
using TyMath
using TyBase
using TyPlot
dx = pi/60;
col = 0:dx:pi;
az = 0:dx:2*pi;
phi,theta = meshgrid2(az,col);
计算l=3的网格上的
l = 3;
Plm = legendre(l,cos.(theta));
由于 legendre 为 m 的所有值计算答案，因此 Plm 会包含一些额外的函数值。提取 m=2 的值并丢弃其余值。使用 reshape 函数将结果定向为与 phi 和 theta 具有相同大小的矩阵。
m = 2;
if l != 0
Plm = reshape(Plm[m+1,:,:],size(phi))
end
计算
a = (2*l+1)*factorial(l-m);
b = 4*pi*factorial(l+m);
C = sqrt(a/b);
Ylm = C .* Plm .*exp.(im*m*phi);
将球面坐标转换为笛卡尔坐标。此处，π/2−θ 成为纬度角，范围从 π/2（位于北极），到 0 度（位于赤道），再到 −π/2 度（位于南极）。使用正负实数值绘制
Xm,Ym,Zm = sph2cart(phi,pi/2 .- theta,abs.(real.(Ylm)))
surf(Xm,Ym,Zm)
title(raw"$Y_3^2$球谐函数")
# 输入参数
n - Legendre 函数的阶标量 | 向量 | 矩阵 | 多维数组
Legendre 函数的阶，指定为正整数。对于指定的阶，legendre 计算 m 表示的所有级数（从 m = 0 到 m = n）的
示例： legendre(2,X)
X - 输入值
输入值，指定为由 [-1,1] 范围内的实数值组成的标量、向量、矩阵或多维数组。例如，对于球谐函数，通常使用 X = cos(theta) 作为输入值来计算
示例： legendre(2,cos(theta))
数据类型： Int | Float64 | Float32 | Float16 | UInt
normalization - 归一化类型"unnorm"（默认） | "sch" | "norm"
归一化类型，指定为下列值之一。
| 值 | 结果 |
|---|---|
| "unnorm" | 连带 Legendre 函数 |
| "sch" | Schmidt 半归一化连带 Legendre 函数 |
| "norm" | 完全归一化的连带 Legendre 函数 |
示例： legendre(n,X,"sch")
# 输出参数
P - 连带 Legendre 函数值标量 | 向量 | 矩阵 | 多维数组
连带 Legendre 函数值，返回为标量、向量、矩阵或多维数组。P 的归一化取决于 normalization 的值。
P 的大小取决于 X 的大小：
- 如果 X 是向量，则 P 是大小为 (n+1)×length(X) 的矩阵。P[m+1,i] 条目是在 X[i] 计算的阶数为 n、级数为 m 的连带 Legendre 函数；
- 通常，P 比 X 多一个维度，每个元素 P[m+1,i,j,k,...] 都包含在 X[i,j,k,...] 计算的阶数为 n 和阶数为 m 的连带 Legendre 函数。
# 局限性
非归一化的连带 Legendre 函数的值溢出 n > 150 的双精度数范围和 n > 28 的单精度数范围。此溢出导致 Inf 和 NaN 值。对于大于这些阈值的阶，请考虑改用 "sch" 或 "norm" 归一化。
# 详细信息
连带 Legendre 函数
连带 Legendre 函数
n 是整数阶，m 是连带 Legendre 函数的整数级数，满足 0≤m≤n。
连带 Legendre 函数
它们是根据 Legendre 多项式 P_n(x) 的导数定义的，它们是由下式给出的解的子集：
前 n 个 Legendre 多项式为：
| n 的值 | |
|---|---|
| 0 | P_0(x) = 1 |
| 1 | p_1(x) = x |
| 2 |
Schmidt 半归一化连带 Legendre 函数
Schmidt 半归一化连带 Legendre 函数与非归一化连带 Legendre 函数
完全归一化的连带 Legendre 函数
完全归一化的连带 Legendre 函数按如下方式进行归一化：
归一化函数
# 算法
legendre 在 m 中使用三项后向递归关系。此递归基于 Schmidt 半归一化连带 Legendre 函数
它们与 Schmidt 形式的关系如下：
# 参考文献
[1] Abramowitz, M. and I. A. Stegun, Handbook of Mathematical Functions, Dover Publications, 1965, Ch.8.
[2] Jacobs, J. A., Geomagnetism, Academic Press, 1987, Ch.4.