.. include:: abbreviation.txt .. _example-introduction-page: .. TO BE CHECKED ============================== 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 `_ * `Pyplot tutorial `_ * `Python Scientific Lecture Notes `_ * `Scientific Python Lectures `_ --------------------------- How to Run these Examples --------------------------- .. CHECK JUPYTER 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 also use `SKiDL `_ which is a Python module that allows you to compactly describe the interconnection of electronic circuits and components, see this full example https://github.com/xesscorp/skidl/blob/master/examples/spice-sim-intro/spice-sim-intro.ipynb .. You can sketch on a sheet of paper or using a pen display in a modern way. ----------------------- How to Draw a Circuit ----------------------- There are several ways to draw a circuit, depending on whether you want a high-quality figure or just something quickly: * Sketch a circuit on a sheet of paper and scan it, or better use a tablet. Note that this can be artistic if you are skilled. * Use a schematic editor like KiCad and export the circuit as SVG, KiCad allows you to choose the line width, a color or black pen and to remove the frame. You can then edit the SVG using `Inkscape `_. Usually KiCad SVG output might not be perfect and the lake of Python interface to the schematic editor does not help. * Use `Schemdraw `_ a Python package for producing high-quality electrical circuit schematic diagrams (SVG). Circuit elements are added, one at a time, similar to how you might draw them by hand, using Python methods. * Use complex graphic languages like `CircuiTikZ `_ or `Circuit_macros `_. The first one is a LaTeX Tikz package and the second use M4 macro and LaTeX to render circuits. These tools are well suited for publications or books. A vector graphic format like SVG is preferable for web publications, rather PDF is preferable for paper publications. The main difference between SVG and PDF is the way they handle fonts, else they are interchangeable and convertible to each other. ---------------------------------------------------- Should I Use a Python File or a Jupyter Notebook ? ---------------------------------------------------- `JupyterLab `_ provides an environment as a web application similar to Matlab for Python and other languages. To answer this question in a few words, if you are looking for an environment similar to Matlab, then Jupyter could be an option. But if you want to do complex programming, then standard Python files are the way to go. From a technical point of view, a `Jupyter Notebook `_ is a JSON file, i.e. a Python dictionary encoded in a text file, that embed cells which are either Python code, Markdown text, or images (base-64 encoded). Form the Git point of view, a plain Python file is more suited than a JSON file that embed codes and outputs. As an alternative to a Jupyter Notebook, we can implement the concept of **literate programming**, the idea is to mix rich texts and codes in source files. Some implementations will embed rich texts as comments, other will require a tool to split the text and the code. Conceptually, it is similar to a Jupyter Notebook, excepted a notebook can embed results and is not designed to be human readable. PySpice examples use the `Pyterate `_ documentation generator where a file is a plain Python file with texts encoded as comments. You can also look to `Pweave `_ as an alternative. A Jupyter Notebook has also the following drawbacks : * a Notebook imposes to use a web browser as an editor, a workaround is to use an editor plugin like `Emacs IPython Notebook (EIn) `_, * JupyterLab is a very bad code editor and doesn't implement common features found in an IDE like completion, `linting `_ etc. * JupyterLab require extensions, e.g. https://github.com/matplotlib/ipympl to get interactive plots, * outputs should not be committed, a workaround is to run the command `jupyter nbconvert my_input_notebook.ipynb --to notebook --ClearOutputPreprocessor.enabled=True --output my_output_notebook`, * a JSON diff is not so readable by humans, * it is risky to apply a text replacement on files, * Jupyter hang on OSX continuous platform virtual machines, this prevents to run notebooks, * SVG image support seems broken in JupyterLab,