VPL: Circuit Simulation Assignments with SPICE | Prof. James Andrew Smith's Blog

Introduction

In YorkU's EECS Department, we have access to NGSPICE on our department's Linux machines (via RemoteLab). NGSPICE is yet another variation on the venerable SPICE circuit simulator. Our the University's Moodle system, eClass, we have access to Virtual Programming Lab, a framework for making interactive exercises for students. It is typically used with programming languages like C, Java or Python. But there is support for electrical engineering languages like Verilog and VHDL. It's also possible to use it with less traditional, outside-the-box, applications like Maple and chip simulators like Microchip's MDB.

While I normally advocate for graphical front-ends as being the most appropriate and accessible for student learning, the fact that SPICE began its life as a terminal-based application works to our advantage. We can use the terminal commands that make SPICE work within VPL.

Let's look at two terminal-based SPICE examples, in their traditional terminal framework. Once we're done with that we'll move on to applying them to VPL.

Video Overview

A YouTube video (link here) has been made to illustrate how all of this is done. The vpl_run.sh, etc. scripts used in the video are found here. Just copy and paste.

Typical SPICE Usage

So, if you're reading this, you likely have never used VPL, but you have probably used SPICE before, either from the command line or integrated in a GUI like gEDA. integrated inside another run SPICE before. Let's look at a basic example, a low pass filter.

This example comes from eCircuits Center. The low pass filter, made with a resistor (R1) and a capacitor (C1). We specific it like this:

LPFILTER.CIR - SIMPLE RC LOW-PASS FILTER
*
VS	1	0	AC	1	SIN(0VOFF 1VPEAK   2KHZ)
*
R1	1	2	1K
C1	2	0	0.032UF
*
* ANALYSIS
.AC 	DEC 	5 10 10MEG
.TRAN 	5US  500US
*
* VIEW RESULTS
.PRINT	AC 	VM(2) VP(2)
.PRINT	TRAN 	V(1) V(2)

*
.PROBE
.END

We save the file and call it eCircuitCenter.netlist. To execute the simulation on this model we do the following from the command line:

ngspice -b eCircuitCenter.netlist

And the output looks like this:

Terminal output for ngspice. — Terminal output for ngspice with the Low Pass filter.

... and it continues....

And if we want to create graphs, we can do ASCII-art graphs with a "plot" command:

.PLOT AC VM(2) VP(2)

just below the .PRINT command in the text file, which then results in a graphical output like this:

It's not the most modern-looking graph, but it's functional. Just turn your head 90 degrees and you'll see it!

Because both the output tables and graphs are text-based we can use the Unix-command "diff" within VPL to compare the students' simulation solutions to the teacher's simulation solution really easily.

Adding SPICE to VPL

NGSpice has been added to our VPL server so you can use it from eClass (Moodle). All you need to do is create a VPL activity within eClass. Here are the steps.

Step 1. Create a VPL activity in eClass

Add a VPL activity as you would an H5P activity or a regular assignment in Moodle / eClass.

Step 2. Describe the VPL activity

Add a description, set the maximum grade. I like to make them out of 1, but the default is out of 100.

Step 3: Specify the Location of the VPL Server

Normally eClass (Moodle) will default to using the VPL server in Spain, as that's where the developers of VPL are. Instead, choose the "Local execution servers" option in the Gear menu and type in

https://xxxxx.yyyyy.yorku.ca
end_of_jails

where xxxx.yyyyy need to be replaced with the name of the VPL server at York that you're using. There can be multiple machines. Talk to your system admin people to figure out which value to use.

Step 4: Add a student template in "Requested Files"

Typically, this is a nearly complete SPICE netlist. The following file is complete, but you may wish to remove or comment out the

R1 1 2 1K

line in the following file and have the students fill it in.

LPFILTER.CIR - SIMPLE RC LOW-PASS FILTER
*
VS      1       0       AC      1       SIN(0VOFF 1VPEAK   2KHZ)
*
R1      1       2       1K
C1      2       0       0.032UF
*
* ANALYSIS
.AC     DEC     5 10 10MEG
.TRAN   5US  500US
*
* VIEW RESULTS
.PRINT  AC      VM(2) VP(2)
.PRINT  TRAN    V(1) V(2)
.PLOT AC VM(2) VP(2)
*
.PROBE
.END

Note that you want to be careful about lines like the opening line

LPFILTER.CIR - SIMPLE RC LOW-PASS FILTER

as this will appear in the simulation. If the student template and the teacher solution differ on this line then VPL will report that the simulation results are inconsistent and the student will get zero.

Step 5. Add a vpl_run.sh file

This file is similar to the one developed for Maple exercises. Nothing much to change in here, although the grade value might be something you wish to tweak. I like grading out of 1. You might now. Change it if you like, by going to the highlighted part. Note that in the "run" file the grade is a preview. It won't show up in the student's grade book. The student needs to "evaluate" for that.

#!/bin/bash
#
# vpl_run.sh script (SPICE version)
# The output of the student program is tested against the expected output file.
# 
# James Andrew Smith; drsmith@yorku.ca July 2021
# Based on example by D. Thiebaut at Smith College
# http://www.science.smith.edu/dftwiki/index.php/Tutorial:_Moodle_VPL_--_Testing_a_C_Program
# and
# https://www.mapleprimes.com/posts/38232-Scripting-With-Maple
# -----------------------------------------------------------------


cat > vpl_execution <<EEOOFF
#!/bin/bash

# Variables (make changes here)
teacherSolution=teacherSpiceSolution
studentProgram=studentTemplate
maxGrade=1
minGrade=0
consolationGrade=0


# --- create test (Teacher Solution) ---

# run Spice on the teacher solution.  Output to solution.txt.  Extra text to /dev/null
echo "running spice on teacher solution..."
ngspice -b \${teacherSolution}.cir -n -o solutionTemp.txt > /dev/null

# erase all lines at the end of the file after "elapsed":
sed -n '/elapsed/q;p' solutionTemp.txt > solution.txt

# Default grade is zero.
grade=\$minGrade

for i in 1 ; do
   echo "TEST \$i"

   # ==============================================
   # TEST i
   # ==============================================
   #--- run program, capture output, display to student ---

   echo "Running SPICE on the student solution..."
ngspice -b \${studentProgram}.cir -n -o userTemp.out > /dev/null

# erase all lines at the end of the file after "elapsed":
sed -n '/elapsed/q;p' userTemp.out > user.out


   # all processing of whitespace to remove it has been, itself removed.
   # want to see how that's done?  Go to 
   # http://www.science.smith.edu/dftwiki/index.php/Tutorial:_Moodle_VPL_--_Testing_a_C_Program
   
   #--- compute difference, with exact whitespace --- 
   diff -y user.out solution.txt > diff.out
   
   # debug:
 #    echo "----- diff.out ------"
 #   cat diff.out
 #   echo "---------------------"

   
   #--- reject if different ---
   if ((\$? > 0)); then
      echo "Your output is NOT correct."


      echo "---------------"
      echo "Your output:"
      echo "---------------"
      cat user.out
      
      echo ""
      echo "---------------"
      echo "Expected output  "
      echo "---------------"
      cat solution.txt

      grade=\$( expr \$minGrade )
   
      #--- consolation grade ("thanks for coming out")---   
      #grade=\$( expr \$consolationGrade )

      # --------------------- REWARD IF CORRECT OUTPUT -----------------
   else
      #--- good output ---
      echo "Congrats, your output is correct."
      echo " --------------------------------"
      cat user.out
      echo "--------------------------------"
      grade=\$( expr \$maxGrade )
   fi
done

echo "Possible Grade : \$grade (you need to evaluate for official grade)"

exit 0
EEOOFF

 
chmod +x vpl_execution
exit 0

Step 6. Add a vpl_evaluate.sh file

You shouldn't have to change much in here. I like to grade out of 1, but you might not. Check out the highlighted part below and change that if you like.

#!/bin/bash
#
# vpl_evaluate.sh script (SPICE version)
# The output of the student program is tested against the expected output file.
# 
# James Andrew Smith; drsmith@yorku.ca July 2021
#
# Based on example by D. Thiebaut at Smith College
# http://www.science.smith.edu/dftwiki/index.php/Tutorial:_Moodle_VPL_--_Testing_a_C_Program
# -----------------------------------------------------------------


cat > vpl_execution <<EEOOFF
#!/bin/bash

# Variables (make changes here)
# ----------------------------------------------
# vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv
# ----------------------------------------------
teacherSolution=teacherSpiceSolution
studentProgram=studentTemplate
maxGrade=1
minGrade=0
consolationGrade=0
# ----------------------------------------------
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# ----------------------------------------------

# --- create test (Teacher Solution) ---
/dev/null
echo "running spice on teacher solution..."
ngspice -b \${teacherSolution}.cir -n -o solutionTemp.txt > /dev/null

# erase all lines at the end of the file after "elapsed":
sed -n '/elapsed/q;p' solutionTemp.txt > solution.txt





# Default grade is zero.
grade=\$minGrade


for i in 1 ; do
   echo "Comment :=>>-TEST \$i"

   # ==============================================
   # TEST i
   # ==============================================
   #--- run program, capture output, display to student ---


   echo "Running SPICE on the student solution..."
ngspice -b \${studentProgram}.cir -n -o userTemp.out > /dev/null

# erase all lines at the end of the file after "elapsed":
sed -n '/elapsed/q;p' userTemp.out > user.out
   


   
   diff -y user.out solution.txt > diff.out

   
   
   #--- reject if different ---
   if ((\$? > 0)); then
      echo "Comment :=>>- Your output is incorrect."


      echo "Comment :=>> ---------------"
      echo "Comment :=>>- Your output:"
      echo "Comment :=>> ---------------"
      echo "<|--"
      cat user.out
      echo "--|>"
      echo ""
      echo "Comment :=>> ---------------"
      echo "Comment :=>>- Expected output: "
      echo "Comment :=>> ---------------"
      echo "<|--"
      cat solution.txt
      echo "--|>"
   
      grade=\$( expr \$minGrade )
   
      #--- consolation grade ("thanks for coming out")---   
      #grade=\$( expr \$consolationGrade )

      # --------------------- REWARD IF CORRECT OUTPUT -----------------
   else
      #--- good output ---
      echo "Comment :=>>- Congrats, your output is correct."
      echo "Comment :=>> --------------------------------."
      echo "<|--"
      cat user.out
      echo "--|>"
      grade=\$( expr \$maxGrade )
   fi
done

      
      

echo "Grade :=>> \$grade"
exit 0
EEOOFF

 
chmod +x vpl_execution
exit 0

Step 7. Add a solution (teacherSpiceSolution.cir)

Name the following file teacherSpiceSolution.cir (yeah, I know it doesn't match the first line of the SPICE file below)

LPFILTER.CIR - SIMPLE RC LOW-PASS FILTER
*
VS	1	0	AC	1	SIN(0VOFF 1VPEAK   2KHZ)
*
R1	1	2	1K
C1	2	0	0.032UF
*
* ANALYSIS
.AC 	DEC 	5 10 10MEG
.TRAN 	5US  500US
*
* VIEW RESULTS
.PRINT	AC 	VM(2) VP(2)
.PRINT	TRAN 	V(1) V(2)
*
.PROBE
.END

Step 8. Make sure that the solution file doesn't get ignored during processing.

Gear -> Files to keep while running.

Check the teacherSpiceSolution.cir file in this list.

Step 9. Test it as a "demo student"

Hopefully, you've enabled the "fake student mode", also known as "demo student". This will give you a nearly one-to-one match of what the students see, including the Grade Book view. This was added to eClass / Moodle in the Summer of 2020 after my colleague, Dr. Ostroff, and I made pitches for it. Use it to test your VPL activity out, but also use it to verify other elements of your eClass page!

Conclusions

Providing students with interactive activities is a great way to get them to practice, whether its developing electric models in SPICE or programming Java applications. Use this for pre-lab work or reviews prior to a midterm test. There are lots of possibilities.

Resources

https://www.ibiblio.org/kuphaldt/electricCircuits/DC/DC_2.html
https://web.stanford.edu/class/ee133/handouts/general/spice_ref.pdf
https://www.seas.upenn.edu/~jan/spice/spice.overview.html

James Andrew Smith is Professional Engineer and an associate professor in Electrical Engineering and Computer Science Department in York University's Lassonde School. Originally from Québec, James has degrees in Electrical Engineering from the University of Alberta and a PhD in Mechanical Engineering from McGill. He did a post-doc from 2006-2008 at the Institute for Sports Science in Jena, Germany. His engineering research background includes galloping robots, human birth and clothing. James believes that we can improve the way we teach. He 2018-19, he lived in Strasbourg and taught at the INSA Strasbourg (France) and Hochschule Karlsruhe (Germany) while on sabbatical with his wife and kids. Some of his other blog posts discuss the family's sabbatical year, from both personal and professional perspectives.