pytorch - 💡(How to fix) Fix Clarify torch.searchsorted behavior when sorted_sequence is unsorted [1 pull requests]

Describe the issue

torch.searchsorted accepts an unsorted sorted_sequence and returns indices without warning or validation.

I understand that the current documentation says sorted_sequence should contain a monotonically increasing sequence on the innermost dimension unless sorter is provided. This report is therefore mainly about documentation/API clarity rather than a security issue.

The current behavior can be surprising because the operator silently returns indices that differ from the result obtained after sorting the boundaries first. It would be helpful if the docs explicitly stated that the result is undefined/unspecified when sorted_sequence is unsorted, or if there were an optional validation path for debugging.

Reproducer

import torch

boundaries = torch.tensor([10, 0, 5])
values = torch.tensor([0, 4, 11])

print("torch:", torch.__version__)
print("boundaries:", boundaries)
print("values:", values)
print("is sorted:", bool(torch.all(boundaries[:-1] <= boundaries[1:])))

out = torch.searchsorted(boundaries, values)
print("searchsorted output:", out)

sorted_boundaries = torch.sort(boundaries).values
out_sorted = torch.searchsorted(sorted_boundaries, values)
print("sorted_boundaries:", sorted_boundaries)
print("output on sorted boundaries:", out_sorted)

Actual behavior

On recent builds, this runs successfully even though boundaries is not sorted.

Example output:

boundaries: tensor([10,  0,  5])
values: tensor([ 0,  4, 11])
is sorted: False
searchsorted output: tensor([0, 2, 3])
sorted_boundaries: tensor([ 0,  5, 10])
output on sorted boundaries: tensor([0, 1, 3])

Expected behavior

Either:

1. the documentation should explicitly say that PyTorch does not validate this precondition and that results are undefined/unspecified when sorted_sequence is not sorted and no sorter is provided; or
2. PyTorch could provide an optional validation/debug path that raises a clear Python exception for unsorted sorted_sequence.

I am not asking for this to be treated as a security issue. This is about avoiding silent, surprising behavior for an invalid-but-easy-to-pass input.

I understand that checking sortedness by default may be too expensive, so a documentation clarification alone would already address the surprising part.

Environments tested

Environment 1:

torch: 2.9.1+cu128
python: 3.12.12
GPU available: NVIDIA RTX PRO 6000 Blackwell Server Edition
probe path: CPU

Environment 2:

python: 3.12.13
platform: Linux-6.6.122+-x86_64-with-glibc2.35
torch: 2.10.0+cpu
cuda available: False
result: searchsorted survived and returned tensor([0, 2, 3])

Environment 3:

python: 3.12.13
platform: Linux-6.6.122+-x86_64-with-glibc2.35
torch: 2.13.0.dev20260521+cpu
torch git version: b0e6c698ed54c38072586530a224a2834d36d222
cuda available: False
result: searchsorted survived and returned tensor([0, 2, 3])

Additional note

This may simply be a documentation issue because the API already requires a monotonically increasing sorted_sequence. I am filing it to ask whether the undefined behavior should be documented more explicitly or whether an optional validation mode would be useful.

cc @svekars @sekyondaMeta @AlannaBurke