phased-array-modeling 1.3.1__tar.gz → 1.4.0__tar.gz

{phased_array_modeling-1.3.1 → phased_array_modeling-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phased-array-modeling
-Version: 1.3.1
+Version: 1.4.0
 Summary: Comprehensive Python library for phased array antenna modeling and visualization
 Author-email: John Hodge <jah70@vt.edu>
 License: MIT
@@ -15,14 +15,13 @@ Classifier: Intended Audience :: Education
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: >=3.8
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
@@ -55,14 +54,15 @@ 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
+- **Polarized Patterns**: Vector (E-theta, E-phi) patterns with dipole/patch/CP element models, co/cross-pol cuts, axial ratio and XPD maps, measured element pattern import
 - **Visualization**: 2D matplotlib, interactive 3D Plotly, UV-space representation
 - **Subarray Support**: Subarray-level beamforming with quantized phase shifters
 - **Data Export**: CSV, JSON, and NumPy formats for patterns, weights, and geometry
@@ -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,13 @@ 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
+├── vector_patterns.py # Polarized elements, vector AF, co/cross patterns
+├── 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 +283,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.1 → phased_array_modeling-1.4.0}/README.md

@@ -9,14 +9,15 @@
 [![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
+- **Polarized Patterns**: Vector (E-theta, E-phi) patterns with dipole/patch/CP element models, co/cross-pol cuts, axial ratio and XPD maps, measured element pattern import
 - **Visualization**: 2D matplotlib, interactive 3D Plotly, UV-space representation
 - **Subarray Support**: Subarray-level beamforming with quantized phase shifters
 - **Data Export**: CSV, JSON, and NumPy formats for patterns, weights, and geometry
@@ -35,7 +36,7 @@ The Streamlit app provides an interactive interface for:
 
 ## Installation
 
-### From GitHub (recommended)
+### From PyPI (recommended)
 
 ```bash
 pip install phased-array-modeling
@@ -189,8 +190,13 @@ 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
+├── vector_patterns.py # Polarized elements, vector AF, co/cross patterns
+├── 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 +238,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.1 → phased_array_modeling-1.4.0}/phased_array/__init__.py

@@ -9,6 +9,7 @@ antenna radiation patterns, including:
 - Various array geometries (rectangular, circular, conformal, sparse)
 - Beamforming techniques (tapering, null steering, multi-beam)
 - Realistic impairments (mutual coupling, quantization, failures, scan blindness)
+- Vector (polarized) patterns: co/cross-pol, axial ratio, XPD, conformal
 - Interactive 3D visualization with Plotly
 - UV-space pattern representation
 
@@ -32,7 +33,7 @@ Example
 >>> theta, phi, pattern_dB = pa.compute_full_pattern(geom.x, geom.y, weights, k)
 """
 
-__version__ = "1.3.1"
+__version__ = "1.4.0"
 
 # Beamforming functions
 from .beamforming import (  # Amplitude tapers; Null steering; Multiple beams; Beam spoiling; Adaptive
@@ -95,6 +96,16 @@ from .utils import (azel_to_thetaphi, create_theta_phi_grid, create_uv_grid,
                     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)
+# Vector (polarized) pattern functions
+from .vector_patterns import (GriddedElementPattern, VectorPattern,
+                              compute_co_cross_pattern_cuts,
+                              compute_full_vector_pattern,
+                              cos_q_polarized_element, crossed_dipole_element,
+                              dipole_element, dual_pol_weights,
+                              element_rotation_matrices,
+                              global_to_local_angles, ideal_patch_element,
+                              vector_array_factor_conformal,
+                              vector_total_pattern)
 # Visualization functions
 from .visualization import (  # 2D matplotlib plots; UV-space; 3D Plotly plots; Wideband
     compute_pattern_uv_space, create_pattern_animation_plotly,
@@ -278,4 +289,18 @@ __all__ = [
     "rotation_matrix_pitch",
     "rotation_matrix_yaw",
     "rotate_pattern",
+    # Vector (polarized) patterns
+    "VectorPattern",
+    "GriddedElementPattern",
+    "dipole_element",
+    "ideal_patch_element",
+    "cos_q_polarized_element",
+    "crossed_dipole_element",
+    "vector_total_pattern",
+    "compute_full_vector_pattern",
+    "compute_co_cross_pattern_cuts",
+    "dual_pol_weights",
+    "element_rotation_matrices",
+    "global_to_local_angles",
+    "vector_array_factor_conformal",
 ]

{phased_array_modeling-1.3.1 → phased_array_modeling-1.4.0}/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

{phased_array_modeling-1.3.1 → phased_array_modeling-1.4.0}/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.1 → phased_array_modeling-1.4.0}/phased_array/geometry.py

@@ -32,6 +32,13 @@ class ArrayGeometry:
         Element normal z-components
     element_indices : ndarray, optional
         Original indices before any thinning (for tracking)
+    tx : ndarray, optional
+        Element tangent x-components (local x-axis / polarization
+        reference for conformal vector patterns)
+    ty : ndarray, optional
+        Element tangent y-components
+    tz : ndarray, optional
+        Element tangent z-components
     """
     x: np.ndarray
     y: np.ndarray
@@ -40,6 +47,9 @@ class ArrayGeometry:
     ny: Optional[np.ndarray] = None
     nz: Optional[np.ndarray] = None
     element_indices: Optional[np.ndarray] = None
+    tx: Optional[np.ndarray] = None
+    ty: Optional[np.ndarray] = None
+    tz: Optional[np.ndarray] = None
 
     @property
     def n_elements(self) -> int:
@@ -74,7 +84,10 @@ class ArrayGeometry:
             nx=self.nx.copy() if self.nx is not None else None,
             ny=self.ny.copy() if self.ny is not None else None,
             nz=self.nz.copy() if self.nz is not None else None,
-            element_indices=self.element_indices.copy() if self.element_indices is not None else None
+            element_indices=self.element_indices.copy() if self.element_indices is not None else None,
+            tx=self.tx.copy() if self.tx is not None else None,
+            ty=self.ty.copy() if self.ty is not None else None,
+            tz=self.tz.copy() if self.tz is not None else None
         )
 
 
@@ -465,14 +478,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 +493,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))
     )
 
@@ -1001,6 +1010,13 @@ def array_factor_conformal(
     obs_y = np.sin(theta_flat) * np.sin(phi_flat)
     obs_z = np.cos(theta_flat)
 
+    has_normals = (geometry.nx is not None and geometry.ny is not None
+                   and geometry.nz is not None)
+    if has_normals and element_pattern_func is not None:
+        from .vector_patterns import (element_rotation_matrices,
+                                      global_to_local_angles)
+        R = element_rotation_matrices(geometry)
+
     AF = np.zeros(n_angles, dtype=complex)
 
     for i in range(geometry.n_elements):
@@ -1010,7 +1026,7 @@ def array_factor_conformal(
             phase += k * geometry.z[i] * obs_z
 
         # Element pattern correction for orientation
-        if geometry.nx is not None and geometry.ny is not None and geometry.nz is not None:
+        if has_normals:
             # Cosine of angle between observation direction and element normal
             cos_angle = (geometry.nx[i] * obs_x +
                         geometry.ny[i] * obs_y +
@@ -1018,9 +1034,11 @@ def array_factor_conformal(
             cos_angle = np.maximum(cos_angle, 0)  # Only forward hemisphere
 
             if element_pattern_func is not None:
-                # Local theta for this element (angle from its normal)
-                local_theta = np.arccos(np.clip(cos_angle, -1, 1))
-                element_gain = element_pattern_func(local_theta, phi_flat, **element_kwargs)
+                # Observation angles in the element's local frame
+                local_theta, local_phi = global_to_local_angles(
+                    R[i], theta_flat, phi_flat
+                )
+                element_gain = element_pattern_func(local_theta, local_phi, **element_kwargs)
             else:
                 element_gain = cos_angle  # Simple cosine pattern
         else:
@@ -1241,7 +1259,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.1 → phased_array_modeling-1.4.0}/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.1 → phased_array_modeling-1.4.0}/phased_array/polarization.py

@@ -81,13 +81,13 @@ def stokes_parameters(jones: np.ndarray) -> Tuple[float, float, float, float]:
     Returns
     -------
     S0 : float or ndarray
-        Total intensity: |Ex|^2 + |Ey|^2
+        Total intensity: ``|Ex|^2 + |Ey|^2``
     S1 : float or ndarray
-        Linear horizontal-vertical: |Ex|^2 - |Ey|^2
+        Linear horizontal-vertical: ``|Ex|^2 - |Ey|^2``
     S2 : float or ndarray
-        Linear +45/-45: 2*Re(Ex*Ey*)
+        Linear +45/-45: ``2*Re(Ex*conj(Ey))``
     S3 : float or ndarray
-        Circular right-left: 2*Im(Ex*Ey*)
+        Circular right-left: ``2*Im(Ex*conj(Ey))``
 
     Examples
     --------
@@ -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.1 → phased_array_modeling-1.4.0}/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