Merge branch 'develop'

Examples/TCAS2-2013/demo_lp_low_dc_noise.py

@@ -62,8 +62,8 @@ def w2(f):
 
 
 print("... computing optimal NTF...")
-ntf1 = ntf_fir_weighting(order, w1, quad_points=[B/fphi])
-ntf2 = ntf_fir_weighting(order, w2, quad_points=[B/fphi, B/fphi/10])
+ntf1 = ntf_fir_weighting(order, w1, quad_opts={'points': [B/fphi]})
+ntf2 = ntf_fir_weighting(order, w2, quad_opts={'points': [B/fphi, B/fphi/10]})
 
 # Prepare frequency axis for plotting
 fmin = 10**np.ceil(np.log10(B/OSR/100))

Examples/TCAS2-2013/demo_multiband_brickwall.py

@@ -68,9 +68,9 @@ def w1(f):
 
 print("... computing optimal NTF")
 ntf_opti = ntf_fir_weighting(order, w1, H_inf=H_inf,
-                             cvxpy_reltol=1E-11,
-                             cvxpy_abstol=1E-9,
-                             cvxpy_feastol=1E-9)
+                             cvxopt_opts={'reltol': 1E-11,
+                                          'abstol': 1E-9,
+                                          'feastol': 1E-9})
 ntf_opti_mag = lambda f: np.abs(evalTF(ntf_opti, np.exp(-2j*np.pi*f)))
 
 

Examples/TCAS2-2013/demo_psychoacoustic.py

@@ -53,9 +53,9 @@
 opti_ntf = ntf_fir_audio_weighting(order, osr, f_weighting,
                                    H_inf=H_inf,
                                    normalize=1E3,
-                                   cvxpy_reltol=1E-12,
-                                   cvxpy_abstol=1E-10,
-                                   cvxpy_feastol=1E-2)
+                                   cvxopt_opts={'reltol': 1E-12,
+                                                'abstol': 1E-10,
+                                                'feastol': 1E-2})
 
 dunn_ntf = ntf_dunn(3, osr, H_inf)
 

TODO

@@ -17,15 +17,11 @@
     representations
 - avoid __import__ statements and follow
     http://docs.scipy.org/doc/scipy/reference/api.html
-- [docstring] possibly move some documentation in the module level docstrings,
-    so that it is available in IDEs
 - [cython] user numpy.require to assure that arrays have the right properties
 - [optimization] move to the newer cvxpy
 - [optimization] check picos too for the optimization backend
 - [python] make python3 compatible
 - [examples] provide notebook version of the examples
-- [setuptools] assure that setuptools build the package before calling
-    build_sphinx
 - [setuptools] make docdist pass options to build_sphinx
 - [documentation] Maybe use the versionadded/versionchanged/deprecated sphinx
     features to document api changes

doc/README

@@ -2,3 +2,8 @@ Regeneration of the documentation requires
 
 sphinx
 numpydoc (Extension to sphinx to manage doc in numpy standard)
+
+Documentation should be built exclusively from the top dir
+of the project by issuing the command
+
+    python setup.py build_sphinx

doc/source/README

@@ -0,0 +1,3 @@
+As of version 1.2.3, sphinx autosummary has issues
+when applied to modules. As such, use it for
+functions only

doc/source/_static/style_variations.css

@@ -0,0 +1,16 @@
+.descclassname {
+    font-size: 1.2em
+}
+
+.descname {
+    font-size: 1.2em
+}
+
+.function {
+    margin-top : 2em
+    margin-bottom : 4em
+}
+
+.field-name {
+    padding-right : 1em
+}

doc/source/_templates/layout.html

@@ -0,0 +1,5 @@
+{# layout.html #}
+{# Import the theme's layout. #}
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/style_variations.css'] %}

doc/source/changelog.rst

@@ -1,6 +1,21 @@
 Changelog
 ---------
 
+0.12.0.0
+   - Switch to new version numbering scheme also in view of
+     PEP 440
+   - Install as zipped package
+   - Modify management of optional parameters in some functions.
+     Note that this implies a minor API breakage.
+   - Implement new hybrid NTF design method
+   - Slightly improve accuracy of weighted NTF design functions
+   - Improve quantization_noise_gain function
+   - Improve html documentation
+   - Let multiple modelers be selected in functions using convex
+     optimization (cvxpy, cvxpy_old and picos are supported)
+   - Implement some more functions in delsig module (axisLabels, rms)
+   - Many small fixes
+
 0.11.0
    - Switch to setuptools for building
    - Improve testing framework

doc/source/conf.py

@@ -11,24 +11,16 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
-from distutils.util import get_platform
-
-# Find build dir
-pv=sys.version_info
-distutil_bd='../../build/lib.'+get_platform()+'-'+\
-  str(pv.major)+'.'+str(pv.minor)
-distutil_bd=os.path.abspath(distutil_bd)
-
-# extend sys.path
-sys.path.insert(0, distutil_bd)
+import sys
+import os
 
+# PYDSM specific
 from pydsm._version import __version__
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('.'))
 
 # -- General configuration -----------------------------------------------------
 
@@ -37,8 +29,8 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.pngmath', 'numpydoc',
-              'sphinx.ext.autosummary']
+extensions = ['latex_hacks', 'sphinx.ext.autodoc', 'sphinx.ext.pngmath',
+              'numpydoc', 'sphinx.ext.autosummary']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -145,6 +137,7 @@
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
+html_sidebars = {'**': ['localtoc.html', 'sourcelink.html', 'searchbox.html']}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -164,6 +157,7 @@
 
 # If true, links to the reST sources are added to the pages.
 #html_show_sourcelink = True
+html_show_sourcelink = False
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
 #html_show_sphinx = True
@@ -188,12 +182,14 @@
 latex_elements = {
 # The paper size ('letterpaper' or 'a4paper').
 #'papersize': 'letterpaper',
+'papersize': 'a4paper',
 
 # The font size ('10pt', '11pt' or '12pt').
 #'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
 #'preamble': '',
+'preamble': r'\usepackage[artemisia]{textgreek}' '\n' '\hypersetup{unicode}'
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
@@ -259,3 +255,28 @@
 
 # -- Autosummary ---------------------------------------
 autosummary_generate = True
+
+
+# Ignore header of main package
+def better_cut_lines(pre, post=0, what=None, name=None):
+    def process(app, what_, name_, obj, options, lines):
+        if what and what_ not in what:
+            return
+        if name and name_ != name:
+            return
+        del lines[:pre]
+        if post:
+            # remove one trailing blank line.
+            if lines and not lines[-1]:
+                lines.pop(-1)
+            del lines[-post:]
+        # make sure there is a blank line at the end
+        if lines and lines[-1]:
+            lines.append('')
+    return process
+
+
+def setup(app):
+    from sphinx.ext.autodoc import cut_lines
+    app.connect('autodoc-process-docstring',
+                better_cut_lines(3, what=['module'], name='pydsm'))

doc/source/getting-started.rst

@@ -85,6 +85,10 @@ experience in Matlab. Conveniently, it offers online help for
 coding. The functions in PyDSM are internally documented to work with
 this online help system.
 
+Recent version of PyDSM may also benefit from alternative modeling
+languages for convex optimization. The interested user may want to
+install also the CVXPY_ and/or the PICOS_ Python packages.
+
 .. toctree::
    :maxdepth: 2
 
@@ -102,3 +106,5 @@ this online help system.
 .. _Matplotlib: http://matplotlib.org/
 .. _CVXOPT: http://abel.ee.ucla.edu/cvxopt/
 .. _Spyder: http://code.google.com/p/spyderlib/
+.. _CVXPY: http://www.cvxpy.org
+.. _PICOS: http://picos.zib.de/

doc/source/index.rst

@@ -12,12 +12,14 @@ Contents:
    replicate-results
    license
    included_code
+   more-references
    changelog
 
+.. only:: html
 
-Indices and tables
-==================
+   Indices and tables
+   ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+   * :ref:`genindex`
+   * :ref:`modindex`
+   * :ref:`search`

doc/source/intro.rst

@@ -17,32 +17,16 @@ Highlights of the current version consist in:
   <http://www.mathworks.com/matlabcentral/fileexchange/19-delta-sigma-toolbox>`__
   for Matlab by R. Schreier
 * The method for the design of psychoacoustically optimal modulators
-  for audio signals proposed by Dunn and Sandler in 1997.
-* The NTF design algorithm presented in:
-
-  * Sergio Callegari, Federico Bizzarri *“Output Filter Aware
-    Optimization of the Noise Shaping Properties of ΔΣ Modulators via
-    Semi-Definite Programming”*, IEEE Transactions on Circuits and
-    systems - Part I: Regular Papers, Vol. 60, N. 9,
-    pp. 2352-2365. Sept. 2013. DOI: `10.1109/TCSI.2013.2239091
-    <http://dx.doi.org/10.1109/TCSI.2013.2239091>`_. Pre-print
-    available on `ArXiv <http://arxiv.org/abs/1302.3020>`__.
-
-  * Sergio Callegari, Federico Bizzarri *“Noise Weighting in the
-    Design of ΔΣ Modulators (with a Psychoacoustic Coder as an
-    Example),”* IEEE Transactions on Circuits and Systems - Part II:
-    Express Briefs, Vol. 60, N. 11, pp. 756-760. Nov. 2013. DOI:
-    `10.1109/TCSII.2013.2281892
-    <http://dx.doi.org/10.1109/TCSII.2013.2281892>`_. Pre-print
-    available on `ArXiv <http://arxiv.org/abs/1309.6151>`__.
-
-  The latter includes an optimal strategy for the design of
+  for audio signals proposed by Dunn and Sandler in 1997 in [Dun97]_.
+* The NTF design algorithm presented in [Cal13a]_ and [Cal13b]_.  The
+  latter includes an optimal strategy for the design of
   psychoacoustically optimal modulators for audio signals,
   configurable to deal with different noise weightings
-  (e.g. A-Weighting, F-Weigting, user supplied weightings, etc.)
-
-If you find this code useful, *please consider citing the above papers
-in your work.*
+  (e.g. A-Weighting, F-Weigting, user supplied weightings, etc.)  If
+  you find this code useful, *please consider citing the two papers
+  in your work.*
+* The NTF design algorithm proposed by  [Nag12]_.
+* The NTF design algorithm presented [Cal15]_.
 
 PyDSM is free software and is licensed as detailed in the
 :ref:`license` Section of this manual.