from multiarray
def matmul(a, b, out=None):
"""
matmul(a, b, out=None)
Matrix product of two arrays.
两个数组的矩阵乘积。
The behavior depends on the arguments in the following way.
行为取决于以下列方式呈现的参数。
- If both arguments are 2-D they are multiplied like conventional
matrices.
如果两个参数都是二维的，它们将像常规矩阵一样相乘。
- If either argument is N-D, N > 2, it is treated as a stack of
matrices residing in the last two indexes and broadcast accordingly.
如果任一自变量为N维，N> 2，则将其视为位于最后两个索引中的矩阵堆栈，并进行相应广播。
- If the first argument is 1-D, it is promoted to a matrix by
prepending a 1 to its dimensions. After matrix multiplication
the prepended 1 is removed.
如果第一个参数是1维，则通过在其尺寸前面加1来将其提升为矩阵。 矩阵相乘后，除去前面的1。
- If the second argument is 1-D, it is promoted to a matrix by
appending a 1 to its dimensions. After matrix multiplication
the appended 1 is removed.
如果第二个参数是1-D，则通过在其维数后附加1来将其提升为矩阵。
矩阵相乘后，将附加的1删除。
Multiplication by a scalar is not allowed, use ``*`` instead. Note that
multiplying a stack of matrices with a vector will result in a stack of
vectors, but matmul will not recognize it as such.
不允许与标量相乘，请改用``*''。 请注意，将一堆矩阵与一个向量相乘会得到一堆向量，
但是matmul不会这样识别。
``matmul`` differs from ``dot`` in two important ways.
``matmul''与``dot''在两个重要方面不同。
- Multiplication by scalars is not allowed.
- Stacks of matrices are broadcast together as if the matrices
were elements.
标量不能相乘。
将矩阵堆栈一起广播，就好像矩阵是元素一样。
.. warning::
This function is preliminary and included in NumPy 1.10.0 for testing
and documentation. Its semantics will not change, but the number and
order of the optional arguments will.
此功能是初步功能，已包含在NumPy 1.10.0中以进行测试和记录。
它的语义不会改变，但是可选参数的数量和顺序会改变。
.. versionadded:: 1.10.0
Parameters
----------
a : array_like
First argument.
b : array_like
Second argument.
out : ndarray, optional
Output argument. This must have the exact kind that would be returned
if it was not used. In particular, it must have the right type, must be
C-contiguous, and its dtype must be the dtype that would be returned
for `dot(a,b)`. This is a performance feature. Therefore, if these
conditions are not met, an exception is raised, instead of attempting
to be flexible.
输出参数。 如果没有使用，它必须具有返回的确切类型。
特别是，它必须具有正确的类型，必须是C连续的，并且它的dtype必须是为dot（a，b）返回的dtype。
这是一项性能功能。 因此，如果不满足这些条件，则会引发异常，而不是尝试变得灵活。
Returns
-------
output : ndarray
Returns the dot product of `a` and `b`. If `a` and `b` are both
1-D arrays then a scalar is returned; otherwise an array is
returned. If `out` is given, then it is returned.
返回“ a”和“ b”的点积。 如果a和b都是一维数组，则返回标量；
否则返回一个数组。 如果给出`out`，则返回它。
Raises
------
ValueError
If the last dimension of `a` is not the same size as
the second-to-last dimension of `b`.
如果a的最后一个尺寸与b的倒数第二个尺寸不同。
If scalar value is passed.
See Also
--------
vdot : Complex-conjugating dot product.
tensordot : Sum products over arbitrary axes.
einsum : Einstein summation convention.
dot : alternative matrix product with different broadcasting rules.
Notes
-----
The matmul function implements the semantics of the `@` operator introduced
in Python 3.5 following PEP465.
Examples
--------
For 2-D arrays it is the matrix product:
>>> a = [[1, 0], [0, 1]]
>>> b = [[4, 1], [2, 2]]
>>> np.matmul(a, b)
array([[4, 1],
[2, 2]])
For 2-D mixed with 1-D, the result is the usual.
>>> a = [[1, 0], [0, 1]]
>>> b = [1, 2]
>>> np.matmul(a, b)
array([1, 2])
>>> np.matmul(b, a)
array([1, 2])
Broadcasting is conventional for stacks of arrays
>>> a = np.arange(2*2*4).reshape((2,2,4))
>>> b = np.arange(2*2*4).reshape((2,4,2))
>>> np.matmul(a,b).shape
(2, 2, 2)
>>> np.matmul(a,b)[0,1,1]
98
>>> sum(a[0,1,:] * b[0,:,1])
98
Vector, vector returns the scalar inner product, but neither argument
is complex-conjugated:
>>> np.matmul([2j, 3j], [2j, 3j])
(-13+0j)
Scalar multiplication raises an error.
>>> np.matmul([1,2], 3)
Traceback (most recent call last):
...
ValueError: Scalar operands are not allowed, use '*' instead
"""
pass
