Merge branch 'master' into rebase-pr431

murrayrm · web-flow · commit b9dc8dfd0e61 · 2020-12-30T21:51:55.000-08:00
diff --git a/control/statesp.py b/control/statesp.py
@@ -73,7 +73,9 @@
 _statesp_defaults = {
     'statesp.use_numpy_matrix': False,  # False is default in 0.9.0 and above
     'statesp.remove_useless_states': True,
-}
+    'statesp.latex_num_format': '.3g',
+    'statesp.latex_repr_type': 'partitioned',
+    }
 
 
 def _ssmatrix(data, axis=1):
@@ -127,6 +129,33 @@ def _ssmatrix(data, axis=1):
     return arr.reshape(shape)
 
 
+def _f2s(f):
+    """Format floating point number f for StateSpace._repr_latex_.
+
+    Numbers are converted to strings with statesp.latex_num_format.
+
+    Inserts column separators, etc., as needed.
+    """
+    fmt = "{:" + config.defaults['statesp.latex_num_format'] + "}"
+    sraw = fmt.format(f)
+    # significand-exponent
+    se = sraw.lower().split('e')
+    # whole-fraction
+    wf = se[0].split('.')
+    s = wf[0]
+    if wf[1:]:
+        s += r'.&\hspace{{-1em}}{frac}'.format(frac=wf[1])
+    else:
+        s += r'\phantom{.}&\hspace{-1em}'
+
+    if se[1:]:
+        s += r'&\hspace{{-1em}}\cdot10^{{{:d}}}'.format(int(se[1]))
+    else:
+        s += r'&\hspace{-1em}\phantom{\cdot}'
+
+    return s
+
+
 class StateSpace(LTI):
     """StateSpace(A, B, C, D[, dt])
 
@@ -164,6 +193,24 @@ class StateSpace(LTI):
     timebase; the result will have the timebase of the latter system.
     The default value of dt can be changed by changing the value of
     ``control.config.defaults['control.default_dt']``.
+
+    StateSpace instances have support for IPython LaTeX output,
+    intended for pretty-printing in Jupyter notebooks.  The LaTeX
+    output can be configured using
+    `control.config.defaults['statesp.latex_num_format']` and
+    `control.config.defaults['statesp.latex_repr_type']`.  The LaTeX output is
+    tailored for MathJax, as used in Jupyter, and may look odd when
+    typeset by non-MathJax LaTeX systems.
+
+    `control.config.defaults['statesp.latex_num_format']` is a format string
+    fragment, specifically the part of the format string after `'{:'`
+    used to convert floating-point numbers to strings.  By default it
+    is `'.3g'`.
+
+    `control.config.defaults['statesp.latex_repr_type']` must either be
+    `'partitioned'` or `'separate'`.  If `'partitioned'`, the A, B, C, D
+    matrices are shown as a single, partitioned matrix; if
+    `'separate'`, the matrices are shown separately.
     """
 
     # Allow ndarray * StateSpace to give StateSpace._rmul_() priority
@@ -329,6 +376,136 @@ def __repr__(self):
             C=asarray(self.C).__repr__(), D=asarray(self.D).__repr__(),
             dt=(isdtime(self, strict=True) and ", {}".format(self.dt)) or '')
 
+    def _latex_partitioned_stateless(self):
+        """`Partitioned` matrix LaTeX representation for stateless systems
+
+        Model is presented as a matrix, D.  No partition lines are shown.
+
+        Returns
+        -------
+        s : string with LaTeX representation of model
+        """
+        lines = [
+            r'\[',
+            r'\left(',
+            (r'\begin{array}'
+             + r'{' + 'rll' * self.inputs + '}')
+            ]
+
+        for Di in asarray(self.D):
+            lines.append('&'.join(_f2s(Dij) for Dij in Di)
+                         + '\\\\')
+
+        lines.extend([
+            r'\end{array}'
+            r'\right)',
+            r'\]'])
+
+        return '\n'.join(lines)
+
+    def _latex_partitioned(self):
+        """Partitioned matrix LaTeX representation of state-space model
+
+        Model is presented as a matrix partitioned into A, B, C, and D
+        parts.
+
+        Returns
+        -------
+        s : string with LaTeX representation of model
+        """
+        if self.states == 0:
+            return self._latex_partitioned_stateless()
+
+        lines = [
+            r'\[',
+            r'\left(',
+            (r'\begin{array}'
+             + r'{' + 'rll' * self.states + '|' + 'rll' * self.inputs + '}')
+            ]
+
+        for Ai, Bi in zip(asarray(self.A), asarray(self.B)):
+            lines.append('&'.join([_f2s(Aij) for Aij in Ai]
+                                  + [_f2s(Bij) for Bij in Bi])
+                         + '\\\\')
+        lines.append(r'\hline')
+        for Ci, Di in zip(asarray(self.C), asarray(self.D)):
+            lines.append('&'.join([_f2s(Cij) for Cij in Ci]
+                                  + [_f2s(Dij) for Dij in Di])
+                         + '\\\\')
+
+        lines.extend([
+            r'\end{array}'
+            r'\right)',
+            r'\]'])
+
+        return '\n'.join(lines)
+
+    def _latex_separate(self):
+        """Separate matrices LaTeX representation of state-space model
+
+        Model is presented as separate, named, A, B, C, and D matrices.
+
+        Returns
+        -------
+        s : string with LaTeX representation of model
+        """
+        lines = [
+            r'\[',
+            r'\begin{array}{ll}',
+            ]
+
+        def fmt_matrix(matrix, name):
+            matlines = [name
+                        + r' = \left(\begin{array}{'
+                        + 'rll' * matrix.shape[1]
+                        + '}']
+            for row in asarray(matrix):
+                matlines.append('&'.join(_f2s(entry) for entry in row)
+                                + '\\\\')
+            matlines.extend([
+                r'\end{array}'
+                r'\right)'])
+            return matlines
+
+        if self.states > 0:
+            lines.extend(fmt_matrix(self.A, 'A'))
+            lines.append('&')
+            lines.extend(fmt_matrix(self.B, 'B'))
+            lines.append('\\\\')
+
+            lines.extend(fmt_matrix(self.C, 'C'))
+            lines.append('&')
+        lines.extend(fmt_matrix(self.D, 'D'))
+
+        lines.extend([
+            r'\end{array}',
+            r'\]'])
+
+        return '\n'.join(lines)
+
+    def _repr_latex_(self):
+        """LaTeX representation of state-space model
+
+        Output is controlled by config options statesp.latex_repr_type
+        and statesp.latex_num_format.
+
+        The output is primarily intended for Jupyter notebooks, which
+        use MathJax to render the LaTeX, and the results may look odd
+        when processed by a 'conventional' LaTeX system.
+
+        Returns
+        -------
+        s : string with LaTeX representation of model
+
+        """
+        if config.defaults['statesp.latex_repr_type'] == 'partitioned':
+            return self._latex_partitioned()
+        elif config.defaults['statesp.latex_repr_type'] == 'separate':
+            return self._latex_separate()
+        else:
+            cfg = config.defaults['statesp.latex_repr_type']
+            raise ValueError("Unknown statesp.latex_repr_type '{cfg}'".format(cfg=cfg))
+
     # Negation of a system
     def __neg__(self):
         """Negate a state space system."""
diff --git a/control/tests/config_test.py b/control/tests/config_test.py
@@ -37,7 +37,7 @@ def test_get_param(self):
         assert ct.config._get_param('config', 'test1', None) == 1
         assert ct.config._get_param('config', 'test1', None, 1) == 1
 
-        ct.config.defaults['config.test3'] is None
+        ct.config.defaults['config.test3'] = None
         assert ct.config._get_param('config', 'test3') is None
         assert ct.config._get_param('config', 'test3', 1) == 1
         assert ct.config._get_param('config', 'test3', None, 1) is None
diff --git a/control/tests/conftest.py b/control/tests/conftest.py
@@ -28,7 +28,22 @@
                                                "PendingDeprecationWarning")
 
 
-@pytest.fixture(scope="session", autouse=TEST_MATRIX_AND_ARRAY,
+@pytest.fixture(scope="session", autouse=True)
+def control_defaults():
+    """Make sure the testing session always starts with the defaults.
+
+    This should be the first fixture initialized,
+    so that all other fixtures see the general defaults (unless they set them
+    themselves) even before importing control/__init__. Enforce this by adding
+    it as an argument to all other session scoped fixtures.
+    """
+    control.reset_defaults()
+    the_defaults = control.config.defaults.copy()
+    yield
+    # assert that nothing changed it without reverting
+    assert control.config.defaults == the_defaults
+
+@pytest.fixture(scope="function", autouse=TEST_MATRIX_AND_ARRAY,
                 params=[pytest.param("arrayout", marks=matrixerrorfilter),
                         pytest.param("matrixout", marks=matrixfilter)])
 def matarrayout(request):
@@ -70,7 +85,7 @@ def check_deprecated_matrix():
         yield
 
 
-@pytest.fixture(scope="session",
+@pytest.fixture(scope="function",
                 params=[p for p, usebydefault in
                         [(pytest.param(np.array,
                                        id="arrayin"),
@@ -90,7 +105,7 @@ def editsdefaults():
     """Make sure any changes to the defaults only last during a test"""
     restore = control.config.defaults.copy()
     yield
-    control.config.defaults.update(restore)
+    control.config.defaults = restore.copy()
 
 
 @pytest.fixture(scope="function")
diff --git a/control/tests/freqresp_test.py b/control/tests/freqresp_test.py
@@ -120,39 +120,62 @@ def test_mimo():
     tf(sysMIMO)
 
 
-def test_bode_margin():
+@pytest.mark.parametrize(
+    "Hz, Wcp, Wcg",
+    [pytest.param(False, 6.0782869, 10., id="omega"),
+     pytest.param(True, 0.9673894, 1.591549, id="Hz")])
+@pytest.mark.parametrize(
+    "deg, p0, pm",
+    [pytest.param(False, -np.pi, -2.748266, id="rad"),
+     pytest.param(True, -180, -157.46405841, id="deg")])
+@pytest.mark.parametrize(
+    "dB, maginfty1, maginfty2, gminv",
+    [pytest.param(False, 1, 1e-8, 0.4, id="mag"),
+     pytest.param(True, 0, -1e+5, -7.9588, id="dB")])
+def test_bode_margin(dB, maginfty1, maginfty2, gminv,
+                     deg, p0, pm,
+                     Hz, Wcp, Wcg):
     """Test bode margins"""
     num = [1000]
     den = [1, 25, 100, 0]
     sys = ctrl.tf(num, den)
     plt.figure()
-    ctrl.bode_plot(sys, margins=True, dB=False, deg=True, Hz=False)
+    ctrl.bode_plot(sys, margins=True, dB=dB, deg=deg, Hz=Hz)
     fig = plt.gcf()
     allaxes = fig.get_axes()
 
-    mag_to_infinity = (np.array([6.07828691, 6.07828691]),
-                       np.array([1., 1e-8]))
-    assert_allclose(mag_to_infinity, allaxes[0].lines[2].get_data())
-
-    gm_to_infinty = (np.array([10., 10.]),
-                     np.array([4e-1, 1e-8]))
-    assert_allclose(gm_to_infinty, allaxes[0].lines[3].get_data())
-
-    one_to_gm = (np.array([10., 10.]),
-                 np.array([1., 0.4]))
-    assert_allclose(one_to_gm, allaxes[0].lines[4].get_data())
-
-    pm_to_infinity = (np.array([6.07828691, 6.07828691]),
-                      np.array([100000., -157.46405841]))
-    assert_allclose(pm_to_infinity, allaxes[1].lines[2].get_data())
-
-    pm_to_phase = (np.array([6.07828691, 6.07828691]),
-                   np.array([-157.46405841, -180.]))
-    assert_allclose(pm_to_phase, allaxes[1].lines[3].get_data())
-
-    phase_to_infinity = (np.array([10., 10.]),
-                         np.array([1e-8, -1.8e2]))
-    assert_allclose(phase_to_infinity, allaxes[1].lines[4].get_data())
+    mag_to_infinity = (np.array([Wcp, Wcp]),
+                       np.array([maginfty1, maginfty2]))
+    assert_allclose(mag_to_infinity,
+                    allaxes[0].lines[2].get_data(),
+                    rtol=1e-5)
+
+    gm_to_infinty = (np.array([Wcg, Wcg]),
+                     np.array([gminv, maginfty2]))
+    assert_allclose(gm_to_infinty,
+                    allaxes[0].lines[3].get_data(),
+                    rtol=1e-5)
+
+    one_to_gm = (np.array([Wcg, Wcg]),
+                 np.array([maginfty1, gminv]))
+    assert_allclose(one_to_gm, allaxes[0].lines[4].get_data(),
+                    rtol=1e-5)
+
+    pm_to_infinity = (np.array([Wcp, Wcp]),
+                      np.array([1e5, pm]))
+    assert_allclose(pm_to_infinity,
+                    allaxes[1].lines[2].get_data(),
+                    rtol=1e-5)
+
+    pm_to_phase = (np.array([Wcp, Wcp]),
+                   np.array([pm, p0]))
+    assert_allclose(pm_to_phase, allaxes[1].lines[3].get_data(),
+                    rtol=1e-5)
+
+    phase_to_infinity = (np.array([Wcg, Wcg]),
+                         np.array([1e-8, p0]))
+    assert_allclose(phase_to_infinity, allaxes[1].lines[4].get_data(),
+                    rtol=1e-5)
 
 
 @pytest.fixture
diff --git a/control/tests/statesp_test.py b/control/tests/statesp_test.py
