pwelch — Estimate power spectral density using Welch's method.
pwelch(x) estimates the power spectral density of a signal by averaging modified periodograms of overlapped, windowed segments. Optional arguments select the window, overlap, FFT length, sampling frequency, frequency range, and spectrum scale.
Syntax
pxx = pwelch(x, window, noverlap, nfft, fs, freqrange)
[pxx, f] = pwelch(x, window, noverlap, nfft, fs, freqrange)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
x | NumericArray | Yes | — | Input signal vector or matrix with one signal per column. |
window | Any | No | [] | Window vector or scalar segment length. |
noverlap | NumericScalar | No | [] | Number of overlapped samples. |
nfft | NumericArray | No | [] | FFT length or explicit frequency vector. |
fs | NumericScalar | No | — | Sampling frequency in Hz. |
freqrange | StringScalar | No | — | Frequency range selector (`onesided`, `twosided`, or `centered`) and spectrum type (`psd` or `power`). |
Returns
| Name | Type | Description |
|---|---|---|
pxx | NumericArray | Power spectral density estimate. |
f | NumericArray | Frequency vector in radians/sample or Hz when fs is supplied. |
Returned values from pwelch depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:pwelch:ArgCount | The argument count is outside supported forms. | pwelch: expected pwelch(x, [window, [noverlap, [nfft_or_f, [fs, [freqrange_or_scale]]]]]) |
RunMat:pwelch:InvalidSignal | Input signal is not a numeric vector or matrix. | pwelch: x must be a nonempty numeric vector or 2-D matrix |
RunMat:pwelch:InvalidWindow | Window input is invalid. | pwelch: window must be a nonempty vector or positive integer length |
RunMat:pwelch:InvalidOverlap | Overlap is invalid. | pwelch: noverlap must be a nonnegative integer less than window length |
RunMat:pwelch:InvalidNfft | FFT length is invalid. | pwelch: nfft must be a positive integer at least as large as the window length |
RunMat:pwelch:InvalidFs | Sampling frequency is invalid. | pwelch: fs must be a positive finite scalar |
RunMat:pwelch:InvalidRange | Frequency range selector is invalid. | pwelch: freqrange must be 'onesided', 'twosided', or 'centered'; spectrum type must be 'psd' or 'power' |
RunMat:pwelch:Internal | Output tensor construction fails internally. | pwelch: internal error |
How pwelch works
pxx = pwelch(x)returns a one-sided PSD estimate for real inputs and a two-sided estimate for complex inputs.- Matrix inputs are processed column-wise;
pxxhas one output column per input column. [pxx, f] = pwelch(...)also returns the frequency grid. Withoutfs, frequencies are in radians/sample; withfs, frequencies are in Hz.- The
windowargument may be a vector or a scalar segment length. A scalar creates a Hamming window of that length;[]uses a default Hamming window sized for roughly eight 50%-overlapped sections, capped at 256 samples. noverlapdefaults to half the window length and must be less than the window length.nfftdefaults tomax(256, length(window)), must be at least the window length, and controls the FFT grid. A real frequency vector may be supplied in the same position to evaluate the PSD at explicit frequencies.- The optional range selector accepts
'onesided','twosided', or'centered'. - The optional spectrum type accepts
'psd'(default) or'power';'power'omits the density bandwidth normalization.
Examples
PSD of a sine wave
fs = 1000;
t = (0:999) / fs;
x = sin(2*pi*100*t);
[pxx, f] = pwelch(x, hamming(256), 128, 512, fs);Use a scalar window length
[pxx, w] = pwelch(randn(1,1024), 128, 64, 256);Two-sided spectrum
x = exp(1i*2*pi*(0:127)/16);
[pxx, w] = pwelch(x, 64, 32, 128, 'twosided');Centered spectrum in Hz
[pxx, f] = pwelch(randn(1,512), [], [], 512, 2000, 'centered');Column-wise spectra for a matrix
x = [sin(2*pi*(0:255)'/16), cos(2*pi*(0:255)'/32)];
[pxx, f] = pwelch(x, 64, 32, 128, 'power');Evaluate at explicit normalized frequencies
w = linspace(0, pi, 64);
[pxx, wout] = pwelch(randn(1,512), hamming(128), 64, w);Using pwelch with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how pwelch changes the result.
Run a small pwelch example, explain the result, then change one input and compare the output.
FAQ
Can I pass a Hamming window from the hamming builtin?⌄
Yes. pwelch(x, hamming(n), noverlap, nfft, fs) uses the provided window directly. Passing the scalar n instead creates the same kind of Hamming segment window internally.
Does pwelch include the Nyquist bin?⌄
For one-sided output and even nfft, yes. The output length is nfft/2 + 1, with DC first and the Nyquist bin last.
Does pwelch plot when no outputs are requested?⌄
RunMat currently returns values using normal output-count semantics instead of opening a plot. Use the returned pxx and frequency vector with plotting functions explicitly.
Related Math functions
Signal
blackman · butter · buttord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · rectpuls · sawtooth · sinc · spectrogram · square · tripuls · unwrap · upsample · zplane
Elementwise
abs · angle · complex · conj · double · exp · expm1 · factorial · gamma · heaviside · hypot · imag · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · sign · single · sqrt · times
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · deg2rad · rad2deg · sin · sind · sinh · tan · tand · tanh
Reduction
all · any · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · mean · median · min · nnz · prod · std · sum · trapz · var
Structure
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how pwelch is executed, line by line, in Rust.
- View the source for pwelch in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.