pytorch - 💡(How to fix) Fix [Feedback about torch.multinomial][Docs] Inconsistency in torch.multinomial: Note says "lower than" but example allows "equal to" for num_samples without replacement [1 participants]

I noticed a minor wording inconsistency in the documentation for torch.multinomial. The Note section states that when replacement=False, num_samples must be strictly lower than the number of non-zero elements. However, the provided example explicitly demonstrates that num_samples can be equal to the number of non-zero elements without raising an error.

TL;DR

The documentation for torch.multinomial should be updated to reflect that num_samples can be equal to the number of non-zero elements when replacement=False.

Guidance

• Review the documentation for torch.multinomial to ensure accuracy regarding the relationship between num_samples and non-zero elements when replacement=False.
• Verify the behavior of torch.multinomial with different inputs and num_samples values to confirm the observed inconsistency.
• Consider updating the Note section to indicate that num_samples can be less than or equal to the number of non-zero elements.
• Check for any potential edge cases or errors that may arise when num_samples equals the number of non-zero elements.

Example

weights = torch.tensor([0, 10, 3, 0], dtype=torch.float)
print(torch.multinomial(weights, 2))  # Expected to run successfully

Notes

The current documentation may cause confusion for users who rely on it for understanding the behavior of torch.multinomial. Updating the documentation will help ensure accuracy and clarity.

Recommendation

Apply workaround: Update the documentation to reflect the correct behavior of torch.multinomial when replacement=False, allowing num_samples to be equal to the number of non-zero elements.