[ndgrigorian]

This PR proposes the addition of dpnp.top_k, which will be available in NumPy 2.6

dpnp.top_k reuses tensor.top_k, but adds NumPy-aligned functionality, including a sorted keyword

Also deprecates behavior in dpnp.tensor.top_k which was part of the initial array API plan that changed during its addition to the spec

• Have you provided a meaningful PR description?
• Have you added a test, reproducer or referred to an issue with a reproducer?
• Have you tested your changes locally for CPU and GPU devices?
• Have you made sure that new changes do not introduce compiler warnings?
• Have you checked performance impact of proposed changes?
• Have you added documentation for your changes, if necessary?
• Have you added your changes to the changelog?

[github-actions]

Array API standard conformance tests for dpnp=0.22.0dev0=np2py314h8d9cdd5_22 ran successfully.
Passed: 1491
Failed: 0
Skipped: 6

[github-actions]

View rendered docs @ https://intelpython.github.io/dpnp/index.html

[coveralls]

coverage: 84.376% (+0.01%) from 84.364% — feature/add-dpnp-topk into master

[Copilot]

🟡 Changes recommended

The sorted=False test compares identical gathers rather than checking returned values against the indexed input, allowing incorrect indices to pass.

1 open issue

• Validate returned values against the original input · New

What changed in this PR

Adds dpnp.top_k as a NumPy-aligned public wrapper around dpnp.tensor.top_k, returning selected values and their indices.

Changes:

• Supports largest/smallest selection along an axis, with optional sorted output.
• Adds tests for dtypes, axes, NaNs, input types, and errors.
• Exports the function and adds API documentation and a changelog entry.

File	Description
dpnp/​tests/​test_sort.py	Adds selection, compatibility, and validation tests.
dpnp/​dpnp_iface_sorting.py	Implements and documents top_k, including output sorting.
dpnp/​__init__.py	Exports top_k in the public namespace.
doc/​reference/​sort.rst	Lists top_k in the sorting reference.
CHANGELOG.md	Records the new function and sorting option.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the new dpnp.top_k API.

No open issues 🎉

1 resolved since last review

• Validate returned values against the original input

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues are recorded for the new top_k API and tensor-axis deprecation.

No open issues 🎉

_{Review effort: Balanced}

[antonwolfy]

LGTM, thank you!

[antonwolfy]

One more follow-up is about an ASV benchmark for dpnp.top_k: I'd suggest not adding one in this PR and covering it in a follow-up instead.

• The benchmark suite has no sorting module yet, so adding one here would mean designing it around a single function.
• dpnp.top_k wraps dpnp.tensor.top_k, so a benchmark would mainly time the existing kernel.
• For the "checked performance impact" item, a quick timing in the PR description is enough (e.g. top_k vs sort + slice for a few k values).

Follow-up proposal: a new benchmarks/benchmarks/bench_sorting.py covering sort, argsort, partition and top_k together, none of which is benchmarked today:

• the shared _SIZES_1D and _FLOAT_DTYPES axes from _utils.py
• a k axis with a few small values and one large one
• sorted=True/False for top_k
• sizes and parameter combinations kept moderate, so the Jenkins ASV job doesn't get noisier