Csim 2.5, Circuit Simulator SHORT DESCRIPTION AND MANUAL 10/25/91 (c) Per Stenius RELEASE NOTE This version differs from the previous (2.3) in the following: - Lossless transmission line for AC analysis at a single freq. point. (T) - The functions CV(node) and CI(branch) that fetch the voltage/current of given node/branch in the previous solution point. CV = ControlVoltage, can be used in other sources to define any functional dependency of a voltage/current in the circuit. Note that there is a delay of 'tstep' when using these functions. - The program 'iterdc' for iterative dc solving to be used with nonlinear components. - Additional examples of circuits in manual. - New sample circuit. INTRODUCTION This text describes a simple circuit simulator called Csim for the HP48. It makes DC, AC and transient simulations and supplies the user with all matrices used. The method used is modified nodal analysis, and thus elements such as an inductor or ideal voltage source require that a current branch is also specified together with the nodes. As soon as a setup is done, single analyses can be made with the 'dc', 'ac' or 'tran' subprograms. All subprograms return the result as a vector, whereas Csim provides the user with a plot in transient and AC analysis. Note that for Csim to work correctly, the 'node' variable should be defined (either a node or branch number) when plotting a result. Note also that the RES variable (in PLOTR) should be 0. Finally, if SYM (in MODES) is not set Csim does not work correctly. For a demo on how Csim works do the following: - download the code (creates the directory CSIM in the current directory) - enter the directory CSIM and press CST - press Csim: for: Setup? Y press: for: Analysis? (D,A,T) press: T for: Sweep range? :tstart:0 :tstep:0 :tstop:1 press: 5 i.e. :tstop:5 after which a time-domain plot is drawn (if you have something that you previously have plotted, press CLRSC before doing this). Press to exit the graph environment. Now, press CST and 3 node and redo the above. Finally, press CST CIR CIR-> to see the circuit description. Here is an explanation on the CST menu: Csim - the simulator program. Runs setup (if requested) and a single analysis. For ac, a single run directly from CST provides a fast solution in one freq-point. When choosing T for transient analysis either tstep (time resolution) or tstop should be given. If both are given tstep is used and tstop ignored. View - the StackView application, for easy check on components. Use ATTN (ON) to exit. You can also use the Interactive Stack the HP48 provides (see manual p.70). node - the node or branch the value of which is wanted as a solution. Used to GET the right value from the solution vector. ymin, ymax - define the picture y-axis (ac or tran analysis) CLRSC - Clears the screen (simply the ERASE command) outp - a program that takes a vector from the stack and returns one value. it can be used to plot a result that is a function of the values in the solution vector. To be edited by the user. (default << node GET >> ) CIR-> - takes a list of lists, such as the one used to store circuit descriptions (see also CIR, ->CIR) and puts the lists in it to the stack (inverse to ->CIR). Usage: Press a variable containing a circuit description (e.g. CIR) and press CIR->. ->CIR - takes the circuit description used by Csim and puts it to a list, that can be stored in a variable. CIR - when 'Setup' is run, the stack containing the circuit is stored in this variable as a list. To use again, recall CIR and run 'CIR->' (see above). Contains a sample circuit as default. Any circuit description can be stored in a variable as a list of components (which also are lists). dc - single DC analysis. Requires that setup is done (the matrices are ready). Takes no argument from stack and returns a solution vector. ac - single AC analysis. Requires that setup is done (the matrices are ready) and that 'w' is specified (rads/s angular freq). Takes no argument from stack and returns a solution vector. Note: Complex values! When A is chosen in Csim, the actual program stored by STEQ is 'acplot', which executes 'ac' and then 'outp'. The program 'outp' should take a vector from stack and return a single number. E.g. << node GET ABS >> would return the absolute value of a node voltage (or branch current) that is to be plotted. tran - single transient analysis. Takes one time step and returns a solution vector. The method used is trapezoidal rule. When T is chosen in Csim, the actual program stored by STEQ is 'tranBE' (or 'tranTR'). These return the result vector and call 'outp'. The program 'outp' should take a vector from stack and return a single number. E.g. << node GET >> would return the value of a node voltage (or branch current) that is to be be plotted. Setup - setup routine for the simulator. Creates and loads the matrices needed and stores the stack as a list into CIR. Takes the circuit description from the stack as an argument (only component declarations are allowed on stack). Setup must be done once before analyzing, however, after that the matrices are ready to be used multiple times. This should be remembered e.g. when calculating a DC solution and thereafter starting a transient analysis from the obtained results. In this case running Setup a second time would zero the result vector. Setup also clears flag -3 (i.e. enables SYM), sets flag -17 and clears flag -18 (i.e. sets radians mode). w - angular frequency (2*pi*f) rad/s. G - conductance matrix. Contains all real valued entries, i.e. those caused by elements the values of which do not have an s or jw factor. C - s-matrix. Contains all elements that have an s or jw factor. Cc - constant valued complex matrix. Can be used in AC analysis only, at a single value of 'w' (angular frequency). Contains entries from Z, Y, z, y (See Section on syntax). W - numerical values of the sources as a vector. This vector is updated in every analysis point. Wlist - the functions representing each source as a list, from which the numerical values for 'W' are obtained. Euler - specifies the method used in the tran analysis. If Euler = 1 then backward Euler ('tranBE') is used (faster but more inaccurate), if Euler = 0 then the trapezoidal rule is used, which is rather accurate but slower ('tranTR' and 'tran'). iterdc - if CV() or CI() are used in DC analysis, iterative solution is required in order to obtain the correct solution. 'iterdc' can be used for this after setup has been done. Note that very few nonlinear circuits can actually be solved by iteration only. Usually some linearization method must also be used, e.g. the Newton-Raphson algorithm. THE SYNTAX USED TO DESCRIBE A CIRCUIT The syntax by which the components are entered is (NOTE! Each circuit needs a ground node and its number is always 0 (zero)): {R node1 node2 numval branch} - resistance [ohm] {G node1 node2 numval} - conductance [mho] {C node1 node2 numval} - capacitance [F] {L node1 node2 numval branch} - inductance [H] {Y node1 node2 complexnumval} - admittance with a constant complex value (re,im) {Z node1 node2 complexnumval} - impedance with a constant complex value (re,im) {J node1 node2 funcval} - indep. current source {E node1 node2 funcval branch} - indep. voltage source {S node1 node2 branch} - short circuit (the current is fetched by branch GET). Can be used to define a current branch for dependent sources. {O in+ in- out+ out- outbranch} - ideal opamp (out- should be ground, outbranch returns the output current) {M l1node1 l1node2 l2node1 l2node2 l1val l2val mval l1branch l2branch} - transformer i.e. two inductors (l1, l2) with mutual inductance (mval). The values required are the four nodes, the value of l1, l2, mval [H] and the branches of l1 and l2. The dots for m are at l1node1 and l2node1. {m l1branch l2branch mval} - mutual inductance of mval [H]. As M, but can be used to define e.g. three inductances that all have mutual inductances. To do this, define the 3 L:s and then 3 m:s between them. Note that m takes the branches of the L:s. Make sure you specify the inductors the right way (the branch of L runs from n1 to n2). Note also that m is not a component, it merely states a dependency between two L:s that should be defined separately. No checking is done that l1branch and l2branch actually belong to L:s. {T node1 node2 node3 node4 llval Zoval} - lossless transmission line (to be used in AC analysis only) of length ll (in wavelengths) and with the characteristic impedance Zo. Note that nodes 2 and 4 must have the same value (equivalent pi-circuit used). {g node1 node2 node3 node4 numval} - voltage-controlled current source i.e. transconductance. The source current is from node3 to node4 and the controlling voltage from node1 to node2. {r node1 node2 node3 node4 numval branch1 branch2} - current-controlled voltage source. Defines a short circuit between node1 and node2 and a controlled voltage source between node3 and node4 (node3 being the positive node). The controlling current runs through branch1 and the current of the source is fetched from branch2. Branch1 must not be a previously defined branch. {p node3 node4 numval branch1 branch2} - same as r but does not define a short circuit between node1 and node2. Instead branch1 must be a predefined branch (e.g. that of a resistor or inductor). {a node1 node2 node3 node4 numval branch} - current-controlled current source. Defines a short circuit between node1 and node2 and a controlled current source the current of which runs from node3 to node4. The controlling current runs through branch which must not be previously defined. {b node3 node4 numval branch} - same as a but does not define a short circuit between node1 and node2. Instead branch must be a predefined branch (e.g. that of a resistor or inductor). Compare with p. {u node1 node2 node3 node4 numval branch} - voltage-controlled voltage source. The current through the source is fetched from branch. {y node1p1 node2p1 node1p2 node2p2 y11 y12 y21 y22} - a two-port with y-parameters that are constant complex values (re,im) {z node1p1 node2p1 node1p2 node2p2 z11 z12 z21 z22} - a two-port with z-parameters that are constant complex values (re,im) FUNCTIONS CV(node) - returns previously calculated value of the voltage of node. In code << X node GET >> CI(branch) - returns previously calculated value of the current of branch. In code << X branch GET >>, the same as CV(). In the above, nodes and branches are integer numbers. The ground node is represented by 0. All nodes and branches should have a unique number and they should be given in order e.g. nodes 0,1,2,3 and branches 4,5,6. These numbers refer DIRECTLY to the position in the matrices/vectors. Thus the 4'th element in the result vector would be the current through branch 4 and the first element is the voltage of node 1. To help remembering the syntax, you could e.g. have a variable y with the following contents: y {y n1p1 n2p1 n1p2 n2p2 y11 y12 y21 y22} The following components form equivalent circuits: {S 1 2 5} {p 3 4 100 5 6} is the same as {r 1 2 3 4 100 5 6}, {S 1 2 5} {b 3 4 100 5} is the same as {a 1 2 3 4 100 5}, {L 1 2 0.1 5} {L 3 4 0.2 6} {m 5 6 0.05} is the same as {M 1 2 3 4 0.1 0.2 0.05 5 6}. Finally, an example of usage for transient analysis: (This is how your stack should look) {E 1 0 '10*SIN(10*t)' 4} {C 1 2 0.01} {L 2 3 1 5} {R 3 0 10 6} This defines a RLC-circuit with nodes 1,2,3 (and ground) and current branches 4,5,6. The current through branch 4 is equal to the current through the ideal voltage source E, the current through branch 5 equals the current through the inductor L, and the current through branch 6 equals the current through the resistor R. The values of the components (which ALWAYS must be numerical) are 10 ohms, 1 henry and 0.01 farads. The voltage source has a time-dependent value (used in transient analysis). If 'node' is set to 3 the voltage over the resistor R is plotted in transient analysis. On the other hand, 'outp' could be written as << DUP 1 GET SWAP 2 GET - >> to return the voltage between nodes 1 and 2 as a result. Note that sources (E,J) may have functional values (should be suitable for the analysis requested! Time dependency for transient analysis and 'w' dependency (angular freq) for AC). When running Csim, the stack may ONLY contain component declarations! Press CST and then View. Now press ATTN (low-left corner, i.e. ON). Press Csim, press Enter on "Setup? Y", press D (or T), Enter on analysis. An example for AC analysis (using A in Csim): {E 2 0 1 3} {G 2 1 1} {C 1 0 1} Set 'node' equal to 1 and write 'outp' equal to << node GET ABS >>. Select A on analysis and choose wstart 0 and wstop 10 (ymin = 0, ymax = 1). Another example for AC analysis (using 'w' = 1 and 'ac'): {J 0 1 10} {G 3 0 1} {G 2 0 1} {Z 1 0 (0,-1)} {M 3 1 2 1 2 1 0.5 4 5} Setup 1 left-shft w ac The currents through the transformer are the 4'th and 5'th elements in the result vector. Here's an example involving a transistor for which we have the y-parameters y11 = 0.001, y12 = -j0.0001, y21 = 0.1 and y22 = 0.0001. Its base is at node 1, emitter at gnd (node 0) and collector at node 2. {J 0 1 1} {Z 1 0 1E3} @ resistance of 1 kohms {Z 2 0 1E3} {Z 1 2 (0,-1000)} @ capacitance of -j1000 ohms {y 1 0 2 0 1E-3 (0,-1E-4) 0.1 1E-4} Setup ac 2 GET ABS (returns |Uo/Jin| = 884.035 V/A) For the use of the lossless transmission line we have the following example (analysis can be made at a single frequency point only, at which ll is valid): {J 0 1 1} {Z 2 0 (75,-69)} {T 1 0 2 0 0.583 50} Setup ac 1 GET returns (25.2092, -34.5800) which is the input impedance (J = 1) of a lossless transmission line of the length 0.583 wavelengths (at some frequency) and with the characteristic impedance of 50, terminated with a load of (75,-69) ohms. DC analysis: {J 0 1 1} {R 1 0 1E3 3} {p 2 0 10 3 4} The voltage of node 2 (the 2'nd element in the result vector) should be 10V. The current through the controlled voltage source should be 0A (the 4'th element in the result vector). For iterative DC solving of circuits, consider these two examples: {E 1 0 1 3} {G 1 0 1} {G 1 2 1} {J 0 2 'SQ(CV(1))'} and {J 0 1 1} {G 1 0 1} {G 1 2 1} {E 2 0 'SQ(CV(1))' 3} Setup iterdc The first circuit converges after only two iterations, but the second one requires several hundred to reach the exact solution ([[1] [1] [0]] in the second case). Good initial guesses may help, and also the use of e.g. the Newton-Raphson algorithm (see Vlach-Singhal; Computer Methods for Circuit Analysis and Design). Note that 'iterdc' should actually also be used at every time step in transient analysis to avoid the delay when using CV() and CI(). A simple small signal model for a transistor (B-1 C-2 E-3): {R 1 3 1E3 4} {G 2 3 0.0001} {b 2 3 100 4} A voltage source used as an digital inverter; if the voltage of node 2 is higher than 2.5 volts, then the voltage of node 3 is 0 volts, otherwise 5 volts (note that there is a delay of one 'tstep'). {E 3 0 'IFTE(CV(2)>2.5,0,5)' 4} Including nonlinear components as such would make solving the matrix equation system a tedious process. It would also make the analysis MUCH slower. However, it could be done. ERROR MESSAGES These are the only error messages in this program. Note that there are not many error checking routines provided, so the user should be careful when entering the circuit description. For any strange behaviour or false results, please email me directly and explain what occurred. SYNTAX ERROR - an error occurred in 'Setup' while Csim was loading the matrices. Check the circuit description and the component that is first on stack. See also section on syntax. NEGATIVE NODE NO. - a negative number was given as a node number. Check the the first component on stack. BOTH NODES SAME - a component was specified having two nodes that were the same value. To override this, use a short-circuit (S) between these nodes. BOTH NODES GND - both nodes of a component were specified to be GND (i.e. their node numbers were zero). ZERO VALUE OR BRANCH - a component with a value of zero was given or its branch number was zero (which is reserved for the ground node). n2 MUST EQUAL n4 IN T - you have entered a transmission line in the circuit with nodes 2 and 4 not equal. This is not allowed since the equivalent pi-circuit to the transmission line is actually used. A good way to avoid errors is to proceed systematically, e.g. in the following way: 1) Choose one reference node to be ground (GND) and set its node number to 0. 2) Assign the rest of the nodes a number each, in numerical order (1,2,3,...) 3) Find all the components that require a branch and assign each required branch a number starting from the highest node number plus one. !) The node and the branch numbers should follow eachother in numerical order, with no 'gaps' in between (e.g. 0,1,2 are nodes and 3,4 are branches). 4) Enter the circuit description component by component. Note that the stack should only contain component descriptions! Check your stack with 'View'. 5) Decide what results you need and edit 'outp' if necessary. Also, set 'node' to the correct value. 6) Run 'Setup' once and start analyzing! Remember to run 'Setup' whenever you change your circuit or want to start from zero. Sometimes all you need to do is to edit your X vector. FREQUENTLY ASKED QUESTIONS Some people have had trouble with the branch currents (the direction...) so here's more on that: In all components (J,E,L etc.) the current is defined to be FROM the first node TO the second node. Thus no matter which way you put your source (E) The value of the branch current remains the same (i.e. in the direction of the U of the source) with respective to the source. In the sample RLC circuit, when the first node of E and L is the same, the currents should be the opposite. When the second node of E is the first node of L, the currents are the same. For E the situation looks like this: --- U=E --> node1 + o->-( E )---o - node2 I for L: --- U1,2 -> node1 o->- Ind ---o node2 I for J: node1 o->-( J )---o node2 I=J for S: --- U=0 --> node1 o----->-----o node2 I This could be defined the other way around too, but in this case it isn't. For two-ports, the node numbers are defined as _________ node1 o->--| |--<-o node3 | | | | | | | | node2 o----|_________|----o node4 Note that the direction of the currents is always towards the two-port. This should be remembered when defining e.g. ideal opamps, controlled sources and two-ports with y- or z-parameter representation. >I can't get the transient analysis to work properly unless I do >an entire setup first. If I do a transient plot, and then repeat it, I >get different results, unless I run setup. What happens is that unless you run setup, the transient analysis continues from where it stopped (however, this time from the beginning of the screen). Thus the new beginning should match with the previous end. As you might have noticed, the transient analysis should always start from time=0. This is due to the fact that solving this problem is an iterative process. >It would be nice to be able to specify initial values for capacitors and >inductors. > This can be done. The X vector contains the starting values, and is zeroed at setup. However, nothing stops you from running a dc-analysis and then running a tran analysis without a setup in between, thereby giving the results from the dc-analysis as beginning values for the tran analysis. The X vector can also be manually edited. To do this, run setup, then press enter for analysis?, which stops the program. Edit the X, and run tran analysis without setup. The execution of setup can be avoided by answering something else than 'Y' at 'Setup?'. >I'm interested in any references you used, for algorithms for circuit solving, >this is something I've never really looked into before. > A good place to start is to look at a book called Computer Methods for Circuit Analysis and Design by Jiri Vlach and Kilshore Singhal (Van Nostrand Reinhold Company 1983, ISBN 0-442-28108-0). Check out chapter 4 and 9. For transient analysis, (which is normally done by Laplace tranforms when working manually) the trapezoidal rule is pretty powerful. Also, for all the theory needed for Csim, I have written a report called A Tutorial on Developing a Simple Circuit Simulating Program which I can email (ps-file format) to anybody interested upon request. It is about 25 pages + 30 pages including this manual and the commented source code for Csim. FINAL REMARK Csim takes 10208.5 bytes when loaded, and its checksum is #45412d. This simulator is not necessarily completely bug-free, so please report to me for any strange behaviour. Note also that the transient analysis methods are not necessarily stable for all values of time steps. Try another time range or time step if this happens. If you get the system error INV Error: Infinite Result in any analysis mode, this usually indicates that the component matrix cannot be inverted. This error can sometimes be avoided by assigning the nodes the values 0...n and the branches the values n+1...m. If this does not help, please send me the circuit description you used. I am happy to provide any further information on this program. Please send also some comments on its appearance, suggestions on improvement etc. Note that very little syntax checking is done (e.g. no node or branch number checks!). I hope this short manual is sufficient, if not please ask me directly via email. copyright Per Stenius, Helsinki University of Technology. email perre@aplac.hut.fi or pstenius@otax.tky.hut.fi