Using the software

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 save it.






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.






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.






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 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:






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.






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 command:

$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 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.