pcb-analysis 0.9.2__tar.gz → 0.9.3__tar.gz

{pcb_analysis-0.9.2/src/pcb_analysis.egg-info → pcb_analysis-0.9.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pcb-analysis
-Version: 0.9.2
+Version: 0.9.3
 Summary: CUDA-accelerated PEEC, matrix-free FEM, and radiated-emission evaluation for electrical, thermal, and EMC PCB analysis
 Author-email: Hiroyuki Yamada <H44bcda@gmail.com>
 License: MIT License

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pcb-analysis"
-version = "0.9.2"
+version = "0.9.3"
 description = "CUDA-accelerated PEEC, matrix-free FEM, and radiated-emission evaluation for electrical, thermal, and EMC PCB analysis"
 readme = "README.md"
 license = { file = "LICENSE" }

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/src/electrical/matrix_free_mpir_fem/__init__.py

@@ -17,7 +17,7 @@ from .pcb import (
     VoltageTerminal,
     solve_pcb_dc,
 )
-from .ports import DCPortBasis, PortSet, dc_port_basis
+from .ports import DCPortBasis, PortSet, dc_port_basis, port_basis_workers
 from .frequency_domain import (
     EPSILON_0_F_PER_M,
     MU_0_H_PER_M,
@@ -80,6 +80,7 @@ __all__ = [
     "refined_grid",
     "cuda_available",
     "dc_port_basis",
+    "port_basis_workers",
     "graded_edges",
     "make_complex64_runtime",
     "make_float32_runtime",

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/src/electrical/matrix_free_mpir_fem/ports.py

@@ -28,10 +28,18 @@ The reduction is evaluated by diagonalising ``C`` restricted to the
 non-reference ports: ``C_rr = Σ_m λ_m u_m u_mᵀ`` gives ``<P_e> = Σ_m λ_m
 P_e(ψ_m)`` with ``ψ_m = Σ_k u_mk φ_k``, so the loss of every element and via
 comes from the exact element quadratic forms of :class:`.pcb.MatrixFreePCBOperator`.
+
+The ``n - 1`` unit solves are independent and share one read-only operator,
+so :func:`dc_port_basis` can run them on a thread pool (``workers=``, or
+``PCB_PORT_BASIS_WORKERS``).  Threads multiply with the OpenMP team of the
+native kernels (``PCB_NATIVE_THREADS``); their product is the core budget.
+A CUDA runtime solves serially, since its stream is shared.
 """
 
 from __future__ import annotations
 
+import os
+from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass
 from typing import Sequence
 
@@ -49,6 +57,15 @@ from .runtime import LowPrecisionRuntime, RuntimeBackend
 from .solver import MPIRConfig, MPIRResult, solve_mpir
 
 
+def port_basis_workers() -> int:
+    """Threads for the unit solves of a basis; ``PCB_PORT_BASIS_WORKERS`` overrides (default 1)."""
+
+    value = os.environ.get("PCB_PORT_BASIS_WORKERS")
+    if value:
+        return max(1, int(value))
+    return 1
+
+
 @dataclass(frozen=True)
 class PortSet:
     """The pads of one conductor role, one node set per port.
@@ -111,6 +128,7 @@ class DCPortBasis:
     port ``k`` is held at 1 V and every other port at 0 V.
     ``unit_current_potential_v[m]`` is the potential field (``mesh.node_shape``)
     for 1 A into port ``ports.driven[m]`` and out of the reference port.
+    ``workers`` is the number of threads the unit solves actually ran on.
     """
 
     mesh: LayeredPCBMesh
@@ -120,6 +138,7 @@ class DCPortBasis:
     unit_voltage_potential_v: np.ndarray
     unit_current_potential_v: np.ndarray
     solves: tuple[MPIRResult, ...]
+    workers: int = 1
 
     @property
     def converged(self) -> bool:
@@ -228,13 +247,17 @@ def dc_port_basis(
     native: bool | None = None,
     native_threads: int | None = None,
     initial: DCPortBasis | None = None,
+    workers: int | None = None,
 ) -> DCPortBasis:
     """Measure the N-port of ``mesh`` at ``ports`` with ``n - 1`` unit voltage solves.
 
     One operator with every port node fixed serves all solves.  ``initial``
     warm-starts each unit solve from the same port's field of an earlier
     basis (for example the previous iterate of a coupled analysis on the
-    same mesh with other conductivities).
+    same mesh with other conductivities).  ``workers`` threads run the unit
+    solves concurrently (``None``: :func:`port_basis_workers`); the operator
+    is read-only once built and every solve owns its vectors, so the result
+    does not depend on the thread count.  A CUDA runtime solves serially.
     """
 
     operator = MatrixFreePCBOperator(
@@ -256,8 +279,8 @@ def dc_port_basis(
     n = ports.count
     conductance = np.zeros((n, n), dtype=np.float64)
     unit_voltage = np.zeros((n - 1,) + mesh.node_shape, dtype=np.float64)
-    solves = []
-    for column, port in enumerate(ports.driven):
+
+    def unit_solve(column: int, port: int) -> tuple[np.ndarray, np.ndarray, MPIRResult]:
         excitation = np.zeros(n)
         excitation[port] = 1.0
         terminals = ports.voltage_terminals(excitation)
@@ -268,8 +291,22 @@ def dc_port_basis(
             guess = np.where(operator.free_nodes.reshape(-1), previous, guess)
         result = solve_mpir(operator, rhs, config=config, initial_guess=guess)
         potential = result.solution.reshape(mesh.node_shape)
+        return potential, operator.terminal_currents(potential, terminals), result
+
+    threads = port_basis_workers() if workers is None else max(1, int(workers))
+    threads = min(threads, n - 1)
+    if getattr(operator.runtime, "is_cuda", False):
+        threads = 1
+    if threads > 1:
+        with ThreadPoolExecutor(max_workers=threads, thread_name_prefix="port-basis") as pool:
+            outcomes = list(pool.map(unit_solve, range(n - 1), ports.driven))
+    else:
+        outcomes = [unit_solve(column, port) for column, port in enumerate(ports.driven)]
+    solves = []
+    for column, port in enumerate(ports.driven):
+        potential, currents, result = outcomes[column]
         unit_voltage[column] = potential
-        conductance[:, port] = operator.terminal_currents(potential, terminals)
+        conductance[:, port] = currents
         solves.append(result)
     # The driven block is what the solves measured; it is symmetrised against
     # solver round-off.  The reference row and column follow from KCL exactly
@@ -295,4 +332,5 @@ def dc_port_basis(
         unit_voltage_potential_v=unit_voltage,
         unit_current_potential_v=unit_current,
         solves=tuple(solves),
+        workers=threads,
     )

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/src/electrical/sheet_peec/current_field_contract.py

@@ -518,7 +518,7 @@ def solve_current_field_problem(
         "tolerance": float(settings.get("relative_tolerance", 1e-9)),
         "max_iterations": int(settings.get("maximum_iterations", 200)),
         "restart": int(settings.get("restart", 120)),
-        "preconditioner": str(settings.get("preconditioner", "near")),
+        "preconditioner": str(settings.get("preconditioner", "auto")),
     }
     if execution_backend == "cuda":
         from .sheet_cuda import solve_sheet_case_cuda

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/src/electrical/sheet_peec/sheet_peec.py

@@ -466,7 +466,7 @@ def solve_sheet_case(
     tolerance: float = 1e-10,
     max_iterations: int = 400,
     restart: int = 60,
-    preconditioner: str = "near",
+    preconditioner: str = "auto",
 ) -> SheetSolution:
     """Solve one excitation of the mesh.
 
@@ -477,7 +477,11 @@ def solve_sheet_case(
     it, ``Z`` couples every branch to every other and is applied through the
     operator's transforms, so the reduction is carried out by a Krylov method.
 
-    ``preconditioner="near"`` (default) factors the saddle-point matrix with
+    ``preconditioner="auto"`` (default) picks ``near`` below :data:`AUTO_BLOCK_FROM_UNKNOWNS`
+    saddle-point unknowns and ``block`` above.  ``preconditioner="block"`` keeps the near-field impedance but factors it
+    on its own and approximates the Schur complement by the diagonal
+    variant's nodal admittance: block elimination at a fraction of the
+    saddle LU's memory.  ``preconditioner="near"`` factors the saddle-point matrix with
     ``Z`` replaced by ``R + j omega L_near``, the exact partial inductance of
     each branch with itself and its neighbours within the operator's
     preconditioner radius (``operator.near_inductance(mesh)``), by sparse LU;
@@ -485,8 +489,8 @@ def solve_sheet_case(
     through a Schur complement but leaves every mutual term to the Krylov
     iterations.
     """
-    if preconditioner not in ("near", "diagonal"):
-        raise ValueError("preconditioner must be 'near' or 'diagonal'")
+    if preconditioner not in ("auto", "near", "block", "diagonal"):
+        raise ValueError("preconditioner must be 'auto', 'near', 'block' or 'diagonal'")
     if operator.shape != mesh.shape:
         raise ValueError("the operator and the mesh must share a shape")
     if len(operator.stackup) != len(mesh.stackup):
@@ -629,6 +633,8 @@ def solve_sheet_case(
             [impedance(currents) - reduced @ voltages, reduced.T @ currents]
         )
 
+    if preconditioner == "auto":
+        preconditioner = choose_preconditioner(size)
     precondition = _build_preconditioner(
         mesh, operator, preconditioner, omega, resistance, active_branches, reduced, branches
     )
@@ -686,6 +692,21 @@ def _near_impedance(
     return (sp.diags(resistance[active_branches]) + 1j * omega * near).tocsr()
 
 
+# Above this many saddle-point unknowns (branches + nodes) the whole-matrix LU
+# of the near preconditioner costs more memory than the block elimination
+# saves in iterations: on a 33 x 30 mm two-layer plane at 800 kHz the near
+# variant needed 2.2 GB and 27 s at 64k branches where block needed 0.5 GB
+# and 21 s, while at 20k branches near was faster (2.1 s against 4.0 s) at
+# 0.3 GB (docs/SHEET_PRECONDITIONER_RESULTS.json).
+AUTO_BLOCK_FROM_UNKNOWNS = 60_000
+
+
+def choose_preconditioner(unknowns: int) -> str:
+    """``near`` for a small saddle-point system, ``block`` for a large one."""
+
+    return "block" if unknowns >= AUTO_BLOCK_FROM_UNKNOWNS else "near"
+
+
 def _build_preconditioner(
     mesh: SheetMesh,
     operator: Any,
@@ -703,6 +724,34 @@ def _build_preconditioner(
         saddle = sp.bmat([[impedance, -reduced], [reduced.T, None]], format="csc")
         factored = spla.splu(saddle)
         return factored.solve
+    if kind == "block" and hasattr(operator, "near_inductance"):
+        # The same near-field impedance, applied by block elimination instead
+        # of one LU of the whole saddle-point matrix.  Z_near is factored on
+        # its own (a local stencil, so the fill stays small), and the Schur
+        # complement A^T Z_near^-1 A, which is dense, is approximated by
+        # A^T diag(Z)^-1 A, the nodal admittance of the diagonal variant.
+        # The saddle LU needs about 13x the memory of these two factors and
+        # is what runs a board at the acceptance grid out of memory.
+        impedance = _near_impedance(mesh, operator, omega, resistance, active_branches).tocsc()
+        factored_z = spla.splu(impedance, permc_spec="MMD_AT_PLUS_A")
+        full_diagonal = resistance + 1j * omega * np.concatenate(
+            [_inline_self_inductance(mesh, operator), _vertical_self_inductance(mesh, operator)]
+        )
+        diagonal = full_diagonal[active_branches]
+        schur = (reduced.T @ sp.diags(1.0 / diagonal) @ reduced).tocsc()
+        factored_s = spla.splu(schur, permc_spec="MMD_AT_PLUS_A")
+
+        def precondition_block(vector: np.ndarray) -> np.ndarray:
+            rhs_current = vector[:branches]
+            rhs_node = vector[branches:]
+            # [[Z, -A], [A^T, 0]] [x; y] = [r1; r2]:
+            # x = Z^-1 (r1 + A y),  A^T Z^-1 A y = r2 - A^T Z^-1 r1.
+            z = factored_z.solve(rhs_current)
+            node = factored_s.solve(rhs_node - reduced.T @ z)
+            current = factored_z.solve(rhs_current + reduced @ node)
+            return np.concatenate([current, node])
+
+        return precondition_block
     # The same system with Z replaced by its diagonal, which is exactly
     # solvable: its Schur complement is the sparse nodal admittance matrix,
     # factored once and reused for every iteration.

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/src/multiphysics/staggered_coupling/circuit_coupled.py

@@ -360,8 +360,14 @@ def run_circuit_coupled(
     device_id: int = 0,
     native: bool | None = None,
     native_threads: int | None = None,
+    port_basis_workers: int | None = None,
 ) -> CircuitCoupledResult:
-    """Iterate N-port, circuit and thermal solves to a self-consistent ρ(T) state."""
+    """Iterate N-port, circuit and thermal solves to a self-consistent ρ(T) state.
+
+    ``port_basis_workers`` threads run the unit solves of every N-port basis
+    concurrently (see :func:`electrical.matrix_free_mpir_fem.dc_port_basis`);
+    ``None`` reads ``PCB_PORT_BASIS_WORKERS``.
+    """
 
     config = config or CouplingConfig()
     fixed_point = TemperatureFixedPoint(scenario, config)
@@ -393,6 +399,7 @@ def run_circuit_coupled(
                 native=native,
                 native_threads=native_threads,
                 initial=bases[conductor.name],
+                workers=port_basis_workers,
             )
             bases[conductor.name] = basis
             heated[conductor.name] = (mesh, vias)

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3/src/pcb_analysis.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pcb-analysis
-Version: 0.9.2
+Version: 0.9.3
 Summary: CUDA-accelerated PEEC, matrix-free FEM, and radiated-emission evaluation for electrical, thermal, and EMC PCB analysis
 Author-email: Hiroyuki Yamada <H44bcda@gmail.com>
 License: MIT License

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/tests/test_dc_ports.py

@@ -227,3 +227,27 @@ def test_invalid_ports_and_correlations_are_rejected() -> None:
         basis.mean_loss_w(-np.array([[2.0, -1.0, -1.0], [-1.0, 2.0, -1.0], [-1.0, -1.0, 2.0]]))
     with pytest.raises(ValueError, match="share the ports"):
         dc_port_basis(mesh, PortSet(pads=ports.pads, reference=0), vias=vias, initial=basis)
+
+
+def test_threaded_unit_solves_give_the_serial_basis(monkeypatch: pytest.MonkeyPatch) -> None:
+    mesh, ports, vias = _three_port_board()
+    serial = dc_port_basis(mesh, ports, vias=vias, config=TIGHT, workers=1)
+    threaded = dc_port_basis(mesh, ports, vias=vias, config=TIGHT, workers=4)
+    assert serial.workers == 1
+    assert threaded.workers == 2  # capped at n - 1 unit solves
+    assert threaded.converged
+    np.testing.assert_array_equal(threaded.conductance_s, serial.conductance_s)
+    np.testing.assert_array_equal(threaded.unit_voltage_potential_v, serial.unit_voltage_potential_v)
+    np.testing.assert_array_equal(threaded.unit_current_potential_v, serial.unit_current_potential_v)
+    assert [r.inner_iterations for r in threaded.solves] == [r.inner_iterations for r in serial.solves]
+
+    # The default comes from the environment; the warm start works on the pool too.
+    monkeypatch.setenv("PCB_PORT_BASIS_WORKERS", "3")
+    from electrical.matrix_free_mpir_fem import port_basis_workers
+
+    assert port_basis_workers() == 3
+    warm = dc_port_basis(mesh, ports, vias=vias, config=TIGHT, initial=serial)
+    assert warm.workers == 2
+    np.testing.assert_allclose(warm.conductance_s, serial.conductance_s, rtol=1.0e-9)
+    monkeypatch.delenv("PCB_PORT_BASIS_WORKERS")
+    assert port_basis_workers() == 1

{pcb_analysis-0.9.2 → pcb_analysis-0.9.3}/tests/test_sheet_peec.py

@@ -239,6 +239,37 @@ class AlternatingCurrentTests(unittest.TestCase):
         for smaller, larger in zip(departures, departures[1:]):
             self.assertAlmostEqual(larger / smaller, 10.0, places=3)
 
+    def test_the_block_preconditioner_reaches_the_near_preconditioner_solution(self):
+        # Block elimination with Z_near factored alone and the Schur complement
+        # approximated by the diagonal variant's nodal admittance: the same
+        # fixed point as the saddle LU, at a fraction of its memory.
+        near = solve_sheet_case(
+            self.mesh, self.operator, self.terminals, frequency_hz=3e5, preconditioner="near"
+        )
+        block = solve_sheet_case(
+            self.mesh, self.operator, self.terminals, frequency_hz=3e5, preconditioner="block"
+        )
+        self.assertTrue(near.converged and block.converged)
+        scale = float(np.abs(near.node_voltage).max())
+        self.assertLess(float(np.abs(block.node_voltage - near.node_voltage).max()) / scale, 1e-7)
+        self.assertLess(
+            float(np.abs(block.branch_current - near.branch_current).max())
+            / float(np.abs(near.branch_current).max()),
+            1e-7,
+        )
+        self.assertLessEqual(block.iterations, 10 * max(near.iterations, 1))
+        with self.assertRaises(ValueError):
+            solve_sheet_case(self.mesh, self.operator, self.terminals, frequency_hz=3e5, preconditioner="exact")
+        # auto: the small fixture takes the near path and reproduces it exactly.
+        auto = solve_sheet_case(
+            self.mesh, self.operator, self.terminals, frequency_hz=3e5, preconditioner="auto"
+        )
+        self.assertEqual(auto.iterations, near.iterations)
+        np.testing.assert_allclose(auto.node_voltage, near.node_voltage, rtol=0.0, atol=1e-12 * scale)
+        from electrical.sheet_peec.sheet_peec import AUTO_BLOCK_FROM_UNKNOWNS, choose_preconditioner
+        self.assertEqual(choose_preconditioner(AUTO_BLOCK_FROM_UNKNOWNS - 1), "near")
+        self.assertEqual(choose_preconditioner(AUTO_BLOCK_FROM_UNKNOWNS), "block")
+
     def test_the_two_span_definitions_are_named(self):
         direct = solve_sheet_case(
             self.mesh, self.operator, self.terminals, frequency_hz=0.0