{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Generally, this method is 99% accurate for 2D signals and 85% accurate for 1D signals for randomly chosen input sizes. For precision, use " }, { "__type": "InlineCode", "__tag": 4051, "value": "measure=True" }, { "__type": "Text", "__tag": 4046, "value": " to find the fastest method by timing the convolution. This can be used to avoid the minimal overhead of finding the fastest " }, { "__type": "InlineCode", "__tag": 4051, "value": "method" }, { "__type": "Text", "__tag": 4046, "value": " later, or to adapt the value of " }, { "__type": "InlineCode", "__tag": 4051, "value": "method" }, { "__type": "Text", "__tag": 4046, "value": " to a particular set of inputs." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Experiments were run on an Amazon EC2 r5a.2xlarge machine to test this function. These experiments measured the ratio between the time required when using " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='auto'" }, { "__type": "Text", "__tag": 4046, "value": " and the time required for the fastest method (i.e., " }, { "__type": "InlineCode", "__tag": 4051, "value": "ratio = time_auto / min(time_fft, time_direct)" }, { "__type": "Text", "__tag": 4046, "value": "). In these experiments, we found:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There is a 95% chance of this ratio being less than 1.5 for 1D signals and a 99% chance of being less than 2.5 for 2D signals." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The ratio was always less than 2.5/5 for 1D/2D signals respectively." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This function is most inaccurate for 1D convolutions that take between 1 and 10 milliseconds with " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='direct'" }, { "__type": "Text", "__tag": 4046, "value": ". A good proxy for this (at least in our experiments) is " }, { "__type": "InlineCode", "__tag": 4051, "value": "1e6 <= in1.size * in2.size <= 1e7" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The 2D results almost certainly generalize to 3D/4D/etc because the implementation is the same (the 1D implementation is different)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "All the numbers above are specific to the EC2 machine. However, we did find that this function generalizes fairly decently across hardware. The speed tests were of similar quality (and even slightly better) than the same tests performed on the machine to tune this function's numbers (a mid-2014 15-inch MacBook Pro with 16GB RAM and a 2.5GHz Intel i7 processor)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "There are cases when " }, { "__type": "CrossRef", "__tag": 4002, "value": "fftconvolve", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:fftconvolve" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " supports the inputs but this function returns " }, { "__type": "InlineRole", "__tag": 4003, "value": "direct", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " (e.g., to protect against floating point integer precision)." } ] }, { "__type": "Admonition", "__tag": 4056, "kind": "versionadded", "base_type": "neutral", "children": [ { "__type": "AdmonitionTitle", "__tag": 4055, "children": [ { "__type": "Text", "__tag": 4046, "value": "versionadded 0.19" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Strong", "__tag": 4048, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array API Standard Support" } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "choose_conv_method", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "scipy.signal._signaltools:choose_conv_method" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " has experimental support for Python Array API Standard compatible backends in addition to NumPy. Please consider testing these features by setting an environment variable " }, { "__type": "InlineCode", "__tag": 4051, "value": "SCIPY_ARRAY_API=1" }, { "__type": "Text", "__tag": 4046, "value": " and providing CuPy, PyTorch, JAX, or Dask arrays as array arguments. The following combinations of backend and device (or other capability) are supported." } ] }, { "__type": "Code", "__tag": 4050, "value": "==================== ==================== ====================\nLibrary CPU GPU\n==================== ==================== ====================\nNumPy ✅ n/a \nCuPy n/a ✅ \nPyTorch ✅ ✅ \nJAX ✅ ✅ \nDask ✅ n/a \n==================== ==================== ====================", "execution_status": null }, { "__type": "Blockquote", "__tag": 4059, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "InlineRole", "__tag": 4003, "value": "dev-arrayapi", "domain": null, "role": "ref", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " for more information." } ] } ] } ], "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": "method", "annotation": "str", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A string indicating which convolution method is fastest, either 'direct' or 'fft'" } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "times", "annotation": "dict, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A dictionary containing the times (in seconds) needed for each method. This value is only returned if " }, { "__type": "InlineCode", "__tag": 4051, "value": "measure=True" }, { "__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": "Find the fastest convolution/correlation method." } ] } ], "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": "in1", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The first argument passed into the convolution function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "in2", "annotation": "array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The second argument passed into the convolution function." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "mode", "annotation": "str {'full', 'valid', 'same'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A string indicating the size of the output:" } ] }, { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "full" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The output is the full discrete linear convolution of the inputs. (Default)" } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "valid" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The output consists only of those elements that do not rely on the zero-padding." } ] } ] }, { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineCode", "__tag": 4051, "value": "same" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The output is the same size as " }, { "__type": "ParamRef", "__tag": 4071, "name": "in1" }, { "__type": "Text", "__tag": 4046, "value": ", centered with respect to the 'full' output." } ] } ] } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "measure", "annotation": "bool, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If True, run and time the convolution of " }, { "__type": "ParamRef", "__tag": 4071, "name": "in1" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "ParamRef", "__tag": 4071, "name": "in2" }, { "__type": "Text", "__tag": 4046, "value": " with both methods and return the fastest. If False (default), predict the fastest method using precomputed values." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "This primarily exists to be called during the " }, { "__type": "InlineCode", "__tag": 4051, "value": "method='auto'" }, { "__type": "Text", "__tag": 4046, "value": " option in " }, { "__type": "InlineRole", "__tag": 4003, "value": "convolve", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineRole", "__tag": 4003, "value": "correlate", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ". It can also be used to determine the value of " }, { "__type": "InlineCode", "__tag": 4051, "value": "method" }, { "__type": "Text", "__tag": 4046, "value": " for many different convolutions of the same dtype/shape. In addition, it supports timing the convolution to adapt the value of " }, { "__type": "InlineCode", "__tag": 4051, "value": "method" }, { "__type": "Text", "__tag": 4046, "value": " to a particular set of inputs and/or hardware." } ] } ], "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/signal/_signaltools.py", "item_line": 1236, "item_type": "function", "aliases": [ "scipy.signal.choose_conv_method" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Text", "__tag": 4046, "value": "Estimate the fastest method for a given input:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "import numpy as np\nfrom scipy import signal\nrng = np.random.default_rng()\nimg = rng.random((32, 32))\nfilter = rng.random((8, 8))\nmethod = signal.choose_conv_method(img, filter, mode='same')\nmethod\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThis can then be applied to other arrays of the same dtype and shape:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "img2 = rng.random((32, 32))\nfilter2 = rng.random((8, 8))\ncorr2 = signal.correlate(img2, filter2, mode='same', method=method)\nconv2 = signal.convolve(img2, filter2, mode='same', method=method)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nThe output of this function (``method``) works with `correlate` and\n`convolve`." } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "convolve", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "convolve" }, "kind": "module" }, "descriptions": [], "type": "func" }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "correlate", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "correlate" }, "kind": "module" }, "descriptions": [], "type": "func" } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "in1", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "in2", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "mode", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "full" }, { "__type": "SigParam", "__tag": 4030, "name": "measure", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "choose_conv_method" }, "references": null, "qa": "scipy.signal._signaltools:choose_conv_method", "arbitrary": [], "local_refs": [ "in1", "in2", "measure", "method", "mode", "times" ] }