2. Examples

This section gives an overview of what we can do with PySpice. These examples are inspired from classical circuits and can serve as learning materials.

Warning

The PDF generated by the Sphinx documentation generator could be poorly formatted.

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 figures can require advanced Matplotlib topics.

2.1. How to Learn Python

Some links to learn about Python programming and Scientific Framework:

2.2. How to Run these Examples

A Linux desktop is the best platform to work with PySpice. Indeed it is easier to get NgSpice running and install Python.

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 the Ipython Notebook. Each 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 live.

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

python examples/.../foo.py

To start the interactive IPython environment:

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.

Warning

Notice that for security reason, web browsers don’t offer a simple way to copy-paste a code block, i.e. fill the clipboard using a button and some javascript behind the scene (Github and others use a hack based on Flash to achieve this).

You must select and copy the code by hand.

2.3. How to Write a Netlist

Obviously it is not easy to write a netlist from scratch. The right approach is to make a quick sketch and to bless each node. You can sketch on a sheet of paper or using a pen display in a modern way. You could also use a sketcher like Kicad and export the netlist to SPICE.

2.4. Documentation Generator

This documentation is automatically generated from the Python examples using the tool generate-rst-examples located in the source in the tools directory.

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

A typical Python file contains such lines:

python code ...

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

python code ...

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

python code ...

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

python code ...

#cm# circuit.m4

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

  • a comment starting with #?# is a comment that must not appear in the documentation,
  • a comment starting with #!# is a Restructuredtext content,
  • a comment starting with #cm# indicates to include a figure generated by the Circuit_macros diagram generator,
  • a comment starting with #fig# indicates to include a figure generated by Matplotlib and a modified version of the Python file including this uncommented line.

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

The documentation generator will also generate a hierarchical table of contents.