In order to improve the QZ decomposition accuracy, the pencil goes
through a balancing step where the sum of absolute values of
:math:`H` and :math:`J` rows/cols (after removing the diagonal entries)
is balanced following the recipe given in [3]_. If the data has small
numerical noise, balancing may amplify their effects and some clean up
is required.

.. versionadded:: 0.11.0

References
----------
.. [1]  P. van Dooren , "A Generalized Eigenvalue Approach For Solving
   Riccati Equations.", SIAM Journal on Scientific and Statistical
   Computing, Vol.2(2), :doi:`10.1137/0902010`

.. [2] A.J. Laub, "A Schur Method for Solving Algebraic Riccati
   Equations.", Massachusetts Institute of Technology. Laboratory for
   Information and Decision Systems. LIDS-R ; 859. Available online :
   http://hdl.handle.net/1721.1/1301

.. [3] P. Benner, "Symplectic Balancing of Hamiltonian Matrices", 2001,
   SIAM J. Sci. Comput., 2001, Vol.22(5), :doi:`10.1137/S1064827500367993`

Examples
--------
Given `a`, `b`, `q`, and `r` solve for `x`:

>>> import numpy as np
>>> from scipy import linalg as la
>>> a = np.array([[0, 1], [0, -1]])
>>> b = np.array([[1, 0], [2, 1]])
>>> q = np.array([[-4, -4], [-4, 7]])
>>> r = np.array([[9, 3], [3, 1]])
>>> x = la.solve_discrete_are(a, b, q, r)
>>> x
array([[-4., -4.],
       [-4.,  7.]])
>>> R = la.solve(r + b.T.dot(x).dot(b), b.T.dot(x).dot(a))
>>> np.allclose(a.T.dot(x).dot(a) - x - a.T.dot(x).dot(b).dot(R), -q)
True

Ú