{
    "nbformat": 4,
    "nbformat_minor": 5,
    "metadata": {
        "kernelspec": {
            "display_name": "Python",
            "language": "python",
            "name": "python"
        },
        "language_info": {
            "name": "python"
        }
    },
    "cells": [
        {
            "id": "9fab364e",
            "cell_type": "markdown",
            "source": "<div class='alert alert-warning'>\n\nSciPy's interactive examples with Jupyterlite are experimental and may not always work as expected. Execution of cells containing imports may result in large downloads (up to 60MB of content for the first import from SciPy). Load times when importing from SciPy may take roughly 10-20 seconds. If you notice any problems, feel free to open an [issue](https://github.com/scipy/scipy/issues/new/choose).\n\n</div>",
            "metadata": {}
        },
        {
            "id": "44a45909",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "import numpy as np\nfrom scipy.linalg import solve_circulant, solve, circulant, lstsq",
            "outputs": []
        },
        {
            "id": "94cd6da4",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "c = np.array([2, 2, 4])\nb = np.array([1, 2, 3])\nsolve_circulant(c, b)",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([ 0.75, -0.25,  0.25])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "8b5a1e31",
            "cell_type": "markdown",
            "source": "Compare that result to solving the system with `scipy.linalg.solve`:\n",
            "metadata": {}
        },
        {
            "id": "5eb5b4ce",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "solve(circulant(c), b)",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([ 0.75, -0.25,  0.25])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "6e9bcd44",
            "cell_type": "markdown",
            "source": "A singular example:\n",
            "metadata": {}
        },
        {
            "id": "f45edb50",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "c = np.array([1, 1, 0, 0])\nb = np.array([1, 2, 3, 4])",
            "outputs": []
        },
        {
            "id": "0d924388",
            "cell_type": "markdown",
            "source": "Calling ``solve_circulant(c, b)`` will raise a `LinAlgError`.  For the\nleast square solution, use the option ``singular='lstsq'``:\n",
            "metadata": {}
        },
        {
            "id": "d059256f",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "solve_circulant(c, b, singular='lstsq')",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([ 0.25,  1.25,  2.25,  1.25])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "bc83b887",
            "cell_type": "markdown",
            "source": "Compare to `scipy.linalg.lstsq`:\n",
            "metadata": {}
        },
        {
            "id": "a59c2281",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "x, resid, rnk, s = lstsq(circulant(c), b)\nx",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([ 0.25,  1.25,  2.25,  1.25])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "6eb58679",
            "cell_type": "markdown",
            "source": "A broadcasting example:\n\nSuppose we have the vectors of two circulant matrices stored in an array\nwith shape (2, 5), and three `b` vectors stored in an array with shape\n(3, 5).  For example,\n",
            "metadata": {}
        },
        {
            "id": "243813de",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "c = np.array([[1.5, 2, 3, 0, 0], [1, 1, 4, 3, 2]])\nb = np.arange(15).reshape(-1, 5)",
            "outputs": []
        },
        {
            "id": "d0b65758",
            "cell_type": "markdown",
            "source": "We want to solve all combinations of circulant matrices and `b` vectors,\nwith the result stored in an array with shape (2, 3, 5). When we\ndisregard the axes of `c` and `b` that hold the vectors of coefficients,\nthe shapes of the collections are (2,) and (3,), respectively, which are\nnot compatible for broadcasting. To have a broadcast result with shape\n(2, 3), we add a trivial dimension to `c`: ``c[:, np.newaxis, :]`` has\nshape (2, 1, 5). The last dimension holds the coefficients of the\ncirculant matrices, so when we call `solve_circulant`, we can use the\ndefault ``caxis=-1``. The coefficients of the `b` vectors are in the last\ndimension of the array `b`, so we use ``baxis=-1``. If we use the\ndefault `outaxis`, the result will have shape (5, 2, 3), so we'll use\n``outaxis=-1`` to put the solution vectors in the last dimension.\n",
            "metadata": {}
        },
        {
            "id": "4857043f",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "x = solve_circulant(c[:, np.newaxis, :], b, baxis=-1, outaxis=-1)\nx.shape",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "(2, 3, 5)"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "ac3c1995",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "np.set_printoptions(precision=3)  # For compact output of numbers.\nx",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([[[-0.118,  0.22 ,  1.277, -0.142,  0.302],\n        [ 0.651,  0.989,  2.046,  0.627,  1.072],\n        [ 1.42 ,  1.758,  2.816,  1.396,  1.841]],\n       [[ 0.401,  0.304,  0.694, -0.867,  0.377],\n        [ 0.856,  0.758,  1.149, -0.412,  0.831],\n        [ 1.31 ,  1.213,  1.603,  0.042,  1.286]]])"
                    },
                    "execution_count": null
                }
            ]
        },
        {
            "id": "93cc16e5",
            "cell_type": "markdown",
            "source": "Check by solving one pair of `c` and `b` vectors (cf. ``x[1, 1, :]``):\n",
            "metadata": {}
        },
        {
            "id": "0ab90487",
            "cell_type": "code",
            "metadata": {},
            "execution_count": null,
            "source": "solve_circulant(c[1], b[1, :])",
            "outputs": [
                {
                    "output_type": "execute_result",
                    "metadata": {},
                    "data": {
                        "text/plain": "array([ 0.856,  0.758,  1.149, -0.412,  0.831])"
                    },
                    "execution_count": null
                }
            ]
        }
    ]
}