{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When ARPACK or LOBPCG is selected as the method, the singular values and singular vectors are computed as the eigenvalues and eigenvectors of the corresponding Gram matrix, either " }, { "__type": "InlineCode", "__tag": 4051, "value": "A.conj().T @ A" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "A @ A.conj().T" }, { "__type": "Text", "__tag": 4046, "value": ", depending on which one is computationally cheaper. It is then followed by the Rayleigh-Ritz method as postprocessing; see Using the normal matrix, in Rayleigh-Ritz method, (2022, Nov. 19), Wikipedia, https://w.wiki/4zms." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Alternatively, the PROPACK solver can be called." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Dtype of " }, { "__type": "ParamRef", "__tag": 4071, "name": "A" }, { "__type": "Text", "__tag": 4046, "value": " is mapped, if possible, to float(32,64) and complex(64,128) for internal computations." } ] } ], "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": "u", "annotation": "ndarray, shape=(M, k)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Unitary matrix having left singular vectors as columns." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "s", "annotation": "ndarray, shape=(k,)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The singular values." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "vh", "annotation": "ndarray, shape=(k, N)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Unitary matrix having right singular vectors as rows." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Partial singular value decomposition of a sparse matrix." } ] } ], "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": "A", "annotation": "ndarray, sparse matrix, or LinearOperator", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Matrix to decompose of a floating point numeric dtype." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "k", "annotation": "int, default: 6", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of singular values and singular vectors to compute. Must satisfy " }, { "__type": "InlineCode", "__tag": 4051, "value": "1 <= k <= kmax" }, { "__type": "Text", "__tag": 4046, "value": ", where " }, { "__type": "InlineCode", "__tag": 4051, "value": "kmax=min(M, N)" }, { "__type": "Text", "__tag": 4046, "value": " for " }, { "__type": "InlineCode", "__tag": 4051, "value": "solver='propack'" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "kmax=min(M, N) - 1" }, { "__type": "Text", "__tag": 4046, "value": " otherwise." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "ncv", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When " }, { "__type": "InlineCode", "__tag": 4051, "value": "solver='arpack'" }, { "__type": "Text", "__tag": 4046, "value": ", this is the number of Lanczos vectors generated. See " }, { "__type": "InlineRole", "__tag": 4003, "value": "'arpack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details. When " }, { "__type": "InlineCode", "__tag": 4051, "value": "solver='lobpcg'" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "solver='propack'" }, { "__type": "Text", "__tag": 4046, "value": ", this parameter is ignored." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "tol", "annotation": "float, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tolerance for singular values. Zero (default) means machine precision." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "which", "annotation": "{'LM', 'SM'}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Which " }, { "__type": "ParamRef", "__tag": 4071, "name": "k" }, { "__type": "Text", "__tag": 4046, "value": " singular values to find: either the largest magnitude ('LM') or smallest magnitude ('SM') singular values." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "v0", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The starting vector for iteration; see method-specific documentation (" }, { "__type": "InlineRole", "__tag": 4003, "value": "'arpack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "'lobpcg' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "), or " }, { "__type": "InlineRole", "__tag": 4003, "value": "'propack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "maxiter", "annotation": "int, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Maximum number of iterations; see method-specific documentation (" }, { "__type": "InlineRole", "__tag": 4003, "value": "'arpack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "'lobpcg' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "), or " }, { "__type": "InlineRole", "__tag": 4003, "value": "'propack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "return_singular_vectors", "annotation": "{True, False, \"u\", \"vh\"}", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Singular values are always computed and returned; this parameter controls the computation and return of singular vectors." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "True" }, { "__type": "Text", "__tag": 4046, "value": ": return singular vectors." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "False" }, { "__type": "Text", "__tag": 4046, "value": ": do not return singular vectors." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "\"u\"" }, { "__type": "Text", "__tag": 4046, "value": ": if " }, { "__type": "InlineCode", "__tag": 4051, "value": "M <= N" }, { "__type": "Text", "__tag": 4046, "value": ", compute only the left singular vectors and return " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " for the right singular vectors. Otherwise, compute all singular vectors." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "\"vh\"" }, { "__type": "Text", "__tag": 4046, "value": ": if " }, { "__type": "InlineCode", "__tag": 4051, "value": "M > N" }, { "__type": "Text", "__tag": 4046, "value": ", compute only the right singular vectors and return " }, { "__type": "InlineCode", "__tag": 4051, "value": "None" }, { "__type": "Text", "__tag": 4046, "value": " for the left singular vectors. Otherwise, compute all singular vectors." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "InlineCode", "__tag": 4051, "value": "solver='propack'" }, { "__type": "Text", "__tag": 4046, "value": ", the option is respected regardless of the matrix shape." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "solver", "annotation": "{'arpack', 'propack', 'lobpcg'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The solver used. " }, { "__type": "InlineRole", "__tag": 4003, "value": "'arpack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", " }, { "__type": "InlineRole", "__tag": 4003, "value": "'lobpcg' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", and " }, { "__type": "InlineRole", "__tag": 4003, "value": "'propack' ", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " are supported. Default: " }, { "__type": "InlineRole", "__tag": 4003, "value": "'arpack'", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "rng", "annotation": "{None, int, `numpy.random.Generator`}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is passed by keyword, types other than " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " are passed to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.default_rng", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random:default_rng" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to instantiate a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": ". If " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " is already a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " instance, then the provided instance is used. Specify " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " for repeatable function behavior." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If this argument is passed by position or " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is passed by keyword, legacy behavior for the argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " applies:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is None (or " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "), the " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.RandomState", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random.mtrand:RandomState" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " singleton is used." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is an int, a new " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " instance is used, seeded with " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " is already a " }, { "__type": "InlineCode", "__tag": 4051, "value": "Generator" }, { "__type": "Text", "__tag": 4046, "value": " or " }, { "__type": "InlineCode", "__tag": 4051, "value": "RandomState" }, { "__type": "Text", "__tag": 4046, "value": " instance then that instance is used." } ] } ] } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionchanged", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionchanged 1.15.0" } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "As part of the " }, { "__type": "Link", "__tag": 4049, "children": [ { "__type": "Text", "__tag": 4046, "value": "SPEC-007" } ], "url": "https://scientific-python.org/specs/spec-0007/", "title": "" }, { "__type": "Text", "__tag": 4046, "value": " transition from use of " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.RandomState", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random.mtrand:RandomState" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.random.Generator", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "numpy", "version": "*", "kind": "api", "path": "numpy.random._generator:Generator" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ", this keyword was changed from " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " to " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": ". For an interim period, both keywords will continue to work, although only one may be specified at a time. After the interim period, function calls using the " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " keyword will emit warnings. The behavior of both " }, { "__type": "ParamRef", "__tag": 4071, "name": "random_state" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " are outlined above, but only the " }, { "__type": "ParamRef", "__tag": 4071, "name": "rng" }, { "__type": "Text", "__tag": 4046, "value": " keyword should be used in new code." } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "options", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dictionary of solver-specific options. No solver-specific options are currently supported; this parameter is reserved for future use." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Compute the largest or smallest " }, { "__type": "ParamRef", "__tag": 4071, "name": "k" }, { "__type": "Text", "__tag": 4046, "value": " singular values and corresponding singular vectors of a sparse matrix " }, { "__type": "ParamRef", "__tag": 4071, "name": "A" }, { "__type": "Text", "__tag": 4046, "value": ". The order in which the singular values are returned is not guaranteed." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In the descriptions below, let " }, { "__type": "InlineCode", "__tag": 4051, "value": "M, N = A.shape" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ], "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/_eigen/_svds.py", "item_line": 108, "item_type": "function", "aliases": [ "scipy.sparse.linalg.svds" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Construct a matrix `A` from singular values and vectors.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import sparse, linalg, stats\nfrom scipy.sparse.linalg import svds, aslinearoperator, LinearOperator\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nConstruct a dense matrix `A` from singular values and vectors.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(258265244568965474821194062361901728911)\northogonal = stats.ortho_group.rvs(10, random_state=rng)\ns = [1e-3, 1, 2, 3, 4] # non-zero singular values\nu = orthogonal[:, :5] # left singular vectors\nvT = orthogonal[:, 5:].T # right singular vectors\nA = u @ np.diag(s) @ vT\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWith only four singular values/vectors, the SVD approximates the original\nmatrix.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "u4, s4, vT4 = svds(A, k=4)\nA4 = u4 @ np.diag(s4) @ vT4\nnp.allclose(A4, A, atol=1e-3)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWith all five non-zero singular values/vectors, we can reproduce\nthe original matrix more accurately.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "u5, s5, vT5 = svds(A, k=5)\nA5 = u5 @ np.diag(s5) @ vT5\nnp.allclose(A5, A)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe singular values match the expected singular values.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.allclose(s5, s)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSince the singular values are not close to each other in this example,\nevery singular vector matches as expected up to a difference in sign.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "(np.allclose(np.abs(u5), np.abs(u)) and\n np.allclose(np.abs(vT5), np.abs(vT)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe singular vectors are also orthogonal.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "(np.allclose(u5.T @ u5, np.eye(5)) and\n np.allclose(vT5 @ vT5.T, np.eye(5)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIf there are (nearly) multiple singular values, the corresponding\nindividual singular vectors may be unstable, but the whole invariant\nsubspace containing all such singular vectors is computed accurately\nas can be measured by angles between subspaces via 'subspace_angles'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(178686584221410808734965903901790843963)\ns = [1, 1 + 1e-6] # non-zero singular values\nu, _ = np.linalg.qr(rng.standard_normal((99, 2)))\nv, _ = np.linalg.qr(rng.standard_normal((99, 2)))\nvT = v.T\nA = u @ np.diag(s) @ vT\nA = A.astype(np.float32)\nu2, s2, vT2 = svds(A, k=2, rng=rng)\nnp.allclose(s2, s)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe angles between the individual exact and computed singular vectors\nmay not be so small. To check use:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "(linalg.subspace_angles(u2[:, :1], u[:, :1]) +\n linalg.subspace_angles(u2[:, 1:], u[:, 1:]))\n(linalg.subspace_angles(vT2[:1, :].T, vT[:1, :].T) +\n linalg.subspace_angles(vT2[1:, :].T, vT[1:, :].T))\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nAs opposed to the angles between the 2-dimensional invariant subspaces\nthat these vectors span, which are small for rights singular vectors\n\n" }, { "__type": "Code", "__tag": 4050, "value": "linalg.subspace_angles(u2, u).sum() < 1e-6\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nas well as for left singular vectors.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "linalg.subspace_angles(vT2.T, vT.T).sum() < 1e-6\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nThe next example follows that of 'sklearn.decomposition.TruncatedSVD'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(0)\nX_dense = rng.random(size=(100, 100))\nX_dense[:, 2 * np.arange(50)] = 0\nX = sparse.csr_array(X_dense)\n_, singular_values, _ = svds(X, k=5, rng=rng)\nprint(singular_values)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe function can be called without the transpose of the input matrix\never explicitly constructed.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "rng = np.random.default_rng(102524723947864966825913730119128190974)\nG = sparse.random_array((8, 9), density=0.5, rng=rng)\nGlo = aslinearoperator(G)\n_, singular_values_svds, _ = svds(Glo, k=5, rng=rng)\n_, singular_values_svd, _ = linalg.svd(G.toarray())\nnp.allclose(singular_values_svds, singular_values_svd[-4::-1])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe most memory efficient scenario is where neither\nthe original matrix, nor its transpose, is explicitly constructed.\nOur example computes the smallest singular values and vectors\nof 'LinearOperator' constructed from the numpy function 'np.diff' used\ncolumn-wise to be consistent with 'LinearOperator' operating on columns.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "diff0 = lambda a: np.diff(a, axis=0)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nLet us create the matrix from 'diff0' to be used for validation only.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "n = 5 # The dimension of the space.\nM_from_diff0 = diff0(np.eye(n))\nprint(M_from_diff0.astype(int))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe matrix 'M_from_diff0' is bi-diagonal and could be alternatively\ncreated directly by\n\n" }, { "__type": "Code", "__tag": 4050, "value": "M = - np.eye(n - 1, n, dtype=int)\nnp.fill_diagonal(M[:,1:], 1)\nnp.allclose(M, M_from_diff0)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nIts transpose\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(M.T)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\ncan be viewed as the incidence matrix; see\nIncidence matrix, (2022, Nov. 19), Wikipedia, https://w.wiki/5YXU,\nof a linear graph with 5 vertices and 4 edges. The 5x5 normal matrix\n``M.T @ M`` thus is\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(M.T @ M)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nthe graph Laplacian, while the actually used in 'svds' smaller size\n4x4 normal matrix ``M @ M.T``\n\n" }, { "__type": "Code", "__tag": 4050, "value": "print(M @ M.T)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nis the so-called edge-based Laplacian; see\nSymmetric Laplacian via the incidence matrix, in Laplacian matrix,\n(2022, Nov. 19), Wikipedia, https://w.wiki/5YXW.\n\nThe 'LinearOperator' setup needs the options 'rmatvec' and 'rmatmat'\nof multiplication by the matrix transpose ``M.T``, but we want to be\nmatrix-free to save memory, so knowing how ``M.T`` looks like, we\nmanually construct the following function to be\nused in ``rmatmat=diff0t``.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def diff0t(a):\n if a.ndim == 1:\n a = a[:,np.newaxis] # Turn 1D into 2D array\n d = np.zeros((a.shape[0] + 1, a.shape[1]), dtype=a.dtype)\n d[0, :] = - a[0, :]\n d[1:-1, :] = a[0:-1, :] - a[1:, :]\n d[-1, :] = a[-1, :]\n return d\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWe check that our function 'diff0t' for the matrix transpose is valid.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.allclose(M.T, diff0t(np.eye(n-1)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNow we setup our matrix-free 'LinearOperator' called 'diff0_func_aslo'\nand for validation the matrix-based 'diff0_matrix_aslo'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "def diff0_func_aslo_def(n):\n return LinearOperator(matvec=diff0,\n matmat=diff0,\n rmatvec=diff0t,\n rmatmat=diff0t,\n shape=(n - 1, n))\ndiff0_func_aslo = diff0_func_aslo_def(n)\ndiff0_matrix_aslo = aslinearoperator(M_from_diff0)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAnd validate both the matrix and its transpose in 'LinearOperator'.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.allclose(diff0_func_aslo(np.eye(n)),\n diff0_matrix_aslo(np.eye(n)))\nnp.allclose(diff0_func_aslo.T(np.eye(n-1)),\n diff0_matrix_aslo.T(np.eye(n-1)))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nHaving the 'LinearOperator' setup validated, we run the solver.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "n = 100\ndiff0_func_aslo = diff0_func_aslo_def(n)\nu, s, vT = svds(diff0_func_aslo, k=3, which='SM')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe singular values squared and the singular vectors are known\nexplicitly; see\nPure Dirichlet boundary conditions, in\nEigenvalues and eigenvectors of the second derivative,\n(2022, Nov. 19), Wikipedia, https://w.wiki/5YX6,\nsince 'diff' corresponds to first\nderivative, and its smaller size n-1 x n-1 normal matrix\n``M @ M.T`` represent the discrete second derivative with the Dirichlet\nboundary conditions. We use these analytic expressions for validation.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "se = 2. * np.sin(np.pi * np.arange(1, 4) / (2. * n))\nue = np.sqrt(2 / n) * np.sin(np.pi * np.outer(np.arange(1, n),\n np.arange(1, 4)) / n)\nnp.allclose(s, se, atol=1e-3)\nnp.allclose(np.abs(u), np.abs(ue), atol=1e-6)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "A", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "k", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "6" }, { "__type": "SigParam", "__tag": 4030, "name": "ncv", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "tol", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "0" }, { "__type": "SigParam", "__tag": 4030, "name": "which", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "LM" }, { "__type": "SigParam", "__tag": 4030, "name": "v0", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "maxiter", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "return_singular_vectors", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "True" }, { "__type": "SigParam", "__tag": 4030, "name": "solver", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "arpack" }, { "__type": "SigParam", "__tag": 4030, "name": "rng", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "options", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "random_state", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "svds" }, "references": null, "qa": "scipy.sparse.linalg._eigen._svds:svds", "arbitrary": [], "local_refs": [ "A", "k", "maxiter", "ncv", "options", "return_singular_vectors", "rng", "s", "solver", "tol", "u", "v0", "vh", "which" ] }