KiPI User Guide

1. In KiCad, enable Preferences → Plugins → Enable KiCad API (once).
2. Open your board in the PCB editor and click the KiPI toolbar button. KiPI reads the board (refilling zones first) and draws it in 3D.
3. In the Nets list on the left, tick the power and ground nets you want to analyze. KiPI pre-ticks a guess the first time.
4. In the PI setup panel on the right, VRMs tab: click Add, pick the regulator's output net and part, set its voltage. Add its Ground pins if you want the ground return solved too.
5. Loads tab: click Add for each part that draws current, pick its supply pins, enter its current and a tolerance (e.g. ±3 %).
6. If a sense resistor, ferrite, fuse or load switch sits between two nets you ticked, add it on the Series links tab.
7. Click Solve all. Watch the log at the bottom.
8. Read the Loads table for PASS/FAIL, and click around the 3D view to probe voltages. Switch the field to Current density and tick Arrows to find bottlenecks.

The setup is saved next to your board as <board>.kipi-setup.yml every time you solve, so the next session starts where you left off.

1. Switch Mode (right end of the toolbar) to AC. The setup panel becomes the AC setup; VRMs and series links are shared with DC.
2. Make sure the rail's net, its ground and every net its capacitors connect to are ticked in the Nets list.
3. Capacitors tab: click Models from values to make one model per capacitor value, then enter each model's ESL and ESR from the datasheet (and check the capacitance).
4. Probes tab: click Add. KiPI picks the busiest part on the rail that also has ground pins, which is usually the load. Or click From DC load and pick a DC load: the probe gets that load's supply and ground pins. Set a target impedance, or open the target calculator.
5. Under the tabs, choose the Rail (by its VRM) and Ground, then click Solve rail.
6. The Impedance tab in the middle shows |Z| against frequency. Click a curve to place a cursor and read the values in the Info box.

The repository includes an example: a 4-phase 12 V → 0.9 V, 40 A core rail with decoupling and probes already set up. From a development checkout run

python -m kipi examples/multiphase_buck/multiphase_buck.kipi.json.gz

which opens it in standalone KiPI, or open that file with Open… (standalone) or Open snapshot… (the plugin).

• The stackup and resistivities are saved with the PI setup. An edited stackup is used again the next time the board is opened (unlocked). If a layer has been added, removed or renamed in KiCad since, the log says so and KiCad's stackup is used.
• To compare stackups, solve, edit, and solve again. A stackup change clears the DC results, which were for the old stackup; the AC results stay until a rail is solved again. Reports note a stackup edited in KiPI.
• KiCad's API cannot change a board's stackup yet, so edits stay in KiPI. To keep a stackup you settle on, enter it in KiCad's Board Setup → Board Stackup → Physical Stackup.
• A board snapshot (Save snapshot) keeps KiCad's stackup; the edits live in the setup.

Every net on the board. Tick the nets you want to analyze. Ticked nets are drawn in 3D and are the only nets offered in the setup's pin pickers, so a net you need for a VRM, load, series link, capacitor or probe must be ticked first.

The ticked nets are saved with the setup. A board with no saved choice starts with a guess: its largest power planes and the main ground. Building the 3D copper of a big net takes a moment; nets appear as they finish, and Cancel stops the build.

Each copper layer with its thickness and height in the stackup. Untick a layer to hide it; All and None show or hide every layer at once. Hiding layers does not change the result colors; set the color scale to look closer.

Part 3D models

• KiPI asks KiCad's command-line tool, kicad-cli, to export just the parts it needs, so KiCad finds the model files the same way its own 3D viewer does (STEP and VRML). It runs in the background, the first time the models are shown; each part is read once per board.
• kicad-cli reads the saved .kicad_pcb file. A part moved since the last save is drawn where it was saved; save the board and click Load from KiCad to update it.
• The Z scale stretches the board but not the parts: top-side parts sit on the stretched board at their true height, and on a board made thicker or thinner in the Stackup window.
• Clicks go through the models to the copper beneath, so probing works as without them.
• A part whose model KiCad cannot find is named in the log with the missing path. If kicad-cli or the board file cannot be found, the log says so once and no models are drawn; see Troubleshooting.

Shows a summary of the board when it loads, and afterwards whatever you last clicked in 3D: the layer and coordinates, the pad or via hit (net, drill, layer span), and, when results are shown, the voltage, drop, current density, power density and via current at that point. In AC mode it shows the impedance plot's cursor values.

The summary says where the board came from (for example From KiCad PCB editor 10.0.7, and the snapshot file it was opened from). Under Placeholders it lists anything KiPI had to fill in because the source did not give it, such as a default stackup when the board's own is incomplete. Results that depend on a placeholder are only as good as the placeholder.

Select in KiCad selects the picked pad or via in the PCB editor, so you can find it in your layout. It needs a live KiCad connection (not a snapshot), so the plugin has it and standalone KiPI does not.

In AC mode two more tabs appear beside 3D view: Impedance, with the impedance plot, and Board map, with the mesh and parts of the solve.

The bottom dock shows the current stage, a progress bar, and Cancel, which stops the running task (loading, building nets or solving). The log streams every stage with its timing, solver residuals and warnings: warnings are amber, errors red, stage headers blue.

Each session also writes a log file to kipi/ in your temporary folder (%TEMP% on Windows, $TMPDIR on macOS, /tmp on Linux). See Troubleshooting.

Net groups

KiPI solves copper one net group at a time. A group is a net plus every net joined to it by a series link. For example, +3V3 and +3V3_FILT joined by a ferrite bead are one group. Each group may be driven by at most one VRM. Ground nets used by VRM or load ground pins are their own groups.

The power tree

A VRM's input pins make it a load on its upstream net. KiPI solves the tree from the leaves back to the source: downstream rails first, then each VRM's input current (from its output current, efficiency or quiescent current) is applied as a load upstream. So the 12 V input rail carries the current of everything it feeds.

Voltage reference

Voltages are measured against the source's ground (0 V). If ground pins are given, the ground return is solved too and a load's ground rises above 0 V. The figure to compare with the set point is the load's effective voltage: supply minus ground at the load.

Drop and boost

A drop is a pin below the VRM's set voltage. A boost is a pin above it, which happens with remote sense: the VRM raises its output to hold a sense point further down the copper, so pins nearer the VRM sit above the set point. A load is judged by its worst pin, whichever direction.

Every "pins" field is three boxes:

1. Net: one of the nets ticked in the Board panel. Type to search.
2. Part: the parts with pads on that net, busiest first, shown as reference, value and pad count, e.g. U4 TPS62130 (3). Type to search (u4 is enough).
3. Pins: optional pin numbers, comma-separated, e.g. 1,2,5. Blank means every pin of that part on that net; the placeholder lists them.

Optional pickers have (none) as their first net.

As you pick pins, KiPI fills in the fields that usually follow from them. Each guess only fills a field you have not set yourself (an empty field, or one it filled in for the previous part), and when the board does not give an answer the field is left as it was. Change anything it fills in: your value is kept.

How the ground net is found. Ground nets are not always called GND, so KiPI tries, in order: ground nets the setup already uses (any VRM, load or probe ground pins), nets named like a ground (GND, PGND, AGND, VSS, EARTH…), then the board's biggest net (the one with the most pads) if it is not named like a rail. Only nets ticked in the Board panel are used, except grounds the setup already uses. Once one VRM or load has ground pins on an unusually named ground, every later guess uses it.

Sense resistors, ferrite beads, fuses, load switches, 0 Ω links: any part that passes DC from one net to another. Give the part's Side A pins and Side B pins and its Resistance (DCR); 0 is a short. Picking side A on a two-terminal part fills in side B on its other net, and when both sides are on the same resistor, the resistance is read from its value field (10m, 4k7, 0R1, 5 mΩ…). ESL is used by AC only. A new link starts on a part that bridges the first two ticked nets that are not grounds, if there is one.

The nets a link joins are solved together as one group, so a group can only hold one VRM. A load pin with no copper path to its VRM is reported, not guessed at (see Loads not connected by copper).

Lists every net group with its role (rail from a VRM, ground, or not driven). Untick groups that are not modeled or routed yet; All and None tick or untick them all. Only ticked groups are validated and solved, and the choice is saved. Where a solved group meets an excluded one:

• A VRM whose output is excluded becomes a constant load on its input pins, drawing the input current its rail would need at nominal voltages.
• A VRM whose input is excluded is treated as an ideal source.
• Ground pins on an excluded ground are ignored.

The Notes results tab lists what was left out and substituted. The Solve button shows how many groups will be solved, e.g. Solve 3 of 5 net groups.

The defaults suit most boards; set the via plating your fabricator states.

Tick Electro-thermal co-simulation to let copper losses heat the board, with warmer copper becoming more resistive. KiPI alternates electrical and thermal solves.

Heat comes from every solved net and layer, vias, DC connections (I²R, at their pins), VRM conversion loss and, with Include load power dissipation, the loads. The report's Component power dissipation table lists the DC connections' and loads' heat. The limits grade the last solve straight away when you change them.

Solve all saves the setup, meshes every ticked net group and solves the power tree. It is disabled while there are problems (listed in red). If you click it while the 3D view is still building nets, the solve is queued and starts as soon as that finishes.

Tick HTML report before solving to also write <board>_kipi_report_<date>_<time>.html next to the board; the time stamp keeps each solve's report instead of overwriting the last one. It opens in your web browser when the solve finishes, and Report opens it again later. The report is a single offline file with every table, an interactive 3D view of each net group, per-layer statistics and maps, and the temperature map.

The report's Pins section, and _pins.csv in Export ▾ Tables as CSV…, list every pin each group was solved with. That covers VRM output, phase, input and sense pins, load supply and ground pins, and DC connection pins. Each row gives the pin's position, voltage, drop or boost from the VRM set point (0 V for a ground), and current. The current is what the pin draws from the copper, so it is negative where current is delivered into the copper, as at a VRM output. VRM output pin currents are solved, so they show how the current shares between the pins. A load's current is split equally across its pins, as the solver applies it, and a DC connection's current across the pins on each side.

A solve that fails on a setup problem (e.g. no copper path) shows Cannot solve in the Notes tab with the reason. Untick the group with the problem in the Solve tab to solve the rest.

Show copper returns to the plain geometry; pick a group or field again to bring the results back. Click anywhere to probe: Info shows the exact value at that point (not clipped).

Color scale: the minimum and maximum of the colors, under the group and field. Each result starts on its whole range, over every layer whether shown or not. Type limits (or step them with the arrows) to stretch the colors over the part you care about; values outside take the end colors. Limits are kept for each net group and field until Auto fits the whole range again; temperature limits apply to every group, so an ambient-to-limit scale stays put while you switch groups. On the logarithmic power-density scale, a minimum of zero or below falls back to four decades below the maximum.

Load verdicts

• Effective voltage is what the load actually sees: its supply pins minus its ground pins. Compare it with the set point, not the raw plane voltage.
• A supply plane reading above its set point is normal with remote sense or when ground return is solved; see drop and boost.
• Worst pin is the one furthest from the set point; with many pins, one far pin can fail a load whose average looks fine.
• The color scale covers the whole result; type a minimum and maximum under it to look closer.
• Losses are I²R in the copper; VRM conversion loss is the difference between input and output power.

The AC analysis computes the PDN impedance seen from a probe, a device's supply and ground pins, looking out into the board over a range of frequencies. A device that draws a changing current I from a PDN of impedance Z sees its supply move by about I·|Z|, so keeping |Z| below a target impedance keeps the supply ripple within tolerance.

A solve covers one rail (the nets its VRM drives, plus nets joined to them by series links) against one ground net. It includes:

• The copper, field-solved: plane and trace resistance (with skin effect), the spreading inductance of planes, the capacitance between facing rail and ground copper, cavity resonances, and the inductance of vias and their mounting.
• Capacitors between the rail and ground, each as a series R-L-C from its model. Only the part's own ESL is entered; its mounting (pads, vias, planes) is simulated.
• Series links as their resistance plus ESL.

Capacitors that sit between the rail and ground but have no model are left out, and the results notes list them.

The same VRMs and series links as the DC setup; edits in one mode show in the other. Every VRM field can be edited in either mode; the tooltip of a field only DC uses says so. In AC:

• A VRM's output net (and ground pins) define a rail and its default ground for the Rail picker.
• A series link adds its ESL to its resistance. A link leading off the rail to a net that is not part of the solve is left out, with a note. A 0 Ω link with no ESL merges the two nets.

A model is a capacitance, ESL and ESR shared by a group of identical parts. All three are required.

From DC load adds a probe on the same supply and ground pins as a DC load picked from its dropdown. The dropdown also lists the input of every LDO and switcher, one entry per phase (e.g. VR4 phase 2 input): a regulator's input pins load the rail feeding it just as a device does.

A rail can have several probes, e.g. one per device; they are all solved together and each sees the others as open circuits.

The AC solve leaves the VRM out of circuit: it gives the open-loop PDN impedance, which keeps rising toward low frequency. In the real circuit the converter's control loop holds the rail below its bandwidth. So when the rail's VRM has a Control loop bandwidth, a probe's target (flat or custom) applies only from that frequency up:

• the plot draws the target only above the bandwidth, and marks the bandwidth with a dotted line;
• PASS/FAIL, the worst |Z| and the margin only look above it. Without a target, the worst |Z| is the highest above the bandwidth;
• the cursor shows "none here" below it.

Fallback: if the bandwidth is at or above a flat target's frequency, or above the whole sweep, no frequencies are left to judge. That probe's target is then judged over its whole range, as if the VRM had no bandwidth, and a note in the results says so.

Works out a flat target from the device's transient spec:

• DC load: the DC load whose tolerance and current the copy buttons use. A load on the probe's own supply and ground pins is used directly. Otherwise the dropdown offers the loads on the probe's part: supply pins on the same footprint, and ground pins too where the load has them. An LDO's or switcher's input pins count as a load too: its Input range is the tolerance, and its input current and the DC drop at its input pins come from the last DC solve.
• AC voltage tolerance: how far the supply may move during a load transient, e.g. the AC part of a ±3 % spec on a 0.9 V rail: 27 mV.
• Copy tolerance from DC load fills the AC voltage tolerance from a DC load's tolerance: ± its tighter side, from the voltage of the VRM feeding it (2 % for -2 % / +5 %). A DC tolerance is the whole budget, and the DC drop uses up part of it, so lower the value if the AC part is smaller.
• Subtract DC drop at the load takes the DC drop the copper causes at the selected load's own pins off the AC voltage tolerance, so what is left is the budget for the transient. It reads the last DC solve: its effective voltage there (supply pins minus ground pins) against the set voltage of the VRM driving it, so solve the power tree on the DC tab first — without a result for that load the button stays disabled and says so. A load above its set voltage (a remote-sensed VRM raises pins near it) has its boost subtracted just the same, since it eats the same symmetric window. Each click subtracts again.
• Subtract VRM DC accuracy takes the DC accuracy of the LDO or switcher driving the probe's rail off the AC voltage tolerance: the larger side of it (20 mV for -1 % / +2 % of 1 V), as the output may already sit that far from its set voltage. It shows a menu when several VRMs drive the rail; each click subtracts again.
• Load step (ΔI): the size of the current step.
• Copy current from DC load fills the load step from a DC load's current, a step from no load to all of it. Lower it if the device's current steps by less.
• Load step slew rate: how fast it steps, A/µs; 10 A/µs until you change it.

Then Z_target = V_AC / ΔI, flat up to f_target = 1 / (π · t_rise), with t_rise = ΔI / slew rate. Use for probe fills the probe's target fields; the inputs are remembered for next time. The target applies above the VRM's control loop bandwidth (Targets and the VRM bandwidth).

The target impedance method was introduced by L. D. Smith, R. E. Anderson, D. W. Forehand, T. J. Pelc and T. Roy, "Power Distribution System Design Methodology and Capacitor Selection for Modern CMOS Technology," IEEE Transactions on Advanced Packaging, vol. 22, no. 3, pp. 284–291, Aug. 1999.

Copper resistivity and the via plating rules come from the DC setup's Copper and Mesh tabs.

Below the tabs: Rail lists each VRM and its output net; Ground lists the ticked nets with grounds first, defaulting to the VRM's ground pins' net. Solve rail saves the setup and runs the sweep; problems that stop it are listed in red above. The log shows the field solves as they go.

Tick HTML report next to Solve rail to also write <board>_<rail>_ac_report_<date>_<time>.html next to the board after each rail's solve; the report opens in your web browser when the rail finishes solving, and Report opens the shown rail's report again later. See AC HTML report.

Each rail keeps its last result: switch Rail to look at another rail's curves without solving again. If you change the rail while a solve is running, the result is kept for its own rail and the notes say so.

The Impedance tab in the middle plots |Z| against frequency on log-log axes: one solid curve per probe and, dashed in the same color, its target. Hovering shows every probe's |Z| at the frequency under the mouse in the line above the plot.

Cursor

The Info box shows the cursor's frequency, |Z|, phase, R and X, the reactance as an equivalent L or C, the target there with PASS/FAIL and the margin in dB (positive is below the target), and every other probe's |Z| at the same frequency.

Screenshot… in the toolbar saves the plot as a PNG while its tab is showing.

The Board map tab shows the solve from above, as in the HTML report: the solver's mesh of the rail (copper colored) and its ground (blue-gray), the board outline, the probes as red stars, and the capacitors in the model as dots, one color per capacitor model. Capacitors between the rail and ground that have no model, and so are left out, are crossed. The view is fixed, always fitted to the board.

The map fills in while the rail solves: the parts as soon as the solve starts, then the mesh once it is built. The tab comes to the front for the solve; the Impedance tab comes back to the front when the results arrive.

The map belongs to each rail's result, so switching Rail shows that rail's map, and saved results keep it. Results saved by KiPI before 0.7.2 have no map.

Below the table, the notes give the rail's nets and ground, the number of capacitors and series links included, the total plane capacitance, the solve size and time, capacitors left out for having no model, and any warnings. Export CSV… writes |Z|, R and X of every probe at every frequency. Save results… writes every rail solved so far to a .kipi-ac-results file (named with the board and the time by default); Open results… in AC mode brings them back, each under its VRM in Rail. Rails whose VRM is no longer in the setup are left out.

With HTML report ticked, each rail's solve also writes <board>_<rail>_ac_report_<date>_<time>.html next to the board; the time stamp keeps every solve's report. Like the DC report, it is a single offline file you can email. It holds:

• a summary and the probe table: pins, minimum and worst |Z|, the target, the margin in dB at the worst point (positive passes), PASS/FAIL, and an overall verdict;
• an interactive impedance plot of |Z| at every probe, with the targets dashed. Drag to zoom, double-click to reset, hover for f, |Z|, R and X. Click a legend entry to hide or show a curve. The grey dotted curves, hidden at first, are each capacitor model on its own (one part, without mounting), useful for matching dips to capacitor banks;
• a board map seen from the top: the board outline, the rail's copper on every layer merged, the probes as stars and each capacitor colored by its model. Capacitors left out for having no model show as grey crosses;
• the capacitor models (C, ESL, ESR, self-resonance, how many parts and which), the series links, the sweep, mesh and copper settings, and the solver's size, backend and time;
• notes: capacitors left out and any warnings.

If the report can't be written, the log says why; the solve's results are kept either way.

• Falling at −20 dB/decade (|Z| ∝ 1/f): capacitive. At the low end this is the bulk capacitance; since the VRM is not modeled, the curve keeps rising toward low frequency.
• Dips: series resonances, where a capacitor bank's C and its ESL plus mounting inductance cancel. The depth is set by ESR.
• Peaks between dips: anti-resonances, where one bank's inductance resonates with the next bank's capacitance. These are usually where a target fails. Fix them with more or lower-ESL parts, more value overlap between banks, or extra damping (ESR).
• Rising at +20 dB/decade (|Z| ∝ f): inductive. The capacitors' ESL and their mounting (pad, via and spreading inductance) dominate. Place the cursor here: Info shows it as an equivalent inductance. Shorter, wider connections and more vias lower it.
• Sharp peaks at high frequency: plane-pair cavity resonances. Their frequencies come from the board's dimensions and stackup.
• Phase near −90° is capacitive, near +90° inductive, near 0° resistive.

1. Tick the rail and its ground in the Nets list; untick everything else.
2. VRMs tab: Add a Source on the regulator's output pins at the set voltage. Add its ground pins.
3. Loads tab: Add each consumer with its current, tolerance and ground pins.
4. Solve all. Check the Loads table. For a FAIL, double-click the row, choose Voltage, and click around the load's pins to see where the drop comes from.
5. Switch to Current density with Arrows to find the bottleneck, change the layout in KiCad, and use Load from KiCad and Solve all again.

1. Tick every rail in the chain and the ground.
2. Add the input as a Source (e.g. the 12 V connector).
3. Add the switcher as Switcher with its efficiency, output pins (inductor), Input pins on the 12 V net, and ground pins.
4. Add the LDO as LDO with its quiescent current, dropout and Input pins on the switcher's output.
5. Add loads on each rail and solve. The VRMs table shows each converter's input current, which includes everything downstream, and its conversion loss.
6. Set Input range and Dropout to catch a regulator starved by upstream drop: its loads show VRM OUT OF REGULATION.

1. Add the VRM and set phase 1's output pins (its inductor), input pins and ground pins.
2. Set Phases to the number of phases. Each new phase takes the next parts in sequence (phase 1 on L1 and Q1 gives phase 2 L2 and Q2), or the same parts on the next sheet of a board annotated by sheet (L101 → L201), or copies the previous phase when there is no next part.
3. Choose each phase in Edit phase to check its pins, and change any that are wrong.
4. Set the shared set voltage, type, efficiency and sense pins once.

Each phase carries an equal share of the output current and settles at whatever voltage its copper needs. The VRM regulates its sense pins or, without them, the average of its phase outputs. The VRMs table lists each phase under its VRM: unequal phase voltages show a layout imbalance.

1. On the VRM, set Sense pins to the point the feedback trace connects to (often the load's supply pins).
2. For differential sensing, also set Ground sense pins on the ground net (the VRM needs ground pins too).
3. Solve. The sense point sits exactly at the set voltage; pins nearer the VRM read above it (a boost). The tolerance check catches both directions.

When some rails are not routed or modeled yet, open the Solve tab and untick their groups. The rest solves, with the substitutions described under Solve tab. Untick the group a Cannot solve message names to get past a setup problem while you fix it.

1. Thermal tab: tick Electro-thermal co-simulation, set ambient and airflow, and limits for maximum temperature and rise.
2. On the Vias results tab, set the Current limit per via from your fab's via current rating (it starts at 1 A).
3. Solve all (electro-thermal). Read the Thermal tab for the hottest point per layer, and sort the Vias tab by current for overloaded vias.
4. Use the Temperature field to see the map; double-click a Thermal row to jump to its group.

1. Make sure the rail has a VRM (Source is fine), and tick the rail, its ground and any nets joined by series links.
2. Switch to AC. Capacitors tab: Models from values, then enter ESL and ESR for each model from the datasheets.
3. Probes tab: add a probe on the device's power and ground pins. Use the calculator for the target, or a custom mask from the device vendor.
4. Solve rail. In the plot, put the cursor on the worst peak (the table's Worst |Z| tells you where).
5. Change capacitor models (values, counts by re-assigning parts) or the layout, and solve again. Each probe's margin in dB shows the improvement.
6. To compare rails, solve each and switch between them with Rail; each keeps its last result for the session.

Capacitors listed under "have no model and were left out" are not part of the result: give them a model or confirm they really do not belong on this rail.

• Save snapshot… stores the board; anyone with KiPI can open it with Open snapshot…, or with Open… in standalone KiPI, without KiCad or your design files.
• Keep <board>.kipi-setup.yml in version control next to the board.
• Tick HTML report for a single file you can email: it needs nothing but a browser.
• Export ▾ → Save results… (DC) or Save results… (AC) lets you reopen a long solve later with Open results….

Enable Preferences → Plugins → Enable KiCad API and restart the PCB editor. The first start builds a Python environment and downloads a few hundred MB, which can take several minutes. If the button never appears, right-click the action in Preferences → Plugins and choose Recreate Plugin Environment. On macOS, select a Python 3.10–3.13 interpreter there.

More than one KiCad project manager or standalone PCB editor is open, and KiPI cannot tell which one holds your board. Close the others (the message lists them with their process IDs) and start KiPI again from the PCB editor of the board you want. If you know the check is wrong, set the environment variable KIPI_ALLOW_MULTIPLE_KICAD=1 to skip it. If the running programs cannot be listed, KiPI carries on.

• No suitable Python: the launcher needs Python 3.10 to 3.13 and names the ones it found. Install one from python.org (on Linux, also python3-venv).
• The setup failed: the message says why, and the launcher's log (in logs next to KiPI's environment) has everything the installer printed. Check the network connection and free disk space, then start the launcher again; it picks up where it stopped. python kipi_launcher.py --repair starts over.
• A message box says to use a terminal: that Python has no tkinter for the setup window. Run python kipi_launcher.py in a terminal and answer there.

• Zones have no copper: they were saved unfilled, and KiPI does not fill zones. Fill them in KiCad (B), save, and Reload. The board summary lists unfilled zones under Placeholders.
• Copper looks out of date: KiCad fills zones when asked, not on every edit. Refill and save in KiCad after moving copper.
• "saved by KiCad 6 or older": open the board in KiCad 7 or later, save it, and open it again.

• "not an ODB++ job": the archive has no matrix/matrix file, e.g. a zip of Gerbers. Export ODB++ from the design tool.
• "no netlist": the job has no eda/data; export it with its netlist, or KiPI cannot tell which copper is which net.
• A net from KiCad has a different name: KiCad's ODB++ export writes spaces in net names as underscores. Pick the net again in the setup.
• A copper drawing carries no current: some exporters (KiCad among them) do not say which net drawn copper is on. KiPI gives it the net of the copper it touches; on its own it has none.

KiPI is already open, perhaps minimized or behind KiCad; the button brings it to the front. If it is not open and still does not start, check the session log for a stale lock and delete kipi-<user>.lock (kipi-standalone-<user>.lock for standalone KiPI) from the temporary folder.

• Check 3D Models is ticked in Display. Over results it starts unticked.
• The log says why. KiPI needs KiCad's kicad-cli: it looks in the connected KiCad, the PATH, the usual install folders and a Flatpak KiCad. Otherwise set the environment variable KIPI_KICAD_CLI to its full path.
• It also needs the board's .kicad_pcb on disk, next to the project or the snapshot. A snapshot opened on another machine usually has none.
• A part whose model file KiCad cannot find is named in the log with the missing path; KiCad's own 3D viewer shows the same gap. Fix the path in the footprint's 3D model settings and save the board.

Pickers only offer nets ticked in the Nets list. Tick it (untick Power & ground only or use the filter to find a signal net).

Before solving, KiPI checks that every load pin has a path to its VRM through copper or series links, and its ground pins to the ground reference. A pin without one draws nothing, and the Notes tab lists it:

• Some pins of a load unconnected: its current is drawn through its other pins. A pin group with no pin connected draws nothing.
• No supply pin, or no ground pin, connected: the load's current is left out of the solve and it shows as DISCONNECTED.
• A rail where no load is connected at all: the solve stops with Cannot solve. So does an unconnected VRM pin.

The cause is usually unrouted copper, an unfilled zone (keep Refill zones on), or a part in series that needs a series link. Show the net in 3D and look for the gap.

Thermal reliefs, necked traces and too few vias dominate DC drop. Use Current density with Arrows, and the Vias table sorted by current. Compare the 3D copper with KiCad: KiPI only sees filled copper.

The iterative solver did not reach its tolerance on a very large group. Raise Max edge to shrink the problem, or install the optional PARDISO solver (see the README) for a direct solve of up to 1M unknowns.

Raise Max edge, analyze fewer nets at once, and untick unneeded groups in the Solve tab. In AC, lower Field solves per decade or raise Min edge. Large planes are cheap; long fine traces are not. PARDISO helps a lot on large boards (Windows and Linux, x86-64).

• Check the notes for capacitors left out for having no model.
• Check every model's ESL and ESR units (nH and mΩ).
• Check the probe's ground pins are on the ground being simulated.
• Remember the VRM is not modeled: the low-frequency rise is expected.
• Raise Field solves per decade if resonances look jagged.

Open an issue at github.com/drewsum/KiPI/issues. Attach the session's .log and .crash.log, the text from About → Copy version info, and if you can, a board snapshot and setup file that show the problem.