pytorch/docs/source
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
..
_static Improve documentation around builtin functions (#30347) 2019-12-04 13:50:40 -08:00
_templates
_templates-stable Add layout.html to template for stable docs (#33770) 2020-03-04 03:14:52 -08:00
community Fix broken links in governance.rst 2020-02-04 14:26:09 -08:00
notes Revert D20346700: [pytorch][PR] Eager autocasting, out-of-place ops only 2020-03-18 11:42:51 -07:00
org/pytorch [jit] kill script namespace (#34515) 2020-03-11 23:32:48 -07:00
scripts Add torch.nn.GELU for GELU activation (#28944) 2019-11-03 21:55:05 -08:00
__config__.rst
amp.rst Revert D20346700: [pytorch][PR] Eager autocasting, out-of-place ops only 2020-03-18 11:42:51 -07:00
autograd.rst Added docs for context method mixins. Fixes issue #27365 (#28643) 2019-10-28 08:31:35 -07:00
bottleneck.rst
checkpoint.rst
conf.py Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00
cpp_extension.rst
cuda.rst
cuda_deterministic.rst
cuda_deterministic_backward.rst
cudnn_deterministic.rst
cudnn_persistent_rnn.rst
data.rst Fix typo in data.rst (#34624) 2020-03-11 19:40:18 -07:00
distributed.rst Fix typos (#30606) 2019-12-02 20:17:42 -08:00
distributions.rst Continuous bernoulli distribution (take 2) (#34619) 2020-03-12 11:53:18 -07:00
dlpack.rst
hub.rst Fix typos, via a Levenshtein-type corrector (#31523) 2020-01-17 16:03:19 -08:00
index.rst Add list of view ops to public doc. (#32560) 2020-02-28 15:05:55 -08:00
jit.rst [jit] kill script namespace (#34515) 2020-03-11 23:32:48 -07:00
jit_builtin_functions.rst
jit_language_reference.rst [docs] add experimental warning to TorchScript classes in language reference (#33697) 2020-02-24 14:01:19 -08:00
jit_python_reference.rst Add Python language reference docs (#30686) 2019-12-26 13:21:36 -08:00
jit_unsupported.rst [JIT] add support for torch.norm (#33783) 2020-03-05 14:46:24 -08:00
math-quantizer-equation.png
model_zoo.rst
multiprocessing.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
name_inference.rst Fix typos (#30606) 2019-12-02 20:17:42 -08:00
named_tensor.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
nn.functional.rst
nn.init.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
nn.rst Pruning Functionality (#24076) 2019-11-08 19:38:00 -08:00
onnx.rst Adds true_divide function, analogous to Python 's, JAX's, NumPy's (true) division (#34236) 2020-03-09 21:06:33 -07:00
optim.rst Fix capitalization inconsistency in optim.rst 2019-12-04 08:17:03 -08:00
packages.rst Revert D19320493: Javadoc changes 2020-01-09 14:23:30 -08:00
quantization.rst Fixed typos in quantization docs / docstrings (#34182) 2020-03-06 21:53:52 -08:00
random.rst
rpc.rst Update descriptions for transmitting CUDA tensors (#34888) 2020-03-17 17:43:48 -07:00
sparse.rst Bag of documentation fixes; fix more sphinx warnings (#27850) 2019-10-15 07:31:14 -07:00
storage.rst
tensor_attributes.rst
tensor_view.rst Add list of view ops to public doc. (#32560) 2020-02-28 15:05:55 -08:00
tensorboard.rst
tensors.rst Makes floor_divide a method, adds sparse floor division (#34552) 2020-03-18 15:00:53 -07:00
torch.rst PCA and SVD for low-rank matrices, LOBPCG for positive-defined generalized eigenvalue problem - copy (#34721) 2020-03-16 14:13:30 -07:00
type_info.rst