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:
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
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
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:
If you are using IDLE in Windows, open the file circuit_solver.py and either press F5 or go to Run menu and choose
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.
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:
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.
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.
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:
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.
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.
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
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:
As said before the first column is the time, the second is the ammeter output and the third is the voltmeter output. So
$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.
And to check the voltage:
$plot "ckt_out.dat" u 1:3 w l
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.
The top right of the graph contains the key to the graph. Since the current is hardly visible, we use the handy
$plot "ckt_out.dat" u 1:($2*20) w l, '' u 1:3 w l
Since the current has being magnified by a factor of 20, it is possible to check the phase of the current with respect to
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.