Whether or not a sparse tensor is coalesced or uncoalesced to be an implementation detail, and operations should operate identically whether or not I have called coalesce or not on a sparse tensor. If an operation DOES behave differently depending on if you've coalesced or not, that is an important detail to document, since it means the operation is mucking about with the internal representation of sparse tensors and you need to be extra careful. In other words, these operations by-in-large should be used internally in PyTorch, and not recommended for external use.

The operators (which I know of) which have this property are:

• values
• indices
• sparse_mask
• nnz

So, I think documenting the behavior here should be pretty uncontroversial, but I also want to make an argument that we should ALSO rename these functions (e.g., prepend an underscore) to make it visually distinctive that something is going on here. The reason I believe this is a good idea is not because people might do it wrong (though, evidenced by bugs in PyTorch today, I DO think people will get it wrong), but because you can get it wrong, and think that your code is correct, because all of your testing happens to be on coalesced sparse tensors where things happen to work out correctly. Then you are in for a nasty surprise if you pass an uncoalesced tensor at some point in the future.

(This is a follow up to #1438.)