Start noting broad changes (#1308)

Fold in some public comments on release changes. Another pass at new builtin function docstrings.

Author: rocky

CHANGES.rst

@@ -1,6 +1,39 @@
 CHANGES
 =======
 
+This release is to get out some of the major changes that have gone on
+already in advance of redoing Boxing and Formatting.
+
+Operators are now controlled from a new operators YAML table from the
+``mathics-scanner`` repository. A pass was made over the Mathics parser
+to handle box operators more properly. More work is needed here.
+
+We started adding more debugging capabilites:
+
+* ``Breakpoint[]``
+* ``Stack[]``, and
+* ``Trace[]``
+
+And in the ``Mathics3-Trepan`` repository:
+
+* ``DebugActivate[]``
+* ``Debugger[]``, and
+* ``TraceActivate[]``
+
+This code is very much alpha quality, but it greatly improves the
+ability to debug problems in loading existing packages written from
+Mathematica. So packages ``BoolEval`` and ``CleanSlate`` were added to
+the repostiory.
+
+Also as a result of the improved ability to debug Mathics3, we now
+provide a version of Rubi 4.17 using git submodules . To use this you
+will need a patched version of ``stopit``.  Aravindh Krishnamoorthy
+led the initial port of Rubi.
+
+David A. Roberts worked on ensuring Mathics3 runs on pyodide and
+contributed a number of new Built-in Functions that are found in `The
+On-Line Encyclopedia of Integer Sequences (OEIS) <https://oeis.org/>`_
+
 
 New Builtins
 ++++++++++++
@@ -13,6 +46,7 @@ New Builtins
 * ``SetEnvironment``
 * ``SequenceForm``
 * ``Stack``
+* ``Trace``
 
 By `@davidar <https://github.com/davidar>`_:
 
@@ -45,8 +79,8 @@ By `@davidar <https://github.com/davidar>`_:
 
 * ``--post-mortem`` option added which will go into the `trepan3k debugger <https https://pypi.org/project/trepan3k/>`_ on an unrecoverable error.
 
-Compatibility
--------------
+WMA Compatibility
+-----------------
 
 * ``GetEnvironment`` expanded to handle ``[]`` and ``{var1, var2,...}`` forms
 * The system ``packages`` directory has been renamed ``Packages`` to conformance with WMA.
@@ -57,13 +91,6 @@ Internals
 
 * Operator information has been gone over and is picked up from JSON
 tables produced from the Mathics Scanner project.
-* Patterns in ``eval_`` and ``format_`` methods of builtin classes
-  parses patterns in docstrings of the form
-  ``Symbol: Expr`` as ``Pattern[Symbol, Expr]``.
-  To specify associated format in ``format_`` methods the
-  docstring, the list of format must be wrapped in parenthesis, like
-  ``(InputForm,): Definitions[...]`` instead of just ``InputForm: Definitions[...]``.
-
 
 Performance
 -----------
@@ -78,6 +105,13 @@ API incompatibility
 * The signature of the ``Definition.__init__`` now receives a single dict parameter instead of the several `*values` parameters.
 * Rule positions in ``Definition.{get|set}_values`` now includes the word ``values``. For example ``pos="up"`` now is ``pos="upvalues"``.
 * ``Definitions.get_ownvalue`` now returns a ``BaseElement`` instead of a ``BaseRule`` object.
+* Patterns in ``eval_`` and ``format_`` methods of builtin classes
+  parses patterns in docstrings of the form
+  ``Symbol: Expr`` as ``Pattern[Symbol, Expr]``.
+  To specify associated format in ``format_`` methods the
+  docstring, the list of format must be wrapped in parenthesis, like
+  ``(InputForm,): Definitions[...]`` instead of just ``InputForm: Definitions[...]``.
+
 
 
 Bugs

README.rst

@@ -1,16 +1,20 @@
 Welcome to Mathics Core!
 ========================
 
-|Pypi Installs| |Latest Version| |Supported Python Versions|
+|PyPI Installs| |Latest Version| |Supported Python Versions|
 
 |Packaging status|
 
 
 Mathics3 is a general-purpose computer algebra system (CAS).
 
-However this repository contains just the Python modules for WL Built-in functions, variables, core primitives, e.g. Symbol, a parser to create Expressions, and an evaluator to execute them.
+However this repository contains just the Mathics3 Kernel: Python
+modules for WL Built-in functions, variables, core primitives,
+e.g. Symbol, a parser to create Expressions, and an evaluator to
+execute them.
 
-The home page for Mathics is https://mathics.org where you will find a list of screenshots and components making up the system.
+The home page for Mathics is https://mathics.org where you will find a
+list of screenshots and components making up the system.
 
 Installing
 ----------
@@ -22,15 +26,15 @@ See the `Installing Mathics3 <https://mathics-development-guide.readthedocs.io/e
 Running:
 --------
 
-Mathics3, the core library comes with a very simple command-line program called ``mathics``::
+Mathics3 Kernel comes with a very simple command-line program called ``mathics``::
 
   $ mathics
 
-  Mathics 5.0.3dev0
-  on CPython 3.8.12 (heads/v2.3.4.1_release:4a6b4d3504, Jun  3 2022, 15:46:12)
-  using SymPy 1.10.1, mpmath 1.2.1, numpy 1.23.1, cython 0.29.30
+  Mathics 8.0.0
+  on CPython 3.12.8 (main, Dec  9 2024, 11:38:23) [GCC 13.2.0]
+  using SymPy 1.13.3, mpmath 1.3.0, numpy 1.26.4, cython Not installed
 
-  Copyright (C) 2011-2022 The Mathics Team.
+ Copyright (C) 2011-2025 The Mathics3 Team.
   This program comes with ABSOLUTELY NO WARRANTY.
   This is free software, and you are welcome to redistribute it
   under certain conditions.
@@ -60,14 +64,12 @@ License
 
 Mathics is released under the GNU General Public License Version 3 (GPL3).
 
-.. |Travis| image:: https://secure.travis-ci.org/Mathics3/mathics-core.svg?branch=master
-.. _Travis: https://travis-ci.org/Mathics3/mathics-core
 .. _PyPI: https://pypi.org/project/Mathics/
 .. |mathicsscript| image:: https://github.com/Mathics3/mathicsscript/blob/master/screenshots/mathicsscript1.gif
 .. |mathicssserver| image:: https://mathics.org/images/mathicsserver.png
 .. |Latest Version| image:: https://badge.fury.io/py/Mathics3.svg
 		 :target: https://badge.fury.io/py/Mathics3
-.. |Pypi Installs| image:: https://pepy.tech/badge/Mathics3
+.. |PyPI Installs| image:: https://pepy.tech/badge/Mathics3
 .. |Supported Python Versions| image:: https://img.shields.io/pypi/pyversions/Mathics3.svg
 .. |Packaging status| image:: https://repology.org/badge/vertical-allrepos/mathics.svg
 			    :target: https://repology.org/project/mathics/versions

mathics/builtin/intfns/recurrence.py

@@ -24,7 +24,10 @@
 
 class Fibonacci(MPMathFunction):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/Fibonacci.html</url>
+    <url>
+    :Fibonacci Sequence:
+    https://en.wikipedia.org/wiki/Fibonacci_sequence</url>, <url>(
+    :WMA link:https://reference.wolfram.com/language/ref/Fibonacci.html</url>)
 
     <dl>
       <dt>'Fibonacci[$n$]'
@@ -43,6 +46,10 @@ class Fibonacci(MPMathFunction):
      = 280571172992510140037611932413038677189525
     >> Fibonacci[7, x]
      = 1 + 6 x ^ 2 + 5 x ^ 4 + x ^ 6
+
+    See also <url>
+    :LinearRecurrence:
+    /doc/reference-of-built-in-symbols/integer-functions/recurrence-and-sum-functions/linearrecurrence</url>.
     """
 
     nargs = {1}
@@ -84,17 +91,36 @@ class HarmonicNumber(MPMathFunction):
 
 class LinearRecurrence(Builtin):
     """
-    <url>:WMA link:https://reference.wolfram.com/language/ref/LinearRecurrence.html</url>
+    <url>:Linear recurrence with constant coefficients:
+      https://en.wikipedia.org/wiki/Linear_recurrence_with_constant_coefficients</url>, <url>
+      :WMA link:https://reference.wolfram.com/language/ref/LinearRecurrence.html</url>
 
     <dl>
       <dt>'LinearRecurrence[$ker$, $init$, $n$]'
-      <dd>computes $n$ terms of the linear recurrence with kernel $ker$ and initial values $init$
+      <dd>computes $n$ terms of the linear recurrence with kernel $ker$ and initial values $init$.
+
+      <dt>'LinearRecurrence[$ker$, $init$, {$n$}]'
+      <dd>computes the $n$th term.
+
+      <dt>'LinearRecurrence[$ker$, $init$, {$n_min$, $n_max$}]'
+      <dd>computes $n$ terms of the linear recurrence with kernel $ker$ and initial values $init$.
     </dl>
 
+    Generate first 10 items of the Fibonacci Sequence, 'F'[0]=1, 'F'[1]=1:
     >> LinearRecurrence[{1, 1}, {1, 1}, 10]
      = {1, 1, 2, 3, 5, 8, 13, 21, 34, 55}
-    >> LinearRecurrence[{1, 1}, {1, 1}, {5, 5}]
-     = {5}
+
+    Extract the 3rd to 5th elements:
+    >> LinearRecurrence[{1, 1}, {1, 1}, {3, 5}]
+     = {2, 3, 5}
+
+    Now just the 6th element:
+    >> LinearRecurrence[{1, 1}, {1, 1}, {6}]
+     = 8
+
+    See also <url>
+    :Fibonacci:
+    /doc/reference-of-built-in-symbols/integer-functions/recurrence-and-sum-functions/fibonacci</url>.
     """
 
     attributes = A_PROTECTED | A_READ_PROTECTED

mathics/builtin/numbers/numbertheory.py

@@ -674,8 +674,10 @@ def eval_with_b(self, n, b, evaluation: Evaluation):
 class MersennePrimeExponent(SympyFunction):
     """
     <url>
+    :Mersenne Prime:
+    https://en.wikipedia.org/wiki/Mersenne_prime</url> exponent (<url>
     :SymPy: https://docs.sympy.org/latest/modules/ntheory.html#sympy.ntheory.factor_.mersenne_prime_exponent</url>, <url>
-    :WMA: https://reference.wolfram.com/language/ref/MersennePrimeExponent.html</url>
+    :WMA: https://reference.wolfram.com/language/ref/MersennePrimeExponent.html</url>)
 
     <dl>
       <dt>'MersennePrimeExponent[$n$]'
@@ -705,12 +707,11 @@ class MoebiusMu(SympyFunction):
 
     <dl>
       <dt>'MoebiusMu[$n$]'
-      <dd>returns μ($n$)
+      <dd>returns μ($n$).
     </dl>
 
     >> Array[MoebiusMu, 10]
     = {1, -1, -1, 0, -1, 1, -1, 0, 0, 1}
-
     """
 
     attributes = A_LISTABLE | A_PROTECTED

mathics/builtin/specialfns/expintegral.py

@@ -54,23 +54,38 @@ class ExpIntegralEi(MPMathFunction):
 
 class LambertW(Builtin):
     """
-    <url>:Lambert W-Function: https://mathworld.wolfram.com/LambertW-Function.html</url>
+    <url>
+      :Lambert <i>W</i> Function:
+      https://en.wikipedia.org/wiki/Lambert_W_function</url>, <url>:MathWorld:
+      https://mathworld.wolfram.com/LambertW-Function.html</url>
 
     <dl>
+      <dt>'LambertW[$k$]'
+      <dd>alias for ProductLog[$z$].
+
       <dt>'LambertW[$k$, $z$]'
       <dd>alias for ProductLog[$k$, $z$].
     </dl>
 
     >> LambertW[k, z]
      = ProductLog[k, z]
+
+    >> Plot[LambertW[x], {x, -1/E, E}]
+     = -Graphics-
+
+    See also <url>
+    :ProductLog:
+    /doc/reference-of-built-in-symbols/special-functions/exponential-integral-and-special-functions/productlog</url>.
     """
 
     attributes = A_LISTABLE | A_PROTECTED
-    summary_text = "undocumented alias"
+    mpmath_name = "lambertw"
     rules = {
         "LambertW[z_]": "ProductLog[z]",
         "LambertW[k_, z_]": "ProductLog[k, z]",
     }
+    summary_text = "Lambert W function"
+    sympy_name = "LambertW"  # function called LambertW in SymPy
 
 
 class ProductLog(MPMathFunction):
@@ -79,7 +94,10 @@ class ProductLog(MPMathFunction):
 
     <dl>
       <dt>'ProductLog[$z$]'
-      <dd>returns the value of the Lambert W function at $z$.
+      <dd>returns the principle solution for $w$ in $z$ == $wE$^$w$.
+
+      <dt>'ProductLog[$k$, $z$]'
+      <dd>gives the $k$th solution.
     </dl>
 
     The defining equation:
@@ -92,14 +110,15 @@ class ProductLog(MPMathFunction):
     >> ProductLog[E]
      = 1
 
+    >> ProductLog[-1.5]
+     = -0.0327837 + 1.54964 I
+
     The graph of 'ProductLog':
     >> Plot[ProductLog[x], {x, -1/E, E}]
      = -Graphics-
     """
 
     attributes = A_LISTABLE | A_PROTECTED | A_READ_PROTECTED
-    summary_text = "Lambert's W function"
-    sympy_name = "LambertW"  # function called LambertW in SymPy
     mpmath_name = "lambertw"
 
     rules = {
@@ -108,9 +127,11 @@ class ProductLog(MPMathFunction):
         "ProductLog[z_] * E ^ ProductLog[z_]": "z",
         "Derivative[1][ProductLog]": "ProductLog[#] / (# (ProductLog[#] + 1))&",
     }
+    summary_text = "Lambert's W function"
+    sympy_name = "LambertW"  # function called LambertW in SymPy
 
 
-# TODO: Zernike polynomials not yet implemented in mpmath nor sympy
+# TODO: Zernike polynomials not yet implemented in mpmath nor SymPy
 #
 # class ZernikeR(MPMathFunction):
 #    """