7. Introduction to the Examples

This section gives an overview of the use of PySpice by means of examples inspired from typical circuits, which can also serve as learning materials.

Usually these examples don’t involve advanced Python programming. You just need to know basic Python programming and how to use the Numpy and Matplotlib framework. However the code to make complex plots can require advanced Matplotlib skills.

Each example features a banner with a download icon just after the file name and a button (>>>) on the right to show the content of the file.

7.1. How to Learn Python

Some links to learn about Python programming and Scientific Framework:

7.2. How to Run these Examples

There are several ways to run the examples: as a script from the console, in the IPython interactive environment or in a web browser using a IPython Notebook. Each of them has their advantages and drawbacks. A script is best when we want to work on a file using an editor, and an interactive environment is best when we want to play with code interactively.

You have to set an environment so as to find the Spice libraries.

On Linux, use this shell command:

export PySpice_source_path=${PWD}
export PySpice_examples_path=${PySpice_source_path}/examples

On Windows, use this command:

SET PySpice_example_path=C:/Users/John/PySpice/examples

To run an example from the console, execute this command:

python examples/.../foo.py

To start the interactive IPython environment, execute one of these commands:

ipython --matplotlib       # enable matplotlib integration
ipython --matplotlib-qt    # enable matplotlib integration with qt4 backend
ipython qtconsole          # start the qtconsole GUI application

then run an example using the magic command:

%run examples/../foo.py

To start the IPython notebook in your web browser:

ipython notebook

When we use IPython notebook, it is convenient to use a matplotlib backend that outputs the graphics embedded in the notebook file. To activate this backend, somewhere in the beginning on the notebook, you must add:

%matplotlib inline

Then you can copy-paste code blocks and execute them.

7.3. How to Write a Netlist

Obviously it is not easy to write a netlist from scratch. The best approach is to make a quick sketch and to bless each node. However you can also use a schematic capture progam like Kicad and then export the netlist to SPICE.

7.4. Documentation Generator

This documentation is automatically generated from the Python examples using the tool generate-rst-examples located in the tools directory of the sources. This tool has a similar purpose than a IPython notebook, but it handles the generation of circuit diagrams and static pages.

This tool walks recursively through the examples directory and processes each Python file.

A typical Python file contains these lines:

# A source code comment
#?# A comment that must not appear in the documentation

python code ...

#!# ==========================
#!#  A Restructuredtext Title
#!# ==========================

python code ...

#!#
#!# Some reStructuredText contents
#!#

python code ...

# Insert the output of the following python code
python code ...
#o#

# Hidden Python code
#h# value = 123

#!# Format RST content with current locals dictionary using @@<<@@...@@>>@@ instead of {...}.
#!#
#!# .. math::
#!#
#!#     I_d = @<@value@>@ I_s \left( e^{\frac{V_d}{n V_T}} - 1 \right)

# Add the file content as literal block
#itxt# kicad-pyspice-example/kicad-pyspice-example.cir

# Add a Python file as a literal block
#i# RingModulator.py

# Insert an image
#lfig# kicad-pyspice-example/kicad-pyspice-example.sch.svg

# Insert Circuit_macros diagram
#cm# circuit.m4

# Insert Tikz figure
#tz# diode.tex

# Insert a Matplotlib figure
#fig# save_figure(figure, 'my-figure.png')

python code ...

As you see it is a valid Python source code, but with some comments having a special meaning, so called directive comments:

  • #?# is a comment that must not appear in the documentation,
  • #h# is a hidden Python code that must not appear in the documentation,
  • #!# is a reStructuredText content,
  • #o# instructs to include the sdtout of the previous Python code chunk,
  • #itxt# instructs to include the file content as a literal block,
  • #i# instructs to include a Python file as a literal block,
  • #lfig# instructs to include an image,
  • #cm# instructs to include a figure generated by the Circuit_macros diagram generator,
  • #tz# instructs to include a Tikz figure generated by pdflatex,
  • #fig# instructs to include a figure generated by Matplotlib and a modified version of the Python file including this uncommented line.

The generator provides a more sophisticated way to embed computations in the RST documentation using the Python string format() function. You just have to use the @<@…@>@ syntax instead of {…}, then the RST string will be formatted using the current locals dictionary as parameter to format(). Note you can use hidden Python code to prepare data for this purpose.

The documentation generator will do these actions for each file:

  • read the source and collect the directive comments
  • generate a Restructuredtext .rst file
  • generate a Circuit_macros figure if a m4 file as a more recent timestamp than the output image
  • generate the Matplotlib figure is the file as a more recent timestamp than the rst file

At the end, the documentation generator generate a table of contents.