Fix the macOS crash at import: defer config.py annotations

First real run on a Mac died before the dialog could open:

    config.py line 15: CELL_UM_OVERRIDE: float | None = None
    TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'

KiCad macOS bundles Python 3.9, where PEP 604 unions in annotations
are evaluated at import time unless deferred - config.py was the one
annotated module without the __future__ import (errors.py has no
annotations, __init__.py is empty).

A new tripwire test walks every shipped module with ast and fails if
a file uses annotations without deferring them, so the next module
added (progress.py was born only last week) cannot regress this
silently while the Windows suite stays green.

Verified for real this time, not audited: the full suite passes under
CPython 3.9.25 with the exact stack a Mac venv resolves (numpy 2.0.2,
scipy 1.13.1, matplotlib 3.9.4, PySide6 6.10.0, pyamg 5.2.1) - 137
passed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -1,15 +1,17 @@
 # Fill Resistance — KiCad 10 plugin
 
-Computes the **DC or AC resistance of copper zone fills and traces**
+Computes the **DC resistance of copper zone fills and traces**
 between two contacts, **single- or multi-layer**: the chosen net's fills
 (teardrops included) and tracks on the selected copper layers are
 solved as coupled finite-difference sheets linked by the net's **via
-and through-hole-pad barrels** (18 µm plating, configurable). At a user-set **frequency** the exact 1D foil/barrel
-skin-effect correction is applied (AC results are a rigorous lower
-bound; see *Model & limits*). Shows per-layer rasterized maps,
-potential, current density, and **power density**, and reports **per-via
-currents** (via ampacity!) and total dissipation at a **selectable test
-current**. PNGs + a text summary are saved per run.
+and through-hole-pad barrels** (18 µm plating, configurable). Shows
+per-layer rasterized maps, potential, current density, and **power
+density**, and reports **per-via currents** (via ampacity!) and total
+dissipation at a **selectable test current**. PNGs + a text summary are
+saved per run. An optional **skin-effect correction** (exact 1D
+foil/barrel solution at a user-set frequency) estimates the resistive
+skin rise only — it is **not** an AC impedance simulation (no proximity
+effect, no inductance; see *Model & limits*).
 
 ![Current density on a two-layer demo net](docs/img/demo-current.png)
 *Real output on a synthetic two-layer net: current from a soldered
@@ -28,14 +30,28 @@ SWIG API. Requires KiCad **10.0.1+**.
 
 ## Setup (one-time)
 
+The plugin is developed and tested on **Windows**. **Linux and macOS
+are expected to work but are untested so far** — the code and the
+dependency stack have been audited for all three OSes (KiCad builds
+the plugin a private Python venv from `requirements.txt` on every
+platform, from pre-built wheels only, no compiler needed), but nobody
+has run the plugin there yet. Reports welcome! Steps 1–4 are the same
+everywhere; OS specifics are spelled out per step and in *Platform
+notes* below.
+
 1. **Enable the API server**: KiCad → Preferences → Plugins → check
    *Enable KiCad API*.
-2. **Check the interpreter path** on the same page: should point at the
-   KiCad 10 Python, e.g. `C:\Program Files\KiCad\10.0\bin\pythonw.exe`
-   on Windows or `/usr/bin/python3` on Linux (after a 9→10 upgrade it
-   can point at KiCad 9).
+2. **Check the interpreter path** on the same page (after a 9→10
+   upgrade it can still point at KiCad 9):
+   - **Windows**: KiCad's own Python,
+     `C:\Program Files\KiCad\10.0\bin\pythonw.exe`;
+   - **macOS**: the Python bundled inside the app,
+     `/Applications/KiCad/KiCad.app/Contents/Frameworks/Python.framework/Versions/Current/bin/python3`;
+   - **Linux**: the first `python3` on `PATH` — needs Python ≥ 3.9
+     with the `venv` module (Debian/Ubuntu:
+     `sudo apt install python3-venv`).
 3. **Deploy** (dev checkout; end users install the PCM zip instead, see
-   *Packaging / publishing*):
+   *Packaging / publishing*). Windows:
    ```powershell
    powershell -ExecutionPolicy Bypass -File deploy.ps1        # junction (dev)
    powershell -ExecutionPolicy Bypass -File deploy.ps1 -Mode Copy
@@ -45,14 +61,37 @@ SWIG API. Requires KiCad **10.0.1+**.
    python3 tools/deploy.py            # symlink (dev)
    python3 tools/deploy.py --copy
    ```
+   Plugin directory: `Documents/KiCad/10.0/plugins` on Windows and
+   macOS, `~/.local/share/kicad/10.0/plugins` on Linux.
 4. **Restart KiCad**; first load builds the plugin venv (numpy, scipy,
    matplotlib, PySide6 — takes minutes; the Ω button appears when done).
    If stuck: in the PCB editor, Preferences → *PCB Editor → Action
    Plugins*, **right-click** the plugin's row → *Recreate Plugin
    Environment* (context menu only — there is no button). Manual
-   equivalent: delete
-   `%LOCALAPPDATA%\kicad\10.0\python-environments\th.co.b4l.fill-resistance`
-   and restart KiCad.
+   equivalent: delete the plugin's venv and restart KiCad —
+   - Windows: `%LOCALAPPDATA%\kicad\10.0\python-environments\th.co.b4l.fill-resistance`
+   - macOS: `~/Library/Caches/kicad/10.0/python-environments/th.co.b4l.fill-resistance`
+   - Linux: `~/.cache/kicad/10.0/python-environments/th.co.b4l.fill-resistance`
+
+### Platform notes
+
+- **Windows** is the development and test platform — everything in
+  this README was exercised here. KiCad's bundled Python is 3.13, so
+  the venv gets the current dependency stack.
+- **macOS** — **untested** (audited only: dependency wheels, paths and
+  Python-version compatibility were checked, the plugin was never run
+  on a Mac). Requires macOS 12+ (KiCad's own minimum; Intel and Apple
+  Silicon — the dmg is universal). KiCad's bundled Python is **3.9**,
+  so pip resolves an older stack (numpy 2.0, scipy 1.13,
+  matplotlib 3.9, PySide6 6.9/6.10) that the plugin code is kept
+  compatible with. Expect plot and dialog windows to open **behind**
+  the KiCad window (they are raised best-effort) — check the Dock if
+  nothing seems to appear after a solve.
+- **Linux** — **untested** (audited only, same caveat). The venv uses
+  the system Python (3.9+), so the stack matches your distribution.
+  On **ARM64 (aarch64)** there are no pyamg wheels —
+  `requirements.txt` skips pyamg there and the solver falls back to
+  Jacobi-CG: same results, noticeably slower on large grids.
 
 ## Usage
 
@@ -84,7 +123,7 @@ SWIG API. Requires KiCad **10.0.1+**.
    multi-layer pours at fine cell sizes may run for minutes (on our
    test setup a typical real-board run finishes in ≈ 8 s). Then read
    R / voltage drop / total power in the figure titles and status
-   bar. Outputs land in `<board dir>\fill_res_results\<timestamp>\`:
+   bar. Outputs land in `<board dir>/fill_res_results/<timestamp>/`:
    per-layer `1_raster_map` / `2_potential` / `3_current_density` /
    `4_power_density` PNGs, `summary.txt` (incl. the busiest vias with
    per-via current and dissipation, and the **current through each
@@ -236,10 +275,14 @@ SWIG API. Requires KiCad **10.0.1+**.
   isolated foil), and the analogous correction for the 18 µm barrel wall.
   Enter one frequency per run (e.g. a switching harmonic, with its RMS
   amplitude as the test current); suffixes `k`/`M` are accepted.
-  **Caveat:** only through-thickness crowding is modeled. Lateral
-  (proximity-effect) redistribution needs a magneto-quasistatic solver
-  and is not captured — since the resistance-driven distribution is the
-  minimum-dissipation one, AC results are a rigorous **lower bound**.
+  **Caveat:** this is **not an AC impedance simulation** — skin
+  resistance is only a small part of real AC behavior. Only
+  through-thickness crowding is modeled: lateral (proximity-effect)
+  redistribution needs a magneto-quasistatic solver and is not
+  captured — since the resistance-driven distribution is the
+  minimum-dissipation one, the f > 0 resistance is a rigorous **lower
+  bound** — and inductance, usually the dominant term of a real AC
+  impedance, is absent entirely.
   Rule of thumb for 70 µm foil: skin is negligible below ~300 kHz
   (δ = 173 µm at 142 kHz), ~+11 % at 1 MHz. At f > 0 the |J| maps are
   referenced to the skin-reduced conduction-equivalent thickness
@@ -286,9 +329,9 @@ accordingly more trustworthy than absolute numbers.
 
 Every run writes `geometry_dump.json`; re-solve without KiCad:
 
-```powershell
-uv run python -m fill_resistance.standalone dump.json `
-    [--current 40] [--cell-um 50] [--layers F.Cu,In1.Cu] [--no-show] `
+```sh
+uv run python -m fill_resistance.standalone dump.json
+    [--current 40] [--cell-um 50] [--layers F.Cu,In1.Cu] [--no-show]
     [--out DIR] [--force-iterative]
 ```
 
@@ -296,7 +339,7 @@ Dev environment, tests, headless extraction — [uv](https://docs.astral.sh/uv/)
 manages the venv from `pyproject.toml`/`uv.lock` (`requirements.txt`
 stays: KiCad builds the plugin's runtime venv from it):
 
-```powershell
+```sh
 uv sync                                              # one-time env setup
 uv run pytest -q                                     # incl. exact analytic cases
 uv run python tools/api_probe.py                     # IPC API probe vs live KiCad
@@ -326,7 +369,8 @@ GPL-3.0-or-later — see [LICENSE](LICENSE).
 - **No toolbar button**: venv still building (wait), or build failed →
   *Recreate Plugin Environment* (right-click the plugin's row in
   Preferences → *PCB Editor → Action Plugins*); check the interpreter
-  path (setup 2).
+  path (setup 2); on Linux make sure `python3-venv` is installed. Last
+  resort: delete the venv directory by hand (setup 4) and restart.
 - **"Could not connect to KiCad's IPC API"**: API server not enabled, or
   KiCad not running (no headless mode in KiCad 10).
 - **"KiCad is busy"**: a modal dialog is open in KiCad — close it, rerun.

docs/release-notes/v1.2.2.md

@@ -0,0 +1,40 @@
+Results are unchanged from 1.2.1 for the same board and settings. This
+release is about what the plugin tells you while it works, and about no
+longer overstating what a frequency result means.
+
+Progress while solving:
+
+- The dialog used to close on OK and leave nothing on screen until the
+  figures appeared - minutes, on a real board, with no sign the plugin
+  was doing anything. A small window now stays up for that whole
+  stretch: the stage running, elapsed seconds, and Cancel.
+- It covers the figure work as well as the solve. Laying out labels and
+  writing the four PNGs at full resolution is seconds on a modest board
+  and 10-15 on a large one, and that used to be silent too.
+- Cancel stops the solve and returns you to the board with no error
+  figure - the run simply reports that it was cancelled.
+
+Frequency results are described honestly:
+
+- Nothing advertises "AC resistance" any more. At f > 0 the plugin
+  applies the exact 1D foil and barrel skin-effect correction and
+  nothing else: proximity redistribution and inductance are not
+  modelled, so the number is a lower bound on the resistive rise, not
+  an AC impedance simulation. The README headline, the PCM and plugin
+  descriptions, the dialog note, the CLI help and the summary line all
+  say so now.
+- The computation itself has not changed - only its description. A
+  frequency result from 1.2.1 is the same number, previously labelled
+  in a way that invited it to be read as an impedance.
+
+Also in this release:
+
+- The offline runner takes --progress, so the same busy window can be
+  used outside KiCad.
+- The frequency field keeps its specific reason for rejecting an input
+  ("1,500" is a thousands separator, "-5" is negative) instead of a
+  generic "cannot parse".
+
+The in-KiCad |J| overlay push remains experimental and opt-in, off by
+default. It writes reference images to User.9-User.12 and replaces what
+is on those layers.

fill_resistance/adaptive.py

@@ -34,7 +34,7 @@ import numpy as np
 from scipy import sparse
 from scipy.sparse import csgraph
 
-from . import config, quadtree, skin
+from . import config, progress, quadtree, skin
 from . import solver as sv
 from .errors import ConnectivityError
 from .geometry import Problem
@@ -300,9 +300,11 @@ def run_solve_adaptive(problem: Problem, stack: RasterStack,
     corr = np.zeros(len(edges.a))
     faces = e_axis >= 0
     fa, fb = edges.a[faces], edges.b[faces]
-    for _ in range(max(0, int(config.ADAPTIVE_CORRECTION_PASSES))):
+    passes = max(0, int(config.ADAPTIVE_CORRECTION_PASSES))
+    for p in range(passes):
         if not faces.any():
             break
+        progress.stage(f"correction pass {p + 1}/{passes} ...")
         gx, gy = _leaf_gradients(N, fa, fb, cxg, cyg, Vflat)
         gt = np.where(e_axis[faces] == 0, 0.5 * (gy[fa] + gy[fb]),
                       0.5 * (gx[fa] + gx[fb]))

fill_resistance/config.py

@@ -2,6 +2,9 @@
 
 A future version may read overrides from <project>/fill_res_config.json.
 """
+from __future__ import annotations   # KiCad's macOS Python is 3.9: without
+                                     # this, `float | None` annotations are
+                                     # evaluated at import and crash there
 
 # --- Grid sizing ---
 # Benchmarked on the VOUT+ plane (147x59 mm): R changes < 0.3% from

fill_resistance/dialog.py

@@ -137,10 +137,10 @@ class _Dialog(QDialog):
         lay = QVBoxLayout(self)
         lay.addLayout(form)
         note = QLabel("Multiple layers are coupled through the net's "
-                      "via/through-pad barrels. At f > 0 the foil-thickness "
-                      "skin effect is applied per layer; lateral (proximity) "
-                      "redistribution is not modeled, so AC results are a "
-                      "lower bound.")
+                      "via/through-pad barrels. f > 0 applies only the "
+                      "foil-thickness skin effect (a lower bound on the "
+                      "resistance rise) - not an AC impedance simulation: "
+                      "proximity and inductance are not modeled.")
         note.setWordWrap(True)
         note.setStyleSheet("color: gray; font-size: 10px;")
         lay.addWidget(note)

fill_resistance/main.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 import sys
 import traceback
 
-from . import config, pipeline, report
+from . import config, pipeline, progress, report
 from .errors import CandidateError, UserFacingError
 
 
@@ -89,6 +89,9 @@ def main() -> None:
         if selection is None:
             print("cancelled")
             return
+        # the solve owns the thread from here; without this the plugin
+        # looks like it did nothing until the figures appear
+        progress.start()
 
         if selection.contact1 != "auto":
             for e in es1:
@@ -122,10 +125,14 @@ def main() -> None:
                      freq_hz=selection.freq_hz,
                      contact_model=selection.contact_model,
                      overlay=overlay_cb)
+    except progress.Cancelled:
+        print("cancelled")             # user's own doing: no error figure
     except UserFacingError as e:
         _fail(str(e), outdir)
     except Exception:
         _fail(traceback.format_exc(), outdir)
+    finally:
+        progress.done()                # also on the error paths
 
 
 if __name__ == "__main__":

fill_resistance/pipeline.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from . import config, plots, raster, report, solver
+from . import config, plots, progress, raster, report, solver
 from .errors import UserFacingError
 from .geometry import Problem
 from .solver import Result
@@ -20,8 +20,8 @@ def run(problem: Problem, outdir: Path | None, show: bool = True,
     if i_test <= 0:
         raise UserFacingError(f"Test current must be > 0 A (got {i_test:g}).")
     h = raster.choose_cell_size(problem.copper_bbox(), len(problem.layers))
-    print(f"rasterizing {len(problem.layers)} layer(s) at cell size "
-          f"{h / 1000:.1f} um ...")
+    progress.stage(f"rasterizing {len(problem.layers)} layer(s) at cell "
+                   f"size {h / 1000:.1f} um ...")
     stack = raster.rasterize_stack(problem, h)
     print(f"grid {stack.shape2d[1]}x{stack.shape2d[0]}x{stack.nlayers}, "
           f"{int(stack.masks.sum())} copper cells, {len(problem.vias)} "
@@ -30,7 +30,7 @@ def run(problem: Problem, outdir: Path | None, show: bool = True,
     e1, e2 = raster.electrode_masks(stack, problem)
     parts1, parts2 = raster.electrode_partition(stack, problem)
 
-    print(f"solving @ {i_test:g} A"
+    progress.stage(f"solving @ {i_test:g} A"
                    + (f", {freq_hz:g} Hz" if freq_hz > 0 else " DC") + " ...")
     result = solver.run_solve(problem, stack, e1, e2, i_test, freq_hz,
                               contact_model, parts1, parts2)
@@ -51,6 +51,7 @@ def run(problem: Problem, outdir: Path | None, show: bool = True,
         except Exception as e:
             print(f"overlay push failed: {e}")
 
+    progress.stage("rendering figures ...")
     figs = [
         (plots.fig_raster(stack, e1, e2, problem, result), "1_raster_map"),
         (plots.fig_potential(result, stack, e1, e2, problem), "2_potential"),
@@ -58,5 +59,5 @@ def run(problem: Problem, outdir: Path | None, show: bool = True,
          "3_current_density"),
         (plots.fig_power(result, stack, e1, e2, problem), "4_power_density"),
     ]
-    plots.save_and_show(figs, outdir, show=show)
+    plots.save_and_show(figs, outdir, show=show)   # closes the window itself
     return result

fill_resistance/plots.py

@@ -43,7 +43,7 @@ from matplotlib.gridspec import GridSpec  # noqa: E402
 from matplotlib.patches import Patch  # noqa: E402
 from matplotlib.widgets import CheckButtons  # noqa: E402
 
-from . import config  # noqa: E402
+from . import config, progress  # noqa: E402
 
 _BG = "#f5f3f0"
 _COPPER = "#c98b4e"
@@ -514,11 +514,15 @@ def save_and_show(figs_named: list[tuple], outdir: Path | None,
                   show: bool = True) -> list[Path]:
     """figs_named: [(figure, basename), ...]. Saves first, then shows."""
     saved = []
+    progress.stage("laying out figures ...", echo=False)
     for fig, _ in figs_named:
         _resolve_label_overlaps(fig)
     if outdir is not None:
         outdir.mkdir(parents=True, exist_ok=True)
         for fig, name in figs_named:
+            # full-DPI savefig with tight bounding boxes is seconds per
+            # figure - the progress window has to stay up for it
+            progress.stage(f"saving {name}.png ...", echo=False)
             panel = getattr(fig, "_layer_panel", None)
             if panel is not None:
                 panel.set_visible(False)     # PNGs carry no checkboxes
@@ -531,13 +535,18 @@ def save_and_show(figs_named: list[tuple], outdir: Path | None,
             print(f"saved {p}")
     if show and config.INTERACTIVE:
         if INTERACTIVE_BACKEND:
+            progress.stage("opening the figure windows ...", echo=False)
             for fig, _ in figs_named:
                 _fit_to_screen(fig)
+            progress.done()      # last thing before the figures are up
             _raise_windows()
             plt.show()
         else:
+            progress.done()
             for p in saved:
                 _open_in_viewer(p)
+    else:
+        progress.done()
     plt.close("all")
     return saved
 

fill_resistance/progress.py

@@ -0,0 +1,145 @@
+"""Busy window for the stretch between the dialog closing and the
+figures appearing.
+
+The solve is seconds to minutes on a real board, and until now nothing
+was on screen for it: the dialog vanished on OK and the plugin looked
+like it had done nothing. This puts a small always-on-top window up for
+that stretch - current stage, elapsed time, and a Cancel button.
+
+The state is module-level rather than an object threaded through the
+call chain: the linear solve is where the time actually goes, and it
+calls tick() from inside a scipy/pyamg iteration callback several
+frames deep. Inactive until start() succeeds, so every call is a no-op
+for the standalone runner and the tests.
+
+Qt only repaints when the event loop runs, and the solve owns the
+thread, so tick() pumps events itself. That is also where a click on
+Cancel is noticed - it raises Cancelled at the next tick.
+"""
+from __future__ import annotations
+
+import time
+
+_win = None
+_label = None
+_text = ""
+_t0 = 0.0
+_last = 0.0
+_cancelled = False
+
+TICK_INTERVAL_S = 0.05          # ~20 fps: enough to look alive, cheap
+
+
+class Cancelled(Exception):
+    """The user closed the progress window. Not a failure - the caller
+    reports it like a cancelled dialog, with no error figure."""
+
+
+def start(title: str = "Fill Resistance") -> bool:
+    """Show the window. False (and inert) if Qt is unavailable."""
+    global _win, _label, _t0, _last, _cancelled, _text
+    if _win is not None:
+        return True
+    try:
+        from PySide6.QtCore import Qt
+        from PySide6.QtWidgets import (QApplication, QDialog,
+                                       QDialogButtonBox, QLabel,
+                                       QProgressBar, QVBoxLayout)
+    except Exception:
+        return False
+    try:
+        app = QApplication.instance() or QApplication([])
+        win = QDialog()
+        win.setWindowTitle(title)
+        win.setWindowFlag(Qt.WindowStaysOnTopHint, True)
+        # no close button: closing is Cancel, and Cancel is the only way
+        # to stop a solve that owns the thread
+        win.setWindowFlag(Qt.WindowCloseButtonHint, False)
+
+        label = QLabel("starting ...")
+        bar = QProgressBar()
+        bar.setRange(0, 0)                  # indeterminate: no total to show
+        buttons = QDialogButtonBox(QDialogButtonBox.Cancel)
+
+        layout = QVBoxLayout()
+        layout.addWidget(label)
+        layout.addWidget(bar)
+        layout.addWidget(buttons)
+        win.setLayout(layout)
+
+        buttons.rejected.connect(_cancel)
+        win.rejected.connect(_cancel)
+        win.setMinimumWidth(340)
+        win.show()
+        win.raise_()
+        win.activateWindow()
+        app.processEvents()
+    except Exception:
+        return False
+
+    _win, _label, _t0, _last, _cancelled, _text = win, label, \
+        time.monotonic(), 0.0, False, ""
+    return True
+
+
+def _cancel() -> None:
+    global _cancelled
+    _cancelled = True
+
+
+def stage(text: str, echo: bool = True) -> None:
+    """Name the phase now running. Always repaints - stages are rare.
+
+    echo=False for phases that already print their own line (saving a
+    PNG prints the path), so the window updates without doubling stdout.
+    """
+    global _text
+    _text = text
+    if echo:
+        print(text)
+    if _win is not None:
+        _refresh()
+
+
+def tick() -> None:
+    """Called from inside the solve. Throttled, so it is safe to call
+    every iteration."""
+    global _last
+    if _win is None:
+        return
+    now = time.monotonic()
+    if now - _last < TICK_INTERVAL_S:
+        return
+    _last = now
+    _refresh()
+
+
+def _refresh() -> None:
+    from PySide6.QtWidgets import QApplication
+
+    elapsed = time.monotonic() - _t0
+    if _label is not None:
+        _label.setText(f"{_text}\n{elapsed:.0f} s elapsed")
+    app = QApplication.instance()
+    if app is not None:
+        app.processEvents()
+    if _cancelled:
+        raise Cancelled()
+
+
+def done() -> None:
+    """Take the window down. Idempotent - callers use it in a finally."""
+    global _win, _label, _text, _cancelled
+    win, _win, _label, _text = _win, None, None, ""
+    _cancelled = False
+    if win is None:
+        return
+    try:
+        win.close()
+        win.deleteLater()
+        from PySide6.QtWidgets import QApplication
+        app = QApplication.instance()
+        if app is not None:
+            app.processEvents()
+    except Exception:
+        pass

fill_resistance/report.py

@@ -59,7 +59,8 @@ def write_summary(outdir: Path, problem: Problem, stack: RasterStack,
          + (f"{result.freq_hz:g} Hz (skin depth {result.skin_depth_um:.0f} um)"
             if result.freq_hz > 0 else "DC")),
         f"RESISTANCE:        {result.R_ohm * 1000:.6g} mOhm"
-        + (" (AC LOWER BOUND: lateral/proximity redistribution not modeled)"
+        + (" (SKIN-ONLY LOWER BOUND: no proximity/inductance - "
+           "not AC impedance)"
            if result.freq_hz > 0 else ""),
         f"VOLTAGE DROP:      {result.R_ohm * result.i_test * 1000:.4g} mV "
         f"@ {result.i_test:g} A",

fill_resistance/solver.py

@@ -45,7 +45,7 @@ from scipy import sparse
 from scipy.sparse import csgraph
 from scipy.sparse import linalg as sla
 
-from . import config, skin
+from . import config, progress, skin
 from .errors import ConnectivityError, ElectrodeError, SolverError
 from .geometry import Problem, slot_distance
 from .raster import RasterStack, electrodes_touch
@@ -375,12 +375,14 @@ class PreparedSolver:
 
     def solve(self, b: np.ndarray) -> tuple[np.ndarray, SolveInfo]:
         if self._lu is not None:
+            progress.tick()      # direct solve: one shot, no iterations
             return self._lu.solve(b), SolveInfo(method="spsolve",
                                                 n_unknowns=self.n)
         if self._ml is not None:
             residuals: list[float] = []
             x = self._ml.solve(b, tol=config.AMG_TOL, maxiter=300,
-                               accel="cg", residuals=residuals)
+                               accel="cg", residuals=residuals,
+                               callback=lambda _: progress.tick())
             res = float(np.linalg.norm(b - self._A @ x)
                         / max(np.linalg.norm(b), 1e-300))
             if not np.isfinite(res) or res > 1e-6:
@@ -404,7 +406,7 @@ def _solve_amg(A: sparse.csr_matrix, b: np.ndarray) -> tuple[np.ndarray, SolveIn
     ml = pyamg.smoothed_aggregation_solver(A.tocsr(), max_coarse=500)
     residuals: list[float] = []
     x = ml.solve(b, tol=config.AMG_TOL, maxiter=300, accel="cg",
-                 residuals=residuals)
+                 residuals=residuals, callback=lambda _: progress.tick())
     res = float(np.linalg.norm(b - A @ x) / max(np.linalg.norm(b), 1e-300))
     if not np.isfinite(res) or res > 1e-6:
         raise SolverError(
@@ -428,6 +430,7 @@ def _solve_cg_jacobi(A: sparse.csr_matrix, b: np.ndarray) -> tuple[np.ndarray, S
     def count(_):
         nonlocal iters
         iters += 1
+        progress.tick()
 
     try:
         x, code = sla.cg(A, b, M=M, rtol=config.CG_TOL,

fill_resistance/standalone.py

@@ -13,7 +13,7 @@ import argparse
 import sys
 from pathlib import Path
 
-from . import config, pipeline
+from . import config, pipeline, progress
 from .errors import UserFacingError
 from .geometry import load_problem
 from .skin import parse_frequency
@@ -26,7 +26,8 @@ def main(argv=None) -> int:
                     help="test current [A] (default: config TEST_CURRENT_A)")
     ap.add_argument("--freq", type=parse_frequency, default=0.0,
                     help="frequency, e.g. 142k or 1.5M (default: DC). "
-                         "AC results are a lower bound (skin per foil only)")
+                         "Skin resistance only, a lower bound - not AC "
+                         "impedance (no proximity, no inductance)")
     ap.add_argument("--cell-um", type=float, default=None,
                     help="force grid cell size [um]")
     ap.add_argument("--layers", type=str, default=None,
@@ -51,6 +52,9 @@ def main(argv=None) -> int:
     ap.add_argument("--force-iterative", action="store_true",
                     help="use the iterative solver (AMG-CG, or Jacobi-CG "
                          "without pyamg) regardless of problem size")
+    ap.add_argument("--progress", action="store_true",
+                    help="show the busy window during the solve, as the "
+                         "KiCad plugin does (needs a GUI)")
     ap.add_argument("--adaptive", action=argparse.BooleanOptionalAction,
                     default=None,
                     help="adaptive quadtree grid (coarse plane interiors); "
@@ -86,13 +90,20 @@ def main(argv=None) -> int:
             return 1
 
     outdir = args.out if args.out is not None else args.dump.parent
+    if args.progress:
+        progress.start()
     try:
         pipeline.run(problem, outdir, show=not args.no_show,
                      i_test=args.current, freq_hz=args.freq,
                      contact_model=args.contact_model)
+    except progress.Cancelled:
+        print("cancelled")
+        return 1
     except UserFacingError as e:
         print(f"ERROR: {e}", file=sys.stderr)
         return 1
+    finally:
+        progress.done()
     return 0
 
 

metadata.json

@@ -1,8 +1,8 @@
 {
     "$schema": "https://go.kicad.org/pcm/schemas/v2",
     "name": "Fill Resistance",
-    "description": "DC/AC resistance of copper zone fills and traces between two contacts, single- or multi-layer with via coupling; current and power density maps.",
-    "description_full": "Computes the DC or AC resistance of copper zone fills and traces between two contacts (marker rectangles on User.1/User.2 and/or selected pads/vias), single- or multi-layer: the chosen net's fills and tracks are solved as coupled finite-difference sheets linked by the net's via and through-hole-pad barrels. Selected vias/THT pads inject at the drill-wall barrel, and every populated THT hole carries its full solder joint (component lead, solder fill, one-sided pad coat and protruding-lead cone) with exact pad shapes and do-not-populate flags read from KiCad, conducting in-plane as its solder plug and lead on every layer it spans. Every net pad's exact copper shape is stamped on the layers it sits on, SMD as well as through-hole, and oblong (slotted) holes are modelled as their true stadium shape rather than an approximating circle. Traces narrower than the grid become exact 1D resistor chains, and an adaptive multi-resolution grid (fine at features, coarse plane interiors, deferred-corrected) keeps large boards fast.\n\nShows per-layer rasterized maps, potential, current density and power density, reports per-via currents (via ampacity) and total dissipation at a selectable test current. At a user-set frequency the exact 1D foil/barrel skin-effect correction is applied (AC results are a rigorous lower bound). PNGs, a text summary and a re-solvable geometry dump are saved per run.\n\nNote: the first load builds the plugin's Python environment (numpy, scipy, pyamg, matplotlib, PySide6) and can take several minutes.",
+    "description": "DC resistance of copper zone fills and traces between two contacts, single- or multi-layer with via coupling; current and power density maps.",
+    "description_full": "Computes the DC resistance of copper zone fills and traces between two contacts (marker rectangles on User.1/User.2 and/or selected pads/vias), single- or multi-layer: the chosen net's fills and tracks are solved as coupled finite-difference sheets linked by the net's via and through-hole-pad barrels. Selected vias/THT pads inject at the drill-wall barrel, and every populated THT hole carries its full solder joint (component lead, solder fill, one-sided pad coat and protruding-lead cone) with exact pad shapes and do-not-populate flags read from KiCad, conducting in-plane as its solder plug and lead on every layer it spans. Every net pad's exact copper shape is stamped on the layers it sits on, SMD as well as through-hole, and oblong (slotted) holes are modelled as their true stadium shape rather than an approximating circle. Traces narrower than the grid become exact 1D resistor chains, and an adaptive multi-resolution grid (fine at features, coarse plane interiors, deferred-corrected) keeps large boards fast.\n\nShows per-layer rasterized maps, potential, current density and power density, reports per-via currents (via ampacity) and total dissipation at a selectable test current. An optional skin-effect correction (exact 1D foil/barrel solution at a user-set frequency) estimates the resistive skin rise only - proximity redistribution and inductance are not modeled, so this is not an AC impedance simulation. PNGs, a text summary and a re-solvable geometry dump are saved per run.\n\nNote: the first load builds the plugin's Python environment (numpy, scipy, pyamg, matplotlib, PySide6) and can take several minutes.",
     "identifier": "th.co.b4l.fill-resistance",
     "type": "plugin",
     "author": {
@@ -17,7 +17,7 @@
     },
     "versions": [
         {
-            "version": "1.2.1",
+            "version": "1.2.2",
             "status": "stable",
             "kicad_version": "10.0",
             "runtime": "ipc"

plugin.json

@@ -2,7 +2,7 @@
     "$schema": "https://go.kicad.org/api/schemas/v1",
     "identifier": "th.co.b4l.fill-resistance",
     "name": "Fill Resistance",
-    "description": "DC/AC resistance of copper zone fills and traces between two contacts (marker rectangles or pads), single- or multi-layer with via coupling",
+    "description": "DC resistance of copper zone fills and traces between two contacts (marker rectangles or pads), single- or multi-layer with via coupling",
     "runtime": {
         "type": "python"
     },

pyproject.toml

@@ -3,15 +3,15 @@
 # the dependency list there in sync with [project.dependencies].
 [project]
 name = "fill-resistance"
-version = "1.2.1"
-description = "DC/AC resistance of copper zone fills and traces between two contacts (KiCad 10 plugin)"
+version = "1.2.2"
+description = "DC resistance of copper zone fills and traces between two contacts (KiCad 10 plugin)"
 license = "GPL-3.0-or-later"
 requires-python = ">=3.11"
 dependencies = [
     "kicad-python>=0.7.0",
     "numpy",
     "scipy",
-    "pyamg",
+    "pyamg ; sys_platform != 'linux' or platform_machine != 'aarch64'",
     "matplotlib",
     "PySide6",
 ]

requirements.txt

@@ -1,6 +1,8 @@
 kicad-python>=0.7.0
 numpy
 scipy
-pyamg
+# no pyamg wheels for Linux aarch64, and KiCad installs wheels-only
+# (--only-binary): skip it there, the solver falls back to Jacobi-CG
+pyamg ; sys_platform != "linux" or platform_machine != "aarch64"
 matplotlib
 PySide6

tests/test_py39_compat.py

@@ -0,0 +1,51 @@
+"""Python 3.9 compatibility tripwire.
+
+KiCad's macOS builds bundle Python 3.9 and build the plugin venv with
+it (README: Platform notes), while the dev environment runs a current
+Python - so nothing else in the suite notices a construct that only
+breaks on 3.9. The first real Mac run died at import: a module-level
+`float | None` annotation in config.py, evaluated at runtime because
+the file lacked the future import (PEP 604 unions need Python 3.10
+unless annotations are deferred).
+"""
+import ast
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SHIPPED = sorted((ROOT / "fill_resistance").glob("*.py"))
+SHIPPED.append(ROOT / "fill_res_action.py")
+
+
+def _has_future_annotations(tree: ast.Module) -> bool:
+    return any(isinstance(node, ast.ImportFrom)
+               and node.module == "__future__"
+               and any(alias.name == "annotations" for alias in node.names)
+               for node in tree.body)
+
+
+def _uses_annotations(tree: ast.Module) -> bool:
+    for node in ast.walk(tree):
+        if isinstance(node, ast.AnnAssign):
+            return True
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            if node.returns is not None:
+                return True
+            a = node.args
+            args = (a.posonlyargs + a.args + a.kwonlyargs
+                    + ([a.vararg] if a.vararg else [])
+                    + ([a.kwarg] if a.kwarg else []))
+            if any(arg.annotation is not None for arg in args):
+                return True
+    return False
+
+
+def test_annotated_modules_defer_annotations():
+    offenders = []
+    for path in SHIPPED:
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        if _uses_annotations(tree) and not _has_future_annotations(tree):
+            offenders.append(path.name)
+    assert not offenders, (
+        f"{offenders} use annotations without 'from __future__ import "
+        f"annotations': they are evaluated at import time and PEP 604 "
+        f"unions crash on KiCad's macOS Python 3.9.")

uv.lock

@@ -216,14 +216,14 @@ wheels = [
 
 [[package]]
 name = "fill-resistance"
-version = "1.2.1"
+version = "1.2.2"
 source = { virtual = "." }
 dependencies = [
     { name = "kicad-python" },
     { name = "matplotlib" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
     { name = "numpy", version = "2.5.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
-    { name = "pyamg" },
+    { name = "pyamg", marker = "platform_machine != 'aarch64' or sys_platform != 'linux'" },
     { name = "pyside6" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.12'" },
     { name = "scipy", version = "1.18.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.12'" },
@@ -239,7 +239,7 @@ requires-dist = [
     { name = "kicad-python", specifier = ">=0.7.0" },
     { name = "matplotlib" },
     { name = "numpy" },
-    { name = "pyamg" },
+    { name = "pyamg", marker = "platform_machine != 'aarch64' or sys_platform != 'linux'" },
     { name = "pyside6" },
     { name = "scipy" },
 ]