pcb-analysis 0.6.0__py3-none-any.whl

electrical/__init__.py

@@ -0,0 +1,10 @@
+"""Electrical analysis algorithms.
+
+The second package level names the numerical method and its acceleration
+strategy.  Thermal and other physics can therefore be added beside this
+package without mixing their discretisations or solver policies.
+"""
+
+from . import dice_peec, matrix_free_mpir_fem
+
+__all__ = ["dice_peec", "matrix_free_mpir_fem"]

electrical/dice_peec/__init__.py

@@ -0,0 +1,117 @@
+"""DICE-PEEC acceleration for single- and multilayer electrical PCB analysis.
+
+There are two solvers here and they answer different questions.
+
+``cuda_pypeec`` runs PyPEEC's own three-dimensional voxel solve on CUDA.  It is
+the high-fidelity path: PyPEEC owns the physics, this owns the device policy,
+and ``pypeec_memory`` predicts what a model will cost before it is attempted --
+which matters once a model spans a board's height rather than one copper layer.
+
+``sheet_peec`` solves the same physics on a mesh built for what a PCB actually
+is: a few thin sheets at known heights.  Its inductance operator is a
+two-dimensional transform per layer pair instead of a three-dimensional one
+over the board's height, which is a large saving on a board of few layers.  It
+is exact in the sense that matters -- at zero frequency it reproduces a
+resistor network to machine precision, and above it, the transform path matches
+a dense assembly of the same operator.
+
+Separately, ``multilayer_peec`` holds a scalar interaction proxy for ranking
+many candidate shapes cheaply.  It does not solve for current or potential and
+is not a substitute for either solver above.
+"""
+
+from .layout_ops import (
+    CandidateEdit,
+    CompiledCandidate,
+    SegmentOp,
+    ViaOp,
+    compile_candidate,
+    compile_many,
+)
+from .multilayer_peec import (
+    FFTInteraction25D,
+    MultilayerDeltaScorer,
+    SparseDeltaML,
+    ViaSet,
+    ViaSpec,
+)
+from .plane_opt_contract import (
+    PLANE_OPT_PROBLEM_SCHEMA,
+    PLANE_OPT_RESULT_SCHEMA,
+    PlaneOptProblem,
+    PlaneOptSolveResult,
+    build_plane_opt_sheet_inputs,
+    solve_plane_opt_problem,
+)
+from .sheet_inductance import (
+    CellGeometry,
+    build_kernel,
+    mutual_partial_inductance,
+    self_partial_inductance,
+)
+from .sheet_cuda import (
+    CudaSheetSolveError,
+    CudaSheetTelemetry,
+    CudaSheetUnavailableError,
+    solve_sheet_case_cuda,
+)
+from .sheet_operator import SheetInductanceOperator, SheetLayer, SheetStackup
+from .sheet_results import (
+    SheetFields,
+    cell_current_density,
+    cell_current_density_phasor,
+    sheet_fields,
+    vertical_currents,
+)
+from .sheet_peec import (
+    SheetMesh,
+    SheetSolution,
+    Terminal,
+    ViaBranch,
+    solve_sheet_case,
+    via_resistance,
+)
+from .stackup import Stackup
+
+__all__ = [
+    "CandidateEdit",
+    "CellGeometry",
+    "CompiledCandidate",
+    "CudaSheetSolveError",
+    "CudaSheetTelemetry",
+    "CudaSheetUnavailableError",
+    "FFTInteraction25D",
+    "MultilayerDeltaScorer",
+    "PLANE_OPT_PROBLEM_SCHEMA",
+    "PLANE_OPT_RESULT_SCHEMA",
+    "PlaneOptProblem",
+    "PlaneOptSolveResult",
+    "SegmentOp",
+    "SheetFields",
+    "SheetInductanceOperator",
+    "SheetLayer",
+    "SheetMesh",
+    "SheetSolution",
+    "SheetStackup",
+    "SparseDeltaML",
+    "Stackup",
+    "Terminal",
+    "ViaBranch",
+    "ViaOp",
+    "ViaSet",
+    "ViaSpec",
+    "build_kernel",
+    "cell_current_density",
+    "cell_current_density_phasor",
+    "compile_candidate",
+    "compile_many",
+    "build_plane_opt_sheet_inputs",
+    "mutual_partial_inductance",
+    "self_partial_inductance",
+    "sheet_fields",
+    "solve_sheet_case",
+    "solve_sheet_case_cuda",
+    "solve_plane_opt_problem",
+    "via_resistance",
+    "vertical_currents",
+]

electrical/dice_peec/_bench_utils.py

@@ -0,0 +1,70 @@
+"""Shared DICE-PEEC benchmark utility functions."""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+
+def relative_difference(reference: float, observed: float) -> float:
+    reference = float(reference)
+    observed = float(observed)
+    if not math.isfinite(reference) or not math.isfinite(observed):
+        return math.inf
+    scale = max(abs(reference), 1e-30)
+    return abs(observed - reference) / scale
+
+
+def ranking_consistent(
+    cpu: dict[str, dict[str, Any]],
+    cuda: dict[str, dict[str, Any]],
+    metric: str,
+    *,
+    separation: float = 0.01,
+) -> bool:
+    """Check every meaningfully separated CPU pair retains its order."""
+    if not math.isfinite(separation) or separation < 0.0:
+        raise ValueError("separation must be finite and non-negative")
+    if set(cpu) != set(cuda):
+        return False
+    names = sorted(cpu)
+    for left_index, left in enumerate(names):
+        for right in names[left_index + 1 :]:
+            cpu_left = float(cpu[left][metric])
+            cpu_right = float(cpu[right][metric])
+            cuda_left = float(cuda[left][metric])
+            cuda_right = float(cuda[right][metric])
+            if not all(
+                math.isfinite(value)
+                for value in (cpu_left, cpu_right, cuda_left, cuda_right)
+            ):
+                return False
+            scale = max(abs(cpu_left), abs(cpu_right), 1e-30)
+            if abs(cpu_left - cpu_right) / scale <= separation:
+                continue
+            cpu_delta = cpu_left - cpu_right
+            cuda_delta = cuda_left - cuda_right
+            if cuda_delta == 0.0 or (cpu_delta < 0.0) != (cuda_delta < 0.0):
+                return False
+    return True
+
+
+def _select_candidate(
+    data: dict[str, Any], candidate_name: str | None
+) -> dict[str, Any]:
+    if "mask_runs" in data:
+        return data
+    if "candidate" in data:
+        return data["candidate"]
+    candidates = list(data.get("candidates", []))
+    if candidate_name is not None:
+        for candidate in candidates:
+            if candidate.get("name") == candidate_name:
+                return candidate
+        raise ValueError(f"candidate not found: {candidate_name}")
+    valid = [candidate for candidate in candidates if candidate.get("valid")]
+    if valid:
+        return valid[0]
+    if candidates:
+        return candidates[0]
+    raise ValueError("candidate file does not contain mask_runs or candidates")

electrical/dice_peec/backends.py

@@ -0,0 +1,62 @@
+"""DICE-PEEC execution backend contracts and a deterministic CPU simulator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from .controller import (
+    ExecutionPlan,
+    ExecutionReport,
+    HardwareTelemetry,
+    ProblemProfile,
+)
+
+
+class CalibrationBackend(Protocol):
+    def probe(self) -> HardwareTelemetry: ...
+
+    def execute(self, plan: ExecutionPlan, problem: ProblemProfile) -> ExecutionReport: ...
+
+
+@dataclass
+class SyntheticBackend:
+    """Predictable backend for controller tests without a CUDA device."""
+
+    total_bytes: int
+    platform: str = "windows"
+    free_fraction: float = 0.90
+    memory_multiplier: float = 1.08
+    force_oom: bool = False
+    force_stagnation: bool = False
+
+    def probe(self) -> HardwareTelemetry:
+        return HardwareTelemetry(
+            total_bytes=self.total_bytes,
+            free_bytes=int(self.total_bytes * self.free_fraction),
+            platform=self.platform,
+            backend="synthetic",
+        )
+
+    def execute(self, plan: ExecutionPlan, problem: ProblemProfile) -> ExecutionReport:
+        peak = int(plan.estimated_bytes * self.memory_multiplier)
+        oom = self.force_oom or peak > self.probe().free_bytes
+        work = (
+            problem.nx * problem.ny * max(problem.layers, 1)
+            / max(plan.tile_size**2 * plan.candidate_batch, 1)
+        )
+        elapsed = 0.08 * work * max(1, 8 / max(plan.kernel_batch, 1))
+        if plan.host_offload:
+            elapsed *= 1.8
+        iterations = 0 if plan.solver == "none" else (34 if plan.solver == "gmres" else 52)
+        stagnated = self.force_stagnation and plan.solver.startswith("bicgstab")
+        return ExecutionReport(
+            peak_bytes=peak,
+            elapsed_ms=elapsed,
+            iterations=iterations,
+            relative_residual=2e-3 if stagnated else plan.tolerance * 0.5,
+            converged=not (oom or stagnated),
+            oom=oom,
+            stagnated=stagnated,
+            precision_gap=0.0,
+        )

electrical/dice_peec/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line entry points for DICE-PEEC.
+
+Scripts under ``examples/`` are repository material and are not installed, so
+anything reachable from ``[project.scripts]`` lives here instead.
+"""

electrical/dice_peec/cli/calibrate.py

@@ -0,0 +1,64 @@
+"""Measure this machine's CUDA and CuPy throughput for the DICE controller.
+
+Installed as ``pcb-analysis-calibrate``.  CuPy is an optional dependency,
+so importing it is left to call time: the package must import on a host
+with no GPU.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+
+from ..controller import DynamicController, FidelityStage, ProblemProfile
+from ..cupy_calibrator import CuPyCalibrationBackend
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--grid", type=int, default=1024)
+    parser.add_argument("--layers", type=int, default=4)
+    parser.add_argument("--unknowns", type=int, default=2_000_000)
+    parser.add_argument("--candidates", type=int, default=1000)
+    parser.add_argument("--changed-cells", type=int, default=32)
+    parser.add_argument("--repeats", type=int, default=5)
+    args = parser.parse_args()
+
+    backend = CuPyCalibrationBackend(repeats=args.repeats)
+    telemetry = backend.probe()
+    problem = ProblemProfile(
+        nx=args.grid, ny=args.grid, layers=args.layers,
+        unknowns=args.unknowns, candidate_count=args.candidates,
+        changed_cells_mean=args.changed_cells,
+    )
+    controller = DynamicController()
+    output = {
+        "telemetry": asdict(telemetry),
+        "stages": [],
+    }
+    for stage in (
+        FidelityStage.NEAR_COARSE,
+        FidelityStage.NEAR_FINE,
+        FidelityStage.CORRECTION,
+        FidelityStage.REFINED,
+    ):
+        plan = controller.make_plan(problem, telemetry, stage)
+        report = backend.execute(plan, problem)
+        if report.oom:
+            plan = controller.make_plan(
+                problem, backend.probe(), stage,
+                previous_report=report, previous_plan=plan,
+            )
+            report = backend.execute(plan, problem)
+        controller.observe(plan, report)
+        output["stages"].append({
+            "stage": stage.name,
+            "plan": asdict(plan),
+            "fft_calibration": asdict(report),
+        })
+    print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()