{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compared to the MATLAB/Octave implementation [1] of 1-, 2-, and 3-D Laplacian, this code allows the arbitrary N-D case and the matrix-free callable option, but is currently limited to pure Dirichlet, Neumann or Periodic boundary conditions only." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Laplacian matrix of a graph (" }, { "__type": "CrossRef", "__tag": 4002, "value": "scipy.sparse.csgraph.laplacian", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "scipy", "version": "*", "kind": "api", "path": "scipy.sparse.csgraph._laplacian:laplacian" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ") of a rectangular grid corresponds to the negative Laplacian with the Neumann conditions, i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "boundary_conditions = 'neumann'" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All eigenvalues and eigenvectors of the discrete Laplacian operator for an " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": "-dimensional regular grid of shape " }, { "__type": "ParamRef", "__tag": 4071, "name": "grid_shape" }, { "__type": "Text", "__tag": 4046, "value": " with the grid step size " }, { "__type": "InlineCode", "__tag": 4051, "value": "h=1" }, { "__type": "Text", "__tag": 4046, "value": " are analytically known [2]." } ] } ], "title": [], "level": 0, "target": null }, "Warns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Raises": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Yields": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Methods": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "toarray()", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a dense array from Laplacian data" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tosparse()", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a sparse array from Laplacian data" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "eigenvalues(m=None)", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a 1D array of " }, { "__type": "InlineRole", "__tag": 4003, "value": "m", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " largest (smallest in absolute value) eigenvalues of the Laplacian matrix in ascending order." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "eigenvectors(m=None):", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct the array with columns made of " }, { "__type": "InlineRole", "__tag": 4003, "value": "m", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " eigenvectors (" }, { "__type": "InlineCode", "__tag": 4051, "value": "float" }, { "__type": "Text", "__tag": 4046, "value": ") of the " }, { "__type": "InlineCode", "__tag": 4051, "value": "Nd" }, { "__type": "Text", "__tag": 4046, "value": " Laplacian corresponding to the " }, { "__type": "InlineRole", "__tag": 4003, "value": "m", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " ordered eigenvalues." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": ".. versionadded:: 1.12.0", "annotation": "", "desc": [] } ] } ], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The grid Laplacian in " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " dimensions and its eigenvalues/eigenvectors." } ] } ], "title": [], "level": 0, "target": null }, "Receives": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Warnings": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Attributes": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null }, "Parameters": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "grid_shape", "annotation": "tuple", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A tuple of integers of length " }, { "__type": "InlineCode", "__tag": 4051, "value": "N" }, { "__type": "Text", "__tag": 4046, "value": " (corresponding to the dimension of the Lapacian), where each entry gives the size of that dimension. The Laplacian matrix is square of the size " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.prod(grid_shape)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "boundary_conditions", "annotation": "{'neumann', 'dirichlet', 'periodic'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The type of the boundary conditions on the boundaries of the grid. Valid values are " }, { "__type": "InlineCode", "__tag": 4051, "value": "'dirichlet'" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "'neumann'``(default) or ``'periodic'" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dtype", "annotation": "dtype", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Numerical type of the array. Default is " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.int8" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct Laplacian on a uniform rectangular grid in " }, { "__type": "InlineRole", "__tag": 4003, "value": "N", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " dimensions and output its eigenvalues and eigenvectors. The Laplacian " }, { "__type": "InlineCode", "__tag": 4051, "value": "L" }, { "__type": "Text", "__tag": 4046, "value": " is square, negative definite, real symmetric array with signed integer entries and zeros otherwise." } ] } ], "title": [], "level": 0, "target": null }, "Other Parameters": { "__type": "Section", "__tag": 4015, "children": [], "title": [], "level": 0, "target": null } }, "_ordered_sections": [ "Summary", "Extended Summary", "Parameters", "Attributes", "Methods", "Returns", "Yields", "Receives", "Other Parameters", "Raises", "Warns", "Warnings", "Notes" ], "item_file": "/scipy/sparse/linalg/_special_sparse_arrays.py", "item_line": 10, "item_type": "class", "aliases": [ "scipy.sparse.linalg.LaplacianNd" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.sparse.linalg import LaplacianNd\nfrom scipy.sparse import diags_array, csgraph\nfrom scipy.linalg import eigvalsh\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe one-dimensional Laplacian demonstrated below for pure Neumann boundary\nconditions on a regular grid with ``n=6`` grid points is exactly the\nnegative graph Laplacian for the undirected linear graph with ``n``\nvertices using the sparse adjacency matrix ``G`` represented by the\nfamous tri-diagonal matrix:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "n = 6\nG = diags_array(np.ones(n - 1), offsets=1, format='csr')\nLf = csgraph.laplacian(G, symmetrized=True, form='function')\ngrid_shape = (n, )\nlap = LaplacianNd(grid_shape, boundary_conditions='neumann')\nnp.array_equal(lap.matmat(np.eye(n)), -Lf(np.eye(n)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSince all matrix entries of the Laplacian are integers, ``'int8'`` is\nthe default dtype for storing matrix representations.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "lap.tosparse()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "lap.toarray()\nnp.array_equal(lap.matmat(np.eye(n)), lap.toarray())\nnp.array_equal(lap.tosparse().toarray(), lap.toarray())\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAny number of extreme eigenvalues and/or eigenvectors can be computed.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "lap = LaplacianNd(grid_shape, boundary_conditions='periodic')\nlap.eigenvalues()\nlap.eigenvalues()[-2:]\nlap.eigenvalues(2)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "lap.eigenvectors(1)\nlap.eigenvectors(2)\nlap.eigenvectors()\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe two-dimensional Laplacian is illustrated on a regular grid with\n``grid_shape = (2, 3)`` points in each dimension.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "grid_shape = (2, 3)\nn = np.prod(grid_shape)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNumeration of grid points is as follows:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.arange(n).reshape(grid_shape + (-1,))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nEach of the boundary conditions ``'dirichlet'``, ``'periodic'``, and\n``'neumann'`` is illustrated separately; with ``'dirichlet'``\n\n" }, { "__type": "Code", "__tag": 4050, "value": "lap = LaplacianNd(grid_shape, boundary_conditions='dirichlet')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "lap.tosparse()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "lap.toarray()\nnp.array_equal(lap.matmat(np.eye(n)), lap.toarray())\nnp.array_equal(lap.tosparse().toarray(), lap.toarray())\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "lap.eigenvalues()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "eigvals = eigvalsh(lap.toarray().astype(np.float64))\nnp.allclose(lap.eigenvalues(), eigvals)\nnp.allclose(lap.toarray() @ lap.eigenvectors(),\n lap.eigenvectors() @ np.diag(lap.eigenvalues()))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nwith ``'periodic'``\n\n" }, { "__type": "Code", "__tag": 4050, "value": "lap = LaplacianNd(grid_shape, boundary_conditions='periodic')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "lap.tosparse()\nlap.toarray()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "np.array_equal(lap.matmat(np.eye(n)), lap.toarray())\nnp.array_equal(lap.tosparse().toarray(), lap.toarray())\nlap.eigenvalues()\neigvals = eigvalsh(lap.toarray().astype(np.float64))\nnp.allclose(lap.eigenvalues(), eigvals)\nnp.allclose(lap.toarray() @ lap.eigenvectors(),\n lap.eigenvectors() @ np.diag(lap.eigenvalues()))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nand with ``'neumann'``\n\n" }, { "__type": "Code", "__tag": 4050, "value": "lap = LaplacianNd(grid_shape, boundary_conditions='neumann')\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "lap.tosparse()\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "lap.toarray()\nnp.array_equal(lap.matmat(np.eye(n)), lap.toarray())\nnp.array_equal(lap.tosparse().toarray(), lap.toarray())\nlap.eigenvalues()\neigvals = eigvalsh(lap.toarray().astype(np.float64))\nnp.allclose(lap.eigenvalues(), eigvals)\nnp.allclose(lap.toarray() @ lap.eigenvectors(),\n lap.eigenvectors() @ np.diag(lap.eigenvalues()))\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "grid_shape", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "boundary_conditions", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "neumann" }, { "__type": "SigParam", "__tag": 4030, "name": "dtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "LaplacianNd" }, "references": [ ".. [1] https://github.com/lobpcg/blopex/blob/master/blopex_tools/matlab/laplacian/laplacian.m", ".. [2] \"Eigenvalues and eigenvectors of the second derivative\", Wikipedia", " https://en.wikipedia.org/wiki/Eigenvalues_and_eigenvectors_of_the_second_derivative" ], "qa": "scipy.sparse.linalg._special_sparse_arrays:LaplacianNd", "arbitrary": [], "local_refs": [ ".. versionadded:: 1.12.0", "boundary_conditions", "dtype", "eigenvalues(m=None)", "eigenvectors(m=None):", "grid_shape", "toarray()", "tosparse()" ] }