Repository: scipy/scipy
File: scipy/linalg/_basic.py (Python)

Code before:
           [  1.  ,  49.  ],
           [  1.  ,  72.25]])

    We want to find the least-squares solution to ``M.dot(p) = y``,
    where ``p`` is a vector with length 2 that holds the parameters
    ``a`` and ``b``.

    >>> p, res, rnk, s = lstsq(M, y)
    >>> p
    array([ 0.20925829,  0.12013861])

    Plot the data and the fitted curve.

    >>> plt.plot(x, y, 'o', label='data')
    >>> xx = np.linspace(0, 9, 101)
    >>> yy = p[0] + p[1]*xx**2
    >>> plt.plot(xx, yy, label='least squares fit, $y = a + bx^2$')
    >>> plt.xlabel('x')
    >>> plt.ylabel('y')
    >>> plt.legend(framealpha=1, shadow=True)
    >>> plt.grid(alpha=0.25)
    >>> plt.show()

    As an illustration of the "batching" feature (see :ref:`linalg_batch` for details),
    suppose that we want to compare least-squares fits of the given data with two
    models: a quadratic model above, and an additional linear term,
    ``y = a + b*x**2 + c*x``.
    To this end, we construct the design matrix for ``y = a + b*x**2 + c*x``, and
    extend ``M`` to have three columns:

    >>> M1 = np.hstack((M, np.zeros((7, 1))))
    >>> M2 = x[:, np.newaxis] ** [0, 2, 1]
    >>> MM = np.stack((M1, M2))
    >>> x, res, rnk, s = lstsq(MM, y)
    >>> x
    array([[0.20925829, 0.12013861, 0.        ],
           [0.0578403 , 0.11262261, 0.07701453]])
    >>> rnk
    array([2, 3])

    Note that the rows of the ``x`` solution are equivalent to using ``M1`` and ``M2``,
    respectively.
    In a similar vein, to simulate an effect of random noise on ``y``, you can turn
    it into an array with multiple columns, where each column corresponds to a specific
    realization of the noise.
    """

    driver = lapack_driver
    if driver is None:
        driver = lstsq.default_lapack_driver
    if driver not in ('gelsd', 'gelsy', 'gelss'):

Review comment (suggestion):
```suggestion
    models: a quadratic model above, and one with an additional linear term,
```

Code after:
    overwrite_a : bool, optional
        This is passed to xGEBAL directly. Essentially, overwrites the result
        to the data. It might increase the space efficiency. See LAPACK manual
        for details. This is False by default.

    Returns
    -------
    B : (n, n) ndarray
        Balanced matrix
    T : (n, n) ndarray
        A possibly permuted diagonal matrix whose nonzero entries are
        integer powers of 2 to avoid numerical truncation errors.
    scale, perm : (n,) ndarray
        If ``separate`` keyword is set to True then instead of the array
        ``T`` above, the scaling and the permutation vectors are given
        separately as a tuple without allocating the full array ``T``.

    Notes
    -----
    The balanced matrix satisfies the following equality

    .. math::
        B = T^{-1} A T

    The scaling coefficients are approximated to the nearest power of 2
    to avoid round-off errors.

    This algorithm is particularly useful for eigenvalue and matrix
    decompositions and in many cases it is already called by various
    LAPACK routines.

    The algorithm is based on the well-known technique of [1]_ and has
    been modified to account for special cases. See [2]_ for details
    which have been implemented since LAPACK v3.5.0. Before this version
    there are corner cases where balancing can actually worsen the
    conditioning. See [3]_ for such examples.

    The code is a wrapper around LAPACK's xGEBAL routine family for matrix
    balancing.

    .. versionadded:: 0.19.0

    References
    ----------
    .. [1] B.N. Parlett and C. Reinsch, "Balancing a Matrix for
       Calculation of Eigenvalues and Eigenvectors", Numerische Mathematik,
       Vol.13(4), 1969, :doi:`10.1007/BF02165404`
    .. [2] R. James, J. Langou, B.R. Lowery, "On matrix balancing and
       eigenvector computation", 2014, :arxiv:`1401.5766`
    .. [3] D.S. Watkins. A case where balancing is harmful.
       Electron. Trans. Numer. Anal, Vol.23, 2006.