.. -*- Mode: rst -*-

.. _examples-page:

.. include:: ../abbreviation.txt

==========
 Examples
==========

This section gives an overwiew 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 complexe
figures can require advanced Matplotlib topics.

---------------------
 How to Learn Python
---------------------

Some links to learn about Python programming and Scientific Framework:

* `The Python Tutorial <https://docs.python.org/2.7/tutorial/index.html>`_
* `Pyplot tutorial <http://matplotlib.org/users/pyplot_tutorial.html>`_
* `Python Scientific Lecture Notes <https://scipy-lectures.github.io/>`_
* `Scientific Python Lectures <http://nbviewer.ipython.org/github/jrjohansson/scientific-python-lectures/tree/master/>`_

----------------------------
 How to Run theses Examples
----------------------------

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

There is 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 in live.

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

.. code-block:: sh

  python examples/.../foo.py

To start the interactive IPython environment:

.. code-block:: sh

  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:

.. code-block:: py

 %run examples/../foo.py

To start the IPython notebook in your web browser:

.. code-block:: sh

  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:

.. code-block:: py

  %matplotlib inline

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

.. warning::

  Notice 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 by hand the code.

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

-------------------------
 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 walk recursively through the *examples* directory and process 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.

--------------------
 Tables of Contents
--------------------

The examples are classified by topics:

.. End
