deltasigma 0.1-9

python-deltasigma
=================

A port of the **MATLAB Delta Sigma Toolbox** based on free software and
very little sleep

The **python-deltasigma** is a Python package to *synthesize, simulate,
scale and map to implementable topologies* **delta sigma modulators**.

It aims to provide **a 1:1 Python port** of Richard Schreier's
***excellent*** `MATLAB Delta Sigma
Toolbox <http://www.mathworks.com/matlabcentral/fileexchange/19-delta-sigma-toolbox>`__,
the *de facto* standard tool for high-level delta sigma simulation, upon
which it is very heavily based. |githalytics.com alpha|

--------------

**Homepage:** `python-deltasigma.io <http://python-deltasigma.io>`__

**Documentation:**
`docs.python-deltasigma.io <http://docs.python-deltasigma.io>`__

**Latest version:** `0.1 <https://pypi.python.org/pypi/deltasigma/>`__

|Build Status| |Coverage Status| |PyPi version| |PyPi downloads| |BSD 2
clause license| |DOI BADGE|

Install
-------

``python-deltasigma`` runs on Linux, Mac OS X and Windows.

Installing requires **Python 2.6+** or **3.3+**, **numpy**, **scipy**
(>= 0.11.0) and **matplotlib**.

Strongly recommended: **Cython** - for significantly faster delta sigma
modulator simulations.

They are packaged by virtually all the major Linux distributions.

I do not run Windows, so I can't really provide more info (sorry),
except that people tell me they manage to have a working setup.

When the dependencies are satisfied, run:

::

pip install deltasigma

to install the latest stable version from the `Python Package Index
(PYPI) <http://pypi.python.org>`__, or:

::

python setup.py install

if you're installing a development version from Git.

Extras
~~~~~~

Install the `sphinx <http://sphinx-doc.org/>`__ package to build the
documentation yourself.

The test suite requires
`setuptools <https://pypi.python.org/pypi/setuptools>`__, used to
access the reference function outputs.

Testing can be automated with
`nose <https://pypi.python.org/pypi/nose/>`__ and triggered with:

::

python setup.py test


Documentation
-------------

In addition to the notebooks found in the ``examples/`` directory,
ported from the MATLAB Delta Sigma toolbox:

1. You can find the included `package documentation
online <http://python-deltasigma.readthedocs.org/en/latest/>`__.

2. The original MATLAB Toolbox provides in-depth documentation, which is
very useful to understand what the toolbox is capable of. See
`DSToolbox.pdf <https://github.com/ggventurini/python-deltasigma/blob/master/delsig/DSToolbox.pdf?raw=true>`__
and
`OnePageStory.pdf <https://github.com/ggventurini/python-deltasigma/blob/master/delsig/OnePageStory.pdf?raw=true>`__
(*PDF warning*).

3. The book:

Richard Schreier, Gabor C. Temes, *Understanding Delta-Sigma Data
Converters*, ISBN: 978-0-471-46585-0, November 2004, Wiley-IEEE Press

is probably *the most authoritative resource on the topic*. Chapter
8-9 show how to use the MATLAB toolkit and the observations apply
also to this Python port. Links `on
amazon <http://www.amazon.com/Understanding-Delta-Sigma-Converters-Richard-Schreier/dp/0471465852>`__,
`on the Wiley-IEEE
press <http://eu.wiley.com/WileyCDA/WileyTitle/productCd-0471465852,miniSiteCd-IEEE2.html>`__.

*I am not affiliated with neither the sellers nor the authors.*

Licensing and copyright notice
------------------------------

All original MATLAB code is Copyright (c) 2009, Richard Schreier. See
the LICENSE file for the licensing terms.

The Python code here provided is a derivative work from the above
toolkit - a faithful port - and subject to the same license terms.

Credit goes to Richard Schreier for writing the MATLAB Delta Sigma
Toolbox, devising algorithms and implementations and doing an excellent
work at it.

This package contains some source code from ``pydsm``, also based on the
same MATLAB toolbox. The ``pydsm`` package is copyright (c) 2012, Sergio
Callegari.

When not otherwise specified, the Python code is Copyright 2013,
Giuseppe Venturini and the python-deltasigma contributors.

MATLAB is a registered trademark of The MathWorks, Inc.

.. |githalytics.com alpha| image:: https://cruel-carlota.pagodabox.com/36f25accf60f391456efe66910bf84f8
:target: http://githalytics.com/ggventurini/python-deltasigma
.. |Build Status| image:: https://travis-ci.org/ggventurini/python-deltasigma.png?branch=master
:target: https://travis-ci.org/ggventurini/python-deltasigma
.. |Coverage Status| image:: https://coveralls.io/repos/ggventurini/python-deltasigma/badge.png?branch=master
:target: https://coveralls.io/r/ggventurini/python-deltasigma?branch=master
.. |PyPi version| image:: http://img.shields.io/badge/version-0.1-brightgreen.png
:target: https://pypi.python.org/pypi/deltasigma/
.. |PyPi downloads| image:: https://pypip.in/download/deltasigma/badge.png
:target: https://pypi.python.org/pypi/deltasigma/
.. |BSD 2 clause license| image:: http://img.shields.io/badge/license-BSD-brightgreen.png
:target: https://raw.githubusercontent.com/ggventurini/python-deltasigma/master/LICENSE
.. |DOI BADGE| image:: https://zenodo.org/badge/doi/10.5281/zenodo.11535.png
:target: http://dx.doi.org/10.5281/zenodo.11535


CHANGES
~~~~~~~

Version 0.1 series
------------------

The 0.1 series features support for (real) baseband and passband modulator
topologies.

**0.1-9**: Add support for modulators with multiple outputs, allowing simulating
MASH cascade DSMs.
* Add support in ``partitionABCD()`` for specifying the number of outputs.
* Add support for multiple quantizers in ``calculateTF()``.
* BUGFIX: Fix simulation of DSMs with multiple quantizers.
* BUGFIX: ``cancelPZ()`` was not testing the first root.
* ``pretty_lti()`` now returns 0 if k is 0 after rounding.
* ``plotPZ()`` doesn't list coincident real roots as complex conjugate
roots with imag(root) = +/-0.
* DOC: add example of MASH cascade.

**0.1-8**: Accept both tuples and lists as NTFs for simulation.
* Previously passing a tuple for the NTF resulted in an error. Fixed.
* Doc fixes in ``mapCtoD()``.

**0.1-7**: Quantization fix in the Cython backends. More tests.
* A bug was found in the function responsible for quantizing the loop
filter output in ``simulateDSM()``, only the Cython implementations are
affected: **all users are strongly recommended to upgrade**.
* Add more test for ``simulateDSM()``.
* Check for the filter and data lengths in ``sinc_decimate()``.

**0.1-6**: ``sinc_decimate()`` fix, NTF matching method in ``realizeNTF_ct()``
* An off-by-1 indexing bug was found in ``sinc_decimate()``, **all users are
strongly recommended to update**.
* Add NTF matching method to ``realizeNTF_ct()``.

**0.1-5**: CRFFD support, separate tests, less verbosity and DOC fixes.
* Add CRFFD support (see ``realizeNTF``, ``mapABCD`` and ``stuffABCD``).
* Move all tests to a dedicated location (tests/).
* Ensure float64 is the data representation when simulating DSM.
* Add the ``simulations_backends`` variable and its doc.
* Cython: disable cblas extension on Win. Reduce verbosity.
* Multiple minor fixes to ensure scalars are never returned in place of
arrays.

Many thanks to Shayne Hodge for reporting issues with ``deltasigma`` on
Windows and several patches to the test suite.

**0.1-4**: Cython implementation of ``simulateDSM()``, PEP8 and DOC fixes.
* ``deltasigma/_simulateDSM_cblas.pyx`` and
``deltasigma/_simulateDSM_scipy_blas.pyx``, Cython implementation from
``pydsm`` of ``simulateDSM()``, available if Cython is, providing a 70x
speed-up of DSM simulations.
* More documentation improvements and PEP8-related fixes.

**0.1-3**: Bugfixes, PEP8, more test coverage
* ``deltasigma/_realizeNT_ct.py`` now supports ``FF`` topologies.
* ``deltasigma/_pulse.py`` now supports MIMO systems.
* ``pretty_lti()`` has been improved to provide the prettiest printing of LTIs
to date.
* Many documentation improvements and PEP8-related fixes.

**0.1-2**: Bugfixes, PEP8, DOC and most importantly a, g, b, c reshape.
* The a, g, b, c coefficients are now 1-dimensional.
* ``deltasigma/_stuffABCD.py``: scalar ``b`` bugfix.
* ``deltasigma/_logsmooth.py``: fix bin width.
* ``deltasigma/_utils.py``: add ``mround()``, round compatibly with MATLAB.
* ``deltasigma/_utils.py``: add root multiplicity support in ``pretty_lti()``.
* ``deltasigma/_utils.py``: bugfix in cplxpair for incoherent complex values.

**0.1-1**: Bugfix: most importantly fix ``realizeNTF_ct()``.
* ``deltasigma/_realizeNTF_ct.py``: Fixes for multi-timing, add unit tests for FB.
* ``deltasigma/_pulse.py``: Bugfix (reshape missing assignment), fix documentation formatting.
* ``deltasigma/_bilogplot.py``: Fix plot. Add unit test.
* ``deltasigma/_rmsGain.py``: Fix docstring.
* ``deltasigma/_lollipop.py``: Use matplotlib's stem function. Enforce PEP8.
Add support for color 'None'.

0.1: Bugfix: missing ``copy()`` in ``mapABCD()``.

0.1rc4 : Multiple bugfixes. Py3k fixes. Test coverage up to 85+%.

0.1rc3 : Fix file-not-found issue with ``setup.py``.

0.1rc2 : Fix travis and coveralls.io support.

0.1rc1 : Initial release