{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To make the statement" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\|Ax\\| \\approx \\|A'x\\|" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "precise, observe the following result which is adapted from the proof of Theorem 14 of " }, { "__type": "FootnoteReference", "__tag": 4066, "label": "2" }, { "__type": "Text", "__tag": 4046, "value": " via Markov's Inequality. If we have a sketch size " }, { "__type": "InlineCode", "__tag": 4051, "value": "sketch_size=k" }, { "__type": "Text", "__tag": 4046, "value": " which is at least" } ] }, { "__type": "Math", "__tag": 4058, "value": "k \\geq \\frac{2}{\\epsilon^2\\delta}" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Then for any fixed vector " }, { "__type": "InlineCode", "__tag": 4051, "value": "x" }, { "__type": "Text", "__tag": 4046, "value": "," } ] }, { "__type": "Math", "__tag": 4058, "value": "\\|Ax\\| = (1\\pm\\epsilon)\\|A'x\\|" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with probability at least one minus delta." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This implementation takes advantage of sparsity: computing a sketch takes time proportional to " }, { "__type": "InlineCode", "__tag": 4051, "value": "A.nnz" }, { "__type": "Text", "__tag": 4046, "value": ". Data " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": " which is in " }, { "__type": "InlineCode", "__tag": 4051, "value": "scipy.sparse.csc_matrix" }, { "__type": "Text", "__tag": 4046, "value": " format gives the quickest computation time for sparse input." } ] }, { "__type": "Code", "__tag": 4050, "value": ">>> import numpy as np\n>>> from scipy import linalg\n>>> from scipy import sparse\n>>> rng = np.random.default_rng()\n>>> n_rows, n_columns, density, sketch_n_rows = 15000, 100, 0.01, 200\n>>> A = sparse.rand(n_rows, n_columns, density=density, format='csc')\n>>> B = sparse.rand(n_rows, n_columns, density=density, format='csr')\n>>> C = sparse.rand(n_rows, n_columns, density=density, format='coo')\n>>> D = rng.standard_normal((n_rows, n_columns))\n>>> SA = linalg.clarkson_woodruff_transform(A, sketch_n_rows) # fastest\n>>> SB = linalg.clarkson_woodruff_transform(B, sketch_n_rows) # fast\n>>> SC = linalg.clarkson_woodruff_transform(C, sketch_n_rows) # slower\n>>> SD = linalg.clarkson_woodruff_transform(D, sketch_n_rows) # slowest", "execution_status": null }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "That said, this method does perform well on dense inputs, just slower on a relative scale." } ] } ], "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": "A'", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Sketch of the input matrix " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": ", of size " }, { "__type": "InlineCode", "__tag": 4051, "value": "(sketch_size, d)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Applies a Clarkson-Woodruff Transform/sketch to the input 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": "input_matrix", "annotation": "array_like, shape (..., n, d)", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Input matrix." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "sketch_size", "annotation": "int", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Number of rows for the sketch." } ] } ] }, { "__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": "seed" }, { "__type": "Text", "__tag": 4046, "value": " is passed by keyword, legacy behavior for the argument " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__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": "seed" }, { "__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": "seed" }, { "__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": "seed" }, { "__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": "seed" }, { "__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": "seed" }, { "__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": "seed" }, { "__type": "Text", "__tag": 4046, "value": " keyword will emit warnings. The behavior of both " }, { "__type": "ParamRef", "__tag": 4071, "name": "seed" }, { "__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." } ] } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Given an input_matrix " }, { "__type": "InlineCode", "__tag": 4051, "value": "A" }, { "__type": "Text", "__tag": 4046, "value": " of size " }, { "__type": "InlineCode", "__tag": 4051, "value": "(n, d)" }, { "__type": "Text", "__tag": 4046, "value": ", compute a matrix " }, { "__type": "InlineCode", "__tag": 4051, "value": "A'" }, { "__type": "Text", "__tag": 4046, "value": " of size (sketch_size, d) so that" } ] }, { "__type": "Math", "__tag": 4058, "value": "\\|Ax\\| \\approx \\|A'x\\|" }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "with high probability via the Clarkson-Woodruff Transform, otherwise known as the CountSketch matrix." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The documentation is written assuming array arguments are of specified \"core\" shapes. However, array argument(s) of this function may have additional \"batch\" dimensions prepended to the core shape. In this case, the array is treated as a batch of lower-dimensional slices; see " }, { "__type": "InlineRole", "__tag": 4003, "value": "linalg_batch", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for details." } ] } ], "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/linalg/_sketches.py", "item_line": 57, "item_type": "function", "aliases": [ "scipy.linalg.clarkson_woodruff_transform" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Create a big dense matrix ``A`` for the example:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import linalg\nn_rows, n_columns = 15000, 100\nrng = np.random.default_rng()\nA = rng.standard_normal((n_rows, n_columns))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nApply the transform to create a new matrix with 200 rows:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "sketch_n_rows = 200\nsketch = linalg.clarkson_woodruff_transform(A, sketch_n_rows, seed=rng)\nsketch.shape\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nNow with high probability, the true norm is close to the sketched norm\nin absolute value.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "linalg.norm(A)\nlinalg.norm(sketch)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nSimilarly, applying our sketch preserves the solution to a linear\nregression of :math:`\\min \\|Ax - b\\|`.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "b = rng.standard_normal(n_rows)\nx = linalg.lstsq(A, b)[0]\nAb = np.hstack((A, b.reshape(-1, 1)))\nSAb = linalg.clarkson_woodruff_transform(Ab, sketch_n_rows, seed=rng)\nSA, Sb = SAb[:, :-1], SAb[:, -1]\nx_sketched = linalg.lstsq(SA, Sb)[0]\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nAs with the matrix norm example, ``linalg.norm(A @ x - b)`` is close\nto ``linalg.norm(A @ x_sketched - b)`` with high probability.\n\n" }, { "__type": "Code", "__tag": 4050, "value": "linalg.norm(A @ x - b)\nlinalg.norm(A @ x_sketched - b)\n", "execution_status": "failure" } ], "title": [], "level": 0, "target": null }, "see_also": [], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "input_matrix", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "sketch_size", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "rng", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "seed", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "clarkson_woodruff_transform" }, "references": [ ".. [1] Kenneth L. Clarkson and David P. Woodruff. Low rank approximation", " and regression in input sparsity time. In STOC, 2013.", ".. [2] David P. Woodruff. Sketching as a tool for numerical linear algebra.", " In Foundations and Trends in Theoretical Computer Science, 2014." ], "qa": "scipy.linalg._sketches:clarkson_woodruff_transform", "arbitrary": [], "local_refs": [ "A'", "input_matrix", "rng", "sketch_size" ] }