{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Laplacian matrix of a graph is sometimes referred to as the \"Kirchhoff matrix\" or just the \"Laplacian\", and is useful in many parts of spectral graph theory. In particular, the eigen-decomposition of the Laplacian can give insight into many properties of the graph, e.g., is commonly used for spectral data embedding and clustering." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The constructed Laplacian doubles the memory use if " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy=True" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "form=\"array\"" }, { "__type": "Text", "__tag": 4046, "value": " which is the default. Choosing " }, { "__type": "InlineCode", "__tag": 4051, "value": "copy=False" }, { "__type": "Text", "__tag": 4046, "value": " has no effect unless " }, { "__type": "InlineCode", "__tag": 4051, "value": "form=\"array\"" }, { "__type": "Text", "__tag": 4046, "value": " or the matrix is sparse in the " }, { "__type": "InlineCode", "__tag": 4051, "value": "coo" }, { "__type": "Text", "__tag": 4046, "value": " format, or dense array, except for the integer input with " }, { "__type": "InlineCode", "__tag": 4051, "value": "normed=True" }, { "__type": "Text", "__tag": 4046, "value": " that forces the float output." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sparse input is reformatted into " }, { "__type": "InlineCode", "__tag": 4051, "value": "coo" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "InlineCode", "__tag": 4051, "value": "form=\"array\"" }, { "__type": "Text", "__tag": 4046, "value": ", which is the default." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If the input adjacency matrix is not symmetric, the Laplacian is also non-symmetric unless " }, { "__type": "InlineCode", "__tag": 4051, "value": "symmetrized=True" }, { "__type": "Text", "__tag": 4046, "value": " is used." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Diagonal entries of the input adjacency matrix are ignored and replaced with zeros for the purpose of normalization where " }, { "__type": "InlineCode", "__tag": 4051, "value": "normed=True" }, { "__type": "Text", "__tag": 4046, "value": ". The normalization uses the inverse square roots of row-sums of the input adjacency matrix, and thus may fail if the row-sums contain negative or complex with a non-zero imaginary part values." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The normalization is symmetric, making the normalized Laplacian also symmetric if the input csgraph was symmetric." } ] } ], "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": [], "title": [], "level": 0, "target": null }, "Returns": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Parameters", "__tag": 4026, "children": [ { "__type": "DocParam", "__tag": 4016, "name": "lap", "annotation": "ndarray, or sparse array or matrix, or `LinearOperator`", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The N x N Laplacian of csgraph. It will be a NumPy array (dense) if the input was dense, or a sparse array otherwise, or the format of a function or " }, { "__type": "CrossRef", "__tag": 4002, "value": "LinearOperator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._interface:LinearOperator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "ParamRef", "__tag": 4071, "name": "form" }, { "__type": "Text", "__tag": 4046, "value": " equals 'function' or 'lo', respectively." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "diag", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The length-N main diagonal of the Laplacian matrix. For the normalized Laplacian, this is the array of square roots of vertex degrees or 1 if the degree is zero." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return the Laplacian of a directed graph." } ] } ], "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": "csgraph", "annotation": "array_like or sparse array or matrix, 2 dimensions", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "compressed-sparse graph, with shape (N, N)." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "normed", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, then compute symmetrically normalized Laplacian. Default: False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "return_diag", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, then also return an array related to vertex degrees. Default: False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "use_out_degree", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, then use out-degree instead of in-degree. This distinction matters only if the graph is asymmetric. Default: False." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "copy: bool, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If False, then change " }, { "__type": "ParamRef", "__tag": 4071, "name": "csgraph" }, { "__type": "Text", "__tag": 4046, "value": " in place if possible, avoiding doubling the memory use. Default: True, for backward compatibility." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "form: 'array', or 'function', or 'lo'", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Determines the format of the output Laplacian:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'array' is a numpy array;" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'function' is a pointer to evaluating the Laplacian-vector or Laplacian-matrix product;" } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'lo' results in the format of the " }, { "__type": "CrossRef", "__tag": 4002, "value": "LinearOperator", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.sparse.linalg._interface:LinearOperator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Choosing 'function' or 'lo' always avoids doubling the memory use, ignoring " }, { "__type": "ParamRef", "__tag": 4071, "name": "copy" }, { "__type": "Text", "__tag": 4046, "value": " value. Default: 'array', for backward compatibility." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dtype: None or one of numeric numpy dtypes, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The dtype of the output. If " }, { "__type": "InlineCode", "__tag": 4051, "value": "dtype=None" }, { "__type": "Text", "__tag": 4046, "value": ", the dtype of the output matches the dtype of the input csgraph, except for the case " }, { "__type": "InlineCode", "__tag": 4051, "value": "normed=True" }, { "__type": "Text", "__tag": 4046, "value": " and integer-like csgraph, where the output dtype is 'float' allowing accurate normalization, but dramatically increasing the memory use. Default: None, for backward compatibility." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "symmetrized: bool, optional", "annotation": "", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, then the output Laplacian is symmetric/Hermitian. The symmetrization is done by " }, { "__type": "InlineCode", "__tag": 4051, "value": "csgraph + csgraph.T.conj" }, { "__type": "Text", "__tag": 4046, "value": " without dividing by 2 to preserve integer dtypes if possible prior to the construction of the Laplacian. The symmetrization will increase the memory footprint of sparse matrices unless the sparsity pattern is symmetric or " }, { "__type": "ParamRef", "__tag": 4071, "name": "form" }, { "__type": "Text", "__tag": 4046, "value": " is 'function' or 'lo'. Default: False, for backward compatibility." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [], "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/csgraph/_laplacian.py", "item_line": 13, "item_type": "function", "aliases": [ "scipy.sparse.csgraph.laplacian" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy.sparse import csgraph\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nOur first illustration is the symmetric graph\n\n" }, { "__type": "Code", "__tag": 4050, "value": "G = np.arange(4) * np.arange(4)[:, np.newaxis]\nG\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nand its symmetric Laplacian matrix\n\n" }, { "__type": "Code", "__tag": 4050, "value": "csgraph.laplacian(G)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe non-symmetric graph\n\n" }, { "__type": "Code", "__tag": 4050, "value": "G = np.arange(9).reshape(3, 3)\nG\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nhas different row- and column sums, resulting in two varieties\nof the Laplacian matrix, using an in-degree, which is the default\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L_in_degree = csgraph.laplacian(G)\nL_in_degree\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nor alternatively an out-degree\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L_out_degree = csgraph.laplacian(G, use_out_degree=True)\nL_out_degree\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nConstructing a symmetric Laplacian matrix, one can add the two as\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L_in_degree + L_out_degree.T\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nor use the ``symmetrized=True`` option\n\n" }, { "__type": "Code", "__tag": 4050, "value": "csgraph.laplacian(G, symmetrized=True)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nthat is equivalent to symmetrizing the original graph\n\n" }, { "__type": "Code", "__tag": 4050, "value": "csgraph.laplacian(G + G.T)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe goal of normalization is to make the non-zero diagonal entries\nof the Laplacian matrix to be all unit, also scaling off-diagonal\nentries correspondingly. The normalization can be done manually, e.g.,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "G = np.array([[0, 1, 1], [1, 0, 1], [1, 1, 0]])\nL, d = csgraph.laplacian(G, return_diag=True)\nL\nd\nscaling = np.sqrt(d)\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "scaling\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "(1/scaling)*L*(1/scaling)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nOr using ``normed=True`` option\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L, d = csgraph.laplacian(G, return_diag=True, normed=True)\nL\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nwhich now instead of the diagonal returns the scaling coefficients\n\n" }, { "__type": "Code", "__tag": 4050, "value": "d\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nZero scaling coefficients are substituted with 1s, where scaling\nhas thus no effect, e.g.,\n\n" }, { "__type": "Code", "__tag": 4050, "value": "G = np.array([[0, 0, 0], [0, 0, 1], [0, 1, 0]])\nG\nL, d = csgraph.laplacian(G, return_diag=True, normed=True)\nL\nd\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nOnly the symmetric normalization is implemented, resulting\nin a symmetric Laplacian matrix if and only if its graph is symmetric\nand has all non-negative degrees, like in the examples above.\n\nThe output Laplacian matrix is by default a dense array or a sparse\narray or matrix inferring its class, shape, format, and dtype from\nthe input graph matrix:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "G = np.array([[0, 1, 1], [1, 0, 1], [1, 1, 0]]).astype(np.float32)\nG\ncsgraph.laplacian(G)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nbut can alternatively be generated matrix-free as a LinearOperator:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L = csgraph.laplacian(G, form=\"lo\")\nL\nL(np.eye(3))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nor as a lambda-function:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "L = csgraph.laplacian(G, form=\"function\")\n", "execution_status": "success" }, { "__type": "Code", "__tag": 4050, "value": "L\n", "execution_status": "failure" }, { "__type": "Code", "__tag": 4050, "value": "L(np.eye(3))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe Laplacian matrix is used for\nspectral data clustering and embedding\nas well as for spectral graph partitioning.\nOur final example illustrates the latter\nfor a noisy directed linear graph.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "from scipy.sparse import diags_array, random_array\nfrom scipy.sparse.linalg import lobpcg\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCreate a directed linear graph with ``N=35`` vertices\nusing a sparse adjacency matrix ``G``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "N = 35\nG = diags_array(np.ones(N - 1), offsets=1, format=\"csr\")\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFix a random seed ``rng`` and add a random sparse noise to the graph ``G``:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng()\nG += 1e-2 * random_array((N, N), density=0.1, rng=rng)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSet initial approximations for eigenvectors:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "X = rng.random((N, 2))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe constant vector of ones is always a trivial eigenvector\nof the non-normalized Laplacian to be filtered out:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "Y = np.ones((N, 1))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAlternating (1) the sign of the graph weights allows determining\nlabels for spectral max- and min- cuts in a single loop.\nSince the graph is undirected, the option ``symmetrized=True``\nmust be used in the construction of the Laplacian.\nThe option ``normed=True`` cannot be used in (2) for the negative weights\nhere as the symmetric normalization evaluates square roots.\nThe option ``form=\"lo\"`` in (2) is matrix-free, i.e., guarantees\na fixed memory footprint and read-only access to the graph.\nCalling the eigenvalue solver ``lobpcg`` (3) computes the Fiedler vector\nthat determines the labels as the signs of its components in (5).\nSince the sign in an eigenvector is not deterministic and can flip,\nwe fix the sign of the first component to be always +1 in (4).\n\n" }, { "__type": "Code", "__tag": 4050, "value": "for cut in [\"max\", \"min\"]:\n G = -G # 1.\n L = csgraph.laplacian(G, symmetrized=True, form=\"lo\") # 2.\n _, eves = lobpcg(L, X, Y=Y, largest=False, tol=1e-2) # 3.\n eves *= np.sign(eves[0, 0]) # 4.\n print(cut + \"-cut labels:\\n\", 1 * (eves[:, 0]>0)) # 5.\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nAs anticipated for a (slightly noisy) linear graph,\nthe max-cut strips all the edges of the graph coloring all\nodd vertices into one color and all even vertices into another one,\nwhile the balanced min-cut partitions the graph\nin the middle by deleting a single edge.\nBoth determined partitions are optimal." } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "csgraph", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "normed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "return_diag", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "use_out_degree", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" }, { "__type": "SigParam", "__tag": 4030, "name": "copy", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "form", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "array" }, { "__type": "SigParam", "__tag": 4030, "name": "dtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "symmetrized", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "laplacian" }, "references": [ ".. [1] Laplacian matrix. https://en.wikipedia.org/wiki/Laplacian_matrix" ], "qa": "scipy.sparse.csgraph._laplacian:laplacian", "arbitrary": [], "local_refs": [ "copy: bool", "csgraph", "diag", "dtype: None or one of numeric numpy dtypes", "form: 'array'", "lap", "normed", "optional", "or 'function'", "or 'lo'", "return_diag", "symmetrized: bool", "use_out_degree" ] }