Deprecate torch.lu_solve

**BC-breaking note**:

This PR deprecates `torch.lu_solve` in favor of `torch.linalg.lu_solve_factor`.
A upgrade guide is added to the documentation for `torch.lu_solve`.

Note this PR DOES NOT remove `torch.lu_solve`.

Pull Request resolved: pytorch#73806

Approved by: https://github.com/IvanYashchuk, https://github.com/nikitaved, https://github.com/mruberry

Author: lezcano

aten/src/ATen/native/BatchLinearAlgebra.cpp

@@ -1470,7 +1470,7 @@ std::tuple<Tensor,Tensor> solve(const Tensor& self, const Tensor& A) {
     "torch.solve is deprecated in favor of torch.linalg.solve",
     "and will be removed in a future PyTorch release.\n",
     "torch.linalg.solve has its arguments reversed and does not return the LU factorization.\n",
-    "To get the LU factorization see torch.linalg.lu_factor, which can be used with torch.lu_solve or torch.lu_unpack.\n",
+    "To get the LU factorization see torch.linalg.lu_factor.\n",
     "X = torch.solve(B, A).solution\n",
     "should be replaced with\n",
     "X = torch.linalg.solve(A, B)"
@@ -1489,7 +1489,7 @@ std::tuple<Tensor&,Tensor&> solve_out(const Tensor& self, const Tensor& A, Tenso
     "torch.solve is deprecated in favor of torch.linalg.solve",
     "and will be removed in a future PyTorch release.\n",
     "torch.linalg.solve has its arguments reversed and does not return the LU factorization.\n",
-    "To get the LU factorization see torch.linalg.lu_factor, which can be used with torch.lu_solve or torch.lu_unpack.\n",
+    "To get the LU factorization see torch.linalg.lu_factor.\n",
     "X = torch.solve(B, A).solution\n",
     "should be replaced with\n",
     "X = torch.linalg.solve(A, B)"
@@ -2439,10 +2439,26 @@ TORCH_IMPL_FUNC(linalg_lu_solve_out)(const Tensor& LU,
 }
 
 Tensor lu_solve(const Tensor& self, const Tensor& LU_data, const Tensor& LU_pivots) {
+  TORCH_WARN_ONCE(
+    "torch.lu_solve is deprecated in favor of torch.linalg.lu_solve",
+    "and will be removed in a future PyTorch release.\n",
+    "Note that torch.linalg.lu_solve has its arguments reversed.\n",
+    "X = torch.lu_solve(B, LU, pivots)\n",
+    "should be replaced with\n",
+    "X = torch.linalg.lu_solve(LU, pivots, B)"
+  );
   return at::linalg_lu_solve(LU_data, LU_pivots, self);
 }
 
 Tensor& lu_solve_out(const Tensor& self, const Tensor& LU_data, const Tensor& LU_pivots, Tensor& result) {
+  TORCH_WARN_ONCE(
+    "torch.lu_solve is deprecated in favor of torch.linalg.lu_solve",
+    "and will be removed in a future PyTorch release.\n",
+    "Note that torch.linalg.lu_solve has its arguments reversed.\n",
+    "X = torch.lu_solve(B, LU, pivots)\n",
+    "should be replaced with\n",
+    "X = torch.linalg.lu_solve(LU, pivots, B)"
+  );
   return at::linalg_lu_solve_out(result, LU_data, LU_pivots, self);
 }
 

torch/_torch_docs.py

@@ -4339,7 +4339,7 @@ def merge_dicts(*dicts):
     and will be removed in a future PyTorch release.
     :func:`torch.linalg.solve` has its arguments reversed and does not return the
     LU factorization of the input. To get the LU factorization see :func:`torch.linalg.lu_factor`,
-    which may be used with :func:`torch.lu_solve`.
+    which may be used with :func:`torch.linalg.lu_solve`.
 
     ``X = torch.solve(B, A).solution`` should be replaced with
 
@@ -5813,6 +5813,16 @@ def merge_dicts(*dicts):
 
 This function supports ``float``, ``double``, ``cfloat`` and ``cdouble`` dtypes for :attr:`input`.
 
+.. warning::
+
+    :func:`torch.lu_solve` is deprecated in favor of :func:`torch.linalg.lu_solve`.
+    :func:`torch.lu_solve` will be removed in a future PyTorch release.
+    ``X = torch.lu_solve(B, LU, pivots)`` should be replaced with
+
+    .. code:: python
+
+        X = torch.linalg.lu_solve(LU, pivots, B)
+
 Arguments:
     b (Tensor): the RHS tensor of size :math:`(*, m, k)`, where :math:`*`
                 is zero or more batch dimensions.