Circuit simulation enhancements (lp:#1814188)

[Original report](https://bugs.launchpad.net/bugs/1814188) created by **Evan Shultz (evan-shultz)**

After playing around with the circuit simulator I've culled a list of
things that I took for granted in other tools and miss in KiCad. I will
attach to this bug a few archived simulation circuits to help illustrate
the items below. Hopefully these suggestions would flesh out the simulation
capability of KiCad and help many users. Some have been taken from
https://github.com/KiCad/kicad-symbols/issues/418.

I realize this is quite a number of items and I can separate them into
unique bugs if desired. Since they do form a theme, at least to me, I'm
submitting them together.

The circuits attached here (and others I've created, if you're interested),
are available if you'd like to include them with KiCad as demos. I'm happy
to update the existing simulation demos to use more attractive and
standardized symbols (including the sources I submitted at
https://github.com/KiCad/kicad-symbols/pull/1473) as well as show off
measurements and other features which may not be obvious.

- [x] Support more SPICE directives (see
http://ngspice.sourceforge.net/docs/ngspice-manual.pdf, and also referenced
below):
.op (displays ".op: no such command available in ngspice" even though it's
on page 258)
.control (see page 295 of the manual; seems to have no effect but maybe I'm
doing it wrong)
.plot (see manual page 275 but seems to have no effect; maybe I'm doing it
wrong)
.print (see manual page 274 but seems to have no effect; maybe I'm doing it
wrong)
.probe (see manual page 276 but seems to have no effect; maybe I'm doing it
wrong)

- [ ] Allow multiple plots to be shown at once. Often one will want to see
sets of waveforms correlated on the X axis but broken up into multiple
plots. This avoids blowing out the scale if one waveform is 1V peak and
another is 100V peak. Or if there are simply too many waveforms to be
easily understood if they're shown at once. Or if it's logical to break up
the waveforms into groups. It is not common (in my experience with multiple
SPICE simulators) to only allow a single plot to be shown at once for just
this reason.

- [ ] Add a measurement pane in the Spice Simulator window near the plot area
so measurements can be easily viewed and correlated with waveforms. This is
especially important when the simulation is stepped so the measurements can
show differences between each step that may be hidden by nearly overlapping
waveforms. LTSpice IV places measurements in the SPICE Error Log which is
hard to find and must be opened after the simulation completes. Every.
Single. Time. Ugh. See included "measurement_pane.png" for a nice example
of how this can be done in another simulator; below the plot you will see
10 steps in the simulation and 12 measurements performed at each step.

- [x] Instead of a fixed list of signals that can be plotted, allow signal
names to be added by typing them in. This is often faster for users that
know the syntax. If I connect a non-polarized component "backwards", like a
resistor, plotting "-I(R4)" is easier that editing the schematic to flip
R4's pins. It would also allow plotting a differential signal between any
two nets, with other simulation tools using "v(<net1>,<net2>)" syntax.
Performing simple math functions, such as "v(out)/10" to show the output
voltage at 1/10th the real value in amplitude, is another reason (easy
scaling/comparison with other signals on the same plot). Having a GUI to
create differential signals and scaled signals would work, but typing in
signals is quick and easy and doesn't depend on a GUI to be created.

- [~] _Provide other signal types besides just voltage and current. Power
("w(<ref des>)"), logarithm (for example "db(v(<net>))"), etc. are all
common and powerful signal types that one may want to plot. This relates to
the above item as these signals types are neither listed nor can be
manually typed in._

Moved to https://gitlab.com/kicad/code/kicad/-/issues/6985.

- [~] Clicking on a signal name (or hovering over it) in the Signals pane and
pressing Delete should remove the signal. Similarly, clicking on a cursor
and pressing Delete should remove that cursor.

- [~] The command "Hide Signal" actually deletes a signal. Actually "hiding" a
signal would no longer show the signal in a plot (or perhaps dim it) but
save the signal so it to be made visible again later. This is a useful
feature and I would like to see "Hide Signal" do what it says on the tin
and add a true "Delete Signal" command as well. This nomenclature
opaqueness also is present with cursors.

- [~] A huge amount of real estate could be saved if a legend of the plotted
signals were shown inside the plot. This would better correlate color with
signal name by putting them physically closer together in the window and
furthermore eliminate the entire Signals section of the Spice Simulator
window. This would be similar to the View > Show Legend feature but make
this an integrated part of the plot window instead of a small overlay which
consumes some of the plot area and only duplicates information.

- [~] _There is no need for "Voltage" on the top left and "Current" on the top
right of every plot if only one unit is being used. This relates with the
items above about being able to perform math functions on signals which
would result in other units and supporting other signal types (power, dB
voltage, etc.)._

- [x] It is not clear what cursor belongs to what signal. Perhaps the cursors
could stay with a dashed style but pick up the color of the associated
signal?

- [~] _Add seek functions for cursors, finding the nearest peak, nearest
valley, max, min, etc. This is common in other SPICE simulators._

Moved to: https://gitlab.com/kicad/code/kicad/-/issues/2321

- [x] White is one of the colors for a signal. As the plot grid and labels
are white, and also the background of the Signals pane, this is a poor
color choice. White signals are still visible in the plot window, at least,
but in the Signals pane a white color swatch completely disappears.

- [~] _There is no correlation between plotted signals and the schematic. It
would be helpful to indicate plotted nets, perhaps by adding some symbol or
icon to the net (or part in the case of power) with the color of the signal
in the visible plot._

Moved to: https://gitlab.com/kicad/code/kicad/-/issues/11254

- [x] It is common to print DC bias point voltages and currents on the
schematic for each net after simulation. This is not possible in KiCad now.
Often I see it as floating text box with a line to the net/component, or as
a small bubble embedded into the net. This is quite helpful for voltage
dividers and other simple circuits where only DC voltages and currents are
needed since it allows performing the simulation and seeing the results in
one place (not having to go to the Simulation window). A way to re-run the
simulation from within Eeschema would be needed to fully realize this item. https://gitlab.com/kicad/code/kicad/-/issues/11253

- [x] Save the open plot(s) + signal(s) when the simulator is closed and open
the same plot(s) + signal(s) after the next simulation. This would help if
the simulator is closed or if the project is sent to someone else so they
can jump in right away, seeing the waveforms the previous person had
configured. This feature should be an option so viewing the previous
plots/signals can be turned on or off with it defaulting to turned on.
Done, workbooks cover this. 

- [x] Allow saving of plot(s) + signal(s) to an external file for recall
later. This will allow setting up a series of plots and waveforms and then
recalling them in groups as desired. It's often helpful to have some
logical groups of plots and signals in those plots. This would also help
with the above item as these could be recalled upon launching the
simulation, or when sharing data with another person.
Done, workbooks cover this. 

- [ ] It does not appear that any possible "\<ident>" can be used in a .param
statement (see page 54 of the ngspice manual for info about this
statement). There is some conflict if a reserved \<ident> is used (like "dc"
which does not converge; see in my precision_rectifier project where I
called one param "vdc" since "dc" didn't work). It would be most helpful if
KiCad could address this under-the-hood so the user can choose any \<ident>
they desire.

- [ ] Combine colors on a plot when waveforms overlap. Currently, if two
waveforms lay on top of each other for any distance along the X axis one
waveform will be covered up and completely invisible. This is required, of
course, if the points are printed to the same pixels on the display and not
if the points are exactly identical.

- [~] _Using the .meas SPICE directive requires putting a forward slash ("/")
in front of the net name if the net has a label. See the diff_amp
simulation I attached. While this is shown in the UI (for example "V(/out)"
in the Signals section of the Spice Simulator window), it's not obvious and
means the text typed when creating the label doesn't match the text typed
when referencing the label in a measurement.  This is required as the label can appear on more than one included sub-page, in which case it will have the subpage before it in the path string._

- [x] Display node voltages in SI units instead of exponential format with
three significant digits (such as "5.72449e+005"). Showing "u" (or the
actual Greek letter mu), "m", "k", "M"/"Meg", etc. is much more clear if a
user really needs to dig into this part of the simulation output, and for a
bias point simulation this is the most salient way to understand the
desired result.

- [ ] If repeated analysis isn't supported, implement it and add a GUI to
configure it. This is a critical part of any simulation tool and is sorely
missed. I've often integrated repeated analysis with using measurements as
described in item 3 above. Creating steps in ngspice using the .control
directive is painful, if it even works (maybe I'm doing it wrong in the
precision_rectifier or high_side_v_i_converter simulations?). Apparently
ngspice doesn't support the easy .step directive for repeating the
simulation with some variation (page 295 of the manual).

- [x] The included version of ngspice isn't anywhere I can find. Not printed
in the console during a simulation and not in Help > About. As updates are
released regularly, knowing the included version with KiCad would be
important in some cases. For example,
https://sourceforge.net/p/ngspice/feature-requests/33/ shows that a feature
was added to ngspice based on a user request/issue but then how does one
know if that feature is available in KiCad without knowing the ngspice
version? I see "<KiCad install location>\lib\ngspice" that looked
promising, but the files in that folder don't look like an executable that
I could query from a command line (and that's not really the point of this
request anyway).

- [x] It seems all pieces of text are passed to ngspice as parameters (the
precision_rectifier simulation has several instances of "<: no such command
available in ngspice" in the output). Only text strings that start with a
period, and hopefully any new line even if it's within a block of text,
should be recognized as spice directives.

- [~] _The simulation output at the bottom left of the Spice Simulator window
has lots and lots of information. Most of it isn't helpfully for a properly
configured and working simulation. I would think just putting error
messages and actual output (like measurements and bias point info) is best
and then hiding the rest of the info. Simulation > Show SPICE netlist takes
a similar approach by allowing the user to see what's going on but not
inundating them with it each simulation run. Having separate areas for
"under the hood" and "the user wants to see this" info may clean things up
and would certainly make it easier to find the desired output in all the
text displayed._

- [x] I find it convenient to paste a model or subcircuit as text onto the
schematic canvas and then use that for simulation rather than having a
separate file with the model/subcircuit. Using text on the schematic also
improves portability. While it appears that the SPICE netlist includes a
model/subcircuit if I place text on the scheamtic page, I'm not able to
make this work. If I leave the Si2304 subcircuit text in the
high_side_v_i_converter simulation I see a variety of problems (an error
message about a vector that I didn't record, "Error: there aren't any
circuits loaded.", KiCad simply crashing, the simulation completes but the
node voltages change, etc.) that go away when the text is removed. In the
simple_transistor simulation I know the symbol is picking up the text on
the schematic because I chose the 2N3904 symbol from the existing
Transistor library and if I change the text of the model name (say to
"a2n3904") I see an error message ("Error on line 5 :\q1 0 /npn_on_b
/npn_on_c 2n3904\could not find a valid modelname"). LTspice, for example,
recognizes models pasted onto the schematic (even supporting "+" for a
multi-line model) but not subcircuits.

```
Application: kicad
Version: (6.0.0-rc1-dev-1521-g81a0ab4d7), release build
Libraries:
    wxWidgets 3.0.4
    libcurl/7.61.1 OpenSSL/1.1.1 (WinSSL) zlib/1.2.11 brotli/1.0.6
libidn2/2.0.5 libpsl/0.20.2 (+libidn2/2.0.5) nghttp2/1.34.0
Platform: Windows 8 (build 9200), 64-bit edition, 64 bit, Little endian,
wxMSW
Build Info:
    wxWidgets: 3.0.4 (wchar_t,wx containers,compatible with 2.8)
    Boost: 1.68.0
    OpenCASCADE Community Edition: 6.9.1
    Curl: 7.61.1
    Compiler: GCC 8.2.0 with C++ ABI 1013

Build settings:
    USE_WX_GRAPHICS_CONTEXT=OFF
    USE_WX_OVERLAY=OFF
    KICAD_SCRIPTING=ON
    KICAD_SCRIPTING_MODULES=ON
    KICAD_SCRIPTING_PYTHON3=OFF
    KICAD_SCRIPTING_WXPYTHON=ON
    KICAD_SCRIPTING_WXPYTHON_PHOENIX=OFF
    KICAD_SCRIPTING_ACTION_MENU=ON
    BUILD_GITHUB_PLUGIN=ON
    KICAD_USE_OCE=ON
    KICAD_USE_OCC=OFF
    KICAD_SPICE=ON
```
Original tags: eeschema ngspice

Story points: 20.0