Miscellaneous Special Functions¶
AUTHORS:
 David Joyner (20061306): initial version
 David Joyner (20063010): bug fixes to pari wrappers of Bessel functions, hypergeometric_U
 William Stein (200802): Impose some sanity checks.
 David Joyner (20080423): addition of elliptic integrals
 Eviatar Bach (2013): making elliptic integrals symbolic
This module provides easy access to many of Maxima and PARI’s special functions.
Maxima’s special functions package (which includes spherical harmonic functions, spherical Bessel functions (of the 1st and 2nd kind), and spherical Hankel functions (of the 1st and 2nd kind)) was written by Barton Willis of the University of Nebraska at Kearney. It is released under the terms of the General Public License (GPL).
Support for elliptic functions and integrals was written by Raymond Toy. It is placed under the terms of the General Public License (GPL) that governs the distribution of Maxima.
Next, we summarize some of the properties of the functions implemented here.
Spherical harmonics: Laplace’s equation in spherical coordinates is:
\[\frac{1}{r^2} \frac{\partial}{\partial r} \left( r^2 \frac{\partial f}{\partial r} \right) + \frac{1}{r^2\sin\theta} \frac{\partial}{\partial \theta} \left( \sin\theta \frac{\partial f}{\partial \theta} \right) + \frac{1}{r^2\sin^2\theta} \frac{\partial^2 f}{\partial \varphi^2} = 0.\]Note that the spherical coordinates \(\theta\) and \(\varphi\) are defined here as follows: \(\theta\) is the colatitude or polar angle, ranging from \(0\leq\theta\leq\pi\) and \(\varphi\) the azimuth or longitude, ranging from \(0\leq\varphi<2\pi\).
The general solution which remains finite towards infinity is a linear combination of functions of the form
\[r^{1\ell} \cos (m \varphi) P_\ell^m (\cos{\theta} )\]and
\[r^{1\ell} \sin (m \varphi) P_\ell^m (\cos{\theta} )\]where \(P_\ell^m\) are the associated Legendre polynomials, and with integer parameters \(\ell \ge 0\) and \(m\) from \(0\) to \(\ell\). Put in another way, the solutions with integer parameters \(\ell \ge 0\) and \( \ell\leq m\leq \ell\), can be written as linear combinations of:
\[U_{\ell,m}(r,\theta , \varphi ) = r^{1\ell} Y_\ell^m( \theta , \varphi )\]where the functions \(Y\) are the spherical harmonic functions with parameters \(\ell\), \(m\), which can be written as:
\[Y_\ell^m( \theta , \varphi ) = (1)^m \sqrt{ \frac{(2\ell+1)}{4\pi} \frac{(\ellm)!}{(\ell+m)!} } \, e^{i m \varphi } \, P_\ell^m ( \cos{\theta} ) .\]The spherical harmonics obey the normalisation condition
\[\int_{\theta=0}^\pi\int_{\varphi=0}^{2\pi} Y_\ell^mY_{\ell'}^{m'*}\,d\Omega = \delta_{\ell\ell'}\delta_{mm'}\quad\quad d\Omega = \sin\theta\,d\varphi\,d\theta .\]The incomplete elliptic integrals (of the first kind, etc.) are:
\[\begin{split}\begin{array}{c} \displaystyle\int_0^\phi \frac{1}{\sqrt{1  m\sin(x)^2}}\, dx,\\ \displaystyle\int_0^\phi \sqrt{1  m\sin(x)^2}\, dx,\\ \displaystyle\int_0^\phi \frac{\sqrt{1mt^2}}{\sqrt(1  t^2)}\, dx,\\ \displaystyle\int_0^\phi \frac{1}{\sqrt{1  m\sin(x)^2\sqrt{1  n\sin(x)^2}}}\, dx, \end{array}\end{split}\]and the complete ones are obtained by taking \(\phi =\pi/2\).
REFERENCES:
 Abramowitz and Stegun: Handbook of Mathematical Functions, http://www.math.sfu.ca/~cbm/aands/
 Wikipedia article Spherical_harmonics
 Wikipedia article Helmholtz_equation
 Online Encyclopedia of Special Function http://algo.inria.fr/esf/index.html
AUTHORS:
 David Joyner and William Stein
Added 16022008 (wdj): optional calls to scipy and replace all ‘#random’ by ‘…’ (both at the request of William Stein)
Warning
SciPy’s versions are poorly documented and seem less accurate than the Maxima and PARI versions; typically they are limited by hardware floats precision.

class
sage.functions.special.
EllipticE
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return the incomplete elliptic integral of the second kind:
\[E(\varphi\,\,m)=\int_0^\varphi \sqrt{1  m\sin(x)^2}\, dx.\]EXAMPLES:
sage: z = var("z") sage: elliptic_e(z, 1) elliptic_e(z, 1) sage: # this is still wrong: must be abs(sin(z)) + 2*round(z/pi) sage: elliptic_e(z, 1).simplify() 2*round(z/pi) + sin(z) sage: elliptic_e(z, 0) z sage: elliptic_e(0.5, 0.1) # abs tol 2e15 0.498011394498832 sage: elliptic_e(1/2, 1/10).n(200) 0.4980113944988315331154610406...
See also
 Taking \(\varphi = \pi/2\) gives
elliptic_ec()
.  Taking \(\varphi = \operatorname{arc\,sin}(\operatorname{sn}(u,m))\)
gives
elliptic_eu()
.
REFERENCES:
 Taking \(\varphi = \pi/2\) gives

class
sage.functions.special.
EllipticEC
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return the complete elliptic integral of the second kind:
\[E(m)=\int_0^{\pi/2} \sqrt{1  m\sin(x)^2}\, dx.\]EXAMPLES:
sage: elliptic_ec(0.1) 1.53075763689776 sage: elliptic_ec(x).diff() 1/2*(elliptic_ec(x)  elliptic_kc(x))/x
See also
REFERENCES:

class
sage.functions.special.
EllipticEU
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return Jacobi’s form of the incomplete elliptic integral of the second kind:
\[E(u,m)= \int_0^u \mathrm{dn}(x,m)^2\, dx = \int_0^\tau {\sqrt{1m x^2}\over\sqrt{1x^2}}\, dx.\]where \(\tau = \mathrm{sn}(u, m)\).
Also,
elliptic_eu(u, m) = elliptic_e(asin(sn(u,m)),m)
.EXAMPLES:
sage: elliptic_eu (0.5, 0.1) 0.496054551286597
See also
REFERENCES:

class
sage.functions.special.
EllipticF
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return the incomplete elliptic integral of the first kind.
\[F(\varphi\,\,m)=\int_0^\varphi \frac{dx}{\sqrt{1  m\sin(x)^2}},\]Taking \(\varphi = \pi/2\) gives
elliptic_kc()
.EXAMPLES:
sage: z = var("z") sage: elliptic_f (z, 0) z sage: elliptic_f (z, 1).simplify() log(tan(1/4*pi + 1/2*z)) sage: elliptic_f (0.2, 0.1) 0.200132506747543
See also
REFERENCES:

class
sage.functions.special.
EllipticKC
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return the complete elliptic integral of the first kind:
\[K(m)=\int_0^{\pi/2} \frac{dx}{\sqrt{1  m\sin(x)^2}}.\]EXAMPLES:
sage: elliptic_kc(0.5) 1.85407467730137
See also
REFERENCES:

class
sage.functions.special.
EllipticPi
¶ Bases:
sage.symbolic.function.BuiltinFunction
Return the incomplete elliptic integral of the third kind:
\[\Pi(n, t, m) = \int_0^t \frac{dx}{(1  n \sin(x)^2)\sqrt{1  m \sin(x)^2}}.\]INPUT:
n
– a real number, called the “characteristic”t
– a real number, called the “amplitude”m
– a real number, called the “parameter”
EXAMPLES:
sage: N(elliptic_pi(1, pi/4, 1)) 1.14779357469632
Compare the value computed by Maxima to the definition as a definite integral (using GSL):
sage: elliptic_pi(0.1, 0.2, 0.3) 0.200665068220979 sage: numerical_integral(1/(10.1*sin(x)^2)/sqrt(10.3*sin(x)^2), 0.0, 0.2) (0.2006650682209791, 2.227829789769088e15)
REFERENCES:

class
sage.functions.special.
SphericalHarmonic
¶ Bases:
sage.symbolic.function.BuiltinFunction
Returns the spherical harmonic function \(Y_n^m(\theta, \varphi)\).
For integers \(n > 1\), \(m \leq n\), simplification is done automatically. Numeric evaluation is supported for complex \(n\) and \(m\).
EXAMPLES:
sage: x, y = var('x, y') sage: spherical_harmonic(3, 2, x, y) 1/8*sqrt(30)*sqrt(7)*cos(x)*e^(2*I*y)*sin(x)^2/sqrt(pi) sage: spherical_harmonic(3, 2, 1, 2) 1/8*sqrt(30)*sqrt(7)*cos(1)*e^(4*I)*sin(1)^2/sqrt(pi) sage: spherical_harmonic(3 + I, 2., 1, 2) 0.351154337307488  0.415562233975369*I sage: latex(spherical_harmonic(3, 2, x, y, hold=True)) Y_{3}^{2}\left(x, y\right) sage: spherical_harmonic(1, 2, x, y) 0

sage.functions.special.
elliptic_eu_f
(u, m)¶ Internal function for numeric evaluation of
elliptic_eu
, defined as \(E\left(\operatorname{am}(u, m)m\right)\), where \(E\) is the incomplete elliptic integral of the second kind and \(\operatorname{am}\) is the Jacobi amplitude function.EXAMPLES:
sage: from sage.functions.special import elliptic_eu_f sage: elliptic_eu_f(0.5, 0.1) mpf('0.49605455128659691')

sage.functions.special.
elliptic_j
(z)¶ Returns the elliptic modular \(j\)function evaluated at \(z\).
INPUT:
z
(complex) – a complex number with positive imaginary part.
OUTPUT:
(complex) The value of \(j(z)\).
ALGORITHM:
Calls the
pari
functionellj()
.AUTHOR:
John Cremona
EXAMPLES:
sage: elliptic_j(CC(i)) 1728.00000000000 sage: elliptic_j(sqrt(2.0)) 8000.00000000000 sage: z = ComplexField(100)(1,sqrt(11))/2 sage: elliptic_j(z) 32768.000... sage: elliptic_j(z).real().round() 32768 :: sage: tau = (1 + sqrt(163))/2 sage: (elliptic_j(tau.n(100)).real().round())^(1/3) 640320