Help

This page is divided into a number of segments that deal with different aspects of the simulator such as installing the software, dependencies needed to use the simulator and simulating sample circuits. Use the links below to access the sections.


  1. Software Dependencies : installing the the software necessary to simulate circuits.
  2. Using the simulator : using the software.
  3. Simulating circuits : simulating circuits with this software.

Software Dependencies

The most essential software is Python. Python 3 has been released, but I still use Python 2.7. So would recommend you to install that. How do you get this? If you are a Linux user, Python usually comes installed. If not use your distribution's package manager to get the 2.7 version of Python. If you are a Windows user, check out this page:
https://www.python.org/downloads/windows/
At the top of the page are listed the latest stable versions of Python 2.7 and 3. The link will take you to a download page where you need to choose your distribution.
If you would like an Integrated Development Environment (IDE), I would recommend Eric which I use in Linux. The link is
http://eric-ide.python-projects.org/index.html

The next software is one for editing spreadsheets as all the inputs from the user are through spreadsheets saved as Comma Separated Value (.csv) files. On Windows, Microsoft Excel will do. On Linux, I use LibreOffice Calc. You can use any software as long as the software allows you to embed each cell within quotes, separate cells within a row with commas and separate lines with newline characters. Read up a little on .csv files if you want to know how to convert a .xls or similar file to .csv.

The next software you need is a plotting software. There are several but I would recommend Gnuplot. If you are a Linux user, use your distribution package to install it as it is standard GNU software. If you are a Windows user, it gets a bit tricky. You need to first install CygWin. You can find that here: https://www.cygwin.com/
CygWin is an embedded Linux system within Windows. You can go all the way and install all the packages it comes with if you want to play aroundwith it. But if you just want to use it for this software, all you need is Gnuplot. In the package installer, search for Gnuplot and select it. It may happen that even after installing Gnuplot, you can't view plots because that needs Xserver installed. I would recommend that you install any Graphics based software like Xfig. Just search for Xfig in the package installer, and the dependency will be Xserver. Say yes to all the dependencies and you should be done.

Using the Simulator

This documentation has been updated from Version 1.3.0. For the older documentation, refer to this link. This is a fairly simple case. For a more advanced example with control functions, click here.

The first step is to create a circuit file. As an example I create a circuit file using LibreOffice Calc. This could also be the process if you are using Microsoft Excel. The figure below is a snapshot of the circuit:

Sample circuit

The circuit is pretty simple. A voltage source is feeding two resistors. The voltage across the second resistor is measured by a voltmeter and the current supplied by the source is measured by an ammeter. To save the circuit, choose the file to be save as a .csv file. In this case, we shall name the file doc_example.csv. The next snapshot shows a warning that LibreOffice gives when you want to save it as a .csv file. Microsoft Excel gives a similar warning. Just go ahead and save it.

Circuit photo

Now the next step after saying yes to saving it as a .csv file is important. It specifies the field delimiter to be a comma and the text delimiter to be a double quote. Make sure this is the case. The field delimiter is how two adjacent cells in a row are separated in the final text file. For the simulator to be able to read the circuit, the field delimiter has to be a comma. Anything else and it will not work. The text delimiter is what encloses a component. This should be a double quote or a single quote. Do not change this to anything else. The simulator will read a component only if it is within quotes.

CSV format

As for the newline character that separates rows in the .csv file, an option does not appear above. Both LibreOffice and Excel use the standard \n newline character. The simulator interprets both the \n and \r as newline characters. If you are having trouble, check what newline character you are using and try to change it to one of these.

The next step is to run the circuit simulator. Make sure all the files of the simulator are in the same directory as the circuit doc_example.csv file above. The simulator must be able to find the file and currently it will search only in the present working directory. If you are using Linux and want to run the command from the shell command line, run the following command from a terminal in the directory with these files:

$python circuit_solver.py

If you are using IDLE in Windows, open the file circuit_solver.py and either press F5 or go to Run menu and choose Run Module.

Now the simulator works in interactive mode. The next set of screenshots will show you the different parameters. Using IDLE in Windows but could be using Linux in command line with just the same results.

First run

If this is an empty project and the circuit file above has just been created, the simulator will create a sample circuit_inputs.csv file. This file contains the parameters of the simulation. The sample is shown below:

Default inputs

Some of the fields are self-explanatory. The first row will take the name of the circuit file which in this case is doc_example.csv. However, the simulator populates this field with sample_ckt.csv. The next field is about the time duration of the simulation - for how long do you want the simulation to run? In this case it is 0.1 seconds but the default is 1s. The time entered is always in seconds, so if you want 2 minutes, enter 120s. The next row is the time step of the simulation. In this case it is 10 microseconds. For more complex power electronic circuits, it is recommended to be 1 microsecond or even less. The next row is about the time step for storing data - how often do you want to store data? The next row is about the name of the output file. The default is ckt_output.dat. The next fields will need explanation.

Row 6 in for control files that the simulation needs. You can enter as many control files as you want. Just make sure they are .py files. Each control file should be in a separate column. If you don't have any, delete all of them but leave the first two columns and the row intact.

Row 7 asks if you wish to split the output file. This is for very large simulations which might generate hundreds of MB or even GB of data. When plotting the waveforms, it is incredibly difficult to plot large amounts of data and some plotting software might just hang. So, in that case use this functionality to split the output file into pieces. Row 8 gives the interval of each part of the output. For example, if it is a 1s simulation, you could split it into files of 0.2s duration. The third column in Row 8 is empty, but this value would be 0.2 in that case.

The screenshot shows the actual inputs for this case.

Actual inputs

The next screenshot shows how the simulator prints out the number of nodes, branches and loops. Next, it will ask for the parameters of the circuit components.

New Simulation

The simulator creates another spreadsheet by adding _params.csv to the circuit file. This spreadsheet contains the parameters of the circuit. The simulator reads the components in the circuit and automatically assigns default parameters to the components. These default parameters are written into the file doc_example_params.csv and are available for the user to change. You need to open this file and change the parameters according to your need. The default parameters are in the next snapshot:

Simulation

You can change all the parameters above. The value you need to change is after the equal to (=) sign in any of the fields. What you should not change are the first three columns. The first column is the type of the component. The second is the name of the component. The third is the cell position of the component. Changing these three will cause the simulator to crash. The three columns are for your reference to know which component exists in which location of the circuit.

Simulation

In the above example, just two parameters are changed to show you how it is done. The polarity of the voltmeter and the voltage source are changed. You need to save and close the file. Not closing the file may cause the simulator to not be able to read the parameter file and abort.

Simulation

The simulator then tells you in what sequence the meters are plotted in the output file. The output of a meter is always plotted. In this circuit, there are two meters. Therefore, there are two outputs being plotted. In the circuit output data file, the first column is always the simulation time. The remaining columns are meter outputs or control signals. So the second column is the meter at 1A which is the ammeter and the third column is the meter at 4G which is the voltmeter.

To check the results of the simulation, we use Cygwin. Start Cygwin and change directory to the directory that contains the simulation files. Then start the X server with the command startx. After the X server has started, run the command gnuplot to enter the Gnuplot shell. It looks like this:

Simulation

As said before the first column is the time, the second is the ammeter output and the third is the voltmeter output. So the command:

$plot "ckt_out.dat" u 1:2 w l

Implies plot the file ckt_out.dat using columns 1 and 2 (where column 1 will be x axis and 2 will be y axis) with line. This is the way I generate my plots. Feel free to read the manual on Gnuplot to see more options.

Simulation

And to check the voltage:

$plot "ckt_out.dat" u 1:3 w l Simulation

And to check the current and voltage together:

$plot "ckt_out.dat" u 1:2 w l, '' u 1:3 w l

In the above command, the empty quote means use the same file for the next line. You can specify the file, but this shortcut will do.

Simulation

The top right of the graph contains the key to the graph. Since the current is hardly visible, we use the handy command:

$plot "ckt_out.dat" u 1:($2*20) w l, '' u 1:3 w l Simulation

Since the current has being magnified by a factor of 20, it is possible to check the phase of the current with respect to the voltage.

This was a fairly simple example to get started. More complex circuits will need more parameters. The examples and case studies provided in the Blog section of the website would make these fairly clear. If in doubt, feel free to contact me.

Simulating Circuits

This section describes how a circuit is designed in this software. As said before, the user interface for this software is spreadsheets saved as Comma Separated Value (.csv) files. To repeat a snapshot of the circuit in the previous section:



Sample circuit

By designing a circuit the way shown above, I avoid the use of a graphical interface but at the same time make it reasonably convenient for the user as they can more or less "draw" the circuit in a spreadsheet. The other option would be to provide a netlist describing the connectivity between nodes which is not feasible for larger circuits. The following components are available to the user as of now:

  1. wire : this is a zero impedance connector between components.
  2. Resistor: a constant value resistor. Initial value = 100 ohm.
  3. VariableResistor: a resistor whose value is a control input and thus can be changed from control code. Initial value = 100 ohm.
  4. Inductor: a constant value inductor: Initial value = 1 millihenry.
  5. VariableInductor: an inductor whose value is a control input and thus can be changed from control code. Initial value = 1 millihenry.
  6. Capacitor: a constant value capacitor. This component has a polarity. Initial value = 10 microfarad.
  7. VoltageSource: a constant value voltage source. This component has a polarity. Initial value - Peak = 120 V, Frequency = 60 Hz, Phase = 0 degrees, Dc offset = 0 V.
  8. Ammeter: measures current. The output is the current through it and it is plotted in the output data file. This component has a polarity.
  9. Voltmeter: measures voltage. The output is the voltage across it and it is plotted in the output data file. This component has a polarity.
  10. CurrentSource: a current source. This is actually a voltage in series with a resistance. The voltage is adjusted so that the current is as desired. This component has a polarity. Initial values - Peak = 5 Amps, Frequency = 60 Hz, Phase = 0 degrees, Dc offset = 0 Amps.
  11. ControlledVoltageSource: a controlled voltage source. The voltage generated is a control input that can be controlled from control code. The value can be anything set by the control code and can change at any rate. This component has a polarity.
  12. Diode: a normal diode. This component has a polarity. The diode turns on when the voltage across it is around 1 V, and turns off when the current reverses. Initial values - Voltage rating = 120 V. This voltage rating is to ensure that in a circuit with that voltage, the leakage current drawn by the diode when off is negligible (around 1 microampere).
  13. Switch: an ideal switch. This has a control input which is the gate signal. A zero gate signal turns it off and a gate signal of 1 turns it on. The control input is initially zero, and can be changed through control code. This component has a polarity. Initial values - Voltage level = 120 V, Name of control = Control. The name of the control should be changed to a unique value the way the user wishes to name the gate signal.

More components may be added as needed. Now that all the components that can be used have been listed, how do you use them? A component as shown in the figure above has two parts - the component type (one of those listed above) and the name of the component separated by an underscore. In the above example, in VoltageSource_V1, the first part is the type which is VoltageSource while the second part is the name which is V1. The underscore is a reserved character, do not use it in anywhere in a circuit description. Everywhere else, like in the control functions, you can use underscore as will be shown later, but never use it in the circuit schematic. The only rule in naming components is that two components of the same type cannot have the same name. Which means there cannot be two VoltageSource components with the name V1. In the above example, VoltageSource and Voltmeter have names V1. That is acceptable. Different component types can have the same name.

Though it is not a component, there is a jump connector. The reason is that sometimes wires will cross each other and it is unavoidable. The way the simulator works, if it sees two or more components in adjacent cells, it forms a physical connection. The way to use a jump connection is shown with this circuit.

Jump example

The above circuit of a single-phase diode bridge rectifier fed by a voltage source cannot be designed without a jumper. The labels jump1 at cell positions 16E and 11K are jump connections. When the simulator encounters a jump connection, it looks for another jump connection with the same name and continues the branch from that connection. There are a few rules for using jump connections:

  1. The first four letters of a jump connection have to be "jump". After that everything else is a label. Though label is matched as is, it is advisable not to use special characters. Letters and numbers are preferred for jump labels.
  2. Jump labels must occur in pairs. Anything else is a violation. A jump label is merely a continuation of a branch.
  3. Two jump labels cannot be next to each other.
  4. A jump label must be the extreme end of a branch segment. Which means a jump label must have a component or wire in only one of its adjacent cells.
  5. A jump cannot form a node or be immediately adjacent to a node.