NumPy unwrap()
The numpy.unwrap() function corrects phase angles in a signal by replacing abrupt jumps larger than a threshold with their 2π (or specified period) complement. This ensures continuity in phase data.
Syntax
numpy.unwrap(p, discont=None, axis=-1, *, period=6.283185307179586)Parameters
| Parameter | Type | Description |
|---|---|---|
p | array_like | Input array containing phase values. |
discont | float, optional | Maximum discontinuity allowed between consecutive values before unwrapping occurs. Default is period/2. |
axis | int, optional | Axis along which unwrapping is performed. Default is the last axis (-1). |
period | float, optional | Defines the range over which the phase wraps. Default is 2π (6.283). |
Return Value
Returns an ndarray with phase values corrected for discontinuities, ensuring smooth transitions.
Examples
1. Basic Unwrapping of a Wrapped Phase Signal
Here, we apply numpy.unwrap() to a simple wrapped phase sequence.
import numpy as np
# Simulated wrapped phase values in radians
wrapped_phase = np.array([0, np.pi/2, np.pi, -np.pi, -np.pi/2, 0])
# Unwrap the phase to remove discontinuities
unwrapped_phase = np.unwrap(wrapped_phase)
# Print results
print("Wrapped phase values:", wrapped_phase)
print("Unwrapped phase values:", unwrapped_phase)Output:
Wrapped phase values: [ 0. 1.57079633 3.14159265 -3.14159265 -1.57079633 0. ]
Unwrapped phase values: [0. 1.57079633 3.14159265 3.14159265 4.71238898 6.28318531]
The function corrects the sudden phase jump from -π to π by adjusting it to a continuous phase progression.
2. Unwrapping Along a Specified Axis
Unwrapping can be applied along a specific axis in multidimensional arrays.
import numpy as np
# 2D array of wrapped phase values
wrapped_phase_2d = np.array([[0, np.pi/2, np.pi, -np.pi, -np.pi/2],
[0, -np.pi/2, -np.pi, np.pi, np.pi/2]])
# Unwrap along the last axis
unwrapped_phase_2d = np.unwrap(wrapped_phase_2d, axis=-1)
# Print results
print("Wrapped phase:\n", wrapped_phase_2d)
print("Unwrapped phase:\n", unwrapped_phase_2d)Output:
Wrapped phase:
[[ 0. 1.57079633 3.14159265 -3.14159265 -1.57079633]
[ 0. -1.57079633 -3.14159265 3.14159265 1.57079633]]
Unwrapped phase:
[[ 0. 1.57079633 3.14159265 3.14159265 4.71238898]
[ 0. -1.57079633 -3.14159265 -3.14159265 -4.71238898]]
The function applies unwrapping along the specified axis, ensuring smooth phase transitions across the row.
3. Adjusting Discontinuity Threshold
By changing the discont parameter, we can control when unwrapping occurs.
import numpy as np
# Wrapped phase values with large jumps
wrapped_phase_large_jump = np.array([0, np.pi/2, np.pi, 3*np.pi, -np.pi, -np.pi/2, 0])
# Unwrap with a custom discontinuity threshold
unwrapped_custom = np.unwrap(wrapped_phase_large_jump, discont=np.pi)
# Print results
print("Wrapped phase values:", wrapped_phase_large_jump)
print("Unwrapped phase values:", unwrapped_custom)Output:
Wrapped phase values: [ 0. 1.57079633 3.14159265 9.42477796 -3.14159265 -1.57079633
0. ]
Unwrapped phase values: [0. 1.57079633 3.14159265 3.14159265 3.14159265 4.71238898
6.28318531]
Since the discontinuity threshold is set to π, jumps greater than this value trigger unwrapping, while smaller jumps are ignored.
4. Changing the Period for Custom Unwrapping
We can specify a different period to unwrap signals wrapping over a different range than 2π.
import numpy as np
# Define a wrapped phase signal with a different periodicity
wrapped_phase_custom = np.array([0, 3, 6, 9, 12, 15, -3, 0])
# Unwrap with a period of 6
unwrapped_custom_period = np.unwrap(wrapped_phase_custom, period=6)
# Print results
print("Wrapped phase values:", wrapped_phase_custom)
print("Unwrapped phase values with period 6:", unwrapped_custom_period)Output:
Wrapped phase values: [ 0 3 6 9 12 15 -3 0]
Unwrapped phase values with period 6: [ 0 3 6 9 12 15 15 18]
By setting period=6, the function treats discontinuities larger than 6/2 as phase jumps, ensuring smooth transitions.