MIP backends: Unify add_col, add_variable; and clarify defaulting behavior of binary, continuous, integer

[mkoeppe]

add_col and add_variable both add a variable to the problem; but add_col only allows to add a column with no name; whereas add_variable only allows to add a column with no coefficients.
There should be one function (add_variable, probably - see #20296 for a possible interface) that can do both; should then deprecate add_col.
Note that add_col is not used by MixedIntegerLinearProgram; it is only used in doctests of the backends.
Also, GurobiBackend does not implement add_col (this is fixed in #20424).
(Also compare with add_linear_constraint, which takes a zipped index/coefficient list, whereas add_col takes two parallel lists.)

While making this change, should also clarify the defaulting behavior of the binary, continuous, integer arguments of add_variable. The argument list is:

cpdef int add_variable(self, lower_bound=0.0, upper_bound=None, binary=False, continuous=False, integer=False, obj=0.0, name=None)

Whereas the documentation says:

• binary - True if the variable is binary (default: False).
• continuous - True if the variable is binary [SIC!] (default: True).
• integer - True if the variable is binary [SIC!] (default: False).
  Probably the defaults in the arglist should be None, and defaulting to creating continuous variables should be explained separately.
  (See MIP backends: Make variable type consistent between add_variable, set_variable_type (with deprecation) #20362 for a discussion of a possible better interface and the mismatch with set_variable_type.)

Also #23600 should be fixed: the signatures of the cpdef functions should be the same in all implementations to fix Cython vtable warnings.

CC: @dimpase @nathanncohen @videlec

Component: numerical

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

[mkoeppe]

Description changed:

--- 
+++ 
@@ -3,3 +3,14 @@
 Note that `add_col` is not used by `MixedIntegerLinearProgram`; it is only used in doctests of the backends.  
 (Also compare with `add_linear_constraint`, which takes a zipped index/coefficient list, whereas `add_col` takes two parallel lists.)
 
+While making this change, should also clarify the defaulting behavior of the `binary`, `continuous`, `integer` arguments of `add_variable`. The argument list is:
+
+```
+cpdef int add_variable(self, lower_bound=0.0, upper_bound=None, binary=False, continuous=False, integer=False, obj=0.0, name=None)
+```
+Whereas the documentation says:
+- `binary` - `True` if the variable is binary (default: `False`).
+- `continuous` - `True` if the variable is binary (default: ``True`).
+- `integer` - `True` if the variable is binary (default: `False`).
+Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
+

[mkoeppe]

Description changed:

--- 
+++ 
@@ -10,7 +10,7 @@
 ```
 Whereas the documentation says:
 - `binary` - `True` if the variable is binary (default: `False`).
-- `continuous` - `True` if the variable is binary (default: ``True`).
-- `integer` - `True` if the variable is binary (default: `False`).
+- `continuous` - `True` if the variable is binary [SIC!] (default: `True`).
+- `integer` - `True` if the variable is binary [SIC!] (default: `False`).
 Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
 

[mkoeppe]

Description changed:

--- 
+++ 
@@ -13,4 +13,4 @@
 - `continuous` - `True` if the variable is binary [SIC!] (default: `True`).
 - `integer` - `True` if the variable is binary [SIC!] (default: `False`).
 Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
-
+(See #20354 discussion for a discussion of a possible better interface and the mismatch with `set_variable_type`.)

[mkoeppe]

Description changed:

--- 
+++ 
@@ -13,4 +13,4 @@
 - `continuous` - `True` if the variable is binary [SIC!] (default: `True`).
 - `integer` - `True` if the variable is binary [SIC!] (default: `False`).
 Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
-(See #20354 discussion for a discussion of a possible better interface and the mismatch with `set_variable_type`.)
+(See #20362 for a discussion of a possible better interface and the mismatch with `set_variable_type`.)

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,6 +1,7 @@
 `add_col` and `add_variable` both add a variable to the problem; but `add_col` only allows to add a column with no name; whereas `add_variable` only allows to add a column with no coefficients. 
 There should be one function (`add_variable`, probably - see #20296 for a possible interface) that can do both; should then deprecate `add_col`. 
 Note that `add_col` is not used by `MixedIntegerLinearProgram`; it is only used in doctests of the backends.  
+Also, `GurobiBackend` does not implement `add_col`.
 (Also compare with `add_linear_constraint`, which takes a zipped index/coefficient list, whereas `add_col` takes two parallel lists.)
 
 While making this change, should also clarify the defaulting behavior of the `binary`, `continuous`, `integer` arguments of `add_variable`. The argument list is:

[mkoeppe]

Dependencies: #20424

[mkoeppe]

Description changed:

--- 
+++ 
@@ -1,7 +1,7 @@
 `add_col` and `add_variable` both add a variable to the problem; but `add_col` only allows to add a column with no name; whereas `add_variable` only allows to add a column with no coefficients. 
 There should be one function (`add_variable`, probably - see #20296 for a possible interface) that can do both; should then deprecate `add_col`. 
 Note that `add_col` is not used by `MixedIntegerLinearProgram`; it is only used in doctests of the backends.  
-Also, `GurobiBackend` does not implement `add_col`.
+Also, `GurobiBackend` does not implement `add_col` (this is fixed in #20424).
 (Also compare with `add_linear_constraint`, which takes a zipped index/coefficient list, whereas `add_col` takes two parallel lists.)
 
 While making this change, should also clarify the defaulting behavior of the `binary`, `continuous`, `integer` arguments of `add_variable`. The argument list is:

[jdemeyer]

Changed dependencies from #20424 to none

[jdemeyer]

Description changed:

--- 
+++ 
@@ -15,3 +15,5 @@
 - `integer` - `True` if the variable is binary [SIC!] (default: `False`).
 Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
 (See #20362 for a discussion of a possible better interface and the mismatch with `set_variable_type`.)
+
+Also #23600 should be fixed: the signatures of the `cpdef` functions should be the same in all implementations.

[jdemeyer]

Description changed:

--- 
+++ 
@@ -16,4 +16,4 @@
 Probably the defaults in the arglist should be `None`, and defaulting to creating continuous variables should be explained separately.
 (See #20362 for a discussion of a possible better interface and the mismatch with `set_variable_type`.)
 
-Also #23600 should be fixed: the signatures of the `cpdef` functions should be the same in all implementations.
+Also #23600 should be fixed: the signatures of the `cpdef` functions should be the same in all implementations to fix Cython vtable warnings.