diff options
| author | mattip <matti.picus@gmail.com> | 2018-04-30 18:13:10 +0300 |
|---|---|---|
| committer | Marten van Kerkwijk <mhvk@astro.utoronto.ca> | 2018-07-17 17:04:59 -0400 |
| commit | f7766b40b64c83a328916de92362cd5d98febb32 (patch) | |
| tree | 8d1070ae4f6399e689a4083245339237a8bdd155 /doc/source/reference/c-api.generalized-ufuncs.rst | |
| parent | 84f6df82f2fbb7e5ce0cd82976b671a180ed3b84 (diff) | |
| download | numpy-f7766b40b64c83a328916de92362cd5d98febb32.tar.gz | |
ENH: test, document, implement flexible signature.
Goal is allow signatures like (m?,n),(n,p?)->(m?,p?) for matmul.
Diffstat (limited to 'doc/source/reference/c-api.generalized-ufuncs.rst')
| -rw-r--r-- | doc/source/reference/c-api.generalized-ufuncs.rst | 51 |
1 files changed, 33 insertions, 18 deletions
diff --git a/doc/source/reference/c-api.generalized-ufuncs.rst b/doc/source/reference/c-api.generalized-ufuncs.rst index dd8cf6558..59aa11d00 100644 --- a/doc/source/reference/c-api.generalized-ufuncs.rst +++ b/doc/source/reference/c-api.generalized-ufuncs.rst @@ -127,34 +127,49 @@ The formal syntax of signatures is as follows:: <Output arguments> ::= <Argument list> <Argument list> ::= nil | <Argument> | <Argument> "," <Argument list> <Argument> ::= "(" <Core dimension list> ")" - <Core dimension list> ::= nil | <Core dimension name> | - <Core dimension name> "," <Core dimension list> - <Core dimension name> ::= valid Python variable name - + <Core dimension list> ::= nil | <Core dimension> | + <Core dimension> "," <Core dimension list> + <Core dimension> ::= <Dimension name> <Dimension modifier> + <Dimension name> ::= valid Python variable name | valid integer + <Dimension modifier> ::= nil | "?" Notes: #. All quotes are for clarity. -#. Core dimensions that share the same name must have the exact same size. +#. Unmodified core dimensions that share the same name must have the same size. Each dimension name typically corresponds to one level of looping in the elementary function's implementation. #. White spaces are ignored. +#. An integer as a dimension name freezes that dimension to the value. +#. If the name is suffixed with the "?" modifier, the dimension is a core + dimension only if it exists on all inputs and outputs that share it; + otherwise it is ignored (and replaced by a dimension of size 1 for the + elementary function). Here are some examples of signatures: -+-------------+------------------------+-----------------------------------+ -| add | ``(),()->()`` | | -+-------------+------------------------+-----------------------------------+ -| inner1d | ``(i),(i)->()`` | | -+-------------+------------------------+-----------------------------------+ -| sum1d | ``(i)->()`` | | -+-------------+------------------------+-----------------------------------+ -| dot2d | ``(m,n),(n,p)->(m,p)`` | matrix multiplication | -+-------------+------------------------+-----------------------------------+ -| outer_inner | ``(i,t),(j,t)->(i,j)`` | inner over the last dimension, | -| | | outer over the second to last, | -| | | and loop/broadcast over the rest. | -+-------------+------------------------+-----------------------------------+ ++-------------+----------------------------+-----------------------------------+ +| add | ``(),()->()`` | | ++-------------+----------------------------+-----------------------------------+ +| sum1d | ``(i)->()`` | | ++-------------+----------------------------+-----------------------------------+ +| inner1d | ``(i),(i)->()`` | | ++-------------+----------------------------+-----------------------------------+ +| matmat | ``(m,n),(n,p)->(m,p)`` | matrix multiplication | ++-------------+----------------------------+-----------------------------------+ +| vecmat | ``(n),(n,p)->(p)`` | vector-matrix multiplication | ++-------------+----------------------------+-----------------------------------+ +| matvec | ``(m,n),(n)->(m)`` | matrix-vector multiplication | ++-------------+----------------------------+-----------------------------------+ +| matmul | ``(m?,n),(n,p?)->(m?,p?)`` | combination of the four above | ++-------------+----------------------------+-----------------------------------+ +| cross1d | ``(3),(3)->(3)`` | cross product where the last | +| | | dimension must be 3 | ++-------------+----------------------------+-----------------------------------+ +| outer_inner | ``(i,t),(j,t)->(i,j)`` | inner over the last dimension, | +| | | outer over the second to last, | +| | | and loop/broadcast over the rest. | ++-------------+----------------------------+-----------------------------------+ C-API for implementing Elementary Functions ------------------------------------------- |