<commit_before>.. _arrays.ndarray:

******************************************
The N-dimensional array (:class:`ndarray`)
******************************************

.. currentmodule:: numpy

An :class:`ndarray` is a (usually fixed-size) multidimensional
container of items of the same type and size. The number of dimensions
and items in an array is defined by its :attr:`shape <ndarray.shape>`,
which is a :class:`tuple` of *N* positive integers that specify the
sizes of each dimension. The type of items in the array is specified by
a separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which
is associated with each ndarray.

As with other container objects in Python, the contents of an
:class:`ndarray` can be accessed and modified by :ref:`indexing or
slicing <arrays.indexing>` the array (using, for example, *N* integers),
and via the methods and attributes of the :class:`ndarray`.

.. index:: view, base

Different :class:`ndarrays <ndarray>` can share the same data, so that
changes made in one :class:`ndarray` may be visible in another. That
is, an ndarray can be a *"view"* to another ndarray, and the data it
is referring to is taken care of by the *"base"* ndarray. ndarrays can
also be views to memory owned by Python :class:`strings <str>` or
objects implementing the :class:`buffer` or :ref:`array
<arrays.interface>` interfaces.


.. admonition:: Example

   A 2-dimensional array of size 2 x 3, composed of 4-byte integer
   elements:

   >>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
   >>> type(x)
   <type 'numpy.ndarray'>
   >>> x.shape
   (2, 3)
   >>> x.dtype
   dtype('int32')

   The array can be indexed using Python container-like syntax:

   >>> # The element of x in the *second* row, *third* column, namely, 6.
   >>> x[1, 2]

   For example :ref:`slicing <arrays.indexing>` can produce views of
   the array:

   >>> y = x[:,1]
   >>> y
   array([2, 5])
   >>> y[0] = 9 # this also changes the corresponding element in x
   >>> y
   array([9, 5])
   >>> x
   array([[1, 9, 3],
          [4, 5, 6]])


Constructing arrays
===================

New arrays can be constructed using the routines detailed in
:ref:`routines.array-creation`, and also by using the low-level
:class:`ndarray` constructor:

.. autosummary::
   :toctree: generated/

   ndarray

.. _arrays.ndarray.indexing:


Indexing arrays
===============

Arrays can be indexed using an extended Python slicing syntax,
``array[selection]``.  Similar syntax is also used for accessing
fields in a :ref:`structured array <arrays.dtypes.field>`.

.. seealso:: :ref:`Array Indexing <arrays.indexing>`.

Internal memory layout of an ndarray
====================================

An instance of class :class:`ndarray` consists of a contiguous
one-dimensional segment of computer memory (owned by the array, or by
some other object), combined with an indexing scheme that maps *N*
integers into the location of an item in the block.  The ranges in
which the indices can vary is specified by the :obj:`shape
<ndarray.shape>` of the array. How many bytes each item takes and how
the bytes are interpreted is defined by the :ref:`data-type object
<arrays.dtypes>` associated with the array.

.. index:: C-order, Fortran-order, row-major, column-major, stride,
  offset

A segment of memory is inherently 1-dimensional, and there are many
different schemes for arranging the items of an *N*-dimensional array
in a 1-dimensional block. NumPy is flexible, and :class:`ndarray`
objects can accommodate any *strided indexing scheme*. In a strided
scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})`
corresponds to the offset (in bytes):

.. math:: n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k

from the beginning of the memory block associated with the
array. Here, :math:`s_k` are integers which specify the :obj:`strides
<ndarray.strides>` of the array. The :term:`column-major` order (used,
for example, in the Fortran language and in *Matlab*) and
:term:`row-major` order (used in C) schemes are just specific kinds of
strided scheme, and correspond to memory that can be *addressed* by the strides:

.. math::

   s_k^{\mathrm{column}} = \prod_{j=0}^{k-1} d_j ,
   \quad  s_k^{\mathrm{row}} = \prod_{j=k+1}^{N-1} d_j .

.. index:: single-segment, contiguous, non-contiguous

where :math:`d_j` `= self.itemsize * self.shape[j]`.

Both the C and Fortran orders are :term:`contiguous`, *i.e.,*
:term:`single-segment`, memory layouts, in which every part of the
memory block can be accessed by some combination of the indices.

While a C-style and Fortran-style contiguous array, which has the corresponding
flags set, can be addressed with the above strides, the actual strides may be
different. This can happen in two cases:

    1. If ``self.shape[k] == 1`` then for any legal index ``index[k] == 0``.
       This means that in the formula for the offset :math:`n_k = 0` and thus
       :math:`s_k n_k = 0` and the value of :math:`s_k` `= self.strides[k]` is
       arbitrary.<commit_msg>Update arrays.ndarray.rst<commit_after>.. _arrays.ndarray:

******************************************
The N-dimensional array (:class:`ndarray`)
******************************************

.. currentmodule:: numpy

An :class:`ndarray` is a (usually fixed-size) multidimensional
container of items of the same type and size. The number of dimensions
and items in an array is defined by its :attr:`shape <ndarray.shape>`,
which is a :class:`tuple` of *N* positive integers that specify the
sizes of each dimension. The type of items in the array is specified by
a separate :ref:`data-type object (dtype) <arrays.dtypes>`, one of which
is associated with each ndarray.

As with other container objects in Python, the contents of an
:class:`ndarray` can be accessed and modified by :ref:`indexing or
slicing <arrays.indexing>` the array (using, for example, *N* integers),
and via the methods and attributes of the :class:`ndarray`.

.. index:: view, base

Different :class:`ndarrays <ndarray>` can share the same data, so that
changes made in one :class:`ndarray` may be visible in another. That
is, an ndarray can be a *"view"* to another ndarray, and the data it
is referring to is taken care of by the *"base"* ndarray. ndarrays can
also be views to memory owned by Python :class:`strings <str>` or
objects implementing the :class:`buffer` or :ref:`array
<arrays.interface>` interfaces.


.. admonition:: Example

   A 2-dimensional array of size 2 x 3, composed of 4-byte integer
   elements:

   >>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
   >>> type(x)
   <type 'numpy.ndarray'>
   >>> x.shape
   (2, 3)
   >>> x.dtype
   dtype('int32')

   The array can be indexed using Python container-like syntax:

   >>> # The element of x in the *second* row, *third* column, namely, 6.
   >>> x[1, 2]

   For example :ref:`slicing <arrays.indexing>` can produce views of
   the array:

   >>> y = x[:,1]
   >>> y
   array([2, 5])
   >>> y[0] = 9 # this also changes the corresponding element in x
   >>> y
   array([9, 5])
   >>> x
   array([[1, 9, 3],
          [4, 5, 6]])


Constructing arrays
===================

New arrays can be constructed using the routines detailed in
:ref:`routines.array-creation`, and also by using the low-level
:class:`ndarray` constructor:

.. autosummary::
   :toctree: generated/

   ndarray

.. _arrays.ndarray.indexing:


Indexing arrays
===============

Arrays can be indexed using an extended Python slicing syntax,
``array[selection]``.  Similar syntax is also used for accessing
fields in a :ref:`structured array <arrays.dtypes.field>`.

.. seealso:: :ref:`Array Indexing <arrays.indexing>`.

Internal memory layout of an ndarray
====================================

An instance of class :class:`ndarray` consists of a contiguous
one-dimensional segment of computer memory (owned by the array, or by
some other object), combined with an indexing scheme that maps *N*
integers into the location of an item in the block.  The ranges in
which the indices can vary is specified by the :obj:`shape
<ndarray.shape>` of the array. How many bytes each item takes and how
the bytes are interpreted is defined by the :ref:`data-type object
<arrays.dtypes>` associated with the array.

.. index:: C-order, Fortran-order, row-major, column-major, stride,
  offset

A segment of memory is inherently 1-dimensional, and there are many
different schemes for arranging the items of an *N*-dimensional array
in a 1-dimensional block. NumPy is flexible, and :class:`ndarray`
objects can accommodate any *strided indexing scheme*. In a strided
scheme, the N-dimensional index :math:`(n_0, n_1, ..., n_{N-1})`
corresponds to the offset (in bytes):

.. math:: n_{\mathrm{offset}} = \mathrm{itemsize} \sum_{k=0}^{N-1} s_k n_k

from the beginning of the memory block associated with the
array. Here, :math:`s_k` are integers which specify the :obj:`strides
<ndarray.strides>` of the array. The :term:`column-major` order (used,
for example, in the Fortran language and in *Matlab*) and
:term:`row-major` order (used in C) schemes are just specific kinds of
strided scheme, and correspond to memory that can be *addressed* by the strides:

.. math::

   s_k^{\mathrm{column}} = \prod_{j=0}^{k-1} d_j ,
   \quad  s_k^{\mathrm{row}} = \prod_{j=k+1}^{N-1} d_j .

.. index:: single-segment, contiguous, non-contiguous

where :math:`d_j` `= self.shape[j]`.

Both the C and Fortran orders are :term:`contiguous`, *i.e.,*
:term:`single-segment`, memory layouts, in which every part of the
memory block can be accessed by some combination of the indices.

While a C-style and Fortran-style contiguous array, which has the corresponding
flags set, can be addressed with the above strides, the actual strides may be
different. This can happen in two cases:

    1. If ``self.shape[k] == 1`` then for any legal index ``index[k] == 0``.
       This means that in the formula for the offset :math:`n_k = 0` and thus
       :math:`s_k n_k = 0` and the value of :math:`s_k` `= self.strides[k]` is
       arbitrary.
{'fraction_non_alphanumeric': 0.14270043877143998, 'fraction_numerical': 0.009573195053849222, 'mean_word_length': 4.177594217862675, 'pattern_counts': {'":': 0, '<': 29, '<?xml version=': 0, '>': 95, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5093723', 'n_tokens_mistral': 3138, 'n_tokens_neox': 2956, 'n_words': 1312}