unwrap — Correct phase-angle jumps by adding multiples of 2*pi.
Q = unwrap(P) adjusts phase angles in radians by adding integer multiples of 2*pi whenever adjacent samples jump by more than the tolerance.
Syntax
Q = unwrap(P)
Q = unwrap(P, tol)
Q = unwrap(P, tol, dim)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
P | NumericArray | Yes | — | Wrapped phase angles in radians. |
tol | NumericScalar | No | pi | Jump tolerance. Values below pi are treated as pi. |
tol | NumericScalar | No | pi | Jump tolerance. Use [] to keep the default. |
dim | NumericScalar | No | first non-singleton dimension | Dimension along which to unwrap. |
Returns
| Name | Type | Description |
|---|---|---|
Q | NumericArray | Phase values with jumps larger than the tolerance corrected by multiples of 2*pi. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:unwrap:ArgCount | More than three input arguments are supplied. | unwrap: expected unwrap(P), unwrap(P, tol), or unwrap(P, tol, dim) |
RunMat:unwrap:InvalidInput | Input cannot be converted to a real numeric/logical phase array. | unwrap: expected real numeric input |
RunMat:unwrap:InvalidTolerance | Tolerance is not a finite, nonnegative scalar. | unwrap: tolerance must be a finite nonnegative scalar |
RunMat:unwrap:InvalidDimension | Dimension argument is missing, non-numeric, non-integer, or less than one. | unwrap: dimension must be a positive integer scalar |
RunMat:unwrap:Internal | Internal gather, tensor conversion, or allocation fails. | unwrap: internal error |
How unwrap works
- The compatibility surface accepts real single or double phase data. Logical and native typed-integer phase data are separately gated RunMat extensions.
- Operates along the first non-singleton dimension by default.
unwrap(P, tol)usesmax(tol, pi)as the discontinuity threshold, matching MATLAB behavior for tolerances belowpi.unwrap(P, [], dim)keeps the default tolerance and unwraps alongdim; the documented dimension accepts all eight integer classes and is decoded exactly as a structural index.- A native typed-integer tolerance is a RunMat extension and must be exactly representable before entering the floating comparison boundary.
- Single phase data returns single and double phase data returns double. The integer and logical phase extensions return double so fractional phase corrections are never coerced into a nonfloating class.
- Complex inputs are rejected because
unwrapexpects real phase angles.
Does RunMat run unwrap on the GPU?
GPU inputs are downloaded through the active provider with dtype normalization.
The host implementation performs MATLAB-compatible phase correction.
The output is a host tensor with the same shape as the input.
GPU memory and residency
unwrap accepts GPU tensors through the normal gather path. Because phase unwrapping is stateful along a dimension and currently materialized on the host, downstream GPU residency resumes only after an explicit gpuArray or another operation that uploads the result.
Examples
Correct a wrapped phase vector
p = [0 1 2 2-2*pi 3-2*pi];
q = unwrap(p)Expected output:
q = [0 1 2 2 3]Use a custom tolerance
p = [0 1 1-2*pi];
q = unwrap(p, 10)Expected output:
q = [0 1 -5.2832]Unwrap across matrix rows
P = [0 1 1-2*pi; 0 -1 -1+2*pi];
Q = unwrap(P, [], 2)Expected output:
Q =
0 1 1
0 -1 -1Recover continuous phase from an analytic signal
x = cos(0:0.1:10);
z = hilbert(x);
phase = unwrap(angle(z));Using unwrap with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how unwrap changes the result.
Run a small unwrap example, explain the result, then change one input and compare the output.
FAQ
What tolerance does unwrap use by default?⌄
The default tolerance is pi. If you pass a tolerance below pi, RunMat uses pi, matching MATLAB's documented behavior.
Which dimension is unwrapped?⌄
The first non-singleton dimension is used unless you pass dim.
Does unwrap change the shape?⌄
No. The output has the same shape as the input.
Can I pass complex input?⌄
No. Use angle(z) first to convert complex samples to real phase angles, then call unwrap.
Related Math functions
Signal
blackman · butter · buttord · cheb2ord · conv · conv2 · deconv · downsample · envelope · filter · filtfilt · fir1 · freqz · gauspuls · hamming · hann · hilbert · periodogram · pulstran · pwelch · rectpuls · resample · sawtooth · sinc · spectrogram · square · tripuls · upsample · zplane
Elementwise
abs · angle · bsxfun · complex · conj · double · erf · erfcinv · exp · expm1 · factorial · flintmax · gamma · gammaln · heaviside · hypot · idivide · imag · intmax · intmin · ldivide · log · log10 · log1p · log2 · minus · nextpow2 · plus · pow2 · power · rdivide · real · realmax · realmin · realsqrt · rescale · sign · single · sqrt · swapbytes · times · typecast · uint16 · uint32 · uint8
Trigonometry
acos · acosh · asin · asinh · atan · atan2 · atanh · cos · cosd · cosh · cospi · deg2rad · pol2cart · rad2deg · sin · sind · sinh · sinpi · tan · tand · tanh
Reduction
all · any · bounds · cummax · cummin · cumprod · cumsum · cumtrapz · diff · gradient · max · maxk · mean · median · min · mink · movmax · movmean · movmedian · movmin · movprod · movstd · movsum · movvar · nnz · prod · rms · std · sum · trapz · var
Structure
bandwidth · isdiag · ishermitian · issymmetric · istril · istriu · symrcm
Optim
coneprog · fminbnd · fminunc · fsolve · fzero · integral · linprog · lsqcurvefit · lsqnonlin · optimoptions · optimset · quad · secondordercone
Ops
cross · ctranspose · dot · mldivide · mpower · mrdivide · mtimes · pagemtimes · pagetranspose · trace · transpose
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how unwrap is executed, line by line, in Rust.
- View the source for unwrap 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.