Opamp path lp

[!WARNING] Vibe-coded, for illustrative purposes only. GroundTruth was written largely with an AI assistant. Many of its results look reasonable, but they have not all been validated on real hardware: don't base design or compliance decisions on them alone.

GroundTruth — return-path and EMI analysis for KiCad

GroundTruth finds where the return currents of fast signals and switching power stages really flow on a KiCad 10+ board, and what that does to emissions. It flags return-path problems (a trace crossing a plane split, a layer change with no stitching via, a trace along a plane edge), solves the return current in every plane layer, and estimates how much each detour adds to radiated and conducted emission, with fixes it checks before suggesting them.

On the same board model it also analyses:

• DC-DC power stages and motor bridges: hot loops, capacitor current sharing, switch-node overshoot, conducted emission through a LISN, losses, current density, control loops, and what the switching couples into the rest of the board (Power stages);
• temperatures: copper and part temperatures from the currents and losses, and each stage's current capacity (Thermal);
• DC loads, power integrity, safety and signal integrity: the drop each load sees, each IC's supply impedance, clearances and part ratings, impedance, skew and crosstalk (Other analyses).

It comes as a KiCad plugin (the window shown under The plugin, with heatmaps, markers drawn on the board and an HTML report) and as the groundtruth command line for CI, which needs neither KiCad nor a display. Both use the same analysis core and the same settings file, and give the same results.

Install

The KiCad plugin. In KiCad, enable the API (Preferences → Plugins → Enable KiCad API, restart KiCad). Then Tools → Plugin and Content Manager → Manage… → Add the repository https://afkiwers.github.io/GroundTruth/repository.json, select it and install GroundTruth; new releases show up as updates. Each release also has the package as a zip for Install from File…. On the first start KiCad builds the plugin's Python environment (a few minutes); the button Analyse return paths then appears in the PCB editor's top toolbar. The plugin has a fair few dependencies, so it can take a couple of KiCad restarts before the buttons show.

The command line. Python 3.11 or newer; install a release's wheel (GroundTruth is not on PyPI):

pip install "groundtruth-pcb @ https://github.com/afkiwers/GroundTruth/releases/download/0.1.44625/groundtruth_pcb-0.1.44625-py3-none-any.whl"

More, including the development setup, GPU acceleration and where everything is on disk: Installing.

Optional speed-ups (once per computer, KiCad closed; the installers are in the installed plugin's tools folder): the faster sparse solver on Windows, install_sparse.cmd (Intel MKL PARDISO, ~250 MB; a Mac has Apple Accelerate built in), and GPU support for an NVIDIA or AMD card, install_gpu.py / install_gpu_amd.cmd (PyTorch, ~2.5 GB). Both only change the speed. Steps: Installing, Optional speed-ups.

Quick start

In KiCad: open the board in the PCB editor and click Analyse return paths.

1. Review what GroundTruth found on the coloured tabs (orange rows): a net's driver and receivers and its timing, a converter's switches and operating point, a bridge's motor. Fill in what the board can't tell, press Mark reviewed.
2. Run checks: the rule checks; the Issues tab lists what they find.
3. Simulate: the field solver on everything ticked; the Results tab shows the maps and margins.
4. Fix: click an issue to see it in KiCad, let Suggest fixes propose vias and capacitors, try them as what-if edits.

The plugin folder has a demo board to try this on (demo\README.txt). On the command line:

groundtruth init board.kicad_pcb                 # the settings file, with every part's suggested model
groundtruth detect board.kicad_pcb --write       # nets, power stages and motor bridges to analyse (review them)
groundtruth check board.kicad_pcb                # the rule checks (seconds)
groundtruth simulate board.kicad_pcb --format html --out-dir report   # the field solver, an HTML report

The plugin

Getting there. Once installed, GroundTruth puts two buttons at the right end of the PCB editor's top toolbar (red box above). They are two separate actions, so each has its own button:

• Analyse return paths (the right one, the ground symbol) opens the GroundTruth window for the board open in the PCB editor. This is where everything happens: setup, Run checks, Simulate, results and issues.

• Add selected net to GroundTruth (the left one, with the green plus) adds a net you pick on the board to the window's Signal paths tab, so you don't need to find it in a list:

  1. In the PCB editor, select a track, via or pad of the net (click it; a right-click selects it too).
  2. Press the button. The net is added as a new signal path, and the GroundTruth window comes to the front. If no window is open for the board, one opens and adds the net once it has read the board.
  3. GroundTruth suggests the driver and receiver pins from the pin types. Check the row, which is orange until you review it; set the frequency and rise time if the net's name matches no signal class.

  To add a whole path through several nets (for example a current-sense amplifier → op-amp → microcontroller ADC), Ctrl+click one bit of copper on each net, then press the button once. GroundTruth puts the nets in order through the parts joining them and adds one signal path, with the series resistors as pass-through parts and the op-amp modelled as an amplifier. Ground, supply and power-stage nets (switch node, inductor output) are refused with the reason. KiCad 10 doesn't let plugins add entries to the right-click menu, hence the toolbar button.

A third action, Clear GT markers, removes the markers, contours and arrows GroundTruth drew on the board. It has no toolbar button: find it under Tools → External Plugins, or in the window's top bar.

Set up. The coloured tabs are what a run analyses: signal paths, converters, motor bridges, DC loads, power integrity rails and signal-integrity pairs, each row with a tick box. GroundTruth detects them when a board is opened (orange until you review them); each tab's badge counts the rows the next run takes. Run checks gives the rule checks in seconds, Simulate the field solver in minutes. Configuration ▾ saves and loads a set-up, Undo takes back a change.

Results. The return current in each plane layer as a heatmap with current arrows, and the vias that carry it between layers. Markers ▾ picks what is drawn over the map, Draw on board ▾ puts the contours, the arrows or the hot loop into KiCad, Open 3D view opens the board in your browser, and Further analysis ▾ adds the thermal solve, the current capacity of a stage and a sharper (finer) map.

A power stage gets its own views: here a buck's hot loop in two layers, with the busiest via, the loop inductance, the switch-node ringing, the input capacitors' share and the radiated and conducted margins in the tiles above it.

Scrolling down, the cross-section shows each plane layer's share of the return current along the route (red: carrying the return, blue: flowing the other way) and the emission spectrum against its limit.

Issues. Every finding with its severity; a click selects, highlights and zooms to it in KiCad.

Fixes proposes stitching vias and capacitors for a route, and design changes for a power stage: a slower switch-node edge, a snubber, an input filter, a common-mode budget. Each is predicted, then verified by running the whole analysis again on a copy of the board, with its margins, overshoot and extra loss, the parts to buy and a circuit (here an input π-filter and its corner frequency). History keeps every Simulate to compare; Export report… writes the results as one HTML page. The plugin's own Help (F1) explains each tab.

Part parameters for your parts database

GroundTruth reads part parameters (a FET's Rds(on) and Coss, a capacitor's ESR and Cbias, an op-amp's GBW, a controller's Vref …) from the symbols' fields. Add them to the parts in your parts database, and KiCad's HTTP library interface brings them into the schematic with the parts, where GroundTruth reads them on every run. The full list, grouped by the tab that uses each (a parameter used on several tabs is listed under each, with where else it is used): Part parameters.

Documentation

For developers: Development (the source tree), ARCHITECTURE.md (the physics, data flow and design decisions) and REFERENCES.md (every source and assumption). Example boards with their settings: examples/.

License

GroundTruth is free software under the GNU General Public License v3.0: see LICENSE.