# unwrap

Shift phase angles

## Description

`Q = unwrap(`

unwraps the radian phase angles
in a vector `P`

)`P`

. Whenever the jump between consecutive angles is greater
than or equal to *π* radians, `unwrap`

shifts the angles
by adding multiples of ±2*π* until the jump is less than
*π*. If `P`

is a matrix, `unwrap`

operates columnwise. If `P`

is a multidimensional array,
`unwrap`

operates on the first dimension whose size is larger than
1.

## Examples

### Correct Phase Angle of Spiral

Define the $$x$$- and $$y$$-coordinates of a spiral with phase angle from 0 to $6\pi $. Plot the spiral.

t = linspace(0,6*pi,201); x = t/pi.*cos(t); y = t/pi.*sin(t); plot(x,y)

Find the phase angle of the spiral from the $$x$$- and $$y$$-coordinates using the `atan2`

function. The `atan2`

function returns the angle values within the closed interval from $-\pi $ to $\pi $.

P = atan2(y,x); plot(t,P)

Note that this plot has discontinuities. Use `unwrap`

to eliminate the discontinuities. `unwrap`

adds multiples of $\pm 2\pi $ when the phase difference between consecutive elements of `P`

are greater than or equal to the jump threshold $\pi $ radians. The shifted phase angle `Q`

lies in the interval from 0 to $6\pi $.

Q = unwrap(P); plot(t,Q)

### Shift Phase Angle with Different Thresholds

Shift the phase angle of a frequency response. The phase curve has two jumps. The first jump is `3.4250`

radians between `W = 3`

and `W = 3.4`

, and the second jump is `6.3420`

radians between `W = 5`

and `W = 5.4`

. Plot the phase curve.

clear; close all; W = [0:0.4:3, 3.4:0.4:5, 5.4:0.4:7]; P = [-1.5723 -1.5747 -1.5790 -1.5852 -1.5922 -1.6044 -1.6269 -1.6998 1.7252 1.5989 1.5916 1.5708 1.5582 -4.7838 -4.8143 -4.8456 -4.8764 -4.9002]; plot(W,P,'bo-')

Use `unwrap`

to shift the phase angle using the default jump threshold $$\pi $$ radians. Plot the shifted phase curve. Both jumps are shifted since they are greater than the jump threshold $$\pi $$ radians.

`plot(W,unwrap(P),'ro-')`

Now shift the phase angle using a jump threshold of `5`

radians. Plot the shifted phase curve. The first jump is not shifted since it is less than the jump threshold `5`

radians.

`plot(W,unwrap(P,5),'ro-')`

### Apply Phase Shift to Matrix

Define a two-column matrix `P`

that contains phase angles.

P = [0 7.07; 0.19 0.98; 6.67 1.18; 0.59 1.37; 0.78 1.56]

`P = `*5×2*
0 7.0700
0.1900 0.9800
6.6700 1.1800
0.5900 1.3700
0.7800 1.5600

The phase angles `P(1,2) = 7.07`

and `P(3,1) = 6.67`

have phase differences that are larger than $$\pi $$ compared to the rest of the data.

Unwrap the phase angles by first comparing the elements columnwise. Specify the `dim`

argument as 1. Use the default jump threshold $$\pi $$ by specifying the second argument as `[]`

.

dim = 1; P1 = unwrap(P,[],dim)

`P1 = `*5×2*
0 7.0700
0.1900 7.2632
0.3868 7.4632
0.5900 7.6532
0.7800 7.8432

To shift phase angles by rows instead of by columns, specify `dim`

as 2 instead of 1.

dim = 2; P2 = unwrap(P1,[],dim)

`P2 = `*5×2*
0 0.7868
0.1900 0.9800
0.3868 1.1800
0.5900 1.3700
0.7800 1.5600

## Input Arguments

`P`

— Input array

vector | matrix | multidimensional array

Input array, specified as a vector, matrix, or multidimensional array.

**Data Types: **`single`

| `double`

`tol`

— Jump threshold to apply phase shift

`pi`

(default) | scalar

Jump threshold to apply phase shift, specified as a scalar. A jump threshold less
than *π* has the same effect as the default threshold
*π*.

**Data Types: **`single`

| `double`

`dim`

— Dimension to operate along

positive integer scalar

Dimension to operate along, specified as a positive integer scalar. If no value is specified, then the default is the first array dimension whose size does not equal 1.

`unwrap(P,[],1)`

operates along the columns of`P`

and returns the shifted phase angle of each column.`unwrap(P,[],2)`

operates along the rows of`P`

and returns the shifted phase angle of each row.

If `dim`

is greater than `ndims(P)`

, then
`unwrap(P,[],dim)`

returns `P`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

## Output Arguments

`Q`

— Shifted phase angle

vector | matrix | multidimensional array

Shifted phase angle, returned as a vector, matrix, or multidimensional array. The
size of the output `Q`

is always the same as the size of the input
`P`

.

**Data Types: **`single`

| `double`

## Extended Capabilities

### C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

Row vector input is only supported when the first two inputs are vectors and nonscalar.

Performs arithmetic in the output class. Therefore, results might not match MATLAB

^{®}due to different rounding errors.

### Thread-Based Environment

Run code in the background using MATLAB® `backgroundPool`

or accelerate code with Parallel Computing Toolbox™ `ThreadPool`

.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The `unwrap`

function
fully supports GPU arrays. To run the function on a GPU, specify the input data as a `gpuArray`

(Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

### Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

## Version History

**Introduced before R2006a**

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)