BasicSimulator Released

Today, I release my first circuit simulator. I worked a lot on this project and I am very satisfied with the results.

In this post, I will present the functionality and limitations of BasicSimulator (this is the name I chose for my program), and I will explain how to use it. A link to download the source code and binaries of the program can be found at the end of this post.


Functionality and Limitations

The BasicSimulator can perform two types of DC analysis: operating point analysis and DC sweep. All circuit elements supported by the simulator are linear elements. It cannot simulate circuits with diodes, transistors, or any nonlinear element. Here is a list of all supported circuit elements.

• Resistors
• Capacitors
• Inductors
• Independent voltage sources
• Independent current sources
• Voltage controlled voltage sources
• Voltage controlled current sources
• Current controlled voltage sources
• Current controlled current sources
• Ideal OpAmps
• Transformers

With DC, capacitors are just open circuits, and inductors and transformers are just short circuits. These elements are not very important in a simulator that can only perform DC analysis, but I included them anyway.


Input Files

The input to the simulator consists of two XML files, the first contains the circuit description, and the second contains the analysis command. The paths to the files should be passed to the program as command line arguments.

BasicSimulator <circuit file> <analysis command file>

1) The circuit description file

Circuits are described using the Circuit Description Language (CDL) which is an XML-based language invented by myself. I wrote an XML Schema to formally define the CDL and to validate the user files before parsing them. The Schema file can be found at
...\BasicSimulator\BasicSimulator\Schemas\CDL.xsd
The CDL is defined in the XML namespace
Bassem.BasicSimulator.CDL
Instance documents should create an alias for this namespace and prefix the root element <Circuit> with this alias.

<cdl:Circuit xmlns:cdl="Bassem.BasicSimulator.CDL">
    ...

   <!-- circuit description here -->
    ...

</Circuit>

Because CDL is an XML-based language, it is self-descriptive. The user can learn it from the circuit files I used to test the program. These can be found at
...\BasicSimulator\BasicSimulator\Tests\Test1\Circuit.xml,
...\BasicSimulator\BasicSimulator\Tests\Test2\Circuit.xml, and
...\BasicSimulator\BasicSimulator\Tests\Test3\Circuit.xml.

2) The analysis command file

The analysis command specifies the type of analysis to be performed. Depending on the type of analysis, it may or may not contain additional information. To request an operating point analysis, only the type of analysis needs to be specified in the analysis command file. If a DC sweep analysis is requested, the user should provide the ID of the independent source which value is to be swept, the starting value of the sweep, the stopping value, and the size of the increment.

The XML schema document that specifies the structure of the analysis command file can be found at
...\BasicSimulator\BasicSimulator\Schemas\AnalysisCommand.xsd
The namespace of the XML vocabulary used in analysis command files is
Bassem.BasicSimulator.AnalysisCommand

The following analysis command specifies that operating point analysis should be performed on the circuit.

<ac:OperatingPoint xmlns:ac="Bassem.BasicSimulator.AnalysisCommands" />

The following analysis command specifies that DC sweep analysis should be performed on the circuit by sweeping the value of the independent source 'V7' from 0 to 30 with a step size of 5.

<ac:DCSweep xmlns:ac="Bassem.BasicSimulator.AnalysisCommands">
    <SourceName>V7</SourceName>
    <Start>0</Start>
    <Stop>30</Stop>
    <Increment>5</Increment>
</ac:DCSweep>

Querying the Analysis Results

The ResQuery is the language used to query the analysis results. Again, this is a language invented by myself. It is very simple. A ResQuery has one of two forms:

node:<node name>
element:<element ID>

The first query gets the node voltage or voltages depending on the analysis type. The second query gets the analysis results associated with the element. For example if the element is a current controlled voltage source, the query will get the value(s) of the input current, the output voltage drop, the output current, and the power consumption in the element.

Click here to download the source code and binaries of the BasicSimulator.

Circuit Formulation

Circuit formulation is the process of deriving from the circuit description a set of linear equations that can be solved to evaluate the desired voltages and currents.

In linear DC analysis - the only type of analysis that concerns me for now - the circuit needs to be formulated only once.

There exists many formulation techniques. Some are much better than the others. Examples of formulation techniques are:

• The basic nodal formulation method which cannot handle circuit elements that are not current sources and do not have an admittance description.
• The tableau formulation method which produces unnecessarily large matrices.

The formulation method I will present here is a variation of the modified nodal formulation. It is well explained in "Electronic Circuit & System Simulation Methods" (chapter 2) and in "Computer Methods for Circuit Analysis and Design" (section 4.4).
The method is better than the basic nodal formulation because it can handle all linear circuit elements. It is also better than the tableau formulation method because using the tableau formulation you get a solution vector containing all branch currents, all branch voltages, and all nodal voltages. Obviously, these quantities can be easily derived from each other.
The version of the modified nodal formulation I will present next gives much smaller matrices. The solution vector will contain only the nodal voltages and the currents through the elements that are not current sources and do not have an admittance description.

Formulation Steps

Step 1:
Number the circuit nodes consecutively. It is a good idea to give the ground node the number zero to facilitate the removal (or the neglect) of its nodal equation and of the coefficients of its voltage.

Step 2:
Number the elements that do not have an admittance description starting from "last node number" + 1. The number of the element will be the index of its first excess equation and also the index of its first excess unknown (elements without an admittance description introduce excess equations and excess unknowns into the set of equations).
Some elements have more than one excess equation (excess unknown), so the elements may not be numbered consecutively.

Step 3:
Scan all the circuit elements to add the element contributions to the set of linear equations. The contribution of an element is represented by a small matrix that is sometimes called the matrix stamp. The following figure shows the matrix stamps of the resistor, the independent current source, and the independent voltage source.



The complete list of ideal element stamps can be found in "Computer Methods for Circuit Analysis and Design" pages 116 and 117.

The independent voltage source is an example of an element that do not have an admittance description, it adds an excess equation and an excess current to the set of linear equations. In the matrix stamp of the independent voltage source, 'm' is the number of the element.

You stamp in an element contribution by adding the elements of its matrix stamp to the corresponding elements of the coefficients matrix and/or the RHS vector.

The LinearEquations Class

The LinearEquations class encapsulates

1. data structures to store the representation of a set of linear equations and
2. methods to solve the linear equations.

The elements of the matrix and the vectors are stored in zero-based arrays but the elements at index zero (row zero and column zero for the matrix) are completely ignored by the solution routine.
This is convenient because the formulation routine will produce an equation for every node, the nodal equations are linearly dependent and one of them must be ignored for the set to become linearly independent. We chose to ignore the equation at index zero which is the equation of the ground node.
Also, the coefficients at column zero are the coefficients of the ground voltage which is known to be zero, so we can safely remove the column zero from the matrix and the unknown at index zero from the solution vector.

Internally, the LinearEquations class uses the same two-dimensional array to store the coefficients matrix before the LU factorization and both the L and U matrices after the factorization. Before the factorization, the two-dimensional array is accessible through the property Coefficients and after the factorization it cannot be accessed.
Also, the same array is used to store the RHS vector before the solution and the solution vector after the solution process. Before solving, the array is accessible through the property Rhs, and after the solution it is accessible through the property Solution.

The values of the properties CurrentMatrixState and CurrentVectorContent determine the state of the LinearEquations object.



In state 1, using the Solution property causes an ApplicationException to be thrown.
In state 2, using the Coefficients property or the Solution property causes an ApplicationException to be thrown.
In state 3, using the Coefficients property or the Rhs property causes an ApplicationException to be thrown.

Click here to download the LinearEquationSolver project which includes the LinearEquations class. The project was created and built using the express edition of Visual Studio 2008.
Please note that the class Program was written just to test the other classes, and that it is not intended for reuse. It does not perform any checking on the format of the input file.

Solution of Linear Equations

The formulation algorithm should produce a system of linear equations that has a solution.
For the system to have a solution, the number of equations must be equal to the number of unknowns and the coefficients matrix must be nonsingular (its determinant must not be equal to zero).

Five of the methods that can be used to solve sets of linear equations are

1. the inverse matrix
2. Carmer's rule
3. Gauss-Seidel
4. Gaussian elimination
5. LU factorization

The inverse matrix and Carmer's rule methods are computationally expensive and are seldom used in computer applications.
Gauss-Seidel is an iterative method that may not converge even if the system of linear equations has a solution.
In the field of computerized circuit analysis, the solution of linear equations is usually performed using either Gaussian elimination or LU factorization.

The Gaussian elimination and the LU factorization algorithms are approximately of equal complexity (the complexity of the Gaussian elimination is slightly smaller).
The LU factorization is better in situations where we want to solve multiple sets of linear equations having equal coefficients matrices but different RHS vectors. Such situations arise when performing sensitivity analysis.

In my programs, I will use the LU factorization technique to solve linear equations.


Solution of Linear Equations by LU Factorization

The algorithm is explained very well in "Electronic Circuit & System Simulation Methods" and in "Computer Methods for Circuit Analysis and Design". Here, I will discuss the high level steps without going into the details of the algorithm.

Step 1: LU factorization
Factorize the coefficients matrix into an upper triangular matrix and a lower triangular matrix.


Step 2: Forward substitution
Consider the product [U][x] to be an unknown vector and solve for this vector.


This step is called forward substitution because you start by evaluating the first unknown in the vector [z] using the first equation and end by evaluating the last unknown using the last equation.

Step 3: Back substitution
Evaluate the unknown vector [x] from

[U][x] = [z]

This step is called back substitution because you start by evaluating the last unknown in the vector [x] using the last equation and end by evaluating the first unknown using the first equation.

To solve other sets of equations having the same LHS and different RHS vectors, we can reuse the factored matrix, only steps 2 and 3 need to be repeated.

Matrix Representation of Linear Equations

A set of linear equations can be represented in matrix form. Ex:

can be written in the matrix form as

or concisely

[a][x] = [b]

[a] is called the coefficients matrix.
[b] is called the Right Hand Side (RHS) vector.
[x] is called the solution vector.

The row index in the coefficients matrix and the index in the RHS vector represent the index of the equation.
The column index in the coefficients matrix and the index in the solution vector represent the index of the unknown.

Steps of Linear DC Analysis

Linear DC analysis is performed in two steps.

Step1: Formulation of the circuit equations.
Step 2: Solution of a system of linear equations.

I will use an example to illustrate these two steps.


The nodal equations for the above circuit are



Remember that in DC analysis, capacitors are replaced by open circuits.

The linear equations can be put in matrix form

The output of the formulation step is a set of linear equations like the one shown above.

In the solution step, the linear equations are solved to evaluate the vector of unknowns.

In my next posts I will present algorithms for formulating circuits and for solving sets of linear equations.

What is linear DC analysis?

DC analysis in general (linear and nonlinear) is used to evaluate the steady state DC voltages and DC currents in the circuit.

During DC analysis

1. Sinusoidal voltage sources and inductors are considered to be short circuits because the DC voltage across them must be zero.
   
2. Sinusoidal current sources and capacitors are considered to be open circuits because the DC current through them must be zero.
   

Linear DC analysis is a special case of DC analysis where the circuit to be analyzed is made up of linear circuit elements.
In the context of DC analysis, a two-terminal element is linear if the relationship between the DC voltage across the element and the DC current through the element can be described by a linear equation.
The following I-V curves show that the ideal resistors, capacitors, inductors, voltage sources, and current sources are all linear elements.


Remember that the voltages and currents represented by the axes are DC voltages and DC currents.

For elements having more than two terminals, an element is linear if the relationships between DC currents and/or DC voltages imposed by the element can be described by a set of linear equations.
The current controlled voltage source for example is a linear element because the two equations describing its I-V behavior are linear.



To conclude, linear DC analysis is used to evaluate the steady state DC currents and DC voltages for a linear circuit.

My first simulator will perform linear DC analysis and linear DC analysis only.