--- /usr/share/doc/gnucap-0.33/acs-tutorial 2000-08-16 18:15:00.000000000 +1000 +++ acs-tutorial-wm 2003-03-16 13:26:18.000000000 +1100 @@ -1,15 +1,19 @@ Tutorial for acs V0.02 Copyright 1999 Telford Tendys +Modified for gnucap-0.33 by W. Metzenthen 2003. >>> Introduction -This is not an alternative to reading the acs manual. The manual is +This is not an alternative to reading the gnucap manual. The manual is very nicely presented in LaTeX and you should print it out and keep -it handy when working with acs. This document is organised starting -from easy and working towards difficult and presumes that you have some -idea of what electrical circuits are but don't know much about simulators. -The acs manual is organised in alphabetical order and in groups of concepts -and it presumes that you know SPICE already. +it handy when working with gnucap. Depending upon how you obtained +gnucap, the manual might be installed as "man.ps" and/or as html pages. + +This document is organised starting from easy and working towards difficult +and presumes that you have some idea of what electrical circuits are but +don't know much about simulators. The gnucap manual is organised in +alphabetical order and in groups of concepts and it presumes that you know +SPICE already. >>> The basic concept of a nodal analysis. @@ -34,7 +38,7 @@ >>> The basic concept of a circuit file. -Tradition has it that acs input files have the extension ``.ckt''. The +Tradition has it that gnucap input files have the extension ``.ckt''. The format is similar to that used by version 2 of the SPICE simulator; it is a line oriented format with items separated by whitespace. The overall file structure is: @@ -76,16 +80,16 @@ source is 10 volts and the resistor is 1000 ohms. The nodes have the numbers ``0'' and ``2''. Note that there is no node ``1'' but this doesn't matter, not every node number needs to be used. Like SPICE version 2 (but -unlike version 3) nodes must be numbered in acs. +unlike version 3) nodes must be numbered in gnucap. In order to load this circuit into the simulator the following command would be used: - acs eg1.ckt + gnucap eg1.ckt -What happens is that acs loads in the circuit, finds no commands to execute +What happens is that gnucap loads in the circuit, finds no commands to execute (since this file has no command lines) and so enters interactive mode with -a ``-->'' prompt. From the interactive mode it is possible to exercise the +a ``gnucap>'' prompt. From the interactive mode it is possible to exercise the circuit model, firstly by putting a probe on the node that needs measuring (using the print statement) then by starting the simulation: @@ -165,7 +169,7 @@ Run this with: - acs eg2.ckt + gnucap eg2.ckt print dc v(1) v(2) v(3) v(4) v(5) dc quit @@ -220,31 +224,36 @@ ---------------------------------------------------------------------- Notice that this example file contains some lines that begin with a dot. -These are command lines and behave exactly like the commands you type -in interactive mode. These command lines are dotted because of the old -SPICE tradition of executing all of the component lines first and then -the command lines, acs doesn't bother with this, it executes every line -in the order that it sees them, but it still follows the old idea of dotting -the command lines as a little tribute to SPICE and to make it easier to -see what is going on when you read a .ckt file. +These are command lines and if gnucap is run in batch mode ('-b' command +line option) they behave exactly like the commands you type in interactive +mode. These command lines are dotted because of the old SPICE tradition of +executing all of the component lines first and then the command lines, +gnucap doesn't bother with this, it executes every line in the order that +it sees them, but it still follows the old idea of dotting the command +lines as a little tribute to SPICE and to make it easier to see what is +going on when you read a .ckt file. -When you run this example, you might try: +When you run this example, you might try batch mode: - acs eg3.ckt + gnucap -b eg3.ckt And (all going well) you will see that node 2 is equivalent to a source of 54.343 volts in series with an 0.83888 ohm resistor. -You should also notice that acs never goes into interactive command mode. -This is because of the ``.end'' command that tells acs to finish at this point. -You may want to use this example circuit in interactive mode, to achieve this -you could either delete the .end command, or (from the system prompt) type: +You should also notice that gnucap never goes into interactive command mode. +This is because the '-b' option tells gnucap to run in batch mode. You may +want to use this example circuit in interactive mode, to achieve this +you could either use: - acs + gnucap eg3.ckt + +or equivalently type: + + gnucap get eg3.ckt Then you can use other interactive commands. Note that you can modify the circuit interactively too. Consider adding another resistor by typing the -following at the acs interactive prompt: +following at the gnucap interactive prompt: build R3 R6 3 4 12k @@ -261,7 +270,7 @@ cat eg3_mod.ckt Looking at what you have saved you will probably notice a few things: -firstly, acs has remembered your comment lines and command lines and +firstly, gnucap has remembered your comment lines and command lines and saved them too; secondly, your extra line was inserted into the file before the line containing component ``R3'', this is caused by the argument on the ``build'' command and allows you to insert your build @@ -284,7 +293,7 @@ some argument between V1 and V2 as to exactly what the final voltage at node 1 really is. You should see that huge currents are flowing through the supplies (10,000 amps) just due to this small voltage -difference. Also note that acs does not throw in the towel and give +difference. Also note that gnucap does not throw in the towel and give up, nor does it fail to converge... the answer that it gets for v(1) is a compromise, halfway between the two sources. @@ -293,7 +302,7 @@ to make the best guess that it can in a difficult situation. How much is this resistance? You can find out like so: - acs + gnucap options Look at the value of the option called ``short'' (near the middle of @@ -301,7 +310,7 @@ resistance of a voltage source. The ``u'' character means ``micro'' or 1e-6 so the default value of a short circuit is 1e-5 ohms. You might decide that a different short circuit value is more appropriate -for running the above circuit so you can type (from the acs prompt): +for running the above circuit so you can type (from the gnucap prompt): options short=0.5 get eg4.ckt @@ -326,7 +335,7 @@ ---------------------------------------------------------------------- The case of putting two current sources in series is much the same -concept as two voltage sources in parallel. However notice that acs +concept as two voltage sources in parallel. However notice that gnucap copes with it in a different manner. It cannot find a compromise current that is partway between the two sources and it always gives a huge value for the voltage at node 1. At least it doesn't crash and it does @@ -340,7 +349,7 @@ the strange node? How would you ever know that the circuit was broken? Try this exercise: - acs + gnucap get eg5.ckt alarm dc v(*)(-1e3,1e3) dc @@ -394,26 +403,26 @@ You can run this example and look at the results like so: - acs eg6.ckt + gnucap eg6.ckt gnuplot set data style lines plot 'eg6.dat' using 1:2, 'eg6.dat' using 1:3, 'eg6.dat' using 1:4 exit You may not like using gnuplot and may prefer some other plotting program -such as gwave or gle. Acs output can be used by most plotting programs +such as gwave or gle. gnucap output can be used by most plotting programs in much the same manner as above by using the redirection arrow on the command that runs the simulation (``dc'' in this case). Note that it usually won't work to redirect the normal output to a file using your shell and then cut and paste that output into your plotting program because the normal output does not use standard scientific notation, using the internal redirection -option provided by acs also guarantees you get a nice, portable data file +option provided by gnucap also guarantees you get a nice, portable data file in standard exponential notation. If the above did work you should have been able to see the node voltages as a function of supply voltage and see the diodes move into their conductive band one by one. And see the traditional 0.7 volt drop across each diode. -However, various diodes behave differently so acs needs to know what sort +However, various diodes behave differently so gnucap needs to know what sort of diode you are using. That is what the ``.model'' command line is doing for you -- it associated parameters in the diode model with a name that you choose to assign to your diodes. (By the way, I have no idea what the @@ -525,13 +534,13 @@ [explain AC analysis here with some bode plots and pole-zero stuff, -can acs do root-locus?] +can gnucap do root-locus?] two examples here eg8.ckt, eg9.ckt AC Analysis has the limitation that it is a LINEAR analysis only. This means that the nonlinear devices (such as diodes) must be regarded -as behaving like linear devices. In order to achieve this, acs finds +as behaving like linear devices. In order to achieve this, gnucap finds the DC operating point first and then presumes that the AC signal is some small value that will slightly perturb the DC operating point but will not be large enough for any nonlinear effect to be visible. @@ -555,7 +564,7 @@ supply is only switched on for half a cycle. Here in Australia, the mains supply is 240V RMS AC at 50Hz. Thus, one half -cycle lasts for 10 miliseconds. The ``generator'' device provided by acs is +cycle lasts for 10 miliseconds. The ``generator'' device provided by gnucap is the ideal thing to create a pulse such as this. --------------------------------------------------------------------- eg10.ckt @@ -658,7 +667,7 @@ Run the simulation in batch mode as follows: - acs eg19.ckt + gnucap eg19.ckt gnuplot set data style lines plot 'eg11.dat', 'eg11.dat' using 1:3, 'eg11.dat' using 1:4 @@ -691,7 +700,7 @@ diodes to switch a coil and does occur in real circuits too. The simulator does not know the junction capacitance of D1 because it has not been specified in the ``.model'' line (actually with no junction capacitance specified, -acs drops the capacitor out of the diode model completely) so the oscillation +gnucap drops the capacitor out of the diode model completely) so the oscillation flips back and forth with each time step and the magnitude of the swing at node 3 is dependent on the size of the timestep used (try a longer timestep and see that node 3 shows a larger voltage swing at this point).