Description

Report incorrect documentation
Location of incorrect documentation

• CuPy docs page: cupyx.signal.freq_shift — the Parameters section lists domain : string (freq or time), while the auto-generated signature at the top is cupyx.signal.freq_shift(x, freq, fs) (no domain). CuPy
• Feature addition noted in the v13.1.0 release notes (“Add cupyx.signal.freq_shift ( Add cupyx.signal.freq_shift #8128 / [backport] Add cupyx.signal.freq_shift #8131)”), but no mention of a domain argument.

Describe the problems or issues found in the documentation

• Mismatched API. The Parameters table documents a domain argument (freq or time), but the actual callable signature exposed in the docs omits it and accepts only (x, freq, fs). This discrepancy suggests either the parameter was planned but never implemented, or the docs were copied from a different design and not updated. Users attempting to pass domain= will get a TypeError: got an unexpected keyword argument 'domain'. The mismatch is visible directly on the doc page (signature vs. parameters list).
• Ambiguity around input/return dtypes. The page describes x as “array_like, complex valued,” but does not clarify whether real-valued inputs are permitted and, if so, what the output dtype will be (e.g., whether it suppport promoting to complex64/complex128, or preserving dtype). The current page lacks a precise dtype contract and promotion rules.

Steps taken to verify documentation is incorrect

1. Read the cupyx.signal.freq_shift documentation and observed the inconsistency between the signature and the parameters section.
2. Reviewed the CuPy release notes around the addition of freq_shift and found no reference to a domain parameter.
3. Compared with SciPy’s signal API surface to confirm there is no equivalent function and that users will rely on CuPy’s docs exclusively. SciPy

Suggested fix for documentation

• Remove or reconcile the domain parameter on the cupyx.signal.freq_shift page. If the function is time-domain–only, explicitly state that and drop the domain row. If a domain switch is intended, update the signature to accept domain and document its behavior precisely (including defaults and error handling).
• Clarify dtype semantics.
• Whether x may be real-valued (float32/float64) and what the output dtype is (e.g., promote to complex with the matching precision).
• Whether support complex precisions (complex64, complex128) and broadcast rules for scalar freq/fs.

A minimal example

import cupy as cp
from cupyx.signal import freq_shift

fs = 1000.0
t = cp.arange(0, 1.0, 1/fs)
f0 = 50.0
x1 = cp.exp(2j * cp.pi * f0 * t)
# y1 = freq_shift(x1, freq=100.0, fs=fs) # TypeError: Type is mismatched. x <class 'numpy.complex128'> <class 'numpy.float64'>

x2 = 0.1
y2 = freq_shift(cp.asnumpy(x2), freq=100.0, fs=fs) # passed, (0.1-0j)

Environment details:

• Environment location: Bare-metal
• Linux Distro/Architecture: [Ubuntu 20.04 x86_64]
• GPU Model/Driver: [A800, driver 525.147.05]
• CUDA: [12.9, V12.9.86]
• Python: [3.12.11]
• cuML version where it reproduces: 25.08
• Method of cuDF & cuML install: conda
  • Due to the such long result, I prefer to paste the command line I used to create the virtual environment.
    conda create -n rapids-25.08 -c rapidsai -c conda-forge -c nvidia
    rapids=25.08 python=3.12 'cuda-version>=12.0,<=12.9'

Detailed Traceback

Idea or request for content

Report needed documentation
Because freq_shift is CuPy-specific (no SciPy analog), users lack a canonical reference for expected behavior, dtypes, and edge cases. The current page does not fully specify semantics (e.g., sign convention, output dtype for real inputs, handling of non-uniform sampling, or multi-dimensional inputs).

Describe the documentation you'd like
A behavioral specification

• Mathematical definition (time-domain modulation) and sign convention.
• Input/output dtypes (e.g., whether support complex-in/complex-out and real-in promoted to complex-out, etc.).
• Shape rules and broadcasting over batch/time axes.
• Numerical considerations (e.g., phase accumulation precision at large n, float32 vs float64).
• Performance notes (elementwise nature, stream/block_size usage) and a short warning on precision for long signals.

Usage examples

• Simple tone shift; shifting a narrowband signal; comparison to doing it via STFT + frequency bin roll.

Steps taken to search for needed documentation

• Checked the cupyx.signal.freq_shift reference page and release notes. Reviewed the cupyx.signal.freq_shift API page and could not find clarification for domain selection, dtype promotion rules, or example usage that covers real inputs.
• Reviewed ElementwiseKernel docs and general custom kernels docs; while they describe parameters and caching, they don’t prominently warn about reserved identifiers like i or give signal-processing–focused examples that avoid common pitfalls. ElementwiseKernel

Rationale:
Clarifying and aligning the docs will prevent user confusion, reduce support load, and make the API safer to adopt in codebases migrating from NumPy/SciPy to CuPy.