"""Prediction result: the full Maxwell capacitance matrix (fF, ground first) with checks, timing and provenance."""
from __future__ import annotations
from dataclasses import asdict, dataclass, field
import numpy as np
CONVENTION = "Maxwell matrix: diagonal = self, off-diagonal = -mutual (negative); row/column 0 = ground (G)"
[docs]
def physical_checks(C) -> dict:
"""Symmetry, Maxwell signs, closure (row sums of the signal rows >= 0) and positive definiteness of the signal block."""
C = np.asarray(C, float)
n = len(C)
off = ~np.eye(n, dtype=bool)
scale = max(1.0, float(np.abs(C).max()))
sym = float(np.max(np.abs(C - C.T)))
rows = C.sum(1)[1:]
eig = float(np.linalg.eigvalsh(C[1:, 1:]).min()) if n > 1 else None
chk = {
"symmetric_max_abs": sym,
"symmetric": sym <= 1e-6 * scale,
"diagonal_positive": bool(np.all(np.diag(C) > 0)),
"offdiag_all_negative": bool(np.all(C[off] < 0)),
"closure_min_row_sum": float(rows.min()) if n > 1 else None,
"closure": bool(n == 1 or rows.min() >= -1e-9 * scale),
"signal_block_min_eig": eig,
"positive_definite": eig is None or eig > 0,
}
chk["passed"] = all(
chk[k] for k in ("symmetric", "diagonal_positive", "offdiag_all_negative", "closure", "positive_definite")
)
return chk
[docs]
def physical_warning(chk: dict) -> str | None:
"""Readable warning when a check of ``physical_checks`` fails (None when the matrix passes)."""
if chk["passed"]:
return None
bad = [
k.replace("_", " ")
for k in ("symmetric", "diagonal_positive", "offdiag_all_negative", "closure", "positive_definite")
if not chk[k]
]
return (
f"physical check failed: {', '.join(bad)} (smallest eigenvalue of the signal block {chk['signal_block_min_eig']:.4g} fF, "
f"smallest signal row sum {chk['closure_min_row_sum']:.4g} fF). This matrix is not physical: do not use it. A model that "
"solves the physics (QCap) is the safer choice, especially outside the trained component families."
)
[docs]
@dataclass
class CapacitanceResult:
names: list[str]
matrix_fF: np.ndarray
model: str
title: str = ""
prior_version: str | None = None
prior_stack: dict | None = None
weights_sha256: list[str] = field(default_factory=list)
learned_prior_sha256: str | None = None
timing_s: dict = field(default_factory=dict)
threads: int = 2
machine: str = ""
checks: dict = field(default_factory=dict)
warnings: list[str] = field(default_factory=list)
substrate: dict = field(default_factory=dict)
ground_detection: dict | None = (
None # pieces and roles when ground and conductors share a layer (see inspect_layout)
)
source: str = ""
layout_hash: str = ""
cached: bool = False
package: str = ""
units: str = "fF"
convention: str = CONVENTION
def __post_init__(self):
self.matrix_fF = np.asarray(self.matrix_fF, float)
if not self.checks:
self.checks = physical_checks(self.matrix_fF)
@property
def n_conductors(self) -> int:
return len(self.names)
[docs]
def to_dataframe(self):
import pandas as pd
return pd.DataFrame(self.matrix_fF, index=list(self.names), columns=list(self.names))
[docs]
def to_dict(self) -> dict:
d = asdict(self)
d["matrix_fF"] = self.matrix_fF.tolist()
return d
[docs]
def to_sim_results(self, names: dict | None = None) -> dict:
"""The SQuADDS_DB ``sim_results`` shape: pairwise positive magnitudes ``<a>_to_<b>`` (self terms on the diagonal,
ground named ``ground``), the signed ``maxwell_matrix`` as ``C_<a>_<b>`` (ground ``G``) and ``units``. ``names`` renames
conductors (e.g. ``{"C1": "north", "C2": "south"}``)."""
names = names or {}
lab = [names.get(n, n) for n in self.names]
C = self.matrix_fF
sig = list(range(1, len(lab)))
out: dict = {}
for a in sig:
out[f"{lab[a]}_to_{lab[a]}"] = float(C[a, a])
for b in sig:
if b > a:
out[f"{lab[a]}_to_{lab[b]}"] = float(abs(C[a, b]))
out[f"{lab[a]}_to_ground"] = float(abs(C[a, 0]))
out["ground_to_ground"] = float(C[0, 0])
out["maxwell_matrix"] = {
f"C_{lab[i]}_{lab[j]}": float(C[i, j]) for i in range(len(lab)) for j in range(len(lab))
}
out["units"] = "fF"
return out
def __repr__(self) -> str:
return (
f"CapacitanceResult({self.model}, N={self.n_conductors}, names={self.names}, "
f"total {self.timing_s.get('total_s', float('nan')):.3g} s, checks {'passed' if self.checks.get('passed') else 'FAILED'})"
)