Text of peps.python.org › pep-0465 as Styx crawled it on Nov 20, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 465 – A dedicated infix operator for matrix multiplication | peps.python.org

PEP 465 – A dedicated infix operator for matrix multiplication PEP 465 – A dedicated infix operator for matrix multiplication Author : Nathaniel J. Smith <njs at pobox.com> Status : Final Type : Standards Track Created : 20-Feb-2014 Python-Version : 3.5 Post-History : 13-Mar-2014 Resolution : Python-Dev message Table of Contents Abstract Specification Motivation Executive summary Background: What’s wrong with the status quo?

Why should matrix multiplication be infix? Transparent syntax is especially crucial for non-expert programmers But isn’t matrix multiplication a pretty niche requirement? So @ is good for matrix formulas, but how common are those really? But isn’t it weird to add an operator with no stdlib uses? Compatibility considerations Intended usage details Semantics Adoption Implementation details Rationale for specification details Choice of operator Precedence and associativity (Non)-Definitions for built-in types Non-definition of matrix power Rejected alternatives to adding a new operator Discussions of this PEP References Copyright Abstract This PEP proposes a new binary operator to be used for matrix multiplication, called @ . (Mnemonic: @ is * for mATrices.) Specification A new binary operator is added to the Python language, together with the corresponding in-place version: Op Precedence/associativity Methods @ Same as * __matmul__ , __rmatmul__ @= n/a __imatmul__ No implementations of these methods are added to the builtin or standard library types.

However, a number of projects have reached consensus on the recommended semantics for these operations; see Intended usage details below for details. For details on how this operator will be implemented in CPython, see Implementation details . Motivation Executive summary In numerical code, there are two important operations which compete for use of Python’s * operator: elementwise multiplication, and matrix multiplication.

In the nearly twenty years since the Numeric library was first proposed, there have been many attempts to resolve this tension [13] ; none have been really satisfactory. Currently, most numerical Python code uses * for elementwise multiplication, and function/method syntax for matrix multiplication; however, this leads to ugly and unreadable code in common circumstances. The problem is bad enough that significant amounts of code continue to use the opposite convention (which has the virtue of producing ugly and unreadable code in different circumstances), and this API fragmentation across codebases then creates yet more problems.

There does not seem to be any good solution to the problem of designing a numerical API within current Python syntax – only a landscape of options that are bad in different ways. The minimal change to Python syntax which is sufficient to resolve these problems is the addition of a single new infix operator for matrix multiplication. Matrix multiplication has a singular combination of features which distinguish it from other binary operations, which together provide a uniquely compelling case for the addition of a dedicated infix operator: Just as for the existing numerical operators, there exists a vast body of prior art supporting the use of infix notation for matrix multiplication across all fields of mathematics, science, and engineering; @ harmoniously fills a hole in Python’s existing operator system. @ greatly clarifies real-world code. @ provides a smoother onramp for less experienced users, who are particularly harmed by hard-to-read code and API fragmentation. @ benefits a substantial and growing portion of the Python user community. @ will be used frequently – in fact, evidence suggests it may be used more frequently than // or the bitwise operators. @ allows the Python numerical community to reduce fragmentation, and finally standardize on a single consensus duck type for all numerical array objects.

Background: What’s wrong with the status quo? When we crunch numbers on a computer, we usually have lots and lots of numbers to deal with. Trying to deal with them one at a time is cumbersome and slow – especially when using an interpreted language. Instead, we want the ability to write down simple operations that apply to large collections of numbers all at once. The n-dimensional array is the basic object that all popular numeric computing environments use to make this possible.

Python has several libraries that provide such arrays, with numpy being at present the most prominent. When working with n-dimensional arrays, there are two different ways we might want to define multiplication. One is elementwise multiplication: [[ 1 , 2 ], [[ 11 , 12 ], [[ 1 * 11 , 2 * 12 ], [ 3 , 4 ]] x [ 13 , 14 ]] = [ 3 * 13 , 4 * 14 ]] and the other is matrix multiplication : [[ 1 , 2 ], [[ 11 , 12 ], [[ 1 * 11 + 2 * 13 , 1 * 12 + 2 * 14 ], [ 3 , 4 ]] x [ 13 , 14 ]] = [ 3 * 11 + 4 * 13 , 3 * 12 + 4 * 14 ]] Elementwise multiplication is useful because it lets us easily and quickly perform many multiplications on a large collection of values, without writing a slow and cumbersome for loop.

And this works as part of a very general schema: when using the array objects provided by numpy or other numerical libraries, all Python operators work elementwise on arrays of all dimensionalities. The result is that one can write functions using straightforward code like a * b + c / d , treating the variables as if they were simple values, but then immediately use this function to efficiently perform this calculation on large collections of values, while keeping them organized using whatever arbitrarily complex array layout works best for the problem at hand.

Matrix multiplication is more of a special case. It’s only defined on 2d arrays (also known as “matrices”), and multiplication is the only operation that has an important “matrix” version – “matrix addition” is the same as elementwise addition; there is no such thing as “matrix bitwise-or” or “matrix floordiv”; “matrix division” and “matrix to-the-power-of” can be defined but are not very useful, etc.

However, matrix multiplication is still used very heavily across all numerical application areas; mathematically, it’s one of the most fundamental operations there is. Because Python syntax currently allows for only a single multiplication operator * , libraries providing array-like objects must decide: either use * for elementwise multiplication, or use * for matrix multiplication. And, unfortunately, it turns out that when doing general-purpose number crunching, both operations are used frequently, and there are major advantages to using infix rather than function call syntax in both cases.

Thus it is not at all clear which convention is optimal, or even acceptable; often it varies on a case-by-case basis. Nonetheless, network effects mean that it is very important that we pick just one convention. In numpy, for example, it is technically possible to switch between the conventions, because numpy provides two different types with different __mul__ methods. For numpy.ndarray objects, * performs elementwise multiplication, and matrix multiplication must use a function call ( numpy.dot ).

For numpy.matrix objects, * performs matrix multiplication, and elementwise multiplication requires function syntax. Writing code using numpy.ndarray works fine. Writing code using numpy.matrix also works fine. But trouble begins as soon as we try to integrate these two pieces of code together. Code that expects an ndarray and gets a matrix , or vice-versa, may crash or return incorrect results. Keeping track of which functions expect which types as inputs, and return which types as outputs, and then converting back and forth all the time, is incredibly cumbersome and impossible to get right at any scale.

Functions that defensively try to handle both types as input and DTRT, find themselves floundering into a swamp of isinstance and if statements. PEP 238 split / into two op

The rest of this page is on the live site.