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