phased-array-systems 0.1.2__tar.gz → 0.2.0__tar.gz

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phased-array-systems
-Version: 0.1.2
+Version: 0.2.0
 Summary: Phased array antenna system design, optimization, and performance visualization
 Project-URL: Homepage, https://github.com/jman4162/phased-array-systems
 Project-URL: Documentation, https://github.com/jman4162/phased-array-systems#readme

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/examples/01_comms_single_case.py

@@ -66,6 +66,7 @@ def main():
 
     print(f"\nArchitecture: {architecture.name}")
     print(f"  Array: {array_config.nx}x{array_config.ny} = {architecture.n_elements} elements")
+    print(f"  Sub-arrays: {array_config.n_subarrays_x}x{array_config.n_subarrays_y} = {array_config.n_subarrays} total")
     print(f"  TX Power/Element: {rf_config.tx_power_w_per_elem} W")
     print(f"  Total TX Power: {architecture.n_elements * rf_config.tx_power_w_per_elem} W")
 

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/examples/02_comms_doe_trade.py

@@ -96,9 +96,11 @@ def main():
     # =========================================================================
     design_space = (
         DesignSpace(name="Comms Array Design Space")
-        # Array dimensions
-        .add_variable("array.nx", type="int", low=4, high=16)
-        .add_variable("array.ny", type="int", low=4, high=16)
+        # Array dimensions (must be powers of 2 for sub-array constraints)
+        .add_variable("array.nx", type="categorical", values=[4, 8, 16])
+        .add_variable("array.ny", type="categorical", values=[4, 8, 16])
+        # Disable sub-array constraint for DOE flexibility (or use power-of-2 values)
+        .add_variable("array.enforce_subarray_constraint", type="categorical", values=[True])
         # Fixed array parameters
         .add_variable("array.geometry", type="categorical", values=["rectangular"])
         .add_variable("array.dx_lambda", type="float", low=0.5, high=0.5)

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/notebooks/tutorial_phased_array_trade_study.ipynb

@@ -356,29 +356,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "# Define the design space to explore\n",
-    "design_space = (\n",
-    "    DesignSpace(name=\"Comms Array Trade Space\")\n",
-    "    # Variable parameters\n",
-    "    .add_variable(\"array.nx\", type=\"int\", low=4, high=16)\n",
-    "    .add_variable(\"array.ny\", type=\"int\", low=4, high=16)\n",
-    "    .add_variable(\"rf.tx_power_w_per_elem\", type=\"float\", low=0.5, high=3.0)\n",
-    "    .add_variable(\"cost.cost_per_elem_usd\", type=\"float\", low=75.0, high=150.0)\n",
-    "    # Fixed parameters\n",
-    "    .add_variable(\"array.geometry\", type=\"categorical\", values=[\"rectangular\"])\n",
-    "    .add_variable(\"array.dx_lambda\", type=\"float\", low=0.5, high=0.5)\n",
-    "    .add_variable(\"array.dy_lambda\", type=\"float\", low=0.5, high=0.5)\n",
-    "    .add_variable(\"array.scan_limit_deg\", type=\"float\", low=60.0, high=60.0)\n",
-    "    .add_variable(\"rf.pa_efficiency\", type=\"float\", low=0.3, high=0.3)\n",
-    "    .add_variable(\"rf.noise_figure_db\", type=\"float\", low=3.0, high=3.0)\n",
-    "    .add_variable(\"rf.n_tx_beams\", type=\"int\", low=1, high=1)\n",
-    "    .add_variable(\"rf.feed_loss_db\", type=\"float\", low=1.0, high=1.0)\n",
-    "    .add_variable(\"rf.system_loss_db\", type=\"float\", low=0.0, high=0.0)\n",
-    ")\n",
-    "\n",
-    "print(f\"Design space: {design_space.n_dims} variables\")"
-   ]
+   "source": "# Define the design space to explore\ndesign_space = (\n    DesignSpace(name=\"Comms Array Trade Space\")\n    # Variable parameters (array dimensions must be powers of 2 for RF constraints)\n    .add_variable(\"array.nx\", type=\"categorical\", values=[4, 8, 16])\n    .add_variable(\"array.ny\", type=\"categorical\", values=[4, 8, 16])\n    .add_variable(\"rf.tx_power_w_per_elem\", type=\"float\", low=0.5, high=3.0)\n    .add_variable(\"cost.cost_per_elem_usd\", type=\"float\", low=75.0, high=150.0)\n    # Fixed parameters\n    .add_variable(\"array.geometry\", type=\"categorical\", values=[\"rectangular\"])\n    .add_variable(\"array.dx_lambda\", type=\"float\", low=0.5, high=0.5)\n    .add_variable(\"array.dy_lambda\", type=\"float\", low=0.5, high=0.5)\n    .add_variable(\"array.scan_limit_deg\", type=\"float\", low=60.0, high=60.0)\n    .add_variable(\"array.enforce_subarray_constraint\", type=\"categorical\", values=[True])\n    .add_variable(\"rf.pa_efficiency\", type=\"float\", low=0.3, high=0.3)\n    .add_variable(\"rf.noise_figure_db\", type=\"float\", low=3.0, high=3.0)\n    .add_variable(\"rf.n_tx_beams\", type=\"int\", low=1, high=1)\n    .add_variable(\"rf.feed_loss_db\", type=\"float\", low=1.0, high=1.0)\n    .add_variable(\"rf.system_loss_db\", type=\"float\", low=0.0, high=0.0)\n)\n\nprint(f\"Design space: {design_space.n_dims} variables\")"
   },
   {
    "cell_type": "code",
@@ -685,4 +663,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 4
-}
+}

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/src/phased_array_systems/__about__.py

@@ -1,4 +1,4 @@
 """Version and metadata for phased-array-systems."""
 
-__version__ = "0.1.2"
+__version__ = "0.2.0"
 __author__ = "phased-array-systems contributors"

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/src/phased_array_systems/architecture/config.py

@@ -1,8 +1,17 @@
 """Architecture configuration models using Pydantic."""
 
+import math
 from typing import Literal
 
-from pydantic import BaseModel, Field, field_validator
+from pydantic import BaseModel, Field, field_validator, model_validator
+
+# Valid power-of-two values for sub-array dimensions
+VALID_POWERS_OF_TWO = [2**i for i in range(1, 10)]  # 2, 4, 8, 16, 32, 64, 128, 256, 512
+
+
+def is_power_of_two(n: int) -> bool:
+    """Check if n is a power of two (and >= 2)."""
+    return n >= 2 and (n & (n - 1)) == 0
 
 
 class ArrayConfig(BaseModel):
@@ -15,6 +24,9 @@ class ArrayConfig(BaseModel):
         dx_lambda: Element spacing in x-direction (wavelengths)
         dy_lambda: Element spacing in y-direction (wavelengths)
         scan_limit_deg: Maximum scan angle from boresight (degrees)
+        max_subarray_nx: Maximum elements per sub-array in x (must be power of 2)
+        max_subarray_ny: Maximum elements per sub-array in y (must be power of 2)
+        enforce_subarray_constraint: Whether to enforce power-of-two sub-array constraint
     """
 
     geometry: Literal["rectangular", "circular", "triangular"] = "rectangular"
@@ -26,11 +38,113 @@ class ArrayConfig(BaseModel):
         default=60.0, ge=0, le=90, description="Maximum scan angle (degrees)"
     )
 
+    # Sub-array constraints for practical RF component design (power-of-two)
+    max_subarray_nx: int = Field(
+        default=8, ge=2, description="Max elements per sub-array in x (must be power of 2)"
+    )
+    max_subarray_ny: int = Field(
+        default=8, ge=2, description="Max elements per sub-array in y (must be power of 2)"
+    )
+    enforce_subarray_constraint: bool = Field(
+        default=True, description="Enforce power-of-two sub-array constraint"
+    )
+
+    @field_validator("max_subarray_nx", "max_subarray_ny")
+    @classmethod
+    def validate_power_of_two(cls, v: int) -> int:
+        """Validate that max sub-array dimensions are powers of two."""
+        if not is_power_of_two(v):
+            raise ValueError(
+                f"max_subarray value {v} must be a power of 2 "
+                f"(valid values: {VALID_POWERS_OF_TWO})"
+            )
+        return v
+
+    @model_validator(mode="after")
+    def validate_subarray_constraints(self) -> "ArrayConfig":
+        """Validate that array dimensions result in power-of-two sub-arrays."""
+        if not self.enforce_subarray_constraint:
+            return self
+
+        if self.geometry != "rectangular":
+            # Sub-array constraints only apply to rectangular arrays for now
+            return self
+
+        # Check x-direction
+        if self.nx > self.max_subarray_nx:
+            # Must be divisible by max_subarray_nx
+            if self.nx % self.max_subarray_nx != 0:
+                raise ValueError(
+                    f"nx={self.nx} must be divisible by max_subarray_nx={self.max_subarray_nx} "
+                    f"for arrays larger than max sub-array size. "
+                    f"Set enforce_subarray_constraint=False to disable."
+                )
+        else:
+            # Small array: nx itself must be power of two
+            if not is_power_of_two(self.nx):
+                raise ValueError(
+                    f"nx={self.nx} must be a power of 2 (2, 4, 8, 16, ...) when "
+                    f"enforce_subarray_constraint=True. Valid values: {VALID_POWERS_OF_TWO}"
+                )
+
+        # Check y-direction
+        if self.ny > self.max_subarray_ny:
+            # Must be divisible by max_subarray_ny
+            if self.ny % self.max_subarray_ny != 0:
+                raise ValueError(
+                    f"ny={self.ny} must be divisible by max_subarray_ny={self.max_subarray_ny} "
+                    f"for arrays larger than max sub-array size. "
+                    f"Set enforce_subarray_constraint=False to disable."
+                )
+        else:
+            # Small array: ny itself must be power of two
+            if not is_power_of_two(self.ny):
+                raise ValueError(
+                    f"ny={self.ny} must be a power of 2 (2, 4, 8, 16, ...) when "
+                    f"enforce_subarray_constraint=True. Valid values: {VALID_POWERS_OF_TWO}"
+                )
+
+        return self
+
     @property
     def n_elements(self) -> int:
         """Total number of elements in the array."""
         return self.nx * self.ny
 
+    @property
+    def subarray_nx(self) -> int:
+        """Actual elements per sub-array in x-direction."""
+        if self.nx <= self.max_subarray_nx:
+            return self.nx
+        return self.max_subarray_nx
+
+    @property
+    def subarray_ny(self) -> int:
+        """Actual elements per sub-array in y-direction."""
+        if self.ny <= self.max_subarray_ny:
+            return self.ny
+        return self.max_subarray_ny
+
+    @property
+    def n_subarrays_x(self) -> int:
+        """Number of sub-arrays in x-direction."""
+        return math.ceil(self.nx / self.max_subarray_nx)
+
+    @property
+    def n_subarrays_y(self) -> int:
+        """Number of sub-arrays in y-direction."""
+        return math.ceil(self.ny / self.max_subarray_ny)
+
+    @property
+    def n_subarrays(self) -> int:
+        """Total number of sub-arrays."""
+        return self.n_subarrays_x * self.n_subarrays_y
+
+    @property
+    def elements_per_subarray(self) -> int:
+        """Number of elements per sub-array."""
+        return self.subarray_nx * self.subarray_ny
+
 
 class RFChainConfig(BaseModel):
     """Configuration for the RF chain.

{phased_array_systems-0.1.2 → phased_array_systems-0.2.0}/tests/test_architecture.py

@@ -38,6 +38,110 @@ class TestArrayConfig:
             ArrayConfig(nx=8, ny=8, scan_limit_deg=95.0)
 
 
+class TestSubarrayConstraints:
+    """Tests for sub-array constraints (power-of-two)."""
+
+    def test_default_subarray_values(self):
+        """Test default sub-array constraint values."""
+        config = ArrayConfig(nx=8, ny=8)
+        assert config.max_subarray_nx == 8
+        assert config.max_subarray_ny == 8
+        assert config.enforce_subarray_constraint is True
+
+    def test_subarray_properties_small_array(self):
+        """Test sub-array properties for array smaller than max."""
+        config = ArrayConfig(nx=4, ny=4)
+        assert config.subarray_nx == 4
+        assert config.subarray_ny == 4
+        assert config.n_subarrays_x == 1
+        assert config.n_subarrays_y == 1
+        assert config.n_subarrays == 1
+        assert config.elements_per_subarray == 16
+
+    def test_subarray_properties_large_array(self):
+        """Test sub-array properties for array larger than max."""
+        config = ArrayConfig(nx=16, ny=32, max_subarray_nx=8, max_subarray_ny=8)
+        assert config.subarray_nx == 8
+        assert config.subarray_ny == 8
+        assert config.n_subarrays_x == 2
+        assert config.n_subarrays_y == 4
+        assert config.n_subarrays == 8
+        assert config.elements_per_subarray == 64
+
+    def test_subarray_constraint_enforced_valid(self):
+        """Test valid array dimensions with constraint enforced."""
+        # 16 is divisible by 8 and both are powers of 2
+        config = ArrayConfig(nx=16, ny=16, max_subarray_nx=8, max_subarray_ny=8)
+        assert config.n_subarrays == 4
+
+    def test_subarray_constraint_invalid_not_power_of_two_small(self):
+        """Test that non-power-of-two small array raises error."""
+        # nx=6 is not a power of 2
+        with pytest.raises(ValidationError, match="nx=6 must be a power of 2"):
+            ArrayConfig(nx=6, ny=8, max_subarray_nx=8, max_subarray_ny=8)
+
+    def test_subarray_constraint_invalid_not_divisible(self):
+        """Test that non-divisible large array raises error."""
+        # nx=12 is larger than 8 but not divisible by 8
+        with pytest.raises(ValidationError, match="nx=12 must be divisible by"):
+            ArrayConfig(nx=12, ny=8, max_subarray_nx=8, max_subarray_ny=8)
+
+    def test_max_subarray_must_be_power_of_two(self):
+        """Test that max_subarray values must be powers of two."""
+        with pytest.raises(ValidationError, match="must be a power of 2"):
+            ArrayConfig(nx=8, ny=8, max_subarray_nx=6, max_subarray_ny=8)
+
+    def test_subarray_constraint_disabled(self):
+        """Test that constraint can be disabled."""
+        # This would fail with constraint enabled (10, 12 not powers of 2)
+        config = ArrayConfig(
+            nx=10, ny=12,
+            max_subarray_nx=8, max_subarray_ny=8,
+            enforce_subarray_constraint=False
+        )
+        assert config.nx == 10
+        assert config.ny == 12
+        assert config.n_subarrays_x == 2  # ceil(10/8)
+        assert config.n_subarrays_y == 2  # ceil(12/8)
+
+    def test_custom_subarray_size_power_of_two(self):
+        """Test custom sub-array sizes (must be powers of two)."""
+        config = ArrayConfig(
+            nx=16, ny=16,
+            max_subarray_nx=4, max_subarray_ny=4
+        )
+        assert config.n_subarrays_x == 4
+        assert config.n_subarrays_y == 4
+        assert config.n_subarrays == 16
+
+    def test_non_rectangular_skips_constraint(self):
+        """Test that non-rectangular geometries skip constraint validation."""
+        # This would fail for rectangular with constraint enforced
+        config = ArrayConfig(
+            nx=10, ny=12,
+            geometry="circular",
+            max_subarray_nx=8, max_subarray_ny=8,
+            enforce_subarray_constraint=True
+        )
+        assert config.nx == 10
+        assert config.ny == 12
+
+    def test_valid_power_of_two_sizes(self):
+        """Test various valid power-of-two array sizes."""
+        for size in [2, 4, 8, 16, 32]:
+            config = ArrayConfig(nx=size, ny=size)
+            assert config.nx == size
+            assert config.ny == size
+
+    def test_large_array_multiple_subarrays(self):
+        """Test large array with multiple sub-arrays."""
+        config = ArrayConfig(nx=64, ny=32, max_subarray_nx=16, max_subarray_ny=8)
+        assert config.n_subarrays_x == 4  # 64/16
+        assert config.n_subarrays_y == 4  # 32/8
+        assert config.n_subarrays == 16
+        assert config.elements_per_subarray == 128  # 16*8
+
+
 class TestRFChainConfig:
     """Tests for RFChainConfig."""