UoN / SACAMOS

User-Manual.html 41.5 KB
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<!------------------------------------------------------------------------------------------------->
<!--                            User-Manual.html                                                 -->
<!--                           ------------------                                                -->
<!-- Description : This is the main page for the gSpiceUI project.                               -->
<!-- Started     : 2014-01-01                                                                    -->
<!-- Last Update : Refer to the footer.                                                          -->
<!-- Copyright   : (C) 2014 by MSWaters                                                          -->
<!-- Note        : This document is formated according to the standard : XHTML 1.0 Strict        -->
<!--               (refer to http://www.w3.org/TR/xhtml1/)                                       -->
<!------------------------------------------------------------------------------------------------->

<html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<!------------------------------------------------------------------------------------------------->

<head>
  <title>GNU SPICE GUI - User Manual</title>
</head>

<!------------------------------------------------------------------------------------------------->

<body>

<a name="TOP"></a>

<h1>
  <center>
    GNU SPICE GUI<br>
    User Manual
  </center>
</h1>

<hr>

<!------------------------------------------------------------------------------------------------->

<h2><center>Table of Contents</center></h2>

<blockquote>

  1.    &nbsp; <a href="#INTRO"    > Introduction      </a><br><br>

  2.    &nbsp; <a href="#MNU_BAR"  > Menu Bar          </a>

  <blockquote>
    2.1 &nbsp; <a href="#MNU_FILE" > File Menu         </a><br>
    2.2 &nbsp; <a href="#MNU_SIM"  > Simulate Menu     </a><br>
    2.3 &nbsp; <a href="#MNU_SETGS"> Settings Menu     </a><br>
    2.4 &nbsp; <a href="#MNU_HELP" > Help Menu         </a>
  </blockquote>

  3.    &nbsp; <a href="#TOOL_BAR" > Tool Bar          </a><br><br>

  4.    &nbsp; <a href="#MAIN_WIN" > Main Window       </a>

  <blockquote>
    4.1 &nbsp; <a href="#LST_NODES"> Node List         </a><br>
    4.2 &nbsp; <a href="#LST_CPNTS"> Component List    </a><br>
    4.3 &nbsp; <a href="#NBK_ANA"  > Analysis Notebook </a><br>
    4.4 &nbsp; <a href="#NBK_TCTLS"> Console Notebook  </a><br>
    4.5 &nbsp; <a href="#STAT_BAR" > Status Bar        </a>
  </blockquote>

  5.    &nbsp; <a href="#TMP_FILES"> Temporary Files   </a>

</blockquote>

<br>
<hr size="5">

<!------------------------------------------------------------------------------------------------->

<a name="INTRO"></a><h2>1. &nbsp; &nbsp; &nbsp; Introduction</h2>
<br>

<p>
  The name <b>gSpiceUI</b> is an abbreviation of the project title <i><b>GNU SPICE GUI</b></i>,
  which is itself an acronym standing for <b>G</b>nu is <b>N</b>ot <b>U</b>nix, <b>S</b>imulation
  <b>P</b>rogram with <b>I</b>ntegrated <b>C</b>ircuit <b>E</b>mphasis, <b>G</b>raphical <b>U</b>ser
  <b>I</b>nterface.
</p>

<p>
  gSpiceUI is intended to provide a GUI for freely available electronic circuit simulation engines
  ie. <b>NG-Spice</b> and <b>GnuCAP</b>. If the <b>gEDA</b> (<b>G</b>NU <b>E</b>lectronic
  <b>D</b>esign <b>A</b>utomation) tool set is used the utility <b>gnetlist</b> is used to convert
  schematic files to netlist files, <b>Gaw</b> or <b>Gwave</b> (no longer supported) display
  simulation results and <b>gschem</b> (part of the gEDA tool set) is the preferred schematic
  capture application. gSpiceUI is useless without the software tools it depends on, credit should
  go to the authors of those tools.
</p>

<p>
  gSpiceUI can also be used in conjunction with the <b>KiCAD</b> tool set. KiCAD doesn't expose it's
  netlist utility like gEDA so this step must be performed by the user inside the schematic capture
  application <b>eeschema</b>. The import mechanism in gSpiceUI cannot be used in this case and as
  yet eeschema can't be envoked inside gSpiceUI. Gaw and Gwave are used to display simulation
  results.
</p>

<p>
  The gSpiceUI GUI is designed to be as consistant as possible between analysis types and simulation
  engines. The intention is to abstract the technical particulars from the user so that the focus
  may be on the simulation rather than the simulation engine or even the analysis type.
</p>

<p>
  Like all open source software gSpiceUI is a work in progress and probably always will be. It has
  been developed over a long period of time (since 2003) and has reached a relatively mature state.
  Experience in software development as well as using software in general has taught me that it's
  better to provide less functionality that works than more functionality that just promises a lot.
  Consequently, as a generally rule, bugs fixes and improvements to the underlying architecture will
  take precedence over new functionality. I believe this approach pays off in the long term.
</p>

<p>
  It is worth noting that whereas NG-Spice is derived from the SPICE code base, GNU-Cap is not.
  GNU-Cap is an independent implementation of the principals used to analyses electronic circuits.
  As a consequence analysis results can be generated using two independant mechanisms and then
  compared. This is one of the reasons for supporting more than one simulation engine; if the same
  or similar results can be achieved using two different simulation engines then it's likely that
  the simulation results will bear some resemblence to what actually happens in reality.
</p>

<p>
  It is important to realise that a simulation engine <b><i>models</i></b> the behaviour of a system
  and therefore can never be 100% accurate. In addition the simulation engine itself is an
  implementation in software of a mathematical model and so is also subject to bugs. As the
  underlying mathematical model and software implementation improve the simulation performance
  improves. One of the reasons for the choice of simulation engines to support was that they are
  both in constant development. (Not to mention the inherent goodness and righteousness of open
  source software, so I won't mention it.)
</p>

<p>
  The skills and judgement of the user have a profound impact on the usefulness of electronic
  simulation. It can be a technically demanding process requiring considerable thought, practice and
  persistence. The alternative is to go straight to building prototypes; in any case, ultimately
  prototypes must be created to finalize a design. However simulation is generally a rewarding step
  in the development process, even if it only provides a better understanding of the internal
  workings of a design.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="5">

<!------------------------------------------------------------------------------------------------->

<a name="MNU_BAR"></a><h2>2. &nbsp; &nbsp; &nbsp; Menu Bar</h2>
<br>

<p>
  The menu bar provides access to almost all of the functionality provided by gSpiceUI. However
  there are a few functions that can only be accessed via command line options.
</p>

<a name="MNU_FILE"></a><h3>2.1 &nbsp; &nbsp; File Menu</h3>

<p>
  This file menu contains options mainly associated with handling netlist and schematic files.
</p>

<h4>2.1.1 &nbsp; Open</h4>

<p>
  Open a netlist (circuit description) file containing component definitions and load it into the
  NetList text control. If the netlist contains simulation instructions gSpiceUI attempts to parse
  them and the settings are displayed in the GUI.
</p>

<p>
  Notes :
</p>
<ul>
  <li>
    Be aware that gSpiceUI will modify the netlist file; it will change the formatting and remove
    things it doesn't understand. If this isn't OK, create a copy of the netlist file and give that
    to gSpiceUI.
  </li>
  <li>
    When using the gEDA tool set the netlist file extension is ".ckt". For the KiCAD tool set the
    netlist extension is "cir". Be sure to specify the appropriate file extension for the tool set.
  </li>
  <li>
    There is an upper limit to the number of lines which may be displayed in any text control (the
    underlying file isn't truncated). This setting maybe adjusted by the user, refer to
    <i>2.3.2 Preferences Dialog</i>.
  </li>
</ul>

<h4>2.1.2 &nbsp; Import</h4>

<p>
  Import one or more schematic files. The utility gnetlist is used to convert the schematic file/s
  to a single netlist file. The netlist file name is automatically derived from the first schematic
  file name in the list with the file extension changed to ".ckt". Eg. if schem1.sch, schem2.sch,
  schem3.sch were specified as the schematic file names to be imported the netlist file name would
  be schem1.ckt.
</p>

<p>
  Notes :
</p>
<ul>
  <li>
    If you are using the KiCAD tool set Import won't work. The gEDA utility gnetlist can't convert
    KiCAD schematics to a netlist file. The netlist utility in KiCAD is built into the schematic
    capture application eeshema so gSpiceUI can't envoke it. The netlist file must be created or
    updated from within eeshema by the user and reloaded into gSpiceUI using the Reload operation.
    
  </li>
</ul>

<h4>2.1.3 &nbsp; Reload</h4>

<p>
  Reload the netlist file. If the netlist was imported from one or more schematic files, the import
  operation will be repeated. As far as possible the simulation settings shown in the currently
  displayed analysis notebook page are retained.
</p>

<p>
  When gSpiceUI is used to create a netlist file from schematic file/s it inserts a reference to the
  schematic file/s near the beginning of the netlist file. If the currently open netlist has this
  schematic reference, reload performs an import operation otherwise the netlist is simply reloaded.
  In either case the simulation settings shown in the currently displayed analysis notebook page are
  retained as far as possible.
</p>

<h4>2.1.4 &nbsp; Close</h4>

<p>
  If a netlist file is open then close it and resets all GUI parameters to default values.
</p>

<h4>2.1.5 &nbsp; Quit</h4>

<p>
  Close all files and child applications, delete temporary files if required and exit the
  application.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="MNU_SIM"></a><h3>2.2 &nbsp; &nbsp; Simulate Menu</h3>

<p>
  The simulate menu contains options associated with circuit simulation operations and provides
  access to other useful applications upon which gSpiceUI dependends.
</p>

<h4>2.2.1 &nbsp; Create</h4>

<p>
  Create a simulation file based on the values currently displayed on the GUI or the contents of the
  Simulation text control. Note, any changes made to the GUI have priority over changes made by the
  user to the Simulation text control contents.
</p>

<p>
  If any changes are made to the GUI control contents the simulation file is completely
  re-constructed, which then causes the Simulation control contents to be over-written and lost.
  However, if changes have been made to the Simulation text control contents alone then it is
  written verbatim to the simulation file.
</p>

<p>
  If a problem is encountered a message box is displayed giving a brief explanation as to why the
  operation could not be completed. The raw console spew generated by the process will have been
  sent to the Console text control, a careful perusal of this generally reveals the cause of the
  problem/s.
</p>

<h4>2.2.2 &nbsp; Run</h4>

<p>
  Run a simulation based on the values currently displayed on the GUI controls or in the Simulation
  text control. If the user has made changes since the last Create operation then a Create operation
  is automatically executed as described above.
</p>

<p>
  If the simulation file is created successfully then gSpiceUI attempts to run the simulation. The
  simulation results are formatted then sent to a data file (refer to section 5. Files) and are
  displayed in the appropriate Simulation Results text control.
</p>

<p>
  If a problem is encountered a message box is displayed giving a brief explanation as to why the
  operation could not be completed. The raw console spew generated by the process will have been
  sent to the Console text control, a careful perusal of this generally reveals the cause of the
  problem/s.
</p>

<h4>2.2.3 &nbsp; Stop</h4>

<p>
  Stop a running simulation immediately. This option can only be executed if a simulation is
  actually running. This is a useful option if a simulation is running too long or appears as if it
  won't converge.
</p>

<h4>2.2.4 &nbsp; Schematic</h4>

<p>
  Edit a schematic file. If there is a schematic file associated with an open netlist file it is
  opened using gschem and may be viewed or edited by the user. Note : if changes are made to the
  schematic file (and the schematic file has been updated on disk by gschem) then an Import
  operation must be performed in gSpiceUI in order for gSpiceUI to "know" about new the changes.
</p>

<p>
  It's important to be aware that gSpiceUI cannot run a simulation based on any old schematic file
  eg. generated by gschem. In fact, the simulation will fail unless the schematic is trivial or
  you're just lucky. Certain prerequisites must be met before a schematic may be simulated. The
  schematic must be translated into a form which can be interpreted by the simulation engine (eg. by
  gnetlist), in short everything must be explicitly defined. The extra information required over
  that sufficient for human readability is :
</p>

<p>
  <ul>
    <li>
      At present if the KiCAD tool set is used this function will not work. The KiCAD schematic
      capture application eeschema must be manually started by the user and the netlist file updated
      by the user from within eeschema whenever the schematic is changed. Perform a Reload operation
      and then proceed as normal.
    </li>
    <li>
      All power supply sources must be explicitly defined.
    </li>
    <li>
      All signal sources must be explicitly defined.</li>
    <li>
      Components not already defined in the simulation environment must be defined using models.
    </li>
    <li>
      Component labels must adhere to the rules specified for the simulation engine eg. resistor
      names always start with the letter 'R'. In particular be aware that often a model file
      contains a sub-circuit which must have a name starting with the character 'X'.
    </li>
    <li>
      Net labels must adhere to the rules specified for the simulation engine eg. they can't start
      with a digit. Refer to the specific simulation engine documentation.
    </li>
  </ul>
</p>

<p>
  Notes :
</p>
<ul>
  <li>
    In gschem, models may be included by setting the component's file attribute or by use of a SPICE
    Model object. Either way the component value is set to the model or sub-circuit label. Check the
    example schematics that come with gSpiceUI to see how it's done eg. the LM555 or operational
    amplifier examples.
  </li>
  <li>
    gSpiceUI recognizes a component type by the first letter of the component name eg. an inductor
    name is expected to start with the letter 'L'. The following is list of the first letter of
    various component types (this format is derived from NG-Spice) :
    <table cellspacing=0 cellpadding=0>
      <tr><td>&nbsp; &nbsp;</td><td>&nbsp; &nbsp; &nbsp;</td><td>&nbsp; &nbsp;</td><td></td></tr>
      <tr><td></td><td>B</td><td>-</td><td>Non-Linear Dependent Source</td></tr>
      <tr><td></td><td>C</td><td>-</td><td>Capacitor</td></tr>
      <tr><td></td><td>D</td><td>-</td><td>Diode</td></tr>
      <tr><td></td><td>E</td><td>-</td><td>Voltage Controlled Voltage Source</td></tr>
      <tr><td></td><td>F</td><td>-</td><td>Current Controlled Current Source</td></tr>
      <tr><td></td><td>G</td><td>-</td><td>Voltage Controlled Current Source</td></tr>
      <tr><td></td><td>H</td><td>-</td><td>Current Controlled Voltage Source</td></tr>
      <tr><td></td><td>I</td><td>-</td><td>Independent Current Source</td></tr>
      <tr><td></td><td>J</td><td>-</td><td>JFET (Junction Field-Effect Transistor)</td></tr>
      <tr><td></td><td>K</td><td>-</td><td>Coupled (Mutual) Inductors</td></tr>
      <tr><td></td><td>L</td><td>-</td><td>Inductor</td></tr>
      <tr><td></td><td>M</td><td>-</td><td>MOSFET (Metal-Oxide Semiconductor Field-Effect Transistor)</td></tr>
      <tr><td></td><td>O</td><td>-</td><td>Lossy Transmission Line (LTRA)</td></tr>
      <tr><td></td><td>P</td><td>-</td><td>Coupled Multi-conductor Transmission Line (CPL)</td></tr>
      <tr><td></td><td>Q</td><td>-</td><td>BJT (Bipolar Junction Transistor)</td></tr>
      <tr><td></td><td>R</td><td>-</td><td>Resistor</td></tr>
      <tr><td></td><td>S</td><td>-</td><td>Voltage Controlled Switch</td></tr>
      <tr><td></td><td>T</td><td>-</td><td>Lossless Transmission Line</td></tr>
      <tr><td></td><td>U</td><td>-</td><td>Uniform Distributed RC Transmission Line (URC)</td></tr>
      <tr><td></td><td>V</td><td>-</td><td>Independent Voltage Source</td></tr>
      <tr><td></td><td>W</td><td>-</td><td>Current Controlled Switch</td></tr>
      <tr><td></td><td>X</td><td>-</td><td>Sub-circuit</td></tr>
      <tr><td></td><td>Y</td><td>-</td><td>Single Lossy Transmission Line (TXL)</td></tr>
      <tr><td></td><td>Z</td><td>-</td><td>MESFET (Metal-Semiconductor Field Effect Transistor)</td></tr>
    </table>
  </li>
</ul>

<h4>2.2.5 &nbsp; View Results</h4>

<p>
  View simulation results in a graphical form. One of the simulation results files is opened using a
  data viewer application eg. Gaw or Gwave. The particular results file loaded into the viewer
  process dependents on the currently selected simulation results tab and analysis type
  tab.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="MNU_SETGS"></a><h3>2.3 &nbsp; &nbsp; Settings Menu</h3>

<p>
  The settings menu contains application configuration options.
</p>

<h4>2.3.1 &nbsp; Simulation Engine Selection</h4>

<p>
  The first section of the Settings Menu contains radio buttons allowing the selection of the
  electronic circuit simulation engine to be used. The analysis notebook is updated based on the
  chosen simulation engine, the selected simulation engine name is displayed in the status line and
  any simulation results are sent to the appropriate console tab.
</p>

<p>
  When the simulation engine is changed gSpiceUI attempts to transfer simulation information to the
  new simulator environment. The information is tranferred via the simulation file so if information
  appears on the GUI but not in the simulation file it will be lost. If this is a problem create a
  fresh simulation file prior to changing the simulation engine.
</p>

<h4>2.3.2 &nbsp; Preferences Dialog</h4>

<p>
  The preferences dialog contains the following settings :
</p>

<ul>
  <li>
    Waveform data viewer :<br>
      A choice box containing the available waveform data viewer utilities. The currently selected
      waveform data viewer utility name is displayed in the status line.
      <br>&nbsp;
  </li>
  <li>
    Temporary files :<br>
      A choice box containing the available temporary file management strategies, ie. automatically
      delete temporary files, prompt the user or just keep the temporary files. Most of the files in
      question contain simulation results data and may be useful outside gSpiceUI. Refer to section
      <a href="#TMP_FILES">5.&nbsp;Temporary&nbsp;Files</a>.
      <br>&nbsp;
  </li>
  <li>
    Main frame layout :<br>
      A choice box containing the available main frame layout schemes. The main has two layout
      schemes to choose from : longer probes (Nodes and Component) controls or a wider console
      notebook control.
      <br>&nbsp;
  </li>
  <li>
    Phase / angle units :<br>
      A choice box containing the available phase or angle units, ie. degrees or radians.
      <br>&nbsp;
  </li>
  <li>
    Results precision :<br>
      A choice box containing the available precisions which may be applied to simulation results.
      The data are rounded to the selected precision not just truncated.
      <br>&nbsp;
  </li>
  <li>
    gnetlist Guile backend :<br>
      A choice box containing the available gnetlist Guile backend procedures. This list of Guile
      backends is derived by querying gnetlist directly so whatever procedures gnetlist can detect
      are listed.
      <br>&nbsp;
  </li>
  <li>
    Max text control lines :<br>
      A value control which sets the maximum number of lines which may be displayed in any of the
      console text controls. Simulation results files can potentially be very large, this value
      allows the user to have some control over the system resources used by gSpiceUI.
      <br>&nbsp;
  </li>
  <li>
    Spin control period :<br>
      A value control which sets the period (in msec) between successive spin button control
      updates.
      <br>&nbsp;
  </li>
  <li>
    Tool tip delay :<br>
      A value control which sets the delay (in msec) before a tool tip is displayed.
      <br>&nbsp;
  </li>
  <li>
    Show tool tips :<br>
      A check box which enables or disables tool tips.
      <br>&nbsp;
  </li>
  <li>
    Sync. sweep sources :<br>
      A check box which enables or disables synchronization of the sweep sources. If a sweep source
      is selected in one analysis page, where possible the same source will appear in other analysis
      pages. Note : the sweep source value is not carried over between pages (I'm not convinced this
      behaviour would be helpful).
      <br>&nbsp;
  </li>
  <li>
    Sync. temperatures :<br>
      A check box which enables or disables synchronization of the ambient temperature values
      between analysis pages and the OPTIONS dialogue.
      <br>&nbsp;
  </li>
  <li>
    Keep the netlist file :<br>
      A check box which controls whether netlist files are included in the list of temporary files
      and therefore the temporary file management strategy.
      <br>&nbsp;
  </li>
  <li>
    gnetlist verbose mode :<br>
      A check box which enables or disables gnetlist verbose mode. With this enabled gnetlist
      generates lots of lovely console spew which appears in the Console tab of the console
      notebook. It's useful for debugging when gnetlist is have problems importing schematic file/s.
      <br>&nbsp;
  </li>
  <li>
    Include model defs. :<br>
      A check box which controls whether .INCLUDE directives are used for model files or the model
      file contents are inserted in the netlist file. )This option controls the the gnetlist SPICE
      backend "include_mode".)
      <br>&nbsp;
  </li>
  <li>
    Embed include files :<br>
      A check box which controls how gnetlist behaves when it encounters a .INCLUDE directive. With
      this option checked gnetlist embeds (inserts) the file contents into the netlist file. (This
      option controls the the gnetlist SPICE backend "embedd_mode".)
      <br>&nbsp;
  </li>
  <li>
    Fix component prefixes :<br>
      A check box which controls whether component label prefixes are automatically tested and
      modified if the incorrect prefix is used. SPICE recognizes different components based on the
      first character of the component label eg. R1 would be identified as a resistor. If an
      incorrect prefix is detected the correct prefix is prepended to the component label. (This
      option controls the the gnetlist SPICE backend "nomunge_mode".)
      <br>&nbsp;
  </li>
  <li>
    The paths to the various programs and utilities used by gSpiceUI may be manually set via this
    menu selection. (Not yet implemented)
  </li>
</ul>

<p>
  Note :
</p>
<ul>
  <li>
    All preferences work if the gEDA tool set is used but some aren't pertinent if the KiCAD tool
    set is used.
  </li>
</ul>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="MNU_HELP"></a><h3>2.4 &nbsp; &nbsp; Help Menu</h3>

<p>
  The Help Menu contains the following options :
</p>

<h4>2.4.1 &nbsp; User Manual</h4>

<p>
  Open the gSpiceUI HTML documentation in a HTML view window (more specifically this document). At
  the time of writing the HTML viewer only performs the basic functions (eg. it is monochrome) but
  it is sufficient for the purpose.
</p>

<h4>2.4.2 &nbsp; About</h4>

<p>
  Open a dialogue containing application "About" information.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="5">

<!------------------------------------------------------------------------------------------------->

<a name="TOOL_BAR"></a><h2>3. &nbsp; &nbsp; &nbsp; Tool Bar</h2>
<br>

<p>
  The tool bar contains buttons which give easy access to the most used functions. The buttons are
  presented in groups associated with the different types of activities. Refer to the matching menu
  bar function in section <a href="#MNU_BAR">Menu&nbsp;Bar</a>.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="5">

<!------------------------------------------------------------------------------------------------->

<a name="MAIN_WIN"></a><h2>4. &nbsp; &nbsp; &nbsp; Main Window</h2>
<br>

<p>
  The main window is made up of various display objects which are described in the following
  sub-sections. There are lists of possible test points, analysis settings, console output and a
  status bar.
</p>

<p>
  The main window title bar always contains at least the application name. If a file is open,
  whether it be a netlist or schematic file/s, the name of a netlist file will be appended to the
  normal window title banner. Keep in mind that this netlist file is the main file that gSpiceUI
  works on.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="LST_NODES"></a><h3>4.1 &nbsp; &nbsp; Node List</h3>

<p>
  Display the list of node labels extracted from the netlist file. One or more nodes may be selected
  (or deselected) by clicking on the node/s in the list with the mouse. The probes for the selected
  nodes will be calculated and included in the simulation results.
</p>

<p>
  A single node may be selected from the list by left clicking on it with the mouse. To select
  multiple nodes press the control key and left click on the desired nodes with the mouse. To select
  a range of nodes left click on the desired range with the mouse while holding down the shift key.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="LST_CPNTS"></a><h3>4.2 &nbsp; &nbsp; Component List</h3>

<p>
  Display the list of components extracted from the netlist file. One or more components may be
  selected (or deselected) by clicking on the component/s in the list with the mouse. The probes for
  the selected components will be calculated and included in the simulation results. At present only
  two terminal components are included in this list.
</p>

<p>
  A single component may be selected from the list by left clicking on it with the mouse. To select
  multiple components press the control key and left click on the desired components with the mouse.
  To select a range of components left click on the desired range with the mouse while holding down
  the shift key.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="NBK_ANA"></a><h3>4.3 &nbsp; &nbsp; Analysis Notebook</a></h3>

<p>
  There are two mildly different analysis notebooks associated with the two simulation engines
  supported by gSpiceUI ie. GNU-Cap or NG-Spice. Each analysis notebook contains analysis pages
  reflecting the various analysis types supported by the associated simulation engine. The following
  brief outlines the various analysis types current supported. For further information refer to the
  user documentation for the appropriate simulation engine (much of what follows is taken from this
  documentation).
</p>

<h4>4.3.1 &nbsp; Operating Point Analysis</h4>

<b>NG-Spice :</b>

<blockquote>
  This analysis type is supported using the DC command in NG-Spice. The DC analysis determines the
  DC operating point of the circuit with inductors shorted and capacitors opened. In this instance
  the DC analysis is used to generate DC transfer curves for temperature stepped over a
  user-specified range and the DC output variables are stored for each sequential temperature value.
</blockquote>

<b>GNU-Cap :</b>

<blockquote>
  Performs a nonlinear DC steady state analysis. If a temperature range is given, it sweeps the
  temperature. If there are numeric arguments, they represent a temperature sweep. They are the
  start and stop temperatures in degrees Celsius, and the step size, in order. This command also
  sets up the quiescent point for subsequent AC analysis. It is necessary to do this for nonlinear
  circuits. The last step in the sweep determines the quiescent point for the AC analysis.
</blockquote>

<h4>4.3.2 &nbsp; DC Analysis</h4>

<b>NG-Spice :</b>

<blockquote>
  The DC analysis determines the DC operating point of the circuit with inductors shorted and
  capacitors opened. A DC analysis is automatically performed prior to a Transient analysis to
  determine the transient initial conditions, and prior to an AC small-signal analysis to determine
  the  linearized, small-signal models for nonlinear devices. The DC analysis can also be used to
  generate DC transfer curves : a specified independent voltage, current source, resistor or
  temperature is stepped over a user-specified range and the DC output variables are stored for each
  sequential source value.
</blockquote>

<b>GNU-Cap :</b>

<blockquote>
  Performs a nonlinear DC steady state analysis, and sweeps the signal input, or a component value.
  If there are numeric arguments, without a part label, they represent a ramp from the generator
  function. They are the start value, stop value and step size, in order. In some cases, you will
  get one more step outside the specified range of inputs due to internal rounding errors. The last
  input may be beyond the end point. The program will sweep any simple component, including
  resistors, capacitors, and controlled sources.
</blockquote>

<h4>4.3.3 &nbsp; AC Analysis</h4>

<b>NG-Spice :</b>

<blockquote>
  The AC small-signal analysis determines the output variables as a function of frequency. The DC
  operating point of the circuit is first determined and used to generate linearized, small-signal
  models for all of the nonlinear devices in the circuit. The resultant linearized version of the
  circuit is then analyzed over a user-specified range of frequencies. The desired output of an AC
  small-signal analysis is usually a transfer function (trans-impedance, voltage gain, etc.). If the
  circuit has only one AC input, it is convenient to set that input to unity and zero phase, so that
  output variables have the same value as the transfer function of the output variable with respect
  to the input.
</blockquote>

<b>GNU-Cap :</b>

<blockquote>
  Performs a small signal, steady state, AC analysis. Sweeps frequency. The AC command does a linear
  analysis about an operating point. It is absolutely necessary to do an OP analysis first on any
  nonlinear circuit. Not doing this is the equivalent of testing it with the power off. If the start
  frequency is zero, the program will still do an AC analysis. The actual frequency can be
  considered to be the limit as the frequency approaches zero. It is, therefore, still possible to
  have a non-zero phase angle, but delays are not shown because they may be infinite.
</blockquote>

<h4>4.3.4 &nbsp; Transient Analysis</h4>

<b>NG-Spice :</b>

<blockquote>
  The Transient analysis determines the transient output variables as a function of time over a
  user-specified time interval. The initial conditions are automatically determined by a DC
  analysis. All sources which are not time dependent (for example, power supplies) are set to their
  DC value.
</blockquote>

<b>GNU-Cap :</b>

<blockquote>
  Performs a nonlinear time domain (transient) analysis. Do not use a step size too large as this
  will result in errors in the results. If you suspect that the results are not accurate, try a
  larger argument to skip. This will force a smaller internal step size. If the results are close to
  the same, they can be trusted. If not, try a still larger skip argument until they appear to match
  close enough. The most obvious error of this type is aliasing. You must select sample frequency at
  least twice the highest signal frequency that exists anywhere in the circuit. This frequency can
  be very high, when you use the default step function as input. The signal generator does not have
  any filtering.
</blockquote>

<h4>4.3.5 &nbsp; Fourier Analysis</h4>

<b>NG-Spice :</b>

<blockquote>
  Not yet implemented.
</blockquote>

<b>GNU-Cap :</b>

<blockquote>
  Performs a nonlinear time domain (transient) analysis, but displays the results in the frequency
  domain. Actually, this command does a nonlinear time domain analysis, then performs a Fourier
  transform on the data to get the frequency data. The transient analysis parameters (start, stop,
  step) are determined by the program as necessary to produce the desired spectral results. The
  internal time steps are selected to match the Fourier points, so there is no interpolation done.
</blockquote>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="NBK_TCTLS"></a><h3>4.4 &nbsp; &nbsp; Text Control Notebook</h3>

<p>
  The console notebook contains various text controls which display text data generated by the
  different operations initiated by gSpiceUI.
</p>

<h4>4.4.1 &nbsp; Console</h4>

<p>
  Display the console input/output for the last process executed by gSpiceUI. If an error occurs
  this is a good place to look for indications of what has gone wrong.
</p>

<h4>4.4.2 &nbsp; Circuit</h4>

<p>
  Display the raw netlist file which was opened or imported via the file menu. The variables and
  values contained in the netlist file are those displayed in the GUI's display objects.
</p>

<h4>4.4.3 &nbsp; Simulation</h4>

<p>
  Display the simulation file to be run. It is basically the netlist file plus simulator commands
  based on user input to the GUI objects. It can be manually edited by the user and will be run as
  is if the Run button is pressed. NOTE : if the create button is pressed the contents of this tab
  will be over-written destroying any user input.
</p>

<h4>4.4.4 &nbsp; NG-Spice Results</h4>

<p>
  Display the results from the last run of the NG-Spice simulation engine. The raw data is
  reformatted to aid readability; non-data records are removed and the precision is set according
  the value set in the Preferences dialog. If required the raw output from the simulation engine may
  be viewed in the Console tab.
</p>

<h4>4.4.5 &nbsp; GNU-Cap Results</h4>

<p>
  Display the results from the last run of the GNU-Cap simulation engine. The raw data is
  reformatted to aid readability; non-data records are removed and the precision is set according
  the value set in the Preferences dialog. If required the raw output from the simulation engine may
  be viewed in the Console tab.
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="1" width="80%" align="center">

<!------------------------------------------------------------------------------------------------->

<a name="STAT_BAR"></a><h3>4.5 &nbsp; &nbsp; Status Bar</h3>

<p>
  The status bar is located at the bottom of the application main frame. It consists of three panes
  which contain text messages showing the state of gSpiceUI. From left to right the panes contain :
</p>

<p>
<ol>
  <li> The last application status or error message.</li>
  <li> The currently selected simulation engine.</li>
  <li> The currently selected waveform viewer utility.</li>
</ol>
</p>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="5">

<!------------------------------------------------------------------------------------------------->

<a name="TMP_FILES"></a><h2>5. &nbsp; &nbsp; &nbsp; Temporary Files</h2>
<br>

<p>
  Whilst running gSpiceUI various temporary files may be generated in the directory occupied by the
  schematic or netlist file/s. To illustrate, consider the situation where the schematic file
  "test-cct.sch" is imported and every possible analysis type is run, using both NG-Spice and
  GNU-Cap. Along with the schematic file the following temporary files which would be created :
</p>

<blockquote>
  <table cellspacing=0 cellpadding=0>

    <tr>
      <td>&lt;path&gt;/sch/test-cct.sch</td><td></td>
      <td>(The schematic file to be analysed)</td>
    </tr>

    <tr><td>&nbsp;</td><td>&nbsp; &nbsp; &nbsp;</td><td>&nbsp;</td></tr>

    <tr>
      <td>&lt;path&gt;/sch/test-cct.ckt</td>       <td></td>
      <td>(Netlist file with simulation commands)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.sch~</td>      <td></td>
      <td>(Backup file to the schematic file)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/gspiceui.log</td>        <td></td>
      <td>(Temporary file for raw process output)</td>
    </tr>

    <tr><td>&nbsp;</td><td></td><td></td></tr>

    <tr>
      <td>&lt;path&gt;/sch/test-cct.ngspice.op</td><td></td>
      <td>(Results file - operating point analysis)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.ngspice.dc</td><td></td>
      <td>(Results file - DC analysis)</td>
      </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.ngspice.ac</td><td></td>
      <td>(Results file - AC analysis)</td>
    </tr>
<!-- <tr>
       <td>&lt;path&gt;/sch/test-cct.ngspice.di</td><td></td>
       <td>(Results file - distortion analysis)</td>
     </tr> -->
<!-- <tr>
       <td>&lt;path&gt;/sch/test-cct.ngspice.no</td><td></td>
       <td>(Results file - noise analysis)</td>
     </tr> -->
<!-- <tr>
       <td>&lt;path&gt;/sch/test-cct.ngspice.pz</td><td></td>
       <td>(Results file - pole-zero analysis)</td>
     </tr> -->
<!-- <tr>
       <td>&lt;path&gt;/sch/test-cct.ngspice.se</td><td></td>
       <td>(Results file - sensitivity analysis)</td>
     </tr> -->
    <tr>
      <td>&lt;path&gt;/sch/test-cct.ngspice.tr</td><td></td>
      <td>(Results file - transient response analysis)</td>
    </tr>
<!-- <tr>
       <td>&lt;path&gt;/sch/test-cct.ngspice.tf</td><td></td>
       <td>(Results file - transfer function analysis)</td>
    </tr> -->

    <tr><td>&nbsp;</td><td></td><td></td></tr>

    <tr>
      <td>&lt;path&gt;/sch/test-cct.gnucap.op</td> <td></td>
      <td>(Results file - operating point analysis)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.gnucap.dc</td> <td></td>
      <td>(Results file - DC analysis)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.gnucap.ac</td> <td></td>
      <td>(Results file - AC analysis)</td>
    </tr>
    <tr>
      <td>&lt;path&gt;/sch/test-cct.gnucap.tr</td> <td></td>
      <td>(Results file - transient response analysis)</td>
    </tr>
<!-- <tr>
      <td>&lt;path&gt;/sch/test-cct.gnucap.fo</td> <td></td>
      <td>(Results file - fourier analysis)</td>
    </tr> -->

  </table>
</blockquote>

<p>
  All file names begin with the prefix "test-cct" (taken from the schematic file name). File name
  extensions then depend on the file type. Files containing simulation results include the name of
  the simulation engine used to generate the data and an abbreviation indicating the analysis type.
</p>

<p>
  Notes :
</p>

<ul>
  <li>
    gSpiceUI has various mechanisms for managing temporary files (eg. delete them), refer to
    <a href="#MNU_SETGS">Settings&nbsp;Menu</a>.
  </li>
  <li>
    If temporary files are deleted this includes the schematic backup file.
  </li>
</ul>

<br>
<a href="#TOP"><center>Return to top</center></a>

<hr size="5">

<!------------------------------------------------------------------------------------------------->

<address>
  Last modified : 2016-11-10
  <br>
  Author : Mike Waters
  <br>
  E-Mail : mwaters517_AT_gmail_DOT_com
</address>

<!------------------------------------------------------------------------------------------------->

<style>
  <!--
    a:link    { color: #0022CC; text-decoration: underline }
    a:active  { color: #FF0000; text-decoration: none      }
    a:visited { color: #551A8B; text-decoration: underline }

    h1
    {
      color:           #E46103;
      font-family:     Arial, Verdana, Helvetica, Sans-Serif;
      font-size:       24pt;
      text-decoration: none;
      text-align:      center;
    }

    h2
    {
      color:           #CD1076;
      font-family:     Arial, Verdana, Helvetica, Sans-Serif;
      font-size:       20pt;
      text-decoration: none;
      text-align:      left;
    }

    h3
    {
      color:           #CD1076;
      font-family:     Arial, Verdana, Helvetica, Sans-Serif;
      font-size:       16pt;
      text-decoration: none;
      text-align:      left;
    }

    h4
    {
      color:           #008208;
      font-family:     Arial, Verdana, Helvetica, Sans-Serif;
      font-size:       14pt;
      text-decoration: none;
      text-align:      left;
    }
  -->
</style>

<!------------------------------------------------------------------------------------------------->

</body>
</html>