ahkab

ahkab
=====

**a SPICE-like electronic circuit simulator written in Python**

The code should be easy to read and modify, the main language is Python
-- 2 or 3 -- and it is platform-independent.

News!
-----

-  Ahkab v0.18 was released on July 18 2015, including new features,
   bugfixes and improved documentation. It is recommended to upgrade.
   Check out `the release
   notes <https://github.com/ahkab/ahkab/releases/tag/v0.18>`__ for
   more!
-  The whole codebase has been going through a (yet incomplete)
   refactoring and documenting effort. The `new documentation is
   available on RTD <http://ahkab.readthedocs.org/en/latest/>`__.

My resources are limited these days, so the much-needed work is
proceeding slowly, albeit hopefully steadily. If you are interested and
you would like to contribute to refactoring or documenting a particular
feature, it would be very welcome.

|Build Status| |Coverage Status| |PyPi version| |GPLv2 license| |DOI|

Supported simulations:
----------------------

-  Numeric:

   -  **Operating point**, with guess computation to speed up the
      solution. See example: `Downscaling current
      mirror <https://ahkab.readthedocs.org/en/latest/examples/OP_simulation.html>`__
   -  **DC sweep**
   -  **Transient analysis**, available differentiation formulas:
      implicit Euler, trapezoidal, gear orders from 2 to 5. See for
      example the `simulation of a Colpitts
      Oscillator <https://ahkab.readthedocs.org/en/latest/examples/Transient-Example.html>`__.
   -  **AC analysis**
   -  **PZ** analysis
   -  **Periodic steady state analysis** of non-autonomous circuits,
      *time* *domain* shooting and brute-force algorithms.

-  Symbolic:

   -  **Small signal analysis**, AC or DC, with extraction of transfer
      functions, DC gain, poles and zeros. Various `symbolic analysis
      examples on this
      page <https://ahkab.readthedocs.org/en/latest/examples/Symbolic-simulation.html>`__.

The results are saved to disk, plotted or printed to stdout and can be
read/processed by the most common tools (eg.
`Octave <http://www.gnu.org/software/octave/>`__,
`gnuplot <http://www.gnuplot.info/>`__,
`Matlab <http://www.mathworks.com/products/matlab/>`__,
`gwave <http://www.telltronics.org/software/gwave/>`__ and others)

Install
-------

The program requires:

-  the Python interpreter version 2 or 3 (at least v.2.6 for Python2,
   v.3.3 for Python3),
-  numpy>=1.7.0, scipy>=0.14.0, sympy>=0.7.6 and tabulate>=0.7.3.

Matplotlib is strongly recommended and no plotting will work without.

If you need more information about the dependencies, check the `Install
notes <https://ahkab.readthedocs.org/en/latest/help/Install-Notes.html>`__.

Usage
-----

1. ``ahkab`` can be run as a Python library
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

    from ahkab import new_ac, run
    from ahkab.circuit import Circuit
    from ahkab.plotting import plot_results # calls matplotlib for you
    import numpy as np

    # Define the circuit
    cir = Circuit('Butterworth 1kHz band-pass filter')
    cir.add_vsource('V1', 'n1', cir.gnd, dc_value=0., ac_value=1.)
    cir.add_resistor('R1', 'n1', 'n2', 50.)
    cir.add_inductor('L1', 'n2', 'n3', 0.245894)
    cir.add_capacitor('C1', 'n3', 'n4', 1.03013e-07)
    cir.add_inductor('L2', 'n4', cir.gnd, 9.83652e-05)
    cir.add_capacitor('C2', 'n4', cir.gnd, 0.000257513)
    cir.add_inductor('L3', 'n4', 'n5', 0.795775)
    cir.add_capacitor('C3', 'n5', 'n6', 3.1831e-08)
    cir.add_inductor('L4', 'n6', cir.gnd, 9.83652e-05)
    cir.add_capacitor('C4', 'n6', cir.gnd, 0.000257513)
    cir.add_capacitor('C5', 'n7', 'n8', 1.03013e-07)
    cir.add_inductor('L5', 'n6', 'n7', 0.245894)
    cir.add_resistor('R2', 'n8', cir.gnd, 50.)

    # Define the analysis
    ac1 = new_ac(2.*np.pi*.97e3, 2.*np.pi*1.03e3, 1e2, x0=None)

    # run it
    res = run(cir, ac1)

    # plot the results
    plot_results('5th order 1kHz Butterworth filter', [('|Vn8|',"")], res['ac'],
                 outfilename='bpf_transfer_fn.png')

2. ``ahkab`` can be run from the command line with a netlist file
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The syntax is:

::

    `$ python ahkab -o graph.dat <netlist file>`

See ``ahkab --help`` for command line switches, `also online on the
documentation
pages. <http://ahkab.readthedocs.org/en/latest/help/Command-Line-Help.html>`__

Documentation
~~~~~~~~~~~~~

The `documentation is available on
RTD <http://ahkab.readthedocs.org/en/latest/>`__.

There, you can find a
`documentation <http://ahkab.readthedocs.org/en/latest/ahkab.html>`__
and
`examples <http://ahkab.readthedocs.org/en/latest/examples/Python_API.html>`__
regarding how to simulate from a Python script.

Refer to the `netlist syntax
page <http://ahkab.readthedocs.org/en/latest/help/Netlist-Syntax.html>`__
if you prefer to write netlist files that describe the circuit.

Experience with running SPICE or related commercial simulators can be
very useful: this is not for the faint of heart.

Development model
~~~~~~~~~~~~~~~~~

-  The development happens on the `github
   repository <https://github.com/ahkab/ahkab>`__,
-  Mostly on the master branch, with feature branch being created only
   for special purposes or non-trivial features.
-  Snapshots are released on a (hopefully) regular basis and are
   available on the `Releases pages, complete with
   changelog <https://github.com/ahkab/ahkab/releases>`__ and on
   `PYPI <https://pypi.python.org/pypi/ahkab/>`__

Patches and pull requests are welcome!

How this project was born
~~~~~~~~~~~~~~~~~~~~~~~~~

This project was born when I was an enthusistic undergrad, apparently
with plenty of free time, attending "Simulazione Circuitale" (*Circuit
Simulation*) taught by `Prof. A.
Brambilla <http://brambilla.dei.polimi.it/>`__ back in Italy at the
Polytechnic University of Milan.

I am grateful to prof. Brambilla for teaching one of the most
interesting courses of my university years. -GV

Bugs and patches
~~~~~~~~~~~~~~~~

Does it work? Bugs? Do you have patches? Did you run some noteworthy
simulation? Let me know! Feedback is very welcome, my `email
address <http://tinymailto.com/5310>`__ is available after a captcha.

Support the development with a donation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If you wish to support the development of ``ahkab``, ***please donate to
cancer research:***

-  `Association for International Cancer Research
   (eng) <http://www.aicr.org.uk/donate.aspx>`__,

or

-  `Fond. IRCCS Istituto Nazionale dei Tumori
   (it) <http://www.istitutotumori.mi.it/modules.php?name=Content&pa=showpage&pid=24>`__.

Credits
~~~~~~~

**Authors:** `Giuseppe Venturini <https://github.com/ggventurini>`__,
with contributions from `Ian Daniher <https://github.com/itdaniher>`__
and `Rob Crowther <https://github.com/weilawei>`__.

**Code:** the module ``py3compat.py`` is (c) 2013 - the Jinja team.

**Dependencies:** many thanks to the authors of ``numpy``, ``scipy``,
``sympy``, ``matplotlib`` and ``tabulate``!

.. |Build Status| image:: https://travis-ci.org/ahkab/ahkab.png?branch=master
   :target: https://travis-ci.org/ahkab/ahkab
.. |Coverage Status| image:: https://coveralls.io/repos/ahkab/ahkab/badge.png?branch=master
   :target: https://coveralls.io/r/ahkab/ahkab?branch=master
.. |PyPi version| image:: http://img.shields.io/badge/version-0.18-brightgreen.png
   :target: https://pypi.python.org/pypi/ahkab/
.. |GPLv2 license| image:: http://img.shields.io/badge/license-GPL%20v2-brightgreen.png
   :target: https://raw.githubusercontent.com/ahkab/ahkab/master/LICENSE
.. |DOI| image:: https://zenodo.org/badge/doi/10.5281/zenodo.17696.svg
   :target: http://dx.doi.org/10.5281/zenodo.17696