Deprecate MixedIntegerLinearProgram.gen(), __call__, linear_function, which do not do anything useful; add default_variable method

[mkoeppe]

As observed in the comments in #20461:

sage: mip = MixedIntegerLinearProgram(solver='GLPK')
sage: mip.gen(0)           ### Names a variable, but does not create it in the backend
x_0
sage: mip.number_of_variables()
0
sage: mip[0]                  ### This now creates a variable. It prints the same as the result of gen(0), but is different.
x_0
sage: mip.get_values(mip.gen(0))
[...]
TypeError: Not a MIPVariable: x_0
sage: mip.is_real(mip.gen(0))
[...]
KeyError: x_0
sage: mip.is_real(mip[0])
True

To summarize, the gen method pretends that it can refer to backend variables (and so do linear_function and the special __call__ method that is identical to linear_function). In reality, these methods cannot be use for anything except for what is tested in the docstring: printing some meaningless stuff.

This patch deprecates these three methods and removes the corresponding confusing and useless examples from the class documentation.

In return, the notion of the "default MIP variable" (which __getitem__ refers to) is explained; and it is exposed to the user by new method default_variable.

CC: @nbruin @dimpase @videlec @jdemeyer @fchapoton @novoselt

Component: numerical

Author: Matthias Koeppe

Branch/Commit: 684e91c

Reviewer: Dima Pasechnik

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

[mkoeppe]

Description changed:

--- 
+++ 
@@ -17,3 +17,9 @@
 sage: mip.is_real(mip[0])
 True
 ```
+
+I think mip.gen(i) should simply return the same variable that mip[i] returns (and like mip[i], it should create this variable in the backend if it does not exist yet). 
+
+
+
+

[mkoeppe]

Description changed:

--- 
+++ 
@@ -18,8 +18,10 @@
 True
 ```
 
-I think mip.gen(i) should simply return the same variable that mip[i] returns (and like mip[i], it should create this variable in the backend if it does not exist yet). 
+To summarize, the `gen` method pretends that it can refer to backend variables (and so do `linear_function` and the special `__call__` method that is identical to `linear_function`). In reality, these methods cannot be use for anything except for what is tested in the docstring: printing some meaningless stuff. 
+
+This patch deprecates these three methods and removes the corresponding confusing and useless examples from the class documentation.
+
+In return, the notion of the "default MIP variable" (which `__getitem__` refers to) is explained; and it is exposed to the user by new method `default_variable`. 
 
 
-
-

[mkoeppe]

Author: Matthias Koeppe

[mkoeppe]

Branch: u/mkoeppe/mixedintegerlinearprogram_gen___does_not_do_anything_useful

[mkoeppe]

New commits:

434775d	Update documentation
c54c656	Update function index
dcbe23f	MixedIntegerLinearProgram: Deprecate linear_function, `__call__`, and gen
72c8837	MixedIntegerLinearProgram.show: Simplify, avoid calling gen
de373d0	default_variable: New

[mkoeppe]

Commit: de373d0

[novoselt]

comment:5

If the old methods were indeed always broken and could not be used for anything useful, I say - just delete (or fix) them instead of deprecating...

[mkoeppe]

comment:6

It's possible that there's some user code around that uses these methods as part of a workaround for the many bugs that had to be fixed in MixedIntegerLinearProgram (see #20302 for a list). That's why I wanted to go the deprecation route with these methods.

[fchapoton]

comment:7

doc does not build + failing doctests, see patchbot report

OSError: [numerical] docstring of sage.numerical.mip:115:
WARNING: Inline interpreted text or phrase reference start-string
without end-string.

[sagetrac-git]

Changed commit from de373d0 to a1a1075

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. New commits:

a1a1075

Fix documentation markup and add deprecation info

[fchapoton]

comment:9

Still 2 failing doctests

[sagetrac-git]

Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:

987a47e	Update documentation
71ebeae	Update function index
e427ccc	MixedIntegerLinearProgram: Deprecate linear_function, `__call__`, and gen
422abf6	MixedIntegerLinearProgram.show: Simplify, avoid calling gen
881d1ac	default_variable: New
77beb8f	Fix documentation markup and add deprecation info
6375b4c	LinearTensor: Add tests for hash and cmp
684e91c	LinearFunction, LinearConstraint: Use linear_functions_parent() instead of deprecated MixedIntegerLinearProgram methods

[sagetrac-git]

Changed commit from a1a1075 to 684e91c

[mkoeppe]

comment:11

I've changed the doctests to no longer use the deprecated methods.
While doing this, I noticed that LinearTensor had some doctests that were copied from LinearFunction and were not testing the methods; and one of the methods needed fixing; done.