search

sagemath / sage

Main repository of SageMath
https://www.sagemath.org
Other
1.47k stars 487 forks source link

Deprecate sage.numerical.optimize functions #32260

Open mkoeppe opened 3 years ago

mkoeppe commented 3 years ago

sage.numerical.optimize provides the following functions:

(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

Symptoms:

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 commented 3 years ago

Changed dependencies from #32226 to none

mkoeppe commented 3 years ago

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 commented 3 years ago

Branch: u/mkoeppe/deprecate_sage_numerical_optimize

mkoeppe commented 3 years ago

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 only refers to one of these functions, find_root (both the global and the Expression.find_root method).

mkoeppe commented 3 years ago

Commit: 84c4a6e

mkoeppe commented 3 years ago

New commits:

84c4a6esrc/sage/coding/code_bounds.py: Replace use of sage.numerical.optimize by a direct scipy call
orlitzky commented 3 years ago
comment:5

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

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 commented 3 years ago
comment:6

Thanks for the input and the pointer.

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

mkoeppe commented 3 years ago

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 commented 3 years ago

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 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 commented 3 years ago

Author: Matthias Koeppe

mkoeppe commented 2 years ago

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 commented 2 years ago
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 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago
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 commented 2 years ago

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 commented 2 years ago
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 commented 2 years ago
comment:17

Yes, find_root is not so bad.

EmmanuelCharpentier commented 3 months ago

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...