DOC: improvements

Author: ggventurini

deltasigma/__init__.py

@@ -703,18 +703,21 @@
     mapCtoD
     evalTFP
 
-Functions for quadrature systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Functions for quadrature Delta-Sigma modulators
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The following functions are available for quadrature modulators.
-Completion of these features is expected in v. 0.2.
 
 .. autosummary::
     :nosignatures:
 
     calculateQTF
     mapQtoR
     mapRtoQ
+    realizeQNTF
+    simulateQDSM
+    simulateQSNR
+    synthesizeQNTF
 
 Other selected functions
 ~~~~~~~~~~~~~~~~~~~~~~~~

deltasigma/_calculateQTF.py

@@ -40,8 +40,7 @@ def calculateQTF(ABCDr):
     ntf, stf, intf, istf : tuple of zpk tuples
         The quadrature noise and signal transfer functions.
 
-    :raises RuntimeError: if the supplied ABCD matrix results in denominator
-    mismatches.
+    :raises RuntimeError: if the supplied ABCD matrix results in denominator mismatches.
     """
     A, B, C, D = partitionABCD(ABCDr, 4)
 

deltasigma/_realizeQNTF.py

@@ -61,6 +61,11 @@ def realizeQNTF(ntf, form='FB', rot=False, bn=0.):
         Coefficient of the auxiliary DAC, to be specified for a
         'FF' form. Defaults to ``0.0``.
 
+    **Returns:**
+
+    ABCD : ndarray
+        ABCD realization of the requested type.
+
     """
     #Code common to all forms
     ntf_z, ntf_p, _ = _get_zpk(ntf)

deltasigma/_simulateDSM.py

@@ -113,7 +113,7 @@ def simulateDSM(u, arg2, nlev=2, x0=0.):
     xmax : nedarray
         The maximum value that each state reached during simulation.
     y : ndarray
-        The quantizer input.
+        The quantizer input (ie the modulator output).
 
     **Notes:**
 

deltasigma/_simulateQDSM.py

@@ -29,23 +29,55 @@
 from ._ds_quantize import ds_quantize
 from ._evalTF import evalTF
 from ._partitionABCD import partitionABCD
-from ._utils import carray, diagonal_indices, _is_zpk
+from ._utils import carray, diagonal_indices, _is_zpk, _is_A_B_C_D, _is_num_den
 
 def simulateQDSM(u, arg2, nlev=2, x0=None):
-    """v, xn, xmax, y = simulateQDSM(u, ABCD, nlev=2, x0=0)
-     or
-    v, xn, xmax, y = simulateQDSM(u, ntf, nlev=2, x0=0)
+    """Simulate a quadrature Delta-Sigma modulator
 
-    Compute the output of a quadrature delta-sigma modulator with input u,
-    a structure described by ABCD, an initial state x0 (default zero) and
+    This function computes the output of a quadrature delta-sigma modulator with input u,
+    a structure described by ABCD, an initial state x0 (default all zeros) and
     a quantizer whose number of levels is specified by nlev.
-    For multiple quantizers, make nlev a column vector;
+
+    For multiple quantizers, make nlev a 1D vector;
     for complex quantization to a diamond lattice, multiply nlev by 1j.
-     size(u) = [nu N], size(nlev) = [nq 1], size(ABCD) = [order+nq order+nq+nu]
+    size(u) = [nu N], size(nlev) = [nq 1], size(ABCD) = [order+nq order+nq+nu]
 
     Alternatively, the modulator may be described by an NTF.
-    The NTF is zpk object. (The STF is assumed to be 1.)
+    The NTF is zpk object. The STF is assumed to be 1.
+
+    **Parameters:**
+
+    u : ndarray
+        The input signal to the modulator.
+    arg2 : ndarray or a supported LTI representation
+        A description of the modulator to simulate.
+        An ndarray instance is interpreted as an ABCD description. Equivalently,
+        the ABCD matrix may be supplied in ``(A, B, C, D)`` tuple form. All
+        other supported modulator specifications result in a conversion to a zpk
+        representation.
+    nlev : int or sequence-like, optional
+        The number of levels in the quantizer. If set to a sequence, each of the
+        elements is assumed to be the number of levels associated with a
+        quantizer. Defaults to ``2``.
+    x0 : float or sequence-like, optional
+        The initial states of the modulator. If it is set to a float, all states
+        are assumed to have the same value, ``x0``. If it is set to a
+        sequence-like objct (list, tuple, 1D ndarray and similar), each entry is
+        assumed to be the value of one of the modulator states, in ascending
+        order. Defaults to ``0``.
+
+    **Returns:**
+
+    v : ndarray
+        The quantizer output.
+    xn : ndarray
+        The modulator states.
+    xmax : nedarray
+        The maximum value that each state reached during simulation.
+    y : ndarray
+        The quantizer input (ie the modulator output).
     """
+
     nu = u.shape[0]
     nlev = np.atleast_1d(nlev)
     nq = max(nlev.shape)

doc/index.rst

@@ -11,7 +11,7 @@
    :maxdepth: 3
 
 .. automodule:: deltasigma.__init__
-    :members: DocumentNTF, PlotExampleSpectrum, SIunits, axisLabels, bilogplot, bplogsmooth, bquantize, bunquantize, calculateSNR, calculateTF, calculateQTF, cancelPZ, changeFig, circ_smooth, circshift, clans, eps, db, dbm, dbp, dbv, delay, ds_f1f2, ds_freq, ds_hann, ds_optzeros, ds_quantize, ds_synNTFobj1, dsclansNTF, evalMixedTF, evalRPoly, evalTF, evalTFP, figureMagic, frespF1, impL1, infnorm, l1norm, logsmooth, lollipop, mapABCD, mapCtoD, mapQtoR, mapRtoQ, mod1, mod2, nabsH, padb, padl, padr, padt, partitionABCD, peakSNR, plotPZ, plotSpectrum, predictSNR, pulse, realizeNTF, realizeNTF_ct, rms, rmsGain, scaleABCD, simulateDSM, simulateSNR, sinc_decimate, stuffABCD, synthesizeChebyshevNTF, synthesizeNTF, undbm, undbp, undbv, cplxpair, mfloor, mround, pretty_lti, rat, gcd, lcm, zinc
+    :members: DocumentNTF, PlotExampleSpectrum, SIunits, axisLabels, bilogplot, bplogsmooth, bquantize, bunquantize, calculateSNR, calculateTF, calculateQTF, cancelPZ, changeFig, circ_smooth, circshift, clans, eps, db, dbm, dbp, dbv, delay, ds_f1f2, ds_freq, ds_hann, ds_optzeros, ds_quantize, ds_synNTFobj1, dsclansNTF, evalMixedTF, evalRPoly, evalTF, evalTFP, figureMagic, frespF1, impL1, infnorm, l1norm, logsmooth, lollipop, mapABCD, mapCtoD, mapQtoR, mapRtoQ, mod1, mod2, nabsH, padb, padl, padr, padt, partitionABCD, peakSNR, plotPZ, plotSpectrum, predictSNR, pulse, realizeNTF, realizeNTF_ct, realizeQNTF, rms, rmsGain, scaleABCD, simulateDSM, simulateQDSM, simulateQSNR, simulateSNR, sinc_decimate, stuffABCD, synthesizeChebyshevNTF, synthesizeNTF, synthesizeQNTF, undbm, undbp, undbv, cplxpair, mfloor, mround, pretty_lti, rat, gcd, lcm, zinc