Skip to content

Commit 41cf276

Browse files
author
Release Manager
committed
gh-36394: Deprecate the backslash operator Deprecate the backslash operator. <!-- ^^^^^ Please provide a concise, informative and self-explanatory title. Don't put issue numbers in there, do this in the PR body below. For example, instead of "Fixes #1234" use "Introduce new method to calculate 1+1" --> Deprecate the backslash operator: it is underused and its current implementation conflicts with standard Python usage of `\`. A [poll on sage-devel ](https://groups.google.com/g/sage- devel/c/8G-tPMdtNX4/m/tRCfUVHiCAAJ) supports this decision. <!-- Describe your changes here in detail --> The backslash operator is only used in a few places, mainly matrices and matroids; those uses are deprecated. <!-- Why is this change required? What problem does it solve? --> <!-- If this PR resolves an open issue, please link to it here. For example "Fixes #12345". --> <!-- If your change requires a documentation PR, please link it appropriately. --> ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. --> <!-- If your change requires a documentation PR, please link it appropriately --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> <!-- Feel free to remove irrelevant items. --> - [X] The title is concise, informative, and self-explanatory. - [X] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [X] I have created tests covering the changes. - [X] I have updated the documentation accordingly. ### ⌛ Dependencies <!-- List all open PRs that this PR logically depends on - #12345: short description why this is a dependency - #34567: ... --> <!-- If you're unsure about any of these, don't hesitate to ask. We're here to help! --> URL: #36394 Reported by: John H. Palmieri Reviewer(s): John H. Palmieri, Kwankyu Lee
2 parents 699dbf1 + b2719f4 commit 41cf276

24 files changed

+103
-140
lines changed

‎src/doc/de/tutorial/tour_linalg.rst

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -42,16 +42,6 @@ gelöst werden. Das Auswerten von ``A.solve_right(Y)`` gibt eine Matrix
4242
sage: A * X # wir überprüfen unsere Antwort...
4343
(0, -4, -1)
4444

45-
Anstelle von ``solve_right`` kann auch ein Backslash ``\`` verwendet
46-
werden. Benutzen Sie ``A \ Y`` anstelle von ``A.solve_right(Y)``.
47-
48-
.. link
49-
50-
::
51-
52-
sage: A \ Y
53-
(-2, 1, 0)
54-
5545
Falls keine Lösung existiert, gibt Sage einen Fehler zurück:
5646

5747
.. skip

‎src/doc/en/tutorial/tour_linalg.rst

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -42,16 +42,6 @@ Evaluating ``A.solve_right(Y)`` returns a matrix (or vector)
4242
sage: A * X # checking our answer...
4343
(0, -4, -1)
4444

45-
A backslash ``\`` can be used in the place of ``solve_right``; use
46-
``A \ Y`` instead of ``A.solve_right(Y)``.
47-
48-
.. link
49-
50-
::
51-
52-
sage: A \ Y
53-
(-2, 1, 0)
54-
5545
If there is no solution, Sage returns an error:
5646

5747
.. skip

‎src/doc/es/tutorial/tour_linalg.rst

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -49,16 +49,6 @@ Resolver ecuaciones matriciales es sencillo, usando el método
4949
sage: A * X # comprobando la solución...
5050
(0, -4, -1)
5151

52-
Se puede usar una barra invertida ``\`` en lugar de ``solve_right``;
53-
usamos ``A \ Y`` en lugar de ``A.solve_right(Y)``.
54-
55-
.. link
56-
57-
::
58-
59-
sage: A \ Y
60-
(-2, 1, 0)
61-
6252
Si no hay solución, Sage lanza un error:
6353

6454
.. skip

‎src/doc/fr/tutorial/tour_linalg.rst

Lines changed: 0 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -42,17 +42,6 @@ une matrice (ou un vecteur) :math:`X` tel que :math:`AX=Y`:
4242
sage: A * X # vérifions la réponse...
4343
(0, -4, -1)
4444

45-
Un antislash (contre-oblique) ``\`` peut être employé à la place de
46-
``solve_right`` : il suffit d'écrire ``A \ Y`` au lieu de
47-
``A.solve_right(Y)``.
48-
49-
.. link
50-
51-
::
52-
53-
sage: A \ Y
54-
(-2, 1, 0)
55-
5645
S'il n'y a aucune solution, Sage renvoie une erreur :
5746

5847
.. skip

‎src/doc/ja/tutorial/tour_linalg.rst

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -45,18 +45,6 @@ Sageでは，行列 :math:`A` の核空間は「左」核空間，すなわち :
4545
(0, -4, -1)
4646

4747

48-
``solve_right`` の代わりにバックスラッシュ ``\`` を使うこともできる．
49-
つまり ``A.solve_right(Y)`` ではなく ``A \ Y`` と書くわけである．
50-
51-
.. link
52-
53-
::
54-
55-
sage: A \ Y
56-
(-2, 1, 0)
57-
58-
59-
6048
解がない場合は，Sageはエラーを返してくる:
6149

6250
.. skip

‎src/doc/pt/tutorial/tour_linalg.rst

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -40,16 +40,6 @@ Calculando ``A.solve_right(Y)`` obtém-se uma matrix (ou vetor)
4040
sage: A * X # checking our answer...
4141
(0, -4, -1)
4242

43-
Uma barra invertida ``\`` pode ser usada no lugar de ``solve_right``;
44-
use ``A \ Y`` no lugar de ``A.solve_right(Y)``.
45-
46-
.. link
47-
48-
::
49-
50-
sage: A \ Y
51-
(-2, 1, 0)
52-
5343
Se não existir solução, o Sage retorna um erro:
5444

5545
.. skip

‎src/doc/ru/tutorial/tour_linalg.rst

Lines changed: 0 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -37,16 +37,6 @@ Sage поддерживает стандартные конструкции из
3737
sage: A * X # проверка...
3838
(0, -4, -1)
3939

40-
``\`` может быть использован вместо ``solve_right``; используйте
41-
``A \ Y`` вместо ``A.solve_right(Y)``.
42-
43-
.. link
44-
45-
::
46-
47-
sage: A \ Y
48-
(-2, 1, 0)
49-
5040
Если решения не существует, то Sage вернет ошибку:
5141

5242
.. skip

‎src/sage/combinat/binary_tree.py

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
from sage.sets.disjoint_union_enumerated_sets import DisjointUnionEnumeratedSets
4040
from sage.sets.family import Family
4141
from sage.misc.cachefunc import cached_method
42+
from sage.misc.superseded import deprecated_function_alias
4243

4344

4445
class BinaryTree(AbstractClonableTree, ClonableArray,
@@ -3214,7 +3215,7 @@ def under(self, bt):
32143215
32153216
sage: b1 = BinaryTree([[],[]])
32163217
sage: b2 = BinaryTree([None,[]])
3217-
sage: ascii_art((b1, b2, b1 \ b2))
3218+
sage: ascii_art((b1, b2, b1.under(b2)))
32183219
( o , o , _o_ )
32193220
( / \ \ / \ )
32203221
( o o o o o )
@@ -3276,7 +3277,7 @@ def under(self, bt):
32763277
else:
32773278
return B([self.under(bt[0]), bt[1]])
32783279

3279-
_backslash_ = under
3280+
_backslash_ = deprecated_function_alias(36394, under)
32803281

32813282
def under_decomposition(self):
32823283
r"""

‎src/sage/features/sagemath.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -232,7 +232,7 @@ class sage__graphs(JoinFeature):
232232
sage: M = Matroid(Matrix(QQ, [[1, 0, 0, 0, 1, 1, 1],
233233
....: [0, 1, 0, 1, 0, 1, 1],
234234
....: [0, 0, 1, 1, 1, 0, 1]]))
235-
sage: N = M / [2] \ [3, 4]
235+
sage: N = (M / [2]).delete([3, 4])
236236
sage: sorted(N.groundset())
237237
[0, 1, 5, 6]
238238

‎src/sage/matrix/matrix2.pyx

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -106,7 +106,7 @@ from sage.matrix.matrix_misc import permanental_minor_polynomial
106106
from sage.misc.misc_c import prod
107107

108108
# used to deprecate only adjoint method
109-
from sage.misc.superseded import deprecated_function_alias
109+
from sage.misc.superseded import deprecation, deprecated_function_alias
110110

111111

112112
# temporary hack to silence the warnings from #34806
@@ -146,21 +146,28 @@ cdef class Matrix(Matrix1):
146146
Used to compute `A \backslash B`, i.e., the backslash solver
147147
operator.
148148

149+
DEPRECATED
150+
149151
EXAMPLES::
150152

151153
sage: A = matrix(QQ, 3, [1,2,4,2,3,1,0,1,2])
152154
sage: B = matrix(QQ, 3, 2, [1,7,5, 2,1,3])
153155
sage: C = A._backslash_(B); C
156+
doctest:...: DeprecationWarning: the backslash operator has been deprecated; use A.solve_right(B) instead
157+
See https://github.com/sagemath/sage/issues/36394 for details.
154158
[ -1 1]
155159
[13/5 -3/5]
156160
[-4/5 9/5]
157161
sage: A*C == B
158162
True
159163
sage: A._backslash_(B) == A \ B
164+
doctest:...: DeprecationWarning: the backslash operator has been deprecated; use A.solve_right(B) instead
165+
See https://github.com/sagemath/sage/issues/36394 for details.
160166
True
161167
sage: A._backslash_(B) == A.solve_right(B)
162168
True
163169
"""
170+
deprecation(36394, 'the backslash operator has been deprecated; use A.solve_right(B) instead')
164171
return self.solve_right(B)
165172

166173
def subs(self, *args, **kwds):
@@ -462,7 +469,7 @@ cdef class Matrix(Matrix1):
462469

463470
.. NOTE::
464471

465-
In Sage one can also write ``A \ B`` for
472+
DEPRECATED. In Sage one can also write ``A \ B`` for
466473
``A.solve_right(B)``, that is, Sage implements "the
467474
MATLAB/Octave backslash operator".
468475

@@ -506,7 +513,7 @@ cdef class Matrix(Matrix1):
506513

507514
sage: A = matrix(QQ, 3, [1,2,3,-1,2,5,2,3,1])
508515
sage: b = vector(QQ,[1,2,3])
509-
sage: x = A \ b; x
516+
sage: x = A.solve_right(b); x
510517
(-13/12, 23/12, -7/12)
511518
sage: A * x
512519
(1, 2, 3)
@@ -525,21 +532,21 @@ cdef class Matrix(Matrix1):
525532
Another nonsingular example::
526533

527534
sage: A = matrix(QQ,2,3, [1,2,3,2,4,6]); v = vector([-1/2,-1])
528-
sage: x = A \ v; x
535+
sage: x = A.solve_right(v); x
529536
(-1/2, 0, 0)
530537
sage: A*x == v
531538
True
532539

533540
Same example but over `\ZZ`::
534541

535542
sage: A = matrix(ZZ,2,3, [1,2,3,2,4,6]); v = vector([-1,-2])
536-
sage: A \ v
543+
sage: A.solve_right(v)
537544
(-1, 0, 0)
538545

539546
An example in which there is no solution::
540547

541548
sage: A = matrix(QQ,2,3, [1,2,3,2,4,6]); v = vector([1,1])
542-
sage: A \ v
549+
sage: A.solve_right(v)
543550
Traceback (most recent call last):
544551
...
545552
ValueError: matrix equation has no solutions
@@ -564,24 +571,24 @@ cdef class Matrix(Matrix1):
564571
sage: A*X == B
565572
True
566573

567-
We illustrate left associativity, etc., of the backslash operator.
574+
We illustrate left associativity, etc., of the ``solve_right`` operator.
568575

569576
::
570577

571578
sage: A = matrix(QQ, 2, [1,2,3,4])
572-
sage: A \ A
579+
sage: A.solve_right(A)
573580
[1 0]
574581
[0 1]
575-
sage: A \ A \ A
582+
sage: (A.solve_right(A)).solve_right(A)
576583
[1 2]
577584
[3 4]
578-
sage: A.parent()(1) \ A
585+
sage: A.parent()(1).solve_right(A)
579586
[1 2]
580587
[3 4]
581-
sage: A \ (A \ A)
588+
sage: A.solve_right(A.solve_right(A))
582589
[ -2 1]
583590
[ 3/2 -1/2]
584-
sage: X = A \ (A - 2); X
591+
sage: X = A.solve_right(A - 2); X
585592
[ 5 -2]
586593
[-3 2]
587594
sage: A * X
@@ -593,7 +600,7 @@ cdef class Matrix(Matrix1):
593600
sage: x = polygen(QQ, 'x')
594601
sage: A = matrix(2, [x,2*x,-5*x^2+1,3])
595602
sage: v = vector([3,4*x - 2])
596-
sage: X = A \ v
603+
sage: X = A.solve_right(v)
597604
sage: X
598605
((-4/5*x^2 + 2/5*x + 9/10)/(x^3 + 1/10*x), (19/10*x^2 - 1/5*x - 3/10)/(x^3 + 1/10*x))
599606
sage: A * X == v
@@ -635,7 +642,7 @@ cdef class Matrix(Matrix1):
635642
[ 2 + O(5^4) 5 + O(5^5) 4 + O(5^4)]
636643
[ 1 + O(5^4) 1 + O(5^4) 2 + O(5^4)]
637644
sage: v = vector(k, 3, [1,2,3])
638-
sage: x = a \ v; x
645+
sage: x = a.solve_right(v); x
639646
(4 + 5 + 5^2 + 3*5^3 + O(5^4), 2 + 5 + 3*5^2 + 5^3 + O(5^4), 1 + 5 + O(5^4))
640647
sage: a * x == v
641648
True

0 commit comments

Comments
 (0)