pytorch/docs
Mike Ruberry 3b7e1cd2cc Makes floor_divide a method, adds sparse floor division (#34552)
Summary:
(Updated per review feedback)

`torch.floor_divide` is currently a function that can operate on two tensors or a tensor and a scalar (scalar x scalar floor division is handled natively by Python and the JIT has a builtin function for it). This PR updates it to:

- have an out variant: `floor_divide(x, y, out=z)`
- be a method on a tensor: `x.floor_divide(y)`
- have an in-place variant: `x.floor_divide_(y)`
- work with sparse tensors

Tests are added to test_sparse.py and test_torch.py for these new behaviors.

In addition, this PR:

- cleans up the existing sparse division and true_division code and improves their error message
- adds testing of sparse true_division to test_sparse.py
- extends existing floor_divide testing in test_torch to run on CUDA, too, not just the CPU

Unfortunately, making floor_divide a method requires breaking backwards compatibility, and floor_divide has been added to the BC whitelist since this is international. The BC issue is that the first parameter name to torch.floor_divide is changing from input to self. If you previously called torch.floor_divide with keyword arguments, e.g. torch.floor_divide(input=x, other=y), you will need to update to torch.floor_divide(self=x, other=y), or the more common torch.floor_divide(x, y).

The intent of this PR is to allow floor_divide to be substituted for division (torch.div, /) wherever division was previously used. In 1.6 we expect torch.div to perform true_division, and floor_divide is how users can continue to perform integer division with tensors.

There are two potential follow-up issues suggested by this PR:

- the test framework might benefit from additional tensor construction classes, like one to create dividends and divisors for multiple dtypes
- the test framework might benefit from a universal function test class. while methods have reasonable coverage as part of test_torch.py's TestTensorOp tests, function coverage is spotty. Universal functions are similar enough it should be possible to generate tests for them.
Pull Request resolved: https://github.com/pytorch/pytorch/pull/34552

Differential Revision: D20509850

Pulled By: mruberry

fbshipit-source-id: 2cd3c828aad67191c77f2ed8470411e246f604f8
2020-03-18 15:00:53 -07:00
..
caffe2 Fix interpreter lines for files with python2-only syntax. 2019-07-09 10:51:43 -07:00
cpp Fix C++ at::Tensor docs generation (#34467) 2020-03-09 08:04:32 -07:00
source Makes floor_divide a method, adds sparse floor division (#34552) 2020-03-18 15:00:53 -07:00
.gitignore .gitignore for the docs folder 2019-10-08 12:18:30 -07:00
libtorch.rst Update libtorch docs (#21150) 2019-05-30 12:49:56 -07:00
make.bat Convert all tabs to spaces, add CI. (#18959) 2019-04-09 08:12:26 -07:00
Makefile Rewrite http://pytorch.org -> https://pytorch.org throughout project (#12636) 2018-10-15 13:03:27 -07:00
requirements.txt Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00