Add document of function torch.as_strided #22842

kianasun · 2019-07-13T23:34:05Z

Documentation of torch.as_strided and Tensor.as_strided is missing. As mentioned in #9886

facebook-github-bot

@soumith is landing this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

ssnl · 2019-07-15T16:26:20Z

torch/_torch_docs.py

+           r"""
+as_strided(input, size, stride, storage_offset=0) -> Tensor
+
+Create a `torch.Tensor` from an existing `torch.Tensor` :attr:`input` with


I think it is important to mention that this creates a view of an existing tensor. :)

You are right. Will Create a view of an existing torch.Tensor ... be better?

Yes, that sounds great! Thank you!

Also, could you also add an entry to the method version of it at https://github.com/pytorch/pytorch/blob/f2f80744be347fab6921fc55181b55dc86c7e07b/torch/_tensor_docs.py? It should be easy and could just refer to torch.as_strided.

Actually I think torch.as_strided probably should not exist. Only the method version should, similar to resize.

cc @gchanan who probably should have better opinion on this.

I think it's fine, torch.as_tensor exists (because it needs to), so other as_ functions seem like fair game.

Cool. I will update both soon.

ssnl

Thank you!

zou3519

Wait, I thought it was intentional that torch.as_strided doesn't have documentation because it is dangerous and that users shouldn't be using it. Can we at least add a big red warning that this is dangerous?

kianasun · 2019-07-16T16:41:48Z

Wait, I thought it was intentional that torch.as_strided doesn't have documentation because it is dangerous and that users shouldn't be using it. Can we at least add a big red warning that this is dangerous?

I think we can do that. Do we need to write some specific reasons why this is dangerous?

zou3519 · 2019-07-16T16:46:35Z

Wait, I thought it was intentional that torch.as_strided doesn't have documentation because it is dangerous and that users shouldn't be using it. Can we at least add a big red warning that this is dangerous?

I think we can do that. Do we need to write some specific reasons why this is dangerous?

Things we should write:

Can lead to the access of memory out of bounds, resulting in garbage data
You should only use this function if you know what you're doing. A lot of pytorch functions are implemented internally with this.
Should also have the same warning as in tensor.expand: https://pytorch.org/docs/master/tensors.html#torch.Tensor.expand

ssnl · 2019-07-16T16:50:30Z

I think that is is not that dangerous. You can’t access data outside the underlying storage. The important thing is to mention that this returns a view. We can check what np says about their counterpart in the docs.

zou3519 · 2019-07-16T16:56:24Z

I think that is is not that dangerous. You can’t access data outside the underlying storage. The important thing is to mention that this returns a view. We can check what np says about their counterpart in the docs.

https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.lib.stride_tricks.as_strided.html for reference @kianasun

kianasun · 2019-07-17T00:21:05Z

@zou3519 Updated. :)

zou3519 · 2019-07-17T02:05:28Z

torch/_torch_docs.py

+
+.. warning::
+    :func:`as_strided` manipulates the internal data structure of tensors.
+    If done incorrectly, it can lead to the access of invalid memory and


@ssnl says this isn't possible anymore. I played around with as_strided as well and noticed there are indeed checks, so maybe it isn't applicable anymore

Ok. I will remove the first paragraph.

zou3519 · 2019-07-17T02:08:36Z

torch/_torch_docs.py

+    vectorized) may result in incorrect behavior. If you need to write to
+    the tensors, please clone them first.
+
+    You should only use this function if you know what you're doing. A lot


You should only use this function if you know what you're doing.

I know I suggested this, but this sounds bad. Something like the following would be better:

"Many PyTorch functions that return a view on a tensor are internally implemented with this function. Those functions, like torch.expand, are easier to read and are therefore more advisable to use"

xuhdev

There is also an inplace version as_strided_, you probably wanna document it as well (in docs/source/tensors.rst). Document test skipping should also be deleted:

pytorch/test/test_torch.py

Lines 196 to 197 in 7d055c2

    
           'as_strided', 
        
           'as_strided_',

ssnl · 2019-07-17T17:21:41Z

I wouldn't document the inplace version.. t_ gives us enough trouble.

xuhdev · 2019-07-17T17:31:16Z

@ssnl Why don't we unexpose that function if we do not want user to use it (this should probably discussed in a different thread)? Leaving a function undocumented doesn't prevent adventurous users from using it.

ssnl · 2019-07-17T21:58:06Z

@xuhdev We should hide it IMHO, just like many other things. It's just that no one has done it. It would probably require a deprecation cycle and fix the internal callsites.

facebook-github-bot

@soumith has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

facebook-github-bot

@soumith has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

soumith · 2019-07-19T06:25:04Z

@pytorchbot rebase this please

facebook-github-bot

@soumith has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

soumith · 2019-07-20T17:50:21Z

@pytorchbot rebase this please

facebook-github-bot

@soumith is landing this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

soumith · 2019-07-22T23:10:43Z

@pytorchbot rebase this please

facebook-github-bot

@soumith has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

facebook-github-bot

@soumith has imported this pull request. If you are a Facebook employee, you can view this diff on Phabricator.

facebook-github-bot · 2019-07-23T16:06:23Z

@soumith merged this pull request in 45d3f49.

pytorchbot added the module: docs Related to our documentation, both in docs/ and docblocks label Jul 13, 2019

ezyang added the open source label Jul 13, 2019

soumith approved these changes Jul 14, 2019

View reviewed changes

facebook-github-bot reviewed Jul 14, 2019

View reviewed changes

ssnl reviewed Jul 15, 2019

View reviewed changes

kianasun force-pushed the document-functionalities branch from ade9299 to e0fe038 Compare July 15, 2019 19:31

ssnl approved these changes Jul 15, 2019

View reviewed changes

zou3519 requested changes Jul 16, 2019

View reviewed changes

kianasun force-pushed the document-functionalities branch from e0fe038 to fd3839a Compare July 17, 2019 00:16

zou3519 reviewed Jul 17, 2019

View reviewed changes

kianasun force-pushed the document-functionalities branch from fd3839a to 132d578 Compare July 17, 2019 03:54

xuhdev reviewed Jul 17, 2019

View reviewed changes

zou3519 approved these changes Jul 18, 2019

View reviewed changes

facebook-github-bot reviewed Jul 18, 2019

View reviewed changes

Add document of function as_strided

5d88cfc

kianasun force-pushed the document-functionalities branch from 132d578 to 5d88cfc Compare July 19, 2019 04:08

facebook-github-bot reviewed Jul 19, 2019

View reviewed changes

Merge remote-tracking branch 'origin/master' into HEAD

3a46ed2

facebook-github-bot reviewed Jul 19, 2019

View reviewed changes

Merge remote-tracking branch 'origin/master' into HEAD

d72d7f9

facebook-github-bot reviewed Jul 20, 2019

View reviewed changes

Update test_torch.py

7748e2d

pytorchbot added the module: operators label Jul 22, 2019

Merge remote-tracking branch 'origin/master' into HEAD

00491c1

facebook-github-bot reviewed Jul 22, 2019

View reviewed changes

Update test_torch.py

245e66d

facebook-github-bot reviewed Jul 23, 2019

View reviewed changes

facebook-github-bot closed this in 45d3f49 Jul 23, 2019

facebook-github-bot added the merged label Jul 23, 2019

kianasun deleted the document-functionalities branch July 23, 2019 22:54

choidongyeon mentioned this pull request Apr 7, 2020

[doc] functionalities not documented #9886

Open

7 tasks

mruberry added the Merged label Oct 28, 2020

mruberry mentioned this pull request Sep 23, 2021

Clarified difference in behavior of empty_strided and as_strided #64568

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add document of function torch.as_strided #22842

Add document of function torch.as_strided #22842

kianasun commented Jul 13, 2019 •

edited by xuhdev

Loading

facebook-github-bot left a comment

ssnl Jul 15, 2019

kianasun Jul 15, 2019

ssnl Jul 15, 2019

ssnl Jul 15, 2019

ssnl Jul 15, 2019

gchanan Jul 15, 2019

kianasun Jul 15, 2019

ssnl left a comment

zou3519 left a comment

kianasun commented Jul 16, 2019

zou3519 commented Jul 16, 2019

ssnl commented Jul 16, 2019

zou3519 commented Jul 16, 2019

kianasun commented Jul 17, 2019

zou3519 Jul 17, 2019

kianasun Jul 17, 2019

zou3519 Jul 17, 2019

xuhdev left a comment

ssnl commented Jul 17, 2019

xuhdev commented Jul 17, 2019

ssnl commented Jul 17, 2019

facebook-github-bot left a comment

facebook-github-bot left a comment

soumith commented Jul 19, 2019

facebook-github-bot left a comment

soumith commented Jul 20, 2019

facebook-github-bot left a comment

soumith commented Jul 22, 2019

facebook-github-bot left a comment

facebook-github-bot left a comment

facebook-github-bot commented Jul 23, 2019

Add document of function torch.as_strided #22842

Add document of function torch.as_strided #22842

Conversation

kianasun commented Jul 13, 2019 • edited by xuhdev Loading

facebook-github-bot left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ssnl left a comment

Choose a reason for hiding this comment

zou3519 left a comment

Choose a reason for hiding this comment

kianasun commented Jul 16, 2019

zou3519 commented Jul 16, 2019

ssnl commented Jul 16, 2019

zou3519 commented Jul 16, 2019

kianasun commented Jul 17, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

xuhdev left a comment

Choose a reason for hiding this comment

ssnl commented Jul 17, 2019

xuhdev commented Jul 17, 2019

ssnl commented Jul 17, 2019

facebook-github-bot left a comment

Choose a reason for hiding this comment

facebook-github-bot left a comment

Choose a reason for hiding this comment

soumith commented Jul 19, 2019

facebook-github-bot left a comment

Choose a reason for hiding this comment

soumith commented Jul 20, 2019

facebook-github-bot left a comment

Choose a reason for hiding this comment

soumith commented Jul 22, 2019

facebook-github-bot left a comment

Choose a reason for hiding this comment

facebook-github-bot left a comment

Choose a reason for hiding this comment

facebook-github-bot commented Jul 23, 2019

kianasun commented Jul 13, 2019 •

edited by xuhdev

Loading