{ "__type": "IngestedDoc", "__tag": 4010, "_content": { "Notes": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The Einstein summation convention can be used to compute many multi-dimensional, linear algebraic array operations. " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " provides a succinct way of representing these." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "A non-exhaustive list of these operations, which can be computed by " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": ", is shown below along with examples:" } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Trace of an array, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.trace", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:trace" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Return a diagonal, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.diag", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:diag" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Array axis summations, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.sum", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:sum" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Transpositions and permutations, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.transpose", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:transpose" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Matrix multiplication and dot product, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.matmul", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:matmul" }, "kind": "module" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "numpy.dot", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:dot" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Vector inner and outer products, " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.inner", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:inner" }, "kind": "module" } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "numpy.outer", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:outer" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Broadcasting, element-wise and scalar multiplication," } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "numpy.multiply", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:multiply" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Tensor contractions, " }, { "__type": "InlineRole", "__tag": 4003, "value": "numpy.tensordot", "domain": "py", "role": "func", "inventory": null }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "DefList", "__tag": 4033, "children": [ { "__type": "DefListItem", "__tag": 4037, "dt": { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Chained array operations, in efficient calculation order," } ] }, "dd": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "CrossRef", "__tag": 4002, "value": "numpy.einsum_path", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:einsum_path" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] } ] } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The subscripts string is a comma-separated list of subscript labels, where each label refers to a dimension of the corresponding operand. Whenever a label is repeated it is summed, so " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('i,i', a, b)" }, { "__type": "Text", "__tag": 4046, "value": " is equivalent to " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.inner(a,b)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:inner" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". If a label appears only once, it is not summed, so " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('i', a)" }, { "__type": "Text", "__tag": 4046, "value": " produces a view of " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " with no changes. A further example " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij,jk', a, b)" }, { "__type": "Text", "__tag": 4046, "value": " describes traditional matrix multiplication and is equivalent to " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.matmul(a,b)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:matmul" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": ". Repeated subscript labels in one operand take the diagonal. For example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ii', a)" }, { "__type": "Text", "__tag": 4046, "value": " is equivalent to " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.trace(a)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:trace" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "implicit mode" } ] }, { "__type": "Text", "__tag": 4046, "value": ", the chosen subscripts are important since the axes of the output are reordered alphabetically. This means that " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij', a)" }, { "__type": "Text", "__tag": 4046, "value": " doesn't affect a 2D array, while " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ji', a)" }, { "__type": "Text", "__tag": 4046, "value": " takes its transpose. Additionally, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij,jk', a, b)" }, { "__type": "Text", "__tag": 4046, "value": " returns a matrix multiplication, while, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij,jh', a, b)" }, { "__type": "Text", "__tag": 4046, "value": " returns the transpose of the multiplication since subscript 'h' precedes subscript 'i'." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "explicit mode" } ] }, { "__type": "Text", "__tag": 4046, "value": " the output can be directly controlled by specifying output subscript labels. This requires the identifier '->' as well as the list of output subscript labels. This feature increases the flexibility of the function since summing can be disabled or forced when required. The call " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('i->', a)" }, { "__type": "Text", "__tag": 4046, "value": " is like " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.sum(a)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:sum" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " is a 1-D array, and " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ii->i', a)" }, { "__type": "Text", "__tag": 4046, "value": " is like " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.diag(a)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:diag" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " if " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " is a square 2-D array. The difference is that " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " does not allow broadcasting by default. Additionally " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij,jh->ih', a, b)" }, { "__type": "Text", "__tag": 4046, "value": " directly specifies the order of the output subscript labels and therefore returns matrix multiplication, unlike the example above in implicit mode." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "To enable and control broadcasting, use an ellipsis. Default NumPy-style broadcasting is done by adding an ellipsis to the left of each term, like " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('...ii->...i', a)" }, { "__type": "Text", "__tag": 4046, "value": ". " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('...i->...', a)" }, { "__type": "Text", "__tag": 4046, "value": " is like " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.sum(a, axis=-1)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:sum" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for array " }, { "__type": "InlineCode", "__tag": 4051, "value": "a" }, { "__type": "Text", "__tag": 4046, "value": " of any shape. To take the trace along the first and last axes, you can do " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('i...i', a)" }, { "__type": "Text", "__tag": 4046, "value": ", or to do a matrix-matrix product with the left-most indices instead of rightmost, one can do " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ij...,jk...->ik...', a, b)" }, { "__type": "Text", "__tag": 4046, "value": "." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "When there is only one operand, no axes are summed, and no output parameter is provided, a view into the operand is returned instead of a new array. Thus, taking the diagonal as " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ii->i', a)" }, { "__type": "Text", "__tag": 4046, "value": " produces a view (changed in version 1.10.0)." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " also provides an alternative way to provide the subscripts and operands as " }, { "__type": "InlineCode", "__tag": 4051, "value": "einsum(op0, sublist0, op1, sublist1, ..., [sublistout])" }, { "__type": "Text", "__tag": 4046, "value": ". If the output shape is not provided in this format " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " will be calculated in implicit mode, otherwise it will be performed explicitly. The examples below have corresponding " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " calls with the two parameter methods." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Views returned from einsum are now writeable whenever the input array is writeable. For example, " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ijk...->kji...', a)" }, { "__type": "Text", "__tag": 4046, "value": " will now have the same effect as " }, { "__type": "CrossRef", "__tag": 4002, "value": "np.swapaxes(a, 0, 2)", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:swapaxes" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " and " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum('ii->i', a)" }, { "__type": "Text", "__tag": 4046, "value": " will return a writeable view of the diagonal of a 2D array." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Added the " }, { "__type": "InlineCode", "__tag": 4051, "value": "optimize" }, { "__type": "Text", "__tag": 4046, "value": " argument which will optimize the contraction order of an einsum expression. For a contraction with three or more operands this can greatly increase the computational efficiency at the cost of a larger memory footprint during computation." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Typically a 'greedy' algorithm is applied which empirical tests have shown returns the optimal path in the majority of cases. In some cases 'optimal' will return the superlative path through a more expensive, exhaustive search. For iterative calculations it may be advisable to calculate the optimal path once and reuse that path by supplying it as an argument. An example is given below." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See " }, { "__type": "CrossRef", "__tag": 4002, "value": "numpy.einsum_path", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:einsum_path" }, "kind": "module" }, { "__type": "Text", "__tag": 4046, "value": " for more details." } ] } ], "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": "output", "annotation": "ndarray", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "The calculation based on the Einstein summation convention." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Evaluates the Einstein summation convention on the operands." } ] } ], "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": "subscripts", "annotation": "str", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Specifies the subscripts for summation as comma separated list of subscript labels. An implicit (classical Einstein summation) calculation is performed unless the explicit indicator '->' is included as well as subscript labels of the precise output form." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "operands", "annotation": "list of array_like", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "These are the arrays for the operation." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "out", "annotation": "ndarray, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, the calculation is done into this array." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "dtype", "annotation": "{data-type, None}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "If provided, forces the calculation to use the data type specified. Note that you may have to also give a more liberal " }, { "__type": "ParamRef", "__tag": 4071, "name": "casting" }, { "__type": "Text", "__tag": 4046, "value": " parameter to allow the conversions. Default is None." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "order", "annotation": "{'C', 'F', 'A', 'K'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls the memory layout of the output. 'C' means it should be C contiguous. 'F' means it should be Fortran contiguous, 'A' means it should be 'F' if the inputs are all 'F', 'C' otherwise. 'K' means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. Default is 'K'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "casting", "annotation": "{'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls what kind of data casting may occur. Setting this to 'unsafe' is not recommended, as it can adversely affect accumulations." } ] }, { "__type": "BulletList", "__tag": 4053, "ordered": false, "start": 1, "children": [ { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'no' means the data types should not be cast at all." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'equiv' means only byte-order changes are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'safe' means only casts which can preserve values are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'same_kind' means only safe casts or casts within a kind, like float64 to float32, are allowed." } ] } ] }, { "__type": "ListItem", "__tag": 4054, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "'unsafe' means any data conversions may be done." } ] } ] } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Default is 'safe'." } ] } ] }, { "__type": "DocParam", "__tag": 4016, "name": "optimize", "annotation": "{False, True, 'greedy', 'optimal'}, optional", "desc": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Controls if intermediate optimization should occur. No optimization will occur if False and True will default to the 'greedy' algorithm. Also accepts an explicit contraction list from the " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum_path" }, { "__type": "Text", "__tag": 4046, "value": " function. See " }, { "__type": "InlineCode", "__tag": 4051, "value": "np.einsum_path" }, { "__type": "Text", "__tag": 4046, "value": " for more details. Defaults to False." } ] } ] } ] } ], "title": [], "level": 0, "target": null }, "Extended Summary": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Using the Einstein summation convention, many common multi-dimensional, linear algebraic array operations can be represented in a simple fashion. In " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "implicit" } ] }, { "__type": "Text", "__tag": 4046, "value": " mode " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " computes these values." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "In " }, { "__type": "Emphasis", "__tag": 4047, "children": [ { "__type": "Text", "__tag": 4046, "value": "explicit" } ] }, { "__type": "Text", "__tag": 4046, "value": " mode, " }, { "__type": "InlineRole", "__tag": 4003, "value": "einsum", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " provides further flexibility to compute other array operations that might not be considered classical Einstein summation operations, by disabling, or forcing summation over specified subscript labels." } ] }, { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "See the notes and examples for clarification." } ] } ], "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": "/numpy/_core/einsumfunc.py", "item_line": 1244, "item_type": "_ArrayFunctionDispatcher", "aliases": [ "numpy.einsum" ], "example_section_data": { "__type": "Section", "__tag": 4015, "children": [ { "__type": "Code", "__tag": 4050, "value": "a = np.arange(25).reshape(5,5)\nb = np.arange(5)\nc = np.arange(6).reshape(2,3)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nTrace of a matrix:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('ii', a)\nnp.einsum(a, [0,0])\nnp.trace(a)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nExtract the diagonal (requires explicit form):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('ii->i', a)\nnp.einsum(a, [0,0], [0])\nnp.diag(a)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSum over an axis (requires explicit form):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('ij->i', a)\nnp.einsum(a, [0,1], [0])\nnp.sum(a, axis=1)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nFor higher dimensional arrays summing a single axis can be done\nwith ellipsis:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('...j->...', a)\nnp.einsum(a, [Ellipsis,1], [Ellipsis])\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nCompute a matrix transpose, or reorder any number of axes:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('ji', c)\nnp.einsum('ij->ji', c)\nnp.einsum(c, [1,0])\nnp.transpose(c)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nVector inner products:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('i,i', b, b)\nnp.einsum(b, [0], b, [0])\nnp.inner(b,b)\n", "execution_status": "failure" }, { "__type": "Text", "__tag": 4046, "value": "\nMatrix vector multiplication:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('ij,j', a, b)\nnp.einsum(a, [0,1], b, [1])\nnp.dot(a, b)\nnp.einsum('...j,j', a, b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nBroadcasting and scalar multiplication:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('..., ...', 3, c)\nnp.einsum(',ij', 3, c)\nnp.einsum(3, [Ellipsis], c, [Ellipsis])\nnp.multiply(3, c)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nVector outer product:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "np.einsum('i,j', np.arange(2)+1, b)\nnp.einsum(np.arange(2)+1, [0], b, [1])\nnp.outer(np.arange(2)+1, b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nTensor contraction:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(60.).reshape(3,4,5)\nb = np.arange(24.).reshape(4,3,2)\nnp.einsum('ijk,jil->kl', a, b)\nnp.einsum(a, [0,1,2], b, [1,0,3], [2,3])\nnp.tensordot(a,b, axes=([1,0],[0,1]))\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nWriteable returned arrays (since version 1.10.0):\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.zeros((3, 3))\nnp.einsum('ii->i', a)[:] = 1\na\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nExample of ellipsis use:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.arange(6).reshape((3,2))\nb = np.arange(12).reshape((4,3))\nnp.einsum('ki,jk->ij', a, b)\nnp.einsum('ki,...k->i...', a, b)\nnp.einsum('k...,jk', a, b)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nChained array operations. For more complicated contractions, speed ups\nmight be achieved by repeatedly computing a 'greedy' path or pre-computing\nthe 'optimal' path and repeatedly applying it, using an `einsum_path`\ninsertion (since version 1.12.0). Performance improvements can be\nparticularly significant with larger arrays:\n\n" }, { "__type": "Code", "__tag": 4050, "value": "a = np.ones(64).reshape(2,4,8)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nBasic `einsum`: ~1520ms (benchmarked on 3.1GHz Intel i5.)\n\n" }, { "__type": "Code", "__tag": 4050, "value": "for iteration in range(500):\n _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a)\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nSub-optimal `einsum` (due to repeated path calculation time): ~330ms\n\n" }, { "__type": "Code", "__tag": 4050, "value": "for iteration in range(500):\n _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a,\n optimize='optimal')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nGreedy `einsum` (faster optimal path approximation): ~160ms\n\n" }, { "__type": "Code", "__tag": 4050, "value": "for iteration in range(500):\n _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize='greedy')\n", "execution_status": "success" }, { "__type": "Text", "__tag": 4046, "value": "\nOptimal `einsum` (best usage pattern in some use cases): ~110ms\n\n" }, { "__type": "Code", "__tag": 4050, "value": "path = np.einsum_path('ijk,ilm,njm,nlk,abc->',a,a,a,a,a,\n optimize='optimal')[0]\nfor iteration in range(500):\n _ = np.einsum('ijk,ilm,njm,nlk,abc->',a,a,a,a,a, optimize=path)\n", "execution_status": "success" } ], "title": [], "level": 0, "target": null }, "see_also": [ { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "dot", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "dot" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "einsum", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "einsum" }, "kind": "module" }, "descriptions": [ { "__type": "Paragraph", "__tag": 4045, "children": [ { "__type": "Text", "__tag": 4046, "value": "Similar verbose interface is provided by the " }, { "__type": "InlineRole", "__tag": 4003, "value": "einops ", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " package to cover additional operations: transpose, reshape/flatten, repeat/tile, squeeze/unsqueeze and reductions. The " }, { "__type": "InlineRole", "__tag": 4003, "value": "opt_einsum ", "domain": null, "role": null, "inventory": null }, { "__type": "Text", "__tag": 4046, "value": " optimizes contraction order for einsum-like expressions in backend-agnostic manner." } ] } ], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "einsum_path", "reference": { "__type": "LocalRef", "__tag": 4022, "kind": "module", "path": "numpy:einsum_path" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "inner", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "inner" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "linalg.multi_dot", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "linalg.multi_dot" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "outer", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "outer" }, "kind": "module" }, "descriptions": [], "type": null }, { "__type": "SeeAlsoItem", "__tag": 4028, "name": { "__type": "CrossRef", "__tag": 4002, "value": "tensordot", "reference": { "__type": "RefInfo", "__tag": 4000, "module": "current-module", "version": "current-version", "kind": "to-resolve", "path": "tensordot" }, "kind": "module" }, "descriptions": [], "type": null } ], "signature": { "__type": "SignatureNode", "__tag": 4029, "kind": "function", "parameters": [ { "__type": "SigParam", "__tag": 4030, "name": "subscripts", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "POSITIONAL_OR_KEYWORD", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "operands", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "VAR_POSITIONAL", "default": { "__type": "Empty", "__tag": 4031 } }, { "__type": "SigParam", "__tag": 4030, "name": "out", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "dtype", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "None" }, { "__type": "SigParam", "__tag": 4030, "name": "order", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "K" }, { "__type": "SigParam", "__tag": 4030, "name": "casting", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "safe" }, { "__type": "SigParam", "__tag": 4030, "name": "optimize", "annotation": { "__type": "Empty", "__tag": 4031 }, "kind": "KEYWORD_ONLY", "default": "False" } ], "return_annotation": { "__type": "Empty", "__tag": 4031 }, "target_name": "einsum" }, "references": null, "qa": "numpy:einsum", "arbitrary": [], "local_refs": [ "casting", "dtype", "operands", "optimize", "order", "out", "output", "subscripts" ] }