<p>In-place operations must be supported as discussed in <a class="reference internal" href="../design_topics/copies_views_and_mutation.html#copyview-mutability"><span class="std std-ref">Copy-view behavior and mutability</span></a>.</p>

function must always copy (performed by the producer; see also <a class="reference internal" href="../../design_topics/copies_views_and_mutation.html#copy-keyword-argument"><span class="std std-ref">Copy keyword argument behavior</span></a>). If <code class="docutils literal notranslate"><span class="pre">False</span></code>, the

<li><p><strong>copy</strong> (<em>Optional</em><em>[</em><em>bool</em><em>]</em>) – boolean indicating whether or not to copy the input. If <code class="docutils literal notranslate"><span class="pre">True</span></code>, the function must always copy (see <a class="reference internal" href="../../design_topics/copies_views_and_mutation.html#copy-keyword-argument"><span class="std std-ref">Copy keyword argument behavior</span></a>). If <code class="docutils literal notranslate"><span class="pre">False</span></code>, the function must never copy for input which supports the buffer protocol and must raise a <code class="docutils literal notranslate"><span class="pre">ValueError</span></code> in case a copy would be necessary. If <code class="docutils literal notranslate"><span class="pre">None</span></code>, the function must reuse existing memory buffer if possible and copy otherwise. Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>

<li><p><strong>copy</strong> (<em>bool</em>) – specifies whether to copy an array when the specified <code class="docutils literal notranslate"><span class="pre">dtype</span></code> matches the data type of the input array <code class="docutils literal notranslate"><span class="pre">x</span></code>. If <code class="docutils literal notranslate"><span class="pre">True</span></code>, a newly allocated array must always be returned (see <a class="reference internal" href="../../design_topics/copies_views_and_mutation.html#copy-keyword-argument"><span class="std std-ref">Copy keyword argument behavior</span></a>). If <code class="docutils literal notranslate"><span class="pre">False</span></code> and the specified <code class="docutils literal notranslate"><span class="pre">dtype</span></code> matches the data type of the input array, the input array must be returned; otherwise, a newly allocated array must be returned. Default: <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p></li>

<li><p><strong>copy</strong> (<em>Optional</em><em>[</em><em>bool</em><em>]</em>) – whether or not to copy the input array. If <code class="docutils literal notranslate"><span class="pre">True</span></code>, the function must always copy (see <a class="reference internal" href="../../design_topics/copies_views_and_mutation.html#copy-keyword-argument"><span class="std std-ref">Copy keyword argument behavior</span></a>). If <code class="docutils literal notranslate"><span class="pre">False</span></code>, the function must never copy. If <code class="docutils literal notranslate"><span class="pre">None</span></code>, the function must avoid copying, if possible, and may copy otherwise. Default: <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p></li>

Copy-view behavior and mutability

belongs to another array (i.e., a different "view" on the original data).

Views are useful for performance reasons—not copying data to a new location

saves memory and is faster than copying—but can also affect the semantics

The following example is illustrative:

Code similar to the above example will not be portable between array

libraries. For example, for NumPy, PyTorch, and CuPy, ``x`` will contain the value ``0``,

while, for TensorFlow, JAX, and Dask, ``x`` will contain the value ``1``. In

this case, the combination of views and mutability is fundamentally problematic

if the goal is to be able to write code with unambiguous semantics.

array libraries. It is not always clear, however, when a library will return a

view and when it will return a copy. This standard does not attempt to

specify this—libraries may do either.

There are several types of operations that may perform in-place mutation of

array data. These include:

1. In-place operators (e.g. ``*=``)

Libraries such as TensorFlow and JAX tend to support in-place operators by providing

function or ``x.at[idx].set(y)``) and have no need for ``out=``.

A potential solution could be to make views read-only or implement copy-on-write

semantics. Both are hard to implement and would present significant backward

compatibility issues for current strided array libraries. Read-only

views would also not be a full solution due to the fact that mutating the original

(base) array will also result in ambiguous semantics. Accordingly, this standard

does not attempt to pursue this solution.

Both in-place operators and item/slice assignment can be mapped onto

``x.at[idx].set(val)``), and, given that both in-place operators and item/slice

The situation with ``out=`` is slightly different—it's less heavily used, and

easier to avoid. It's also not an optimal API because it mixes an

in-place") with the semantics of a function ("the output _must_ be placed into

this array"). There are libraries that do some form of tracing or abstract

interpretation over a vocabulary that does not support mutation (to make

analysis easier). In those cases implementing ``out=`` with correct handling of

views may even be impossible to do.

There are alternatives. For example, the concept of donated arguments in JAX or

working buffers in LAPACK which allow the user to express "you _may_ overwrite

this data; do whatever is fastest". Given that those alternatives aren't widely

used in array libraries today, this standard chooses to (a) leave out ``out=``,

and (b) not specify another method of reusing arrays that are no longer needed

as buffers.

This leaves the problem of the initial example—despite the best efforts of this

standard, it remains possible to write code that will not work the same for all

array libraries. This is something that the users are advised to best keep in

mind and to reason carefully about the potential ambiguity of implemented code.

.. _copy-keyword-argument:

Copy keyword argument behavior

Several APIs in this standard support a ``copy`` keyword argument (e.g.,

``asarray``, ``astype``, ``reshape``, and ``__dlpack__``). Typically, when a

user sets ``copy=True``, the user does so in order to ensure that they are free

to mutate the returned array without side-effects—namely, without mutating other

views on the original (base) array. Accordingly, when ``copy=True``, unless an

array library can guarantee that an array can be mutated without side-effects,

conforming libraries are recommended to always perform a physical copy of the

underlying array data.

.. note::

Typically, in order to provide such a guarantee, libraries must perform

whole-program analysis.

Conversely, consumers of this standard should expect that, if they set

``copy=True``, they are free to use in-place operations on a returned array.

<a href="copies_views_and_mutation.html" class="md-nav__link">Copy-view behavior and mutability</a>

<a href="copies_views_and_mutation.html" class="md-nav__link">Copy-view behavior and mutability</a>

<a href="copies_views_and_mutation.html" class="md-nav__link">Copy-view behavior and mutability</a>