.. include:: abbreviation.txt

.. _example-introduction-page:

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

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

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

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

.. code-block:: sh

    python examples/.../foo.py

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

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

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

.. You can sketch on a sheet of paper or using a pen display in a modern way.
