Deprecate sage.numerical.optimize functions

[mkoeppe]

sage.numerical.optimize provides the following functions:

• find_root

  • [1] refers to this function and to the Expression.find_root method
  • [2] refers to this function in a short section "using Sage as a numerical solver" - which explains sage_root and nothing else

• find_local_minimum, find_local_maximum

  • does not appear in [1]
  • does not appear in [2]

• minimize

  • does not appear in [1]
  • appears in [2] in a section "Minimizations and Lagrange Multipliers" (the latter ends in a disappointment)

• minimize_constrained

  • does not appear in [2]

• find_fit

  • does not appear in [1]
  • appears in [2] in a short section titled "making your own regressions in Sage"

(linear_program is already deprecated; we ignore the function binpacking in this ticket.)

[1] Book Computational Mathematics with SageMath [2] Gregory Bard's book

Within the Sage library itself, there is only minimal use of this module.

$ git grep sage.numerical.optimize
src/doc/en/reference/numerical/index.rst:   sage/numerical/optimize
src/sage/coding/code_bounds.py:    from sage.numerical.optimize import find_root
src/sage/crypto/lwe.py:from sage.numerical.optimize import find_root
src/sage/numerical/all.py:lazy_import("sage.numerical.optimize",
src/sage/numerical/optimize.py:        sage: from sage.numerical.optimize import binpacking
src/sage/numerical/optimize.py:        sage: from sage.numerical.optimize import binpacking
src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_root
src/sage/symbolic/expression.pyx:        Uses :func:`sage.numerical.optimize.find_local_minimum`.
src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_local_minimum

In this ticket, we

• discuss which of these functions provide sufficient added value to users over just using scipy;
• deprecate functions that do not provide sufficient added value;
• provide documentation that empowers users to use Sage functions with scipy (including the sage.ext.fast_callable facility) - see #24536 for some new adapters

Symptoms:

• minimize_constrained https://groups.google.com/g/sage-devel/c/5vp5UTexpxQ/m/DG_lmN9ZAwAJ

CC: @dimpase @orlitzky @sagetrac-tmonteil @slel

Component: numerical

Author: Matthias Koeppe

Branch/Commit: u/mkoeppe/deprecate_sage_numerical_optimize @ 84c4a6e

Issue created by migration from https://trac.sagemath.org/ticket/32260

[mkoeppe]

Changed dependencies from #32226 to none

[mkoeppe]

Description changed:

--- 
+++ 
@@ -2,5 +2,19 @@
 
 We should replace it by documentation that empowers users to use Sage functions with `scipy` (including the `sage.ext.fast_callable` facility).
 
+Within the Sage library itself, there is only minimal use of this module.
+
+```
+$ git grep sage.numerical.optimize
+src/doc/en/reference/numerical/index.rst:   sage/numerical/optimize
+src/sage/coding/code_bounds.py:    from sage.numerical.optimize import find_root
+src/sage/crypto/lwe.py:from sage.numerical.optimize import find_root
+src/sage/numerical/all.py:lazy_import("sage.numerical.optimize",
+src/sage/numerical/optimize.py:        sage: from sage.numerical.optimize import binpacking
+src/sage/numerical/optimize.py:        sage: from sage.numerical.optimize import binpacking
+src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_root
+src/sage/symbolic/expression.pyx:        Uses :func:`sage.numerical.optimize.find_local_minimum`.
+src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_local_minimum
+```
 
 

[mkoeppe]

Branch: u/mkoeppe/deprecate_sage_numerical_optimize

[mkoeppe]

Description changed:

--- 
+++ 
@@ -17,4 +17,5 @@
 src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_local_minimum
 ```
 
+The book [Computational Mathematics with SageMath](http://sagebook.gforge.inria.fr/english.html) only refers to one of these functions,  `find_root` (both the global and the `Expression.find_root` method).
 

[mkoeppe]

Commit: 84c4a6e

[mkoeppe]

New commits:

84c4a6e

src/sage/coding/code_bounds.py: Replace use of sage.numerical.optimize by a direct scipy call

[orlitzky]

comment:5

I'm not so sure about this one. These functions are minimal(ish) wrappers around scipy that,

• allow you to use sage types as input/output
• check the results for correctness
• drop "verbose" return values

The essence of sage is wrapping other scientific libraries in a consistent and user-friendly interface. What find_root does (for example) is not rocket surgery, but I certainly wouldn't want to write it myself every time I have a calc1 problem to double-check.

In other news, Gregory Bard's book (http://gregorybard.com/Sage.html) also uses a few of these functions.

[mkoeppe]

comment:6

Thanks for the input and the pointer.

I think we need to break this down function by function.

[mkoeppe]

Description changed:

--- 
+++ 
@@ -19,3 +19,6 @@
 
 The book [Computational Mathematics with SageMath](http://sagebook.gforge.inria.fr/english.html) only refers to one of these functions,  `find_root` (both the global and the `Expression.find_root` method).
 
+
+Symptoms:
+- `minimize_constrained` https://groups.google.com/g/sage-devel/c/5vp5UTexpxQ/m/DG_lmN9ZAwAJ

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,6 +1,20 @@
-There is no added value that the functions `find_root`, `find_local_maximum`, `find_local_minimum`, `minimize`, `minimize_constrained`, `find_fit` would provide over just using `scipy`. 
+`sage.numerical.optimize` provides the following functions:
 
-We should replace it by documentation that empowers users to use Sage functions with `scipy` (including the `sage.ext.fast_callable` facility).
+- [find_root](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_root) [1] refers to this function and to the `Expression.find_root` method
+
+- [find_local_minimum](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_local_minimum), `find_local_maximum`
+
+- [minimize](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize)
+
+- [minimize_constrained](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize_constrained)
+
+- [find_fit](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_fit)
+
+([linear_program](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.linear_program) is already deprecated; we ignore the function [binpacking](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.binpacking) in this ticket.)
+
+[1] Book [Computational Mathematics with SageMath](http://sagebook.gforge.inria.fr/english.html)
+[2] [Gregory Bard's book](http://gregorybard.com/Sage.html)
+
 
 Within the Sage library itself, there is only minimal use of this module.
 
@@ -17,7 +31,12 @@
 src/sage/symbolic/expression.pyx:        from sage.numerical.optimize import find_local_minimum
 ```
 
-The book [Computational Mathematics with SageMath](http://sagebook.gforge.inria.fr/english.html) only refers to one of these functions,  `find_root` (both the global and the `Expression.find_root` method).
+
+In this ticket, we 
+- discuss which of these functions provide sufficient added value to users over just using `scipy`; 
+- deprecate functions that do not provide sufficient added value;
+- provide documentation that empowers users to use Sage functions with `scipy` (including the `sage.ext.fast_callable` facility).
+
 
 
 Symptoms:

[slel]

Author: Matthias Koeppe

[mkoeppe]

Description changed:

--- 
+++ 
@@ -35,7 +35,7 @@
 In this ticket, we 
 - discuss which of these functions provide sufficient added value to users over just using `scipy`; 
 - deprecate functions that do not provide sufficient added value;
-- provide documentation that empowers users to use Sage functions with `scipy` (including the `sage.ext.fast_callable` facility).
+- provide documentation that empowers users to use Sage functions with `scipy` (including the `sage.ext.fast_callable` facility) - see #24536 for some new adapters
 
 
 

[kcrisman]

comment:12

Thanks for the input and the pointer.

I think we need to break this down function by function.

+1

Ideally these could be pretty light wrappers in general. But having something top-level for undergraduate instruction is very, very convenient (as evidenced by the two books mentioned in the ticket).

[mkoeppe]

Description changed:

--- 
+++ 
@@ -9,6 +9,7 @@
 - [minimize_constrained](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize_constrained)
 
 - [find_fit](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_fit)
+  - appears in [2] in a short section titled "making your own regressions in Sage"
 
 ([linear_program](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.linear_program) is already deprecated; we ignore the function [binpacking](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.binpacking) in this ticket.)
 

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,12 +1,16 @@
 `sage.numerical.optimize` provides the following functions:
 
-- [find_root](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_root) [1] refers to this function and to the `Expression.find_root` method
+- [find_root](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_root) 
+  - [1] refers to this function and to the `Expression.find_root` method
+  - [2] refers to this function in a short section "using Sage as a numerical solver" - which explains `sage_root` and nothing else
 
 - [find_local_minimum](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_local_minimum), `find_local_maximum`
+  - does not appear in [2]
 
 - [minimize](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize)
-
+  - appears in [2] in a section "Minimizations and Lagrange Multipliers"
 - [minimize_constrained](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize_constrained)
+  - does not appear in [2]
 
 - [find_fit](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_fit)
   - appears in [2] in a short section titled "making your own regressions in Sage"

[mkoeppe]

comment:15

Replying to @kcrisman:

something top-level for undergraduate instruction is very, very convenient (as evidenced by the two books mentioned in the ticket).

Well, I have looked at the sections related to the present ticket in the books and I wouldn't recommend using these parts for instruction at any level.

[mkoeppe]

Description changed:

--- 
+++ 
@@ -5,14 +5,18 @@
   - [2] refers to this function in a short section "using Sage as a numerical solver" - which explains `sage_root` and nothing else
 
 - [find_local_minimum](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_local_minimum), `find_local_maximum`
+  - does not appear in [1]
   - does not appear in [2]
 
 - [minimize](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize)
-  - appears in [2] in a section "Minimizations and Lagrange Multipliers"
+  - does not appear in [1]
+  - appears in [2] in a section "Minimizations and Lagrange Multipliers" (the latter ends in a disappointment)
+
 - [minimize_constrained](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.minimize_constrained)
   - does not appear in [2]
 
 - [find_fit](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.find_fit)
+  - does not appear in [1]
   - appears in [2] in a short section titled "making your own regressions in Sage"
 
 ([linear_program](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.linear_program) is already deprecated; we ignore the function [binpacking](https://doc.sagemath.org/html/en/reference/numerical/sage/numerical/optimize.html#sage.numerical.optimize.binpacking) in this ticket.)

[egourgoulhon]

comment:16

Replying to @kcrisman:

Ideally these could be pretty light wrappers in general. But having something top-level for undergraduate instruction is very, very convenient (as evidenced by the two books mentioned in the ticket).

I fully agree. For instance, I would be -1 in removing find_root for it is heavily used and very convenient for a basic usage. For more sophisticated use, of course, the user shall import scipy functions.

[mkoeppe]

comment:17

Yes, find_root is not so bad.

[EmmanuelCharpentier]

An ask.sagemath.org question stumbles on a problem possibly related to minimize_constrained ; I have filed a corresponding issue.

On the general deprecation issue : I think that we should keep "frequently used" numerical methods, rathervthan force the end-users to sift through the external spkgs documentation. vind_root is a caricatural example, but minimize and minimize_constrained are also examples often arising in engineering problems. If we aim to make Sage usable by "mere engineers", we'd better keep (and advertise !) these tools.

Life is not all geometric algebra...