Merge pull request #718 from Mathics3/gamma-and-elliptic-docs

rocky · web-flow · commit e7c64d41602d · 2023-01-03T23:38:50.000-05:00
Make a pass over these special functions
diff --git a/mathics/builtin/specialfns/elliptic.py b/mathics/builtin/specialfns/elliptic.py
@@ -1,8 +1,13 @@
 """
 Elliptic Integrals
 
-In integral calculus, an <url>:elliptic integral: https://en.wikipedia.org/wiki/Elliptic_integral</url>  is one of a number of related functions defined as the value of certain integral. Their name originates from their originally arising in connection with the problem of finding the arc length of an ellipse. These functions often are used in cryptography to encode and decode messages.
+In integral calculus, an <url>:elliptic integral:
+https://en.wikipedia.org/wiki/Elliptic_integral</url>  is one of a number of \
+related functions defined as the value of certain integral. Their name \
+originates from their originally arising in connection with the problem of \
+finding the arc length of an ellipse.
 
+These functions often are used in cryptography to encode and decode messages.
 """
 
 import sympy
@@ -17,7 +22,12 @@
 
 class EllipticE(SympyFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/EllipticE.html</url>
+    <url>
+    :Elliptic complete elliptic integral of the second kind:
+    https://en.wikipedia.org/wiki/Elliptic_integral#Complete_elliptic_integral_of_the_second_kind</url> (<url>:SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.elliptic_integrals.elliptic_e</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/EllipticE.html</url>)
 
     <dl>
       <dt>'EllipticE[$m$]'
@@ -46,19 +56,19 @@ class EllipticE(SympyFunction):
     summary_text = "elliptic integral of the second kind E(ϕ|m)"
     sympy_name = "elliptic_e"
 
-    def apply_default(self, args, evaluation):
+    def eval_default(self, args, evaluation):
         "%(name)s[args___]"
         evaluation.message("EllipticE", "argt", Integer(len(args.elements)))
 
-    def apply_m(self, m, evaluation):
+    def eval_m(self, m, evaluation):
         "%(name)s[m_]"
         sympy_arg = numerify(m, evaluation).to_sympy()
         try:
             return from_sympy(sympy.elliptic_e(sympy_arg))
         except:
             return
 
-    def apply_phi_m(self, phi, m, evaluation):
+    def eval_phi_m(self, phi, m, evaluation):
         "%(name)s[phi_, m_]"
         sympy_args = [numerify(a, evaluation).to_sympy() for a in (phi, m)]
         try:
@@ -69,7 +79,12 @@ def apply_phi_m(self, phi, m, evaluation):
 
 class EllipticF(SympyFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/EllipticF.html</url>
+    <url>
+    :Complete elliptic integral of the first kind:
+    https://en.wikipedia.org/wiki/Elliptic_integral#Complete_elliptic_integral_of_the_first_kind</url> (<url>:SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.elliptic_integrals.elliptic_f</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/EllipticF.html</url>)
 
     <dl>
       <dt>'EllipticF[$phi$, $m$]'
@@ -92,11 +107,11 @@ class EllipticF(SympyFunction):
     summary_text = "elliptic integral F(ϕ|m)"
     sympy_name = "elliptic_f"
 
-    def apply_default(self, args, evaluation):
+    def eval_default(self, args, evaluation):
         "%(name)s[args___]"
         evaluation.message("EllipticE", "argx", Integer(len(args.elements)))
 
-    def apply(self, phi, m, evaluation):
+    def eval(self, phi, m, evaluation):
         "%(name)s[phi_, m_]"
         sympy_args = [numerify(a, evaluation).to_sympy() for a in (phi, m)]
         try:
@@ -107,7 +122,12 @@ def apply(self, phi, m, evaluation):
 
 class EllipticK(SympyFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/EllipticK.html</url>
+    <url>
+    :Complete elliptic integral of the first kind:
+    https://en.wikipedia.org/wiki/Elliptic_integral#Complete_elliptic_integral_of_the_first_kind</url> (<url>:SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/EllipticK.html</url>)
 
     <dl>
       <dt>'EllipticK[$m$]'
@@ -128,16 +148,16 @@ class EllipticK(SympyFunction):
 
     attributes = A_NUMERIC_FUNCTION | A_LISTABLE | A_PROTECTED
     messages = {
-        "argx": "EllipticE called with `` arguments; 1 argument is expected.",
+        "argx": "EllipticK called with `` arguments; 1 argument is expected.",
     }
     summary_text = "elliptic integral of the first kind K(m)"
     sympy_name = "elliptic_k"
 
-    def apply_default(self, args, evaluation):
+    def eval_default(self, args, evaluation):
         "%(name)s[args___]"
         evaluation.message("EllipticK", "argx", Integer(len(args.elements)))
 
-    def apply(self, m, evaluation):
+    def eval(self, m, evaluation):
         "%(name)s[m_]"
         args = numerify(m, evaluation).get_sequence()
         sympy_args = [a.to_sympy() for a in args]
@@ -149,7 +169,12 @@ def apply(self, m, evaluation):
 
 class EllipticPi(SympyFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/EllipticPi.html</url>
+    <url>
+    :Complete elliptic integral of the third kind:
+    https://en.wikipedia.org/wiki/Elliptic_integral#Incomplete_elliptic_integral_of_the_third_kind</url> (<url>:SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.elliptic_integrals.elliptic_pi</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/EllipticPi.html</url>)
 
     <dl>
       <dt>'EllipticPi[$n$, $m$]'
@@ -172,11 +197,11 @@ class EllipticPi(SympyFunction):
     summary_text = "elliptic integral of the third kind P(n|m)"
     sympy_name = "elliptic_pi"
 
-    def apply_default(self, args, evaluation):
+    def eval_default(self, args, evaluation):
         "%(name)s[args___]"
         evaluation.message("EllipticPi", "argt", Integer(len(args.elements)))
 
-    def apply_n_m(self, n, m, evaluation):
+    def eval_n_m(self, n, m, evaluation):
         "%(name)s[n_, m_]"
         sympy_m = to_numeric_sympy_args(m, evaluation)[0]
         sympy_n = to_numeric_sympy_args(n, evaluation)[0]
@@ -185,7 +210,7 @@ def apply_n_m(self, n, m, evaluation):
         except:
             return
 
-    def apply_n_phi_m(self, n, phi, m, evaluation):
+    def eval_n_phi_m(self, n, phi, m, evaluation):
         "%(name)s[n_, phi_, m_]"
         sympy_n = to_numeric_sympy_args(n, evaluation)[0]
         sympy_phi = to_numeric_sympy_args(m, evaluation)[0]
diff --git a/mathics/builtin/specialfns/gamma.py b/mathics/builtin/specialfns/gamma.py
@@ -33,7 +33,12 @@
 
 class Beta(_MPMathMultiFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/Beta.html</url>
+    <url>
+    :Euler beta function:
+    https://en.wikipedia.org/wiki/Beta_function</url> (<url>:SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.beta_functions.beta</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/Beta.html</url>)
 
     <dl>
       <dt>'Beta[$a$, $b$]'
@@ -75,8 +80,8 @@ def from_sympy(self, sympy_name, elements):
         else:
             return Expression(Symbol(self.get_name()), *elements)
 
-    # sympy does not handles Beta for integer arguments.
-    def apply_2(self, a, b, evaluation):
+    # SymPy does not handles Beta for integer arguments.
+    def eval(self, a, b, evaluation):
         """Beta[a_, b_]"""
         if not (a.is_numeric() and b.is_numeric()):
             return
@@ -85,7 +90,7 @@ def apply_2(self, a, b, evaluation):
         gamma_a_plus_b = Expression(SymbolGamma, a + b)
         return gamma_a * gamma_b / gamma_a_plus_b
 
-    def apply_3(self, z, a, b, evaluation):
+    def eval_with_z(self, z, a, b, evaluation):
         """Beta[z_, a_, b_]"""
         # Here I needed to do that because the order of the arguments in WL
         # is different from the order in mpmath. Most of the code is the same
@@ -215,7 +220,7 @@ class Factorial2(PostfixOperator, _MPMathFunction):
     summary_text = "semi-factorial"
     options = {"Method": "Automatic"}
 
-    def apply(self, number, evaluation, options={}):
+    def eval(self, number, evaluation, options={}):
         "Factorial2[number_?NumberQ, OptionsPattern[%(name)s]]"
 
         try:
@@ -357,10 +362,11 @@ def from_sympy(self, sympy_name, elements):
 
 class LogGamma(_MPMathMultiFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/LogGamma.html</url>
-
-    In number theory the logarithm of the gamma function often appears. For positive real numbers, this can be evaluated as 'Log[Gamma[$z$]]'.
-
+    <url>:log-gamma function:
+    https://en.wikipedia.org/wiki/Gamma_function#The_log-gamma_function</url> (<url>
+    :SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.gamma_functions.loggamma</url>, <url>
+    :WMA:https://reference.wolfram.com/language/ref/LogGamma.html</url>)
     <dl>
       <dt>'LogGamma[$z$]'
       <dd>is the logarithm of the gamma function on the complex number $z$.
@@ -402,22 +408,53 @@ def get_sympy_names(self):
 
 class Pochhammer(SympyFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/Pochhammer.html</url>
+    <url>:Rising factorial:
+    https://en.wikipedia.org/wiki/Falling_and_rising_factorials</url> (<url>
+    :SymPy:
+    https://docs.sympy.org/latest/modules/functions/combinatorial.html#risingfactorial</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/Pochhammer.html</url>)
+
+    The Pochhammer symbol or rising factorial often appears in series \
+    expansions for hypergeometric functions.
 
-    The Pochhammer symbol or rising factorial often appears in series expansions for hypergeometric functions.
-    The Pochammer symbol has a definie value even when the gamma functions which appear in its definition are infinite.
+    The Pochammer symbol has a definite value even when the gamma \
+    functions which appear in its definition are infinite.
     <dl>
       <dt>'Pochhammer[$a$, $n$]'
-      <dd>is the Pochhammer symbol (a)_n.
+      <dd>is the Pochhammer symbol $a_n$.
     </dl>
 
-    >> Pochhammer[4, 8]
-     = 6652800
+    Product of the first 3 numbers:
+    >> Pochhammer[1, 3]
+     = 6
+
+    'Pochhammer[1, $n$]' is \
+    the same as Pochhammer[2, $n$-1] since 1 is a multiplicative identity.
+
+    >> Pochhammer[1, 3] == Pochhammer[2, 2]
+     = True
+
+    Although sometimes 'Pochhammer[0, $n$]' is taken to be 1, in Mathics it is 0:
+    >> Pochhammer[0, n]
+     = 0
+
+    Pochhammer uses Gamma for non-Integer values of $n$:
+
+    >> Pochhammer[1, 3.001]
+     = 6.00754
+
+    >> Pochhammer[1, 3.001] == Pochhammer[2, 2.001]
+     = True
+
+    >> Pochhammer[1.001, 3] == 1.001 2.001 3.001
+      = True
     """
 
     attributes = A_LISTABLE | A_NUMERIC_FUNCTION | A_PROTECTED
 
     rules = {
+        "Pochhammer[0, n_]": "0",  # Wikipedia says it should be 1 though.
         "Pochhammer[a_, n_]": "Gamma[a + n] / Gamma[a]",
         "Derivative[1,0][Pochhammer]": "(Pochhammer[#1, #2]*(-PolyGamma[0, #1] + PolyGamma[0, #1 + #2]))&",
         "Derivative[0,1][Pochhammer]": "(Pochhammer[#1, #2]*PolyGamma[0, #1 + #2])&",
@@ -428,7 +465,12 @@ class Pochhammer(SympyFunction):
 
 class PolyGamma(_MPMathMultiFunction):
     r"""
-    <url>:WMA link:https://reference.wolfram.com/language/ref/PolyGamma.html</url>
+    <url>:Polygamma function:
+    https://en.wikipedia.org/wiki/Polygamma_function</url> (<url>
+    :SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.gamma_functions.polygamma</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/PolyGamma.html</url>)
 
     PolyGamma is a meromorphic function on the complex numbers and is defined as a derivative of the logarithm of the gamma function.
     <dl>
@@ -464,13 +506,17 @@ class PolyGamma(_MPMathMultiFunction):
 
 
 class StieltjesGamma(SympyFunction):
-    r"""
-    <url>:WMA link:https://reference.wolfram.com/language/ref/StieltjesGamma.html</url>
+    """
+    <url>:Stieltjes constants:
+    https://en.wikipedia.org/wiki/Stieltjes_constants</url> (<url>
+    :SymPy:
+    https://docs.sympy.org/latest/modules/functions/special.html#sympy.functions.special.zeta_functions.stieltjes</url>, <url>
+    :WMA:
+    https://reference.wolfram.com/language/ref/StieltjesGamma.html</url>)
 
-    PolyGamma is a meromorphic function on the complex numbers and is defined as a derivative of the logarithm of the gamma function.
     <dl>
       <dt>'StieltjesGamma[$n$]'
-      <dd>returns the Stieljs contstant for $n$.
+      <dd>returns the Stieltjes constant for $n$.
 
       <dt>'StieltjesGamma[$n$, $a$]'
       <dd>gives the generalized Stieltjes constant of its parameters
