ENH: Generalized ufunc signature expansion for frozen and flexible dimensions by mhvk · Pull Request #11175 · numpy/numpy (original) (raw)
@@ -127,38 +127,56 @@ The formal syntax of signatures is as follows::
::=
::= nil | | ","
::= "(" ")"
::= nil | |
","
::= valid Python variable name
::= nil | |
","
::=
::= valid Python variable name | valid integer
::= 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 | ``(),()->()`` | |
+-------------+------------------------+-----------------------------------+
| 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 |
+-------------+------------------------+-----------------------------------+
| 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. |
+-------------+------------------------+-----------------------------------+
+-------------+----------------------------+-----------------------------------+
| name | signature | common usage |
+=============+============================+===================================+
| add | ``(),()->()`` | binary ufunc |
+-------------+----------------------------+-----------------------------------+
| sum1d | ``(i)->()`` | reduction |
+-------------+----------------------------+-----------------------------------+
| inner1d | ``(i),(i)->()`` | vector-vector multiplication |
+-------------+----------------------------+-----------------------------------+
| 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 |
+-------------+----------------------------+-----------------------------------+
| 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. |
+-------------+----------------------------+-----------------------------------+
| cross1d | ``(3),(3)->(3)`` | cross product where the last |
| | | dimension is frozen and must be 3 |
+-------------+----------------------------+-----------------------------------+
.. _frozen:
The last is an instance of freezing a core dimension and can be used to
improve ufunc performance
C-API for implementing Elementary Functions
-------------------------------------------