Utilities Module#

The utils module provides helper functions for coordinate system conversions, unit transformations, and grid generation.

Coordinate Transforms#

phased_array.theta_phi_to_uv(theta, phi)[source]#

Convert theta/phi angles to UV-space (direction cosines).

Parameters:

  • theta (array_like) – Polar angle from z-axis in radians

  • phi (array_like) – Azimuthal angle in radians

Returns:

  • u (array_like) – Direction cosine u = sin(theta) * cos(phi)

  • v (array_like) – Direction cosine v = sin(theta) * sin(phi)

Return type:

Tuple[ndarray | float, ndarray | float]

phased_array.uv_to_theta_phi(u, v)[source]#

Convert UV-space (direction cosines) to theta/phi angles.

Parameters:

  • u (array_like) – Direction cosine u = sin(theta) * cos(phi)

  • v (array_like) – Direction cosine v = sin(theta) * sin(phi)

Returns:

  • theta (array_like) – Polar angle from z-axis in radians

  • phi (array_like) – Azimuthal angle in radians

Return type:

Tuple[ndarray | float, ndarray | float]

Notes

Points outside the visible region (u^2 + v^2 > 1) will have theta values computed from the magnitude, which may be complex or undefined. Use is_visible_region() to check validity.

phased_array.azel_to_thetaphi(az, el)[source]#

Convert azimuth/elevation to theta/phi (spherical coordinates).

Parameters:

  • az (array_like) – Azimuth angle in radians (0 = boresight, positive = right)

  • el (array_like) – Elevation angle in radians (0 = horizon, positive = up)

Returns:

  • theta (array_like) – Polar angle from z-axis in radians (0 = zenith)

  • phi (array_like) – Azimuthal angle in radians

Return type:

Tuple[ndarray | float, ndarray | float]

phased_array.thetaphi_to_azel(theta, phi)[source]#

Convert theta/phi (spherical coordinates) to azimuth/elevation.

Parameters:

  • theta (array_like) – Polar angle from z-axis in radians (0 = zenith)

  • phi (array_like) – Azimuthal angle in radians

Returns:

  • az (array_like) – Azimuth angle in radians

  • el (array_like) – Elevation angle in radians

Return type:

Tuple[ndarray | float, ndarray | float]

phased_array.is_visible_region(u, v)[source]#

Check if UV coordinates are within the visible region.

Parameters:

  • u (array_like) – Direction cosines

  • v (array_like) – Direction cosines

Returns:

visible – Boolean array, True where u^2 + v^2 <= 1

Return type:

ndarray

Angle Conversions#

phased_array.deg2rad(degrees)[source]#

Convert degrees to radians.

phased_array.rad2deg(radians)[source]#

Convert radians to degrees.

Wavenumber and Wavelength#

phased_array.wavelength_to_k(wavelength)[source]#

Convert wavelength to wavenumber.

Parameters:

wavelength (float) – Wavelength in meters

Returns:

k – Wavenumber (2*pi/wavelength) in rad/m

Return type:

float

Examples

For normalized wavelength (positions in wavelengths):

>>> import phased_array as pa
>>> k = pa.wavelength_to_k(1.0)
>>> round(k, 4)
6.2832

For physical wavelength (10 GHz = 3 cm):

>>> wavelength = 0.03  # meters
>>> k = pa.wavelength_to_k(wavelength)
>>> round(k, 2)
209.44

Or use frequency directly:

>>> k = pa.frequency_to_k(10e9)  # 10 GHz
>>> round(k, 2)
209.44
phased_array.frequency_to_wavelength(frequency, c=300000000.0)[source]#

Convert frequency to wavelength.

Parameters:

  • frequency (float) – Frequency in Hz

  • c (float, optional) – Speed of light in m/s (default: 3e8)

Returns:

wavelength – Wavelength in meters

Return type:

float

phased_array.frequency_to_k(frequency, c=300000000.0)[source]#

Convert frequency to wavenumber.

Parameters:

  • frequency (float) – Frequency in Hz

  • c (float, optional) – Speed of light in m/s (default: 3e8)

Returns:

k – Wavenumber in rad/m

Return type:

float

Decibel Conversions#

phased_array.db_to_linear(db)[source]#

Convert decibels to linear scale (power).

phased_array.linear_to_db(linear, min_db=-100.0)[source]#

Convert linear scale (power) to decibels.

Parameters:

  • linear (array_like) – Linear power values

  • min_db (float, optional) – Minimum dB value to return (clips zeros/negatives)

Returns:

db – Power in decibels

Return type:

array_like

phased_array.normalize_pattern(pattern, mode='peak')[source]#

Normalize a radiation pattern.

Parameters:

  • pattern (ndarray) – Complex or magnitude pattern values

  • mode (str) – ‘peak’ - normalize to peak value ‘power’ - normalize to total radiated power

Returns:

normalized – Normalized pattern (same type as input)

Return type:

ndarray

Grid Generation#

phased_array.create_theta_phi_grid(theta_range=(0, 3.141592653589793), phi_range=(0, 6.283185307179586), n_theta=181, n_phi=361)[source]#

Create a theta/phi grid for pattern computation.

Parameters:

  • theta_range (tuple) – (theta_min, theta_max) in radians

  • phi_range (tuple) – (phi_min, phi_max) in radians

  • n_theta (int) – Number of theta points

  • n_phi (int) – Number of phi points

Returns:

  • theta_1d (ndarray) – 1D array of theta values

  • phi_1d (ndarray) – 1D array of phi values

  • theta_grid (ndarray) – 2D meshgrid of theta values

  • phi_grid (ndarray) – 2D meshgrid of phi values

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray]

phased_array.create_uv_grid(u_range=(-1, 1), v_range=(-1, 1), n_u=201, n_v=201)[source]#

Create a UV-space grid for pattern computation.

Parameters:

  • u_range (tuple) – (u_min, u_max) direction cosine range

  • v_range (tuple) – (v_min, v_max) direction cosine range

  • n_u (int) – Number of u points

  • n_v (int) – Number of v points

Returns:

  • u_1d (ndarray) – 1D array of u values

  • v_1d (ndarray) – 1D array of v values

  • u_grid (ndarray) – 2D meshgrid of u values

  • v_grid (ndarray) – 2D meshgrid of v values

Return type:

Tuple[ndarray, ndarray, ndarray, ndarray]