Doc updates part7 (#1314)

Subfactorial is not a mpmath function, SymPy only. SymPy can't handle
machine reals that are not integers. Add rule to handle lists.

Various summaries have been gone over to have them start with an active
verb when possible.

Author: rocky

mathics/builtin/colors/named_colors.py

@@ -33,7 +33,7 @@ def __init__(self, *args, **kwargs):
             "name": strip_context(self.get_name()),
             "text_name": text_name,
         }
-        self.summary_text = f"{text_name} color"
+        self.summary_text = f"specify {text_name} color"
         if self.__doc__ is None:
             self.__doc__ = doc
         else:

mathics/builtin/directories/user_directories.py

@@ -69,7 +69,7 @@ class UserBaseDirectory(Predefined):
     """
 
     name = "$UserBaseDirectory"
-    summary_text = "directory where user configurations are stored"
+    summary_text = "get directory where user configurations are stored"
 
     def evaluate(self, evaluation: Evaluation):
         return String(HOME_DIR + os.sep + ".mathics")

mathics/builtin/distance/numeric.py

@@ -300,7 +300,7 @@ class SquaredEuclideanDistance(Builtin):
      = 8
     """
 
-    summary_text = "square of the euclidean distance"
+    summary_text = "compute square of the Euclidean distance"
 
     def eval(self, u, v, evaluation: Evaluation):
         "SquaredEuclideanDistance[u_, v_]"

mathics/builtin/graphics.py

@@ -1413,7 +1413,7 @@ class Large(Builtin):
     </dl>
     """
 
-    summary_text = "large size style or option setting"
+    summary_text = "large size symbol for style or option setting"
 
 
 class Medium(Builtin):
@@ -1426,7 +1426,7 @@ class Medium(Builtin):
     </dl>
     """
 
-    summary_text = "medium size style or option setting"
+    summary_text = "medium size symbol for style or option setting"
 
 
 class Offset(Builtin):

mathics/builtin/intfns/combinatorial.py

@@ -295,19 +295,26 @@ class LucasL(SympyFunction):
     <dl>
       <dt>'LucasL[$n$]'
       <dd>gives the $n$th Lucas number.
+
+      <dt>'LucasL[$n$, $x$]'
+      <dd>gives the $n$th Lucas polynomical $L$_($x$).
     </dl>
 
     A list of the first five Lucas numbers:
     >> Table[LucasL[n], {n, 1, 5}]
      = {1, 3, 4, 7, 11}
+
     >> Series[LucasL[1/2, x], {x, 0, 5}]
      = 1 + 1 / 4 x + 1 / 32 x ^ 2 + (-1 / 128) x ^ 3 + (-5 / 2048) x ^ 4 + 7 / 8192 x ^ 5 + O[x] ^ 6
+
+    >> Plot[LucasL[1/2, x], {x, -5, 5}]
+     = -Graphics-
     """
 
     attributes = A_LISTABLE | A_NUMERIC_FUNCTION | A_PROTECTED | A_READ_PROTECTED
 
-    summary_text = "lucas number"
     sympy_name = "lucas"
+    summary_text = "get a Lucas number or polynomial"
 
     rules = {
         "LucasL[n_, 1]": "LucasL[n]",

mathics/builtin/numbers/calculus.py

@@ -1745,34 +1745,41 @@ def to_sympy(self, expr: Expression, **kwargs):
 
 class Series(Builtin):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/Series.html</url>
+     <url>:WMA link:https://reference.wolfram.com/language/ref/Series.html</url>
 
-    <dl>
-      <dt>'Series[$f$, {$x$, $x0$, $n$}]'
-      <dd>Represents the series expansion around '$x$=$x0$' up to order $n$.
-    </dl>
+     <dl>
+       <dt>'Series[$f$, {$x$, $x0$, $n$}]'
+       <dd>Represents the series expansion around '$x$=$x0$' up to order $n$.
+     </dl>
 
-    For elementary expressions, 'Series' returns the explicit power series as a 'SeriesData' expression:
-    >> Series[Exp[x], {x,0,2}]
-     = 1 + x + 1 / 2 x ^ 2 + O[x] ^ 3
-    >> % // FullForm
-     = SeriesData[x, 0, {1,1,Rational[1, 2]}, 0, 3, 1]
-    Replacing the variable by a value, the series will not be evaluated as
-    an expression, but as a 'SeriesData' object:
-    >> s = Series[Exp[x^2],{x,0,2}]
-     = 1 + x ^ 2 + O[x] ^ 3
-    >> s /. x->4
-     = 1 + 4 ^ 2 + O[4] ^ 3
-
-    'Normal' transforms a 'SeriesData' expression into a polynomial:
-    >> s // Normal
-     = 1 + x ^ 2
-    >> (s // Normal) /. x-> 4
-     = 17
-    >> Clear[s];
-    We can also expand over multiple variables
-    >> Series[Exp[x-y], {x, 0, 2}, {y, 0, 2}]
-     = (1 - y + 1 / 2 y ^ 2 + O[y] ^ 3) + (1 - y + 1 / 2 y ^ 2 + O[y] ^ 3) x + (1 / 2 + (-1 / 2) y + 1 / 4 y ^ 2 + O[y] ^ 3) x ^ 2 + O[x] ^ 3
+     For elementary expressions, 'Series' returns the explicit power series as a 'SeriesData' expression:
+     >> series = Series[Exp[x^2], {x,0,2}]
+      = 1 + x ^ 2 + O[x] ^ 3
+
+     The expression created is a 'SeriesData' object:
+     >> series // FullForm
+      = SeriesData[x, 0, {1,0,1}, 0, 3, 1]
+
+     Replacing $x$ with does a value produces another 'SeriesData' object:
+     >> series /. x->4
+      = 1 + 4 ^ 2 + O[4] ^ 3
+
+     'Normal' transforms a 'SeriesData' expression into a polynomial:
+     >> series // Normal
+      = 1 + x ^ 2
+     >> (series // Normal) /. x-> 4
+      = 17
+     >> Clear[series];
+
+     We can also expand over multiple variables:
+     >> Series[Exp[x-y], {x, 0, 2}, {y, 0, 2}]
+      = (1 - y + 1 / 2 y ^ 2 + O[y] ^ 3) + (1 - y + 1 / 2 y ^ 2 + O[y] ^ 3) x + (1 / 2 + (-1 / 2) y + 1 / 4 y ^ 2 + O[y] ^ 3) x ^ 2 + O[x] ^ 3
+
+    See also <url>
+     :'SeriesCoefficient':
+     /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/seriescoefficient/</url> and <url>
+     :'SeriesData':
+     /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/seriesdata/</url>.
 
     """
 
@@ -1782,7 +1789,7 @@ class Series(Builtin):
         "sspec": "Series specification `1` is not a list with three elements.",
     }
 
-    summary_text = "power series and asymptotic expansions"
+    summary_text = "compute power series and asymptotic expansions"
 
     def eval_series(self, f, x, x0, n, evaluation: Evaluation):
         """Series[f_, {x_Symbol, x0_, n_Integer}]"""
@@ -1810,13 +1817,24 @@ class SeriesCoefficient(Builtin):
 
     <dl>
       <dt>'SeriesCoefficient[$series$, $n$]'
-      <dd>Find the $n$th coefficient in the given $series$
+      <dd>Find the $n$th coefficient in the given $series$.
+
+      <dt>'SeriesCoefficient[$f$, {$x$, $x0$, $n$}]'
+      <dd>Find the ($x$-$x0$)^n in the expansion of $f$ about the point $x$=$x0$.
     </dl>
 
-    >> SeriesCoefficient[Series[Exp[Sin[x]], {x, 0, 10}], 8]
-     = 31 / 5760
-    >> SeriesCoefficient[Exp[-x], {x, 0, 5}]
-     = -1 / 120
+    First we list 5 terms of a series:
+    >> Series[Exp[Sin[x]], {x, 0, 5}]
+     = 1 + x + 1 / 2 x ^ 2 + (-1 / 8) x ^ 4 + (-1 / 15) x ^ 5 + O[x] ^ 6
+
+    Now get the $x$^4 coefficient:
+    >> SeriesCoefficient[%, 4]
+     = -1 / 8
+
+    Do the same thing, but without calling 'Series' first:
+    >> SeriesCoefficient[Exp[Sin[x]], {x, 0, 4}]
+     = -1 / 8
+
     >> SeriesCoefficient[2x, {x, 0, 2}]
      = 0
 
@@ -1826,14 +1844,19 @@ class SeriesCoefficient(Builtin):
      = 0
     >> SeriesCoefficient[SeriesData[x, c, Table[i^2, {i, 10}], 7, 17, 3], 17/3]
      = Indeterminate
+
+    See also <url>
+    :'Series':
+    /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/series/</url> and <url>
+    :'SeriesData':
+    /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/seriesdata/</url>.
     """
 
     attributes = A_PROTECTED
-    summary_text = "power series coefficient"
-
     rules = {
         "SeriesCoefficient[f_, {x_Symbol, x0_, n_Integer}]": "SeriesCoefficient[Series[f, {x, x0, n}], n]"
     }
+    summary_text = "compute power series coefficient"
 
     def eval(self, series: Expression, n: Rational, evaluation: Evaluation):
         """SeriesCoefficient[series_SeriesData, n_]"""
@@ -1856,25 +1879,48 @@ class SeriesData(Builtin):
     <url>:WMA link:https://reference.wolfram.com/language/ref/SeriesData.html</url>
 
     <dl>
-      <dt>'SeriesData[...]'
-      <dd>Represents a series expansion.
+      <dt>'SeriesData[$x$, $x0$, {$a0$, $a1$, ...}, $nmin$, $nmax$, $den$]'
+      <dd>produces a power series in the variable $x$ about point $x0$. The \
+      $ai$ are the coefficients of the power series. The powers of ($x$-$x0$) that appear \
+      are $nmin$/$den$, ($nmin$+1)/$den$, ..., $nmax$/$den$.
     </dl>
 
-    Sum of two series:
-    >> Series[Cosh[x],{x,0,2}] + Series[Sinh[x],{x,0,3}]
+    'SeriesData' is the 'Head' of expressions generated by 'Series':
+
+    >> series = Series[Cosh[x],{x,0,2}]
+     = 1 + 1 / 2 x ^ 2 + O[x] ^ 3
+
+    >> Head[series]
+     = SeriesData
+
+    >> series // FullForm
+     = SeriesData[x, 0, {1,0,Rational[1, 2]}, 0, 3, 1]
+
+    You can apply certain mathematical operations to 'SeriesData' objects to get \
+    new 'SeriesData' objects truncated to the appropriate order.
+
+    >> series + Series[Sinh[x],{x,0,3}]
      = 1 + x + 1 / 2 x ^ 2 + O[x] ^ 3
+
     >> Series[f[x],{x,0,2}] * g[w]
      = f[0] g[w] + g[w] f'[0] x + g[w] f''[0] / 2 x ^ 2 + O[x] ^ 3
-    The product of two series on the same neighbourhood of the same variable are multiplied
+
+    The product of two series on the same neighborhood of the same variable are multiplied:
     >> Series[Exp[-a x],{x,0,2}] * Series[Exp[-b x],{x,0,2}]
      = 1 + (-a - b) x + (a ^ 2 / 2 + a b + b ^ 2 / 2) x ^ 2 + O[x] ^ 3
     >> D[Series[Exp[-a x],{x,0,2}],a]
      = -x + a x ^ 2 + O[x] ^ 3
+
+    See also <url>
+    :'Series':
+    /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/series/</url> and <url>
+    :'SeriesCoefficient':
+    /doc/reference-of-built-in-symbols/integer-and-number-theoretical-functions/calculus/seriescoefficient/</url>.
     """
 
     # TODO: Implement sum, product and composition of series
 
-    summary_text = "power series of a variable about a point"
+    summary_text = "compute power series of a variable about a point"
 
     def eval_reduce(
         self, x, x0, data, nummin: Integer, nummax: Integer, den, evaluation: Evaluation

mathics/builtin/numbers/linalg.py

@@ -366,7 +366,7 @@ class LeastSquares(Builtin):
         "underdetermined": "Solving for underdetermined system not implemented.",
         "matrix": "Argument `1` at position `2` is not a non-empty rectangular matrix.",
     }
-    summary_text = "least square solver for linear problems"
+    summary_text = "compute least squares of linear problems"
 
     def eval(self, m, b, evaluation: Evaluation):
         "LeastSquares[m_, b_]"

mathics/builtin/numbers/numbertheory.py

@@ -1109,7 +1109,6 @@ class SquaresR(Builtin):
     """
 
     attributes = A_LISTABLE | A_PROTECTED | A_READ_PROTECTED
-    summary_text = "function to compute the sum of squares"
 
     rules = {
         "SquaresR[d_Integer, 0]": "1",
@@ -1118,3 +1117,4 @@ class SquaresR(Builtin):
         "SquaresR[6, n_Integer?Positive]": "4 Total[#^2 * (4 * KroneckerSymbol[-4, n/#] - KroneckerSymbol[-4, #]) & /@ Divisors[n]]",
         "SquaresR[8, n_Integer?Positive]": "16 Total[(-1)^(n + #) #^3 & /@ Divisors[n]]",
     }
+    summary_text = "compute the sum of squares"