phased-array-systems 0.1.0__py3-none-any.whl

phased_array_systems/trades/doe.py

@@ -0,0 +1,146 @@
+"""Design of Experiments (DOE) generation utilities."""
+
+from typing import Literal
+
+import pandas as pd
+
+from phased_array_systems.trades.design_space import DesignSpace
+
+
+def generate_doe(
+    design_space: DesignSpace,
+    method: Literal["grid", "random", "lhs"] = "lhs",
+    n_samples: int = 100,
+    seed: int | None = None,
+    grid_levels: int | list[int] | None = None,
+) -> pd.DataFrame:
+    """Generate a Design of Experiments from a design space.
+
+    This is a convenience function that wraps DesignSpace.sample().
+
+    Args:
+        design_space: DesignSpace defining the variables and bounds
+        method: Sampling method
+            - "grid": Full factorial grid (n_samples ignored)
+            - "random": Uniform random sampling
+            - "lhs": Latin Hypercube Sampling (space-filling)
+        n_samples: Number of samples (for random/lhs methods)
+        seed: Random seed for reproducibility
+        grid_levels: Number of levels per variable for grid method
+
+    Returns:
+        DataFrame with columns:
+            - case_id: Unique identifier for each case
+            - One column per design variable
+
+    Examples:
+        >>> space = DesignSpace()
+        >>> space.add_variable("array.nx", "int", low=4, high=16)
+        >>> space.add_variable("array.ny", "int", low=4, high=16)
+        >>> space.add_variable("rf.tx_power_w_per_elem", "float", low=0.5, high=2.0)
+        >>> doe = generate_doe(space, method="lhs", n_samples=50, seed=42)
+    """
+    return design_space.sample(
+        method=method,
+        n_samples=n_samples,
+        seed=seed,
+        grid_levels=grid_levels,
+    )
+
+
+def generate_doe_from_dict(
+    variables: dict,
+    method: Literal["grid", "random", "lhs"] = "lhs",
+    n_samples: int = 100,
+    seed: int | None = None,
+) -> pd.DataFrame:
+    """Generate DOE from a simplified dictionary specification.
+
+    Convenience function for quick DOE generation without creating
+    explicit DesignVariable objects.
+
+    Args:
+        variables: Dictionary mapping variable names to specs:
+            - For continuous: {"name": (low, high)} or {"name": (low, high, "float")}
+            - For discrete: {"name": (low, high, "int")}
+            - For categorical: {"name": ["value1", "value2", ...]}
+        method: Sampling method
+        n_samples: Number of samples
+        seed: Random seed
+
+    Returns:
+        DataFrame with DOE cases
+
+    Examples:
+        >>> doe = generate_doe_from_dict({
+        ...     "array.nx": (4, 16, "int"),
+        ...     "array.ny": (4, 16, "int"),
+        ...     "rf.tx_power_w_per_elem": (0.5, 2.0),
+        ...     "array.geometry": ["rectangular", "triangular"],
+        ... }, n_samples=50)
+    """
+    space = DesignSpace()
+
+    for name, spec in variables.items():
+        if isinstance(spec, list):
+            # Categorical
+            space.add_variable(name, type="categorical", values=spec)
+        elif isinstance(spec, tuple):
+            if len(spec) == 2:
+                # (low, high) -> float
+                space.add_variable(name, type="float", low=spec[0], high=spec[1])
+            elif len(spec) == 3:
+                # (low, high, type)
+                space.add_variable(name, type=spec[2], low=spec[0], high=spec[1])
+            else:
+                raise ValueError(f"Invalid spec for '{name}': {spec}")
+        else:
+            raise ValueError(f"Invalid spec type for '{name}': {type(spec)}")
+
+    return generate_doe(space, method=method, n_samples=n_samples, seed=seed)
+
+
+def augment_doe(
+    existing_doe: pd.DataFrame,
+    design_space: DesignSpace,
+    n_additional: int,
+    method: Literal["random", "lhs"] = "lhs",
+    seed: int | None = None,
+) -> pd.DataFrame:
+    """Add additional samples to an existing DOE.
+
+    Useful for adaptive sampling or expanding a study.
+
+    Args:
+        existing_doe: Existing DOE DataFrame
+        design_space: DesignSpace defining the variables
+        n_additional: Number of additional samples to add
+        method: Sampling method for new samples
+        seed: Random seed
+
+    Returns:
+        Combined DataFrame with original + new cases
+    """
+    # Generate new samples
+    new_doe = generate_doe(
+        design_space,
+        method=method,
+        n_samples=n_additional,
+        seed=seed,
+    )
+
+    # Renumber case IDs to avoid collision
+    max_existing_id = 0
+    for case_id in existing_doe["case_id"]:
+        if case_id.startswith("case_"):
+            try:
+                num = int(case_id.replace("case_", ""))
+                max_existing_id = max(max_existing_id, num)
+            except ValueError:
+                pass
+
+    new_ids = [f"case_{i:05d}" for i in range(max_existing_id + 1, max_existing_id + 1 + n_additional)]
+    new_doe["case_id"] = new_ids
+
+    # Combine
+    return pd.concat([existing_doe, new_doe], ignore_index=True)

phased_array_systems/trades/pareto.py

@@ -0,0 +1,266 @@
+"""Pareto frontier extraction and analysis utilities."""
+
+from typing import Literal
+
+import numpy as np
+import pandas as pd
+
+from phased_array_systems.requirements import RequirementSet
+from phased_array_systems.types import OptimizeDirection
+
+
+def filter_feasible(
+    results: pd.DataFrame,
+    requirements: RequirementSet | None = None,
+    verification_column: str = "verification.passes",
+) -> pd.DataFrame:
+    """Filter results to only feasible (requirement-passing) designs.
+
+    Args:
+        results: DataFrame with evaluation results
+        requirements: Optional RequirementSet to verify against
+        verification_column: Column name for verification status
+
+    Returns:
+        DataFrame containing only feasible designs
+    """
+    if requirements is not None and len(requirements) > 0:
+        # Re-verify against requirements
+        mask = []
+        for _, row in results.iterrows():
+            metrics = row.to_dict()
+            report = requirements.verify(metrics)
+            mask.append(report.passes)
+        return results[mask].copy()
+
+    elif verification_column in results.columns:
+        # Use pre-computed verification
+        return results[results[verification_column] == 1.0].copy()
+
+    else:
+        # No filtering - return all
+        return results.copy()
+
+
+def extract_pareto(
+    results: pd.DataFrame,
+    objectives: list[tuple[str, OptimizeDirection]],
+    include_dominated: bool = False,
+) -> pd.DataFrame:
+    """Extract Pareto-optimal designs from results.
+
+    A design is Pareto-optimal if no other design is better in all objectives.
+
+    Args:
+        results: DataFrame with evaluation results
+        objectives: List of (column_name, direction) tuples where direction
+            is "minimize" or "maximize"
+        include_dominated: If True, include a 'pareto_optimal' column marking
+            Pareto-optimal rows
+
+    Returns:
+        DataFrame containing only Pareto-optimal designs (or all designs
+        with pareto_optimal column if include_dominated=True)
+
+    Examples:
+        >>> pareto = extract_pareto(results, [
+        ...     ("cost_usd", "minimize"),
+        ...     ("eirp_dbw", "maximize"),
+        ... ])
+    """
+    if len(results) == 0:
+        return results.copy()
+
+    # Convert to minimization (negate maximization objectives)
+    obj_matrix = np.zeros((len(results), len(objectives)))
+    for i, (name, direction) in enumerate(objectives):
+        values = results[name].values
+        if direction == "maximize":
+            obj_matrix[:, i] = -values
+        else:
+            obj_matrix[:, i] = values
+
+    # Find Pareto-optimal points
+    is_pareto = np.ones(len(results), dtype=bool)
+
+    for i in range(len(results)):
+        if not is_pareto[i]:
+            continue
+
+        # Check if any other point dominates point i
+        for j in range(len(results)):
+            if i == j or not is_pareto[j]:
+                continue
+
+            # j dominates i if j is <= in all objectives and < in at least one
+            all_leq = np.all(obj_matrix[j] <= obj_matrix[i])
+            any_lt = np.any(obj_matrix[j] < obj_matrix[i])
+
+            if all_leq and any_lt:
+                is_pareto[i] = False
+                break
+
+    if include_dominated:
+        result_df = results.copy()
+        result_df["pareto_optimal"] = is_pareto
+        return result_df
+    else:
+        return results[is_pareto].copy()
+
+
+def rank_pareto(
+    pareto: pd.DataFrame,
+    objectives: list[tuple[str, OptimizeDirection]],
+    weights: list[float] | None = None,
+    method: Literal["weighted_sum", "topsis"] = "weighted_sum",
+) -> pd.DataFrame:
+    """Rank Pareto-optimal designs using weighted objectives.
+
+    Args:
+        pareto: DataFrame with Pareto-optimal designs
+        objectives: List of (column_name, direction) tuples
+        weights: Weights for each objective (default: equal weights)
+        method: Ranking method ("weighted_sum" or "topsis")
+
+    Returns:
+        DataFrame with added 'rank' and 'score' columns, sorted by rank
+    """
+    if len(pareto) == 0:
+        return pareto.copy()
+
+    n_obj = len(objectives)
+    if weights is None:
+        weights = [1.0 / n_obj] * n_obj
+    else:
+        # Normalize weights
+        total = sum(weights)
+        weights = [w / total for w in weights]
+
+    # Extract and normalize objective values
+    obj_matrix = np.zeros((len(pareto), n_obj))
+    for i, (name, direction) in enumerate(objectives):
+        values = pareto[name].values.astype(float)
+        # Normalize to [0, 1]
+        min_val, max_val = values.min(), values.max()
+        if max_val > min_val:
+            normalized = (values - min_val) / (max_val - min_val)
+        else:
+            normalized = np.zeros_like(values)
+
+        # Flip for maximization (higher is better -> lower normalized score)
+        if direction == "maximize":
+            normalized = 1 - normalized
+
+        obj_matrix[:, i] = normalized
+
+    if method == "weighted_sum":
+        # Weighted sum (lower is better)
+        scores = np.sum(obj_matrix * weights, axis=1)
+
+    elif method == "topsis":
+        # TOPSIS method
+        # Ideal point: min of all (already normalized to minimization)
+        ideal = np.zeros(n_obj)
+        # Anti-ideal: max of all
+        anti_ideal = np.ones(n_obj)
+
+        # Distance to ideal and anti-ideal
+        d_ideal = np.sqrt(np.sum(weights * (obj_matrix - ideal) ** 2, axis=1))
+        d_anti = np.sqrt(np.sum(weights * (obj_matrix - anti_ideal) ** 2, axis=1))
+
+        # TOPSIS score (higher is better, so negate for ranking)
+        with np.errstate(divide="ignore", invalid="ignore"):
+            scores = d_ideal / (d_ideal + d_anti)
+            scores = np.nan_to_num(scores, nan=1.0)
+
+    else:
+        raise ValueError(f"Unknown ranking method: {method}")
+
+    # Add scores and rank
+    result_df = pareto.copy()
+    result_df["pareto_score"] = scores
+    result_df["pareto_rank"] = result_df["pareto_score"].rank(method="min").astype(int)
+
+    return result_df.sort_values("pareto_rank")
+
+
+def compute_hypervolume(
+    pareto: pd.DataFrame,
+    objectives: list[tuple[str, OptimizeDirection]],
+    reference_point: list[float] | None = None,
+) -> float:
+    """Compute hypervolume indicator for a Pareto front.
+
+    The hypervolume is the volume of objective space dominated by the
+    Pareto front, bounded by a reference point. Higher is better.
+
+    Args:
+        pareto: DataFrame with Pareto-optimal designs
+        objectives: List of (column_name, direction) tuples
+        reference_point: Reference point in objective space (default: worst point + 10%)
+
+    Returns:
+        Hypervolume value
+
+    Note:
+        For >3 objectives, this uses a simple approximation.
+    """
+    if len(pareto) == 0:
+        return 0.0
+
+    n_obj = len(objectives)
+
+    # Extract objective values (convert to minimization)
+    obj_matrix = np.zeros((len(pareto), n_obj))
+    for i, (name, direction) in enumerate(objectives):
+        values = pareto[name].values.astype(float)
+        if direction == "maximize":
+            obj_matrix[:, i] = -values
+        else:
+            obj_matrix[:, i] = values
+
+    # Set reference point if not provided
+    if reference_point is None:
+        worst = obj_matrix.max(axis=0)
+        reference_point = worst * 1.1 + 0.1  # 10% beyond worst
+
+    ref = np.array(reference_point)
+
+    # For 2D, compute exact hypervolume
+    if n_obj == 2:
+        # Sort by first objective
+        sorted_idx = np.argsort(obj_matrix[:, 0])
+        sorted_obj = obj_matrix[sorted_idx]
+
+        hv = 0.0
+        prev_y = ref[1]
+        for i in range(len(sorted_obj)):
+            x, y = sorted_obj[i]
+            if x < ref[0] and y < ref[1]:
+                hv += (ref[0] - x) * (prev_y - y)
+                prev_y = y
+
+        return hv
+
+    else:
+        # Monte Carlo approximation for higher dimensions
+        n_samples = 10000
+        rng = np.random.default_rng(42)
+
+        # Sample random points in hyperbox
+        samples = np.zeros((n_samples, n_obj))
+        for i in range(n_obj):
+            min_val = obj_matrix[:, i].min()
+            samples[:, i] = rng.uniform(min_val, ref[i], n_samples)
+
+        # Count points dominated by at least one Pareto point
+        dominated = np.zeros(n_samples, dtype=bool)
+        for pareto_point in obj_matrix:
+            is_dominated = np.all(samples >= pareto_point, axis=1)
+            dominated |= is_dominated
+
+        # Estimate hypervolume
+        box_volume = np.prod(ref - obj_matrix.min(axis=0))
+        hv = box_volume * dominated.sum() / n_samples
+
+        return hv

phased_array_systems/trades/runner.py

@@ -0,0 +1,245 @@
+"""Batch evaluation runner for DOE trade studies."""
+
+import time
+import traceback
+from collections.abc import Callable
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from pathlib import Path
+
+import pandas as pd
+
+from phased_array_systems.architecture import Architecture
+from phased_array_systems.evaluate import evaluate_case
+from phased_array_systems.requirements import RequirementSet
+from phased_array_systems.types import Scenario
+
+
+def _evaluate_single_case(
+    case_row: dict,
+    scenario: Scenario,
+    requirements: RequirementSet | None,
+    architecture_builder: Callable[[dict], Architecture],
+) -> dict:
+    """Worker function to evaluate a single case.
+
+    Args:
+        case_row: Dictionary of design variable values
+        scenario: Scenario to evaluate against
+        requirements: Optional requirements for verification
+        architecture_builder: Function to build Architecture from case dict
+
+    Returns:
+        Dictionary with case_id, all design variables, and all metrics
+    """
+    case_id = case_row.get("case_id", "unknown")
+
+    try:
+        # Build architecture from case parameters
+        arch = architecture_builder(case_row)
+
+        # Evaluate
+        metrics = evaluate_case(arch, scenario, requirements, case_id=case_id)
+
+        # Merge case params with metrics
+        result = dict(case_row)
+        result.update(metrics)
+        result["meta.error"] = None
+
+    except Exception as e:
+        # Case-level error handling - don't crash the batch
+        result = dict(case_row)
+        result["meta.error"] = f"{type(e).__name__}: {e}"
+        result["meta.traceback"] = traceback.format_exc()
+        result["meta.runtime_s"] = 0.0
+
+    return result
+
+
+class BatchRunner:
+    """Parallel batch evaluation of DOE cases.
+
+    Evaluates multiple architecture/scenario combinations with
+    case-level error handling, progress reporting, and resume capability.
+
+    Attributes:
+        scenario: Scenario to evaluate against
+        requirements: Optional requirements for verification
+        architecture_builder: Function to build Architecture from case dict
+    """
+
+    def __init__(
+        self,
+        scenario: Scenario,
+        requirements: RequirementSet | None = None,
+        architecture_builder: Callable[[dict], Architecture] | None = None,
+    ):
+        """Initialize the batch runner.
+
+        Args:
+            scenario: Scenario to evaluate
+            requirements: Optional requirements for verification
+            architecture_builder: Function to convert case dict to Architecture.
+                If None, uses default_architecture_builder.
+        """
+        self.scenario = scenario
+        self.requirements = requirements
+        self.architecture_builder = architecture_builder or default_architecture_builder
+
+    def run(
+        self,
+        cases: pd.DataFrame,
+        n_workers: int = 1,
+        cache_path: Path | None = None,
+        progress_callback: Callable[[int, int], None] | None = None,
+    ) -> pd.DataFrame:
+        """Run batch evaluation.
+
+        Args:
+            cases: DataFrame with design variable columns + case_id
+            n_workers: Number of parallel workers (1 = sequential)
+            cache_path: Optional path to save/load partial results
+            progress_callback: Optional callback(completed, total) for progress
+
+        Returns:
+            DataFrame with all input columns + all metric columns
+        """
+        # Load cached results if available
+        completed_ids = set()
+        cached_results = []
+
+        if cache_path is not None and cache_path.exists():
+            try:
+                cached_df = pd.read_parquet(cache_path)
+                completed_ids = set(cached_df["case_id"])
+                cached_results = cached_df.to_dict("records")
+                print(f"Resuming: {len(completed_ids)} cases already completed")
+            except Exception:
+                pass  # Ignore cache errors
+
+        # Filter to uncompleted cases
+        cases_to_run = cases[~cases["case_id"].isin(completed_ids)]
+        total_cases = len(cases)
+        remaining = len(cases_to_run)
+
+        if remaining == 0:
+            print("All cases already completed")
+            return pd.DataFrame(cached_results)
+
+        print(f"Running {remaining} cases ({len(completed_ids)} cached)")
+
+        # Convert to list of dicts for processing
+        case_dicts = cases_to_run.to_dict("records")
+
+        results = list(cached_results)
+        start_time = time.perf_counter()
+
+        if n_workers == 1:
+            # Sequential execution
+            for i, case_row in enumerate(case_dicts):
+                result = _evaluate_single_case(
+                    case_row,
+                    self.scenario,
+                    self.requirements,
+                    self.architecture_builder,
+                )
+                results.append(result)
+
+                if progress_callback:
+                    progress_callback(len(results), total_cases)
+
+                # Save intermediate results
+                if cache_path is not None and (i + 1) % 10 == 0:
+                    self._save_cache(results, cache_path)
+
+        else:
+            # Parallel execution
+            with ProcessPoolExecutor(max_workers=n_workers) as executor:
+                futures = {
+                    executor.submit(
+                        _evaluate_single_case,
+                        case_row,
+                        self.scenario,
+                        self.requirements,
+                        self.architecture_builder,
+                    ): case_row["case_id"]
+                    for case_row in case_dicts
+                }
+
+                for future in as_completed(futures):
+                    result = future.result()
+                    results.append(result)
+
+                    if progress_callback:
+                        progress_callback(len(results), total_cases)
+
+                    # Save intermediate results periodically
+                    if cache_path is not None and len(results) % 10 == 0:
+                        self._save_cache(results, cache_path)
+
+        elapsed = time.perf_counter() - start_time
+        print(f"Completed {remaining} cases in {elapsed:.1f}s ({elapsed/remaining:.3f}s/case)")
+
+        # Final save
+        if cache_path is not None:
+            self._save_cache(results, cache_path)
+
+        # Build result DataFrame
+        result_df = pd.DataFrame(results)
+
+        # Ensure consistent column order
+        cols = list(cases.columns) + [
+            c for c in result_df.columns if c not in cases.columns
+        ]
+        result_df = result_df[[c for c in cols if c in result_df.columns]]
+
+        return result_df
+
+    def _save_cache(self, results: list[dict], cache_path: Path) -> None:
+        """Save results to cache file."""
+        try:
+            df = pd.DataFrame(results)
+            cache_path.parent.mkdir(parents=True, exist_ok=True)
+            df.to_parquet(cache_path)
+        except Exception as e:
+            print(f"Warning: Failed to save cache: {e}")
+
+
+def default_architecture_builder(case_row: dict) -> Architecture:
+    """Default function to build Architecture from DOE case dictionary.
+
+    Expects keys like "array.nx", "rf.tx_power_w_per_elem", etc.
+
+    Args:
+        case_row: Dictionary with dot-notation keys
+
+    Returns:
+        Architecture object
+    """
+    # Filter out non-architecture keys
+    arch_keys = {k: v for k, v in case_row.items()
+                 if k.startswith(("array.", "rf.", "cost.")) or k == "name"}
+
+    return Architecture.from_flat(arch_keys)
+
+
+def run_batch_simple(
+    cases: pd.DataFrame,
+    scenario: Scenario,
+    requirements: RequirementSet | None = None,
+    n_workers: int = 1,
+) -> pd.DataFrame:
+    """Simple batch run without caching or progress.
+
+    Convenience function for basic batch evaluation.
+
+    Args:
+        cases: DataFrame with design variable columns
+        scenario: Scenario to evaluate
+        requirements: Optional requirements
+        n_workers: Number of parallel workers
+
+    Returns:
+        Results DataFrame
+    """
+    runner = BatchRunner(scenario, requirements)
+    return runner.run(cases, n_workers=n_workers)