frozenleaves/pytorch
1
0
Fork 0
mirror of https://github.com/pytorch/pytorch.git synced 2025-10-20 21:14:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated warning documentation

Mike Ruberry
2020-12-22 16:58:51 -08:00
parent 60eabb739d
commit 292c8cc8ac
1 changed files with 5 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
Developer-FAQ.md

@ -28,26 +28,11 @@ Each PR takes costly machine and developer time. "Small" PRs that may correct a
### When should I TORCH_WARN vs. TORCH_WARN_ONCE?
PyTorch offers both [TORCH_WARN](https://github.com/pytorch/pytorch/blob/4f538a2ba48afeb2a2a1f3b6e01b1ec461d4a5ed/c10/util/Exception.h#L391) and [TORCH_WARN_ONCE](https://github.com/pytorch/pytorch/blob/4f538a2ba48afeb2a2a1f3b6e01b1ec461d4a5ed/c10/util/Exception.h#L402). The latter, as the name suggests, will cause a warning to be triggered one time, while TORCH_WARN will throw a warning every time.
Generally you should use TORCH_WARN_ONCE. Warning the user every time a behavior occurs is often onerous, especially if the warning occurs in a network's training loop. TORCH_WARN is appropriate only if the warning may occur in contexts so different that a user could not infer that the warning would be triggered after reading the first warning. Let's look at a few examples that clarify this principle.
`TORCH_WARN_ONCE("Casting complex values to real discards the imaginary part");`
This is a good use of TORCH_WARN_ONCE. Once a user has been warned that this behavior occurs they should be able to infer when it's occurring. Warning them each time it happens is unnecessary.
`TORCH_WARN("Use of masked_fill_ on expanded tensors is deprecated...`
This is a poor use of TORCH_WARN, and TORCH_WARN_ONCE is preferred when warning a user about deprecated behavior. Once a user knows the behavior is deprecated they don't need to be told again and again and again.
`TORCH_WARN("An output with one or more elements was resized since it had...`
This is a good use of TORCH_WARN. This warning [occurs in a helper function](https://github.com/pytorch/pytorch/blob/dae94ed02299cd1e9840ce6e49ea142b4d118b2d/aten/src/ATen/native/Resize.cpp#L12) that can be called from multiple different contexts. This particular behavior of resizing tensors given to `out=` can also be tricky to identify and rarely reflects the user's intent, unlike casting complex tensors to floating point, which is likely an intentional act.
PyTorch offers both [TORCH_WARN](https://github.com/pytorch/pytorch/blob/4f538a2ba48afeb2a2a1f3b6e01b1ec461d4a5ed/c10/util/Exception.h#L391) and [TORCH_WARN_ONCE](https://github.com/pytorch/pytorch/blob/4f538a2ba48afeb2a2a1f3b6e01b1ec461d4a5ed/c10/util/Exception.h#L402). The latter, as the name suggests, will cause a warning to be triggered one time per process, while TORCH_WARN will throw a warning every time.
Generally you should use TORCH_WARN_ONCE. Warning the user every time a behavior occurs is often onerous, especially if the warning occurs in a network's training loop. Only use TORCH_WARN in the following situations:
- a user opted-in to the warnings, like by enabling anomaly mode
- a non-critical operation failed
For all other situations, like deprecation warnings and behavior that may result in crashes, use TORCH_WARN_ONCE.