phased-array-modeling 1.3.0__tar.gz → 1.3.2__tar.gz

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phased-array-modeling
-Version: 1.3.0
+Version: 1.3.2
 Summary: Comprehensive Python library for phased array antenna modeling and visualization
 Author-email: John Hodge <jah70@vt.edu>
 License: MIT
@@ -55,11 +55,11 @@ Dynamic: license-file
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://phased-array-antenna-model.streamlit.app/)
 [![Documentation](https://readthedocs.org/projects/phased-array-antenna-model/badge/?version=latest)](https://phased-array-antenna-model.readthedocs.io/en/latest/)
 
-A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features **125x faster** vectorized computations, multiple array geometries, advanced beamforming, and interactive 3D visualization.
+A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features vectorized computations (50-100x faster than naive loops), multiple array geometries, advanced beamforming, and interactive 3D visualization.
 
 ## Features
 
-- **High Performance**: Vectorized array factor computation (125x faster than naive loops)
+- **High Performance**: Vectorized array factor computation (50-100x faster than naive loops)
 - **Multiple Geometries**: Rectangular, triangular, circular, cylindrical, spherical, sparse/thinned arrays
 - **Beamforming**: Amplitude tapering (Taylor, Chebyshev, etc.), null steering, multi-beam
 - **Realistic Impairments**: Mutual coupling, phase quantization, element failures, scan blindness
@@ -81,7 +81,7 @@ The Streamlit app provides an interactive interface for:
 
 ## Installation
 
-### From GitHub (recommended)
+### From PyPI (recommended)
 
 ```bash
 pip install phased-array-modeling
@@ -235,8 +235,12 @@ For hands-on learning, see the [demo notebook](Phased_Array_Demo.ipynb) which co
 phased_array/
 ├── core.py          # Vectorized AF, FFT, steering, element patterns
 ├── geometry.py      # Array geometries and subarray architectures
-├── beamforming.py   # Tapering, null steering, multi-beam
+├── beamforming.py   # Tapering, null steering, multi-beam, adaptive
 ├── impairments.py   # Coupling, quantization, failures, scan blindness
+├── wideband.py      # True-time-delay steering, beam squint, bandwidth
+├── polarization.py  # Jones/Stokes, axial ratio, XPD, Ludwig-3
+├── coordinates.py   # Antenna/radar/cone frames, pattern rotation
+├── export.py        # CSV/JSON/NPZ export, summary reports
 ├── visualization.py # 2D, 3D Plotly, UV-space plotting
 └── utils.py         # Coordinate transforms, helpers
 ```
@@ -278,7 +282,7 @@ If you use this library in your research, please cite:
   author = {Hodge, John},
   title = {Phased Array Antenna Modeling},
   url = {https://github.com/jman4162/Phased-Array-Antenna-Model},
-  year = {2024}
+  year = {2026}
 }
 ```
 

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/README.md

@@ -9,11 +9,11 @@
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://phased-array-antenna-model.streamlit.app/)
 [![Documentation](https://readthedocs.org/projects/phased-array-antenna-model/badge/?version=latest)](https://phased-array-antenna-model.readthedocs.io/en/latest/)
 
-A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features **125x faster** vectorized computations, multiple array geometries, advanced beamforming, and interactive 3D visualization.
+A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features vectorized computations (50-100x faster than naive loops), multiple array geometries, advanced beamforming, and interactive 3D visualization.
 
 ## Features
 
-- **High Performance**: Vectorized array factor computation (125x faster than naive loops)
+- **High Performance**: Vectorized array factor computation (50-100x faster than naive loops)
 - **Multiple Geometries**: Rectangular, triangular, circular, cylindrical, spherical, sparse/thinned arrays
 - **Beamforming**: Amplitude tapering (Taylor, Chebyshev, etc.), null steering, multi-beam
 - **Realistic Impairments**: Mutual coupling, phase quantization, element failures, scan blindness
@@ -35,7 +35,7 @@ The Streamlit app provides an interactive interface for:
 
 ## Installation
 
-### From GitHub (recommended)
+### From PyPI (recommended)
 
 ```bash
 pip install phased-array-modeling
@@ -189,8 +189,12 @@ For hands-on learning, see the [demo notebook](Phased_Array_Demo.ipynb) which co
 phased_array/
 ├── core.py          # Vectorized AF, FFT, steering, element patterns
 ├── geometry.py      # Array geometries and subarray architectures
-├── beamforming.py   # Tapering, null steering, multi-beam
+├── beamforming.py   # Tapering, null steering, multi-beam, adaptive
 ├── impairments.py   # Coupling, quantization, failures, scan blindness
+├── wideband.py      # True-time-delay steering, beam squint, bandwidth
+├── polarization.py  # Jones/Stokes, axial ratio, XPD, Ludwig-3
+├── coordinates.py   # Antenna/radar/cone frames, pattern rotation
+├── export.py        # CSV/JSON/NPZ export, summary reports
 ├── visualization.py # 2D, 3D Plotly, UV-space plotting
 └── utils.py         # Coordinate transforms, helpers
 ```
@@ -232,7 +236,7 @@ If you use this library in your research, please cite:
   author = {Hodge, John},
   title = {Phased Array Antenna Modeling},
   url = {https://github.com/jman4162/Phased-Array-Antenna-Model},
-  year = {2024}
+  year = {2026}
 }
 ```
 

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/__init__.py

@@ -32,7 +32,7 @@ Example
 >>> theta, phi, pattern_dB = pa.compute_full_pattern(geom.x, geom.y, weights, k)
 """
 
-__version__ = "1.3.0"
+__version__ = "1.3.2"
 
 # Beamforming functions
 from .beamforming import (  # Amplitude tapers; Null steering; Multiple beams; Beam spoiling; Adaptive
@@ -45,8 +45,13 @@ from .beamforming import (  # Amplitude tapers; Null steering; Multiple beams; B
     hamming_taper_2d, hanning_taper_1d, hanning_taper_2d, monopulse_weights,
     multi_beam_weights_orthogonal, multi_beam_weights_superposition,
     null_steering_lcmv, null_steering_projection, plot_adapted_pattern,
-    quadratic_phase_spoil, spoiled_beam_gain, spoiled_beamwidth, taylor_taper_1d,
-    taylor_taper_2d)
+    quadratic_phase_spoil, spoiled_beam_gain, spoiled_beamwidth,
+    taylor_taper_1d, taylor_taper_2d)
+# Coordinate transformation functions
+from .coordinates import (antenna_to_cone, antenna_to_radar, cone_to_antenna,
+                          radar_to_antenna, rotate_pattern,
+                          rotation_matrix_pitch, rotation_matrix_roll,
+                          rotation_matrix_yaw)
 # Core computation functions
 from .core import (array_factor_fft, array_factor_uv, array_factor_vectorized,
                    compute_directivity, compute_full_pattern,
@@ -78,6 +83,12 @@ from .impairments import (  # Mutual coupling; Phase quantization; Element failu
     mutual_coupling_matrix_theoretical, quantization_rms_error,
     quantization_sidelobe_increase, quantize_phase, scan_blindness_model,
     simulate_element_failures, surface_wave_scan_angle, vswr_vs_scan)
+# Polarization functions
+from .polarization import (axial_ratio, co_pol_pattern,
+                           cross_pol_discrimination, cross_pol_pattern,
+                           jones_vector, ludwig3_decomposition,
+                           polarization_loss_factor, stokes_parameters,
+                           tilt_angle)
 # Utility functions
 from .utils import (azel_to_thetaphi, create_theta_phi_grid, create_uv_grid,
                     db_to_linear, deg2rad, frequency_to_k,
@@ -93,14 +104,6 @@ from .visualization import (  # 2D matplotlib plots; UV-space; 3D Plotly plots;
     plot_pattern_contour, plot_pattern_polar, plot_pattern_uv_plotly,
     plot_pattern_uv_space, plot_pattern_vs_frequency,
     plot_pattern_vs_frequency_plotly, plot_subarray_delays)
-# Polarization functions
-from .polarization import (axial_ratio, co_pol_pattern, cross_pol_discrimination,
-                           cross_pol_pattern, jones_vector, ludwig3_decomposition,
-                           polarization_loss_factor, stokes_parameters, tilt_angle)
-# Coordinate transformation functions
-from .coordinates import (antenna_to_cone, antenna_to_radar, cone_to_antenna,
-                          radar_to_antenna, rotate_pattern, rotation_matrix_pitch,
-                          rotation_matrix_roll, rotation_matrix_yaw)
 # Wideband / TTD functions
 from .wideband import (analyze_instantaneous_bandwidth, compare_steering_modes,
                        compute_beam_squint, compute_pattern_vs_frequency,

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/beamforming.py

@@ -391,7 +391,10 @@ def null_steering_projection(
 
     Verify null depth:
 
-    >>> null_depth = pa.compute_null_depth(geom, k, weights, null_dirs[0])
+    >>> null_depth = pa.compute_null_depth(
+    ...     weights, geom, k, theta_deg=45, phi_deg=0,
+    ...     theta_main_deg=30, phi_main_deg=0
+    ... )
     >>> null_depth < -30  # Deep null achieved
     True
     """
@@ -1275,15 +1278,15 @@ def compute_sinr_improvement(
     >>> geom = pa.create_rectangular_array(8, 8, dx=0.5, dy=0.5)
     >>> k = pa.wavelength_to_k(1.0)
     >>> w_q = pa.steering_vector(k, geom.x, geom.y, 0, 0)
-    >>> # Create adapted weights that null an interferer
+    >>> # Create adapted weights that null an interferer in a sidelobe
     >>> w_adapted = pa.null_steering_projection(
     ...     geom, k, theta_main_deg=0, phi_main_deg=0,
-    ...     null_directions=[(30, 0)]
+    ...     null_directions=[(20, 0)]
     ... )
     >>> sinr_b, sinr_a, imp = pa.compute_sinr_improvement(
     ...     w_q, w_adapted, geom, k,
     ...     signal_direction=(0, 0),
-    ...     interference_directions=[(30, 0)],
+    ...     interference_directions=[(20, 0)],
     ...     signal_power=1.0, interference_powers=[10.0], noise_power=0.1
     ... )
     >>> imp > 0  # Should show improvement
@@ -1381,6 +1384,7 @@ def plot_adapted_pattern(
     ... )  # doctest: +SKIP
     """
     import matplotlib.pyplot as plt
+
     from .core import array_factor_vectorized
     from .utils import linear_to_db
 

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/core.py

@@ -5,6 +5,7 @@ Includes vectorized array factor, FFT-based computation, steering vectors,
 and element patterns.
 """
 
+import warnings
 from typing import Optional, Tuple, Union
 
 import numpy as np
@@ -307,11 +308,13 @@ def element_pattern(
     theta : ndarray
         Polar angle in radians
     phi : ndarray
-        Azimuthal angle in radians (not used in basic model)
+        Azimuthal angle in radians (not used; the model is phi-symmetric)
     cos_exp_theta : float
         Cosine exponent for theta dependence (1.0 = simple cosine)
     cos_exp_phi : float
-        Cosine exponent for additional roll-off
+        Deprecated and unused. The basic model has no phi dependence;
+        for polarized/phi-dependent element models see the v1.4 vector
+        pattern API.
     max_gain_dBi : float
         Peak element gain in dBi
 
@@ -320,6 +323,16 @@ def element_pattern(
     pattern : ndarray
         Element pattern (linear scale, same shape as theta)
     """
+    if cos_exp_phi != 1.0:
+        warnings.warn(
+            "cos_exp_phi is unused: element_pattern is phi-symmetric. "
+            "The parameter is deprecated and will be removed in a future "
+            "release; use the vector element models for phi-dependent "
+            "patterns.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
     # Convert max gain to linear
     max_gain_linear = 10 ** (max_gain_dBi / 10)
 
@@ -385,7 +398,7 @@ def total_pattern(
     z: Optional[np.ndarray] = None,
     **element_kwargs
 ) -> np.ndarray:
-    """
+    r"""
     Compute total radiation pattern (element pattern * array factor).
 
     Parameters
@@ -668,7 +681,18 @@ def compute_half_power_beamwidth(
     while right_idx < len(pattern_dB) - 1 and above_3dB[right_idx + 1]:
         right_idx += 1
 
-    # Interpolate for more accurate beamwidth
-    hpbw = angles_deg[right_idx] - angles_deg[left_idx]
-
-    return abs(hpbw)
+    # Linearly interpolate the -3 dB crossings; fall back to the sample
+    # position when the crossing lies outside the sampled range
+    left_angle = angles_deg[left_idx]
+    if left_idx > 0 and pattern_dB[left_idx - 1] < -3.0:
+        a0, a1 = angles_deg[left_idx - 1], angles_deg[left_idx]
+        p0, p1 = pattern_dB[left_idx - 1], pattern_dB[left_idx]
+        left_angle = a0 + (-3.0 - p0) * (a1 - a0) / (p1 - p0)
+
+    right_angle = angles_deg[right_idx]
+    if right_idx < len(pattern_dB) - 1 and pattern_dB[right_idx + 1] < -3.0:
+        a0, a1 = angles_deg[right_idx], angles_deg[right_idx + 1]
+        p0, p1 = pattern_dB[right_idx], pattern_dB[right_idx + 1]
+        right_angle = a0 + (-3.0 - p0) * (a1 - a0) / (p1 - p0)
+
+    return abs(right_angle - left_angle)

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/geometry.py

@@ -465,14 +465,10 @@ def create_concentric_rings_array(
     """
     x_list = []
     y_list = []
-    nx_list = []
-    ny_list = []
 
     if include_center:
         x_list.append(0.0)
         y_list.append(0.0)
-        nx_list.append(0.0)
-        ny_list.append(0.0)
 
     if isinstance(elements_per_ring, int):
         elements_per_ring = [elements_per_ring] * n_rings
@@ -484,18 +480,18 @@ def create_concentric_rings_array(
         for angle in angles:
             x_list.append(radius * np.cos(angle))
             y_list.append(radius * np.sin(angle))
-            nx_list.append(np.cos(angle))
-            ny_list.append(np.sin(angle))
 
     x = np.array(x_list)
     y = np.array(y_list)
 
+    # Planar array: all elements face broadside (+z), like the other
+    # planar factories
     return ArrayGeometry(
         x=x, y=y,
         z=np.zeros_like(x),
-        nx=np.array(nx_list),
-        ny=np.array(ny_list),
-        nz=np.zeros_like(x),
+        nx=np.zeros_like(x),
+        ny=np.zeros_like(x),
+        nz=np.ones_like(x),
         element_indices=np.arange(len(x))
     )
 
@@ -1241,7 +1237,6 @@ def overlapped_subarray_weights(
     """
     if not architecture.overlapped:
         # Fall back to standard subarray weights
-        from .beamforming import compute_subarray_weights
         return compute_subarray_weights(architecture, k, theta0_deg, phi0_deg)
 
     geom = architecture.geometry

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/impairments.py

@@ -73,7 +73,8 @@ def mutual_coupling_matrix_theoretical(
 
 
 def mutual_coupling_matrix_measured(
-    s_parameters: np.ndarray
+    s_parameters: np.ndarray,
+    formulation: str = 'impedance'
 ) -> np.ndarray:
     """
     Convert measured S-parameters to coupling matrix.
@@ -85,16 +86,36 @@ def mutual_coupling_matrix_measured(
     ----------
     s_parameters : ndarray
         N x N S-parameter matrix (complex)
+    formulation : str
+        'impedance' (default): C = (I + S)(I - S)^(-1), the normalized
+        impedance matrix. 'voltage': C = I + S, the total-voltage
+        coupling used before v1.3.2.
 
     Returns
     -------
     C : ndarray
         Mutual coupling matrix
+
+    Notes
+    -----
+    Before v1.3.2 this function returned I + S while documenting the
+    impedance formulation; pass ``formulation='voltage'`` to reproduce
+    the old behavior.
     """
     n = s_parameters.shape[0]
-    # C = (I + S)(I - S)^(-1) for impedance normalization
-    # Or simply use S directly for voltage coupling
-    C = np.eye(n, dtype=complex) + s_parameters
+    identity = np.eye(n, dtype=complex)
+
+    if formulation == 'impedance':
+        try:
+            C = np.linalg.solve((identity - s_parameters).T, (identity + s_parameters).T).T
+        except np.linalg.LinAlgError:
+            C = (identity + s_parameters) @ np.linalg.pinv(identity - s_parameters)
+    elif formulation == 'voltage':
+        C = identity + s_parameters
+    else:
+        raise ValueError(
+            f"formulation must be 'impedance' or 'voltage', got {formulation!r}"
+        )
     return C
 
 
@@ -436,7 +457,7 @@ def simulate_element_failures(
     Analyze graceful degradation:
 
     >>> results = pa.analyze_graceful_degradation(
-    ...     geom, k, weights, failure_rates=[0.0, 0.05, 0.1]
+    ...     weights, geom, k, failure_rates=[0.0, 0.05, 0.1], n_trials=5
     ... )
     """
     if seed is not None:

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/polarization.py

@@ -104,7 +104,7 @@ def stokes_parameters(jones: np.ndarray) -> Tuple[float, float, float, float]:
 
     >>> j = pa.jones_vector(1.0, 1.0, phase_diff=-np.pi/2)  # RHCP
     >>> S0, S1, S2, S3 = pa.stokes_parameters(j)
-    >>> np.isclose(S3, -S0, atol=1e-10)
+    >>> np.isclose(S3, S0, atol=1e-10)  # right circular: S3 = +S0
     True
     """
     jones = np.asarray(jones, dtype=complex)

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/utils.py

@@ -38,12 +38,20 @@ def azel_to_thetaphi(az: ArrayLike, el: ArrayLike) -> Tuple[ArrayLike, ArrayLike
         Polar angle from z-axis in radians (0 = zenith)
     phi : array_like
         Azimuthal angle in radians
+
+    Notes
+    -----
+    Convention: boresight is +z, azimuth rotates toward +x ("right"),
+    elevation toward +y ("up"), with elevation applied over azimuth:
+    the direction vector is (sin(az)cos(el), sin(el), cos(az)cos(el)).
+    Inverse of `thetaphi_to_azel`. Before v1.3.2 the two functions used
+    inconsistent conventions and did not round-trip.
     """
     az = np.asarray(az)
     el = np.asarray(el)
 
     theta = np.arccos(np.cos(az) * np.cos(el))
-    phi = np.arctan2(np.sin(az), np.tan(el))
+    phi = np.arctan2(np.sin(el), np.sin(az) * np.cos(el))
 
     return theta, phi
 
@@ -62,15 +70,21 @@ def thetaphi_to_azel(theta: ArrayLike, phi: ArrayLike) -> Tuple[ArrayLike, Array
     Returns
     -------
     az : array_like
-        Azimuth angle in radians
+        Azimuth angle in radians (0 = boresight, positive = right)
     el : array_like
-        Elevation angle in radians
+        Elevation angle in radians (0 = boresight, positive = up)
+
+    Notes
+    -----
+    Inverse of `azel_to_thetaphi`; see its docstring for the convention.
+    Before v1.3.2 the two functions used inconsistent conventions and
+    did not round-trip.
     """
     theta = np.asarray(theta)
     phi = np.asarray(phi)
 
-    el = np.arcsin(np.cos(theta))
-    az = np.arctan2(np.sin(theta) * np.sin(phi), np.sin(theta) * np.cos(phi))
+    el = np.arcsin(np.sin(theta) * np.sin(phi))
+    az = np.arctan2(np.sin(theta) * np.cos(phi), np.cos(theta))
 
     return az, el
 

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array/wideband.py

@@ -83,9 +83,11 @@ def steering_vector_ttd(
 
     >>> # TTD maintains beam direction across bandwidth
     >>> # Phase steering causes beam squint at off-center frequencies
+    >>> import numpy as np
     >>> squint = pa.compute_beam_squint(
     ...     geom.x, geom.y, theta0_deg=30, phi0_deg=0,
-    ...     center_freq=10e9, bandwidth=2e9, n_freqs=11
+    ...     center_frequency=10e9,
+    ...     frequencies=np.linspace(9e9, 11e9, 5)
     ... )
     """
     theta0 = np.deg2rad(theta0_deg)

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array_modeling.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phased-array-modeling
-Version: 1.3.0
+Version: 1.3.2
 Summary: Comprehensive Python library for phased array antenna modeling and visualization
 Author-email: John Hodge <jah70@vt.edu>
 License: MIT
@@ -55,11 +55,11 @@ Dynamic: license-file
 [![Streamlit App](https://static.streamlit.io/badges/streamlit_badge_black_white.svg)](https://phased-array-antenna-model.streamlit.app/)
 [![Documentation](https://readthedocs.org/projects/phased-array-antenna-model/badge/?version=latest)](https://phased-array-antenna-model.readthedocs.io/en/latest/)
 
-A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features **125x faster** vectorized computations, multiple array geometries, advanced beamforming, and interactive 3D visualization.
+A comprehensive Python library for computing and visualizing phased array antenna radiation patterns. Features vectorized computations (50-100x faster than naive loops), multiple array geometries, advanced beamforming, and interactive 3D visualization.
 
 ## Features
 
-- **High Performance**: Vectorized array factor computation (125x faster than naive loops)
+- **High Performance**: Vectorized array factor computation (50-100x faster than naive loops)
 - **Multiple Geometries**: Rectangular, triangular, circular, cylindrical, spherical, sparse/thinned arrays
 - **Beamforming**: Amplitude tapering (Taylor, Chebyshev, etc.), null steering, multi-beam
 - **Realistic Impairments**: Mutual coupling, phase quantization, element failures, scan blindness
@@ -81,7 +81,7 @@ The Streamlit app provides an interactive interface for:
 
 ## Installation
 
-### From GitHub (recommended)
+### From PyPI (recommended)
 
 ```bash
 pip install phased-array-modeling
@@ -235,8 +235,12 @@ For hands-on learning, see the [demo notebook](Phased_Array_Demo.ipynb) which co
 phased_array/
 ├── core.py          # Vectorized AF, FFT, steering, element patterns
 ├── geometry.py      # Array geometries and subarray architectures
-├── beamforming.py   # Tapering, null steering, multi-beam
+├── beamforming.py   # Tapering, null steering, multi-beam, adaptive
 ├── impairments.py   # Coupling, quantization, failures, scan blindness
+├── wideband.py      # True-time-delay steering, beam squint, bandwidth
+├── polarization.py  # Jones/Stokes, axial ratio, XPD, Ludwig-3
+├── coordinates.py   # Antenna/radar/cone frames, pattern rotation
+├── export.py        # CSV/JSON/NPZ export, summary reports
 ├── visualization.py # 2D, 3D Plotly, UV-space plotting
 └── utils.py         # Coordinate transforms, helpers
 ```
@@ -278,7 +282,7 @@ If you use this library in your research, please cite:
   author = {Hodge, John},
   title = {Phased Array Antenna Modeling},
   url = {https://github.com/jman4162/Phased-Array-Antenna-Model},
-  year = {2024}
+  year = {2026}
 }
 ```
 

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/phased_array_modeling.egg-info/SOURCES.txt

@@ -20,8 +20,11 @@ phased_array_modeling.egg-info/top_level.txt
 tests/test_beamforming.py
 tests/test_coordinates.py
 tests/test_core.py
+tests/test_docstrings.py
 tests/test_export.py
 tests/test_geometry.py
 tests/test_impairments.py
 tests/test_polarization.py
+tests/test_utils.py
+tests/test_visualization.py
 tests/test_wideband.py

{phased_array_modeling-1.3.0 → phased_array_modeling-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phased-array-modeling"
-version = "1.3.0"
+version = "1.3.2"
 description = "Comprehensive Python library for phased array antenna modeling and visualization"
 readme = "README.md"
 license = {text = "MIT"}

phased_array_modeling-1.3.2/tests/test_docstrings.py

@@ -0,0 +1,33 @@
+"""Run every module's docstring examples as doctests."""
+
+import doctest
+import importlib
+
+import pytest
+
+MODULES = [
+    "core",
+    "utils",
+    "geometry",
+    "beamforming",
+    "impairments",
+    "wideband",
+    "polarization",
+    "coordinates",
+    "export",
+    "visualization",
+]
+
+
+@pytest.mark.parametrize("module_name", MODULES)
+def test_module_doctests(module_name):
+    module = importlib.import_module(f"phased_array.{module_name}")
+    results = doctest.testmod(
+        module,
+        verbose=False,
+        report=True,
+        optionflags=doctest.ELLIPSIS | doctest.NORMALIZE_WHITESPACE,
+    )
+    assert results.failed == 0, (
+        f"{results.failed} doctest failure(s) in phased_array.{module_name}"
+    )

phased_array_modeling-1.3.2/tests/test_utils.py

@@ -0,0 +1,148 @@
+"""Tests for phased_array.utils coordinate transforms and helpers."""
+
+import numpy as np
+import pytest
+
+import phased_array as pa
+from phased_array.utils import (
+    azel_to_thetaphi,
+    create_theta_phi_grid,
+    create_uv_grid,
+    db_to_linear,
+    deg2rad,
+    frequency_to_k,
+    frequency_to_wavelength,
+    is_visible_region,
+    linear_to_db,
+    normalize_pattern,
+    rad2deg,
+    theta_phi_to_uv,
+    thetaphi_to_azel,
+    uv_to_theta_phi,
+    wavelength_to_k,
+)
+
+
+class TestAngleConversions:
+    def test_deg2rad_known_values(self):
+        assert np.isclose(deg2rad(180.0), np.pi)
+        assert np.isclose(deg2rad(0.0), 0.0)
+
+    def test_rad2deg_known_values(self):
+        assert np.isclose(rad2deg(np.pi / 2), 90.0)
+
+    def test_deg_rad_roundtrip(self):
+        angles = np.linspace(-180, 180, 19)
+        assert np.allclose(rad2deg(deg2rad(angles)), angles)
+
+
+class TestAzElThetaPhi:
+    def test_boresight(self):
+        theta, phi = azel_to_thetaphi(0.0, 0.0)
+        assert np.isclose(theta, 0.0)
+
+    def test_roundtrip(self):
+        az = np.deg2rad(np.array([10.0, -20.0, 30.0]))
+        el = np.deg2rad(np.array([5.0, 15.0, -25.0]))
+        theta, phi = azel_to_thetaphi(az, el)
+        az2, el2 = thetaphi_to_azel(theta, phi)
+        assert np.allclose(az2, az)
+        assert np.allclose(el2, el)
+
+
+class TestUVConversions:
+    def test_boresight_is_origin(self):
+        u, v = theta_phi_to_uv(0.0, 0.0)
+        assert np.isclose(u, 0.0)
+        assert np.isclose(v, 0.0)
+
+    def test_known_value(self):
+        u, v = theta_phi_to_uv(np.pi / 2, 0.0)
+        assert np.isclose(u, 1.0)
+        assert np.isclose(v, 0.0, atol=1e-12)
+
+    def test_roundtrip(self):
+        theta = np.deg2rad(np.array([10.0, 30.0, 60.0]))
+        phi = np.deg2rad(np.array([0.0, 45.0, 200.0]))
+        u, v = theta_phi_to_uv(theta, phi)
+        theta2, phi2 = uv_to_theta_phi(u, v)
+        u2, v2 = theta_phi_to_uv(theta2, phi2)
+        # Angles may wrap; direction cosines must round-trip exactly
+        assert np.allclose(u2, u)
+        assert np.allclose(v2, v)
+
+    def test_visible_region_boundary(self):
+        assert is_visible_region(0.0, 0.0)
+        assert is_visible_region(1.0, 0.0)
+        assert not is_visible_region(0.8, 0.8)
+        mask = is_visible_region(np.array([0.0, 0.9, 0.5]), np.array([0.0, 0.9, 0.5]))
+        assert mask.tolist() == [True, False, True]
+
+
+class TestWavenumberFrequency:
+    def test_wavelength_to_k(self):
+        assert np.isclose(wavelength_to_k(1.0), 2 * np.pi)
+        assert np.isclose(wavelength_to_k(0.5), 4 * np.pi)
+
+    def test_frequency_to_wavelength(self):
+        assert np.isclose(frequency_to_wavelength(3e8), 1.0)
+        assert np.isclose(frequency_to_wavelength(10e9, c=3e8), 0.03)
+
+    def test_frequency_to_k_consistent(self):
+        f = 10e9
+        assert np.isclose(frequency_to_k(f), wavelength_to_k(frequency_to_wavelength(f)))
+
+
+class TestDbConversions:
+    def test_roundtrip(self):
+        values = np.array([1e-3, 0.5, 1.0, 100.0])
+        assert np.allclose(db_to_linear(linear_to_db(values)), values)
+
+    def test_known_values(self):
+        assert np.isclose(linear_to_db(10.0), 10.0)
+        assert np.isclose(db_to_linear(3.0), 10 ** 0.3)
+
+    def test_min_db_floor(self):
+        assert linear_to_db(0.0) == -100.0
+        assert linear_to_db(0.0, min_db=-60.0) == -60.0
+        assert np.all(linear_to_db(np.array([0.0, 1e-30])) == -100.0)
+
+
+class TestNormalizePattern:
+    def test_peak_mode(self):
+        pattern = np.array([1.0, 2.0, 4.0])
+        normalized = normalize_pattern(pattern, mode="peak")
+        assert np.isclose(np.max(normalized), 1.0)
+
+    def test_power_mode(self):
+        pattern = np.array([1.0, 2.0, 2.0])
+        normalized = normalize_pattern(pattern, mode="power")
+        assert np.isclose(np.sum(np.abs(normalized) ** 2), 1.0)
+
+    def test_unknown_mode_raises(self):
+        with pytest.raises(ValueError):
+            normalize_pattern(np.array([1.0]), mode="bogus")
+
+
+class TestGrids:
+    def test_theta_phi_grid_shapes(self):
+        theta, phi, THETA, PHI = create_theta_phi_grid(n_theta=19, n_phi=37)
+        assert theta.shape == (19,)
+        assert phi.shape == (37,)
+        assert THETA.shape == (19, 37)
+        assert PHI.shape == (19, 37)
+
+    def test_theta_phi_grid_ranges(self):
+        theta, phi, _, _ = create_theta_phi_grid(
+            theta_range=(0, np.pi / 2), phi_range=(0, np.pi), n_theta=10, n_phi=10
+        )
+        assert np.isclose(theta[0], 0.0)
+        assert np.isclose(theta[-1], np.pi / 2)
+        assert np.isclose(phi[-1], np.pi)
+
+    def test_uv_grid_shapes(self):
+        u, v, U, V = create_uv_grid(n_u=21, n_v=31)
+        assert u.shape == (21,)
+        assert v.shape == (31,)
+        assert U.shape == (31, 21) or U.shape == (21, 31)
+        assert U.shape == V.shape

phased_array_modeling-1.3.2/tests/test_visualization.py

@@ -0,0 +1,180 @@
+"""Smoke tests for phased_array.visualization plotting functions."""
+
+import matplotlib
+
+matplotlib.use("Agg")
+
+import matplotlib.pyplot as plt
+import numpy as np
+import pytest
+
+import phased_array as pa
+from phased_array.visualization import (
+    compute_pattern_uv_space,
+    plot_array_geometry,
+    plot_beam_squint,
+    plot_comparison_patterns,
+    plot_pattern_2d,
+    plot_pattern_contour,
+    plot_pattern_polar,
+    plot_pattern_uv_space,
+    plot_pattern_vs_frequency,
+    plot_subarray_delays,
+)
+
+plotly = pytest.importorskip("plotly", reason="plotly not installed")
+import plotly.graph_objects as go  # noqa: E402
+
+from phased_array.visualization import (  # noqa: E402
+    create_pattern_animation_plotly,
+    plot_array_geometry_3d_plotly,
+    plot_pattern_3d_cartesian_plotly,
+    plot_pattern_3d_plotly,
+    plot_pattern_uv_plotly,
+    plot_pattern_vs_frequency_plotly,
+)
+
+
+@pytest.fixture(autouse=True)
+def close_figures():
+    yield
+    plt.close("all")
+
+
+@pytest.fixture(scope="module")
+def small_array():
+    geom = pa.create_rectangular_array(4, 4, dx=0.5, dy=0.5)
+    k = pa.wavelength_to_k(1.0)
+    weights = pa.steering_vector(k, geom.x, geom.y, 0, 0)
+    return geom, k, weights
+
+
+@pytest.fixture(scope="module")
+def pattern_cut(small_array):
+    geom, k, weights = small_array
+    angles = np.linspace(-90, 90, 181)
+    theta = np.deg2rad(np.abs(angles))
+    phi = np.where(angles >= 0, 0.0, np.pi)
+    af = pa.array_factor_vectorized(theta, phi, geom.x, geom.y, weights, k)
+    pattern_dB = 20 * np.log10(np.abs(af) / np.abs(af).max() + 1e-12)
+    return angles, pattern_dB
+
+
+@pytest.fixture(scope="module")
+def full_pattern(small_array):
+    geom, k, weights = small_array
+    theta, phi, pattern_dB = pa.compute_full_pattern(
+        geom.x, geom.y, weights, k, n_theta=19, n_phi=37
+    )
+    return theta, phi, pattern_dB
+
+
+class TestMatplotlibPlots:
+    def test_plot_pattern_2d(self, pattern_cut):
+        ax = plot_pattern_2d(*pattern_cut)
+        assert ax is not None
+
+    def test_plot_pattern_2d_existing_ax(self, pattern_cut):
+        fig, ax_in = plt.subplots()
+        ax = plot_pattern_2d(*pattern_cut, ax=ax_in)
+        assert ax is ax_in
+
+    def test_plot_pattern_polar(self, pattern_cut):
+        ax = plot_pattern_polar(*pattern_cut)
+        assert ax is not None
+
+    def test_plot_pattern_contour(self, full_pattern):
+        theta, phi, pattern_dB = full_pattern
+        ax = plot_pattern_contour(np.rad2deg(theta), np.rad2deg(phi), pattern_dB)
+        assert ax is not None
+
+    def test_plot_array_geometry(self, small_array):
+        geom, _, weights = small_array
+        ax = plot_array_geometry(geom, weights=weights)
+        assert ax is not None
+
+    def test_plot_comparison_patterns(self, pattern_cut):
+        angles, pattern_dB = pattern_cut
+        ax = plot_comparison_patterns(
+            angles, {"a": pattern_dB, "b": pattern_dB - 3.0}
+        )
+        assert ax is not None
+
+    def test_plot_beam_squint(self):
+        freqs = np.linspace(9e9, 11e9, 5)
+        squint = {"phase": np.linspace(-2, 2, 5), "ttd": np.zeros(5)}
+        ax = plot_beam_squint(freqs, squint, center_frequency=10e9)
+        assert ax is not None
+
+    def test_plot_pattern_vs_frequency(self, pattern_cut):
+        angles, pattern_dB = pattern_cut
+        freqs = np.linspace(9e9, 11e9, 4)
+        patterns = np.tile(pattern_dB, (4, 1))
+        ax = plot_pattern_vs_frequency(angles, freqs, patterns, center_frequency=10e9)
+        assert ax is not None
+
+    def test_plot_subarray_delays(self):
+        arch = pa.create_rectangular_subarrays(8, 8, 4, 4, dx=0.5, dy=0.5)
+        delays = pa.compute_subarray_delays_ttd(arch, theta0_deg=20, phi0_deg=0)
+        ax = plot_subarray_delays(arch, delays)
+        assert ax is not None
+
+
+class TestUVSpace:
+    def test_compute_pattern_uv_space(self, small_array):
+        geom, k, weights = small_array
+        u, v, pattern_dB = compute_pattern_uv_space(geom, weights, k, n_u=41, n_v=41)
+        assert pattern_dB.shape == (41, 41)
+        # Invisible region must be masked or finite-valued; peak is 0 dB
+        assert np.isclose(np.nanmax(pattern_dB), 0.0, atol=1e-6)
+
+    def test_plot_pattern_uv_space(self, small_array):
+        geom, k, weights = small_array
+        u, v, pattern_dB = compute_pattern_uv_space(geom, weights, k, n_u=41, n_v=41)
+        ax = plot_pattern_uv_space(
+            u, v, pattern_dB, show_grating_circles=True,
+            dx_wavelengths=0.5, dy_wavelengths=0.5,
+        )
+        assert ax is not None
+
+
+class TestPlotlyPlots:
+    def test_plot_pattern_3d_plotly(self, full_pattern):
+        fig = plot_pattern_3d_plotly(*full_pattern)
+        assert isinstance(fig, go.Figure)
+        assert len(fig.data) >= 1
+
+    def test_plot_pattern_3d_cartesian_plotly(self, full_pattern):
+        theta, phi, pattern_dB = full_pattern
+        fig = plot_pattern_3d_cartesian_plotly(
+            np.rad2deg(theta), np.rad2deg(phi), pattern_dB
+        )
+        assert isinstance(fig, go.Figure)
+
+    def test_plot_array_geometry_3d_plotly(self, small_array):
+        geom, _, weights = small_array
+        fig = plot_array_geometry_3d_plotly(geom, weights=weights)
+        assert isinstance(fig, go.Figure)
+
+    def test_plot_pattern_uv_plotly(self, small_array):
+        geom, k, weights = small_array
+        u, v, pattern_dB = compute_pattern_uv_space(geom, weights, k, n_u=41, n_v=41)
+        fig = plot_pattern_uv_plotly(u, v, pattern_dB)
+        assert isinstance(fig, go.Figure)
+
+    def test_create_pattern_animation_plotly(self, full_pattern):
+        theta, phi, pattern_dB = full_pattern
+        fig = create_pattern_animation_plotly(
+            theta, phi, [pattern_dB, pattern_dB - 3.0], ["f0", "f1"]
+        )
+        assert isinstance(fig, go.Figure)
+        assert len(fig.frames) == 2
+
+    def test_plot_pattern_vs_frequency_plotly(self, pattern_cut):
+        angles, pattern_dB = pattern_cut
+        freqs = np.linspace(9e9, 11e9, 4)
+        patterns = np.tile(pattern_dB, (4, 1))
+        fig = plot_pattern_vs_frequency_plotly(
+            angles, freqs, patterns, center_frequency=10e9
+        )
+        assert isinstance(fig, go.Figure)