"""
========
Glossary
========

.. glossary::

   along an axis
       Axes are defined for arrays with more than one dimension.  A
       2-dimensional array has two corresponding axes: the first running
       vertically downwards across rows (axis 0), and the second running
       horizontally across columns (axis 1).

       Many operations can take place along one of these axes.  For example,
       we can sum each row of an array, in which case we operate along
       columns, or axis 1::

         >>> x = np.arange(12).reshape((3,4))

         >>> x
         array([[ 0,  1,  2,  3],
                [ 4,  5,  6,  7],
                [ 8,  9, 10, 11]])

         >>> x.sum(axis=1)
         array([ 6, 22, 38])

   array
       A homogeneous container of numerical elements.  Each element in the
       array occupies a fixed amount of memory (hence homogeneous), and
       can be a numerical element of a single type (such as float, int
       or complex) or a combination (such as ``(float, int, float)``).  Each
       array has an associated data-type (or ``dtype``), which describes
       the numerical type of its elements::

         >>> x = np.array([1, 2, 3], float)

         >>> x
         array([ 1.,  2.,  3.])

         >>> x.dtype # floating point number, 64 bits of memory per element
         dtype('float64')


         # More complicated data type: each array element is a combination of
         # and integer and a floating point number
         >>> np.array([(1, 2.0), (3, 4.0)], dtype=[('x', int), ('y', float)])
         array([(1, 2.0), (3, 4.0)],
               dtype=[('x', '<i4'), ('y', '<f8')])

       Fast element-wise operations, called a :term:`ufunc`, operate on arrays.

   array_like
       Any sequence that can be interpreted as an ndarray.  This includes
       nested lists, tuples, scalars and existing arrays.

   attribute
       A property of an object that can be accessed using ``obj.attribute``,
       e.g., ``shape`` is an attribute of an array::

         >>> x = np.array([1, 2, 3])
         >>> x.shape
         (3,)

   big-endian
       When storing a multi-byte value in memory as a sequence of bytes, the
       sequence addresses/sends/stores the most significant byte first (lowest
       address) and the least significant byte last (highest address). Common in
       micro-processors and used for transmission of data over network protocols.

   BLAS
       `Basic Linear Algebra Subprograms <https://en.wikipedia.org/wiki/Basic_Linear_Algebra_Subprograms>`_

   broadcast
       NumPy can do operations on arrays whose shapes are mismatched::

         >>> x = np.array([1, 2])
         >>> y = np.array([[3], [4]])

         >>> x
         array([1, 2])

         >>> y
         array([[3],
                [4]])

         >>> x + y
         array([[4, 5],
                [5, 6]])

       See `numpy.doc.broadcasting` for more information.

   C order
       See `row-major`

   column-major
       A way to represent items in a N-dimensional array in the 1-dimensional
       computer memory. In column-major order, the leftmost index "varies the
       fastest": for example the array::

            [[1, 2, 3],
             [4, 5, 6]]

       is represented in the column-major order as::

           [1, 4, 2, 5, 3, 6]

       Column-major order is also known as the Fortran order, as the Fortran
       programming language uses it.

   decorator
       An operator that transforms a function.  For example, a ``log``
       decorator may be defined to print debugging information upon
       function execution::

         >>> def log(f):
         ...     def new_logging_func(*args, **kwargs):
         ...         print("Logging call with parameters:", args, kwargs)
         ...         return f(*args, **kwargs)
         ...
         ...     return new_logging_func

       Now, when we define a function, we can "decorate" it using ``log``::

         >>> @log
         ... def add(a, b):
         ...     return a + b

       Calling ``add`` then yields:

       >>> add(1, 2)
       Logging call with parameters: (1, 2) {}
       3

   dictionary
       Resembling a language dictionary, which provides a mapping between
       words and descriptions thereof, a Python dictionary is a mapping
       between two objects::

         >>> x = {1: 'one', 'two': [1, 2]}

       Here, `x` is a dictionary mapping keys to values, in this case
       the integer 1 to the string "one", and the string "two" to
       the list ``[1, 2]``.  The values may be accessed using their
       corresponding keys::

         >>> x[1]
         'one'

         >>> x['two']
         [1, 2]

       Note that dictionaries are not stored in any specific order.  Also,
       most mutable (see *immutable* below) objects, such as lists, may not
       be used as keys.

       For more information on dictionaries, read the
       `Python tutorial <https://docs.python.org/tutorial/>`_.

   field
       In a :term:`structured data type`, each sub-type is called a `field`.
       The `field` has a name (a string), a type (any valid dtype), and
       an optional `title`. See :ref:`arrays.dtypes`

   Fortran order
       See `column-major`

   flattened
       Collapsed to a one-dimensional array. See `numpy.ndarray.flatten`
       for details.

   homogenous
       Describes a block of memory comprised of blocks, each block comprised of 
       items and of the same size, and blocks are interpreted in exactly the
       same way. In the simplest case each block contains a single item, for
       instance int32 or float64.

   immutable
       An object that cannot be modified after execution is called
       immutable.  Two common examples are strings and tuples.

   instance
       A class definition gives the blueprint for constructing an object::

         >>> class House:
         ...     wall_colour = 'white'

       Yet, we have to *build* a house before it exists::

         >>> h = House() # build a house

       Now, ``h`` is called a ``House`` instance.  An instance is therefore
       a specific realisation of a class.

   iterable
       A sequence that allows "walking" (iterating) over items, typically
       using a loop such as::

         >>> x = [1, 2, 3]
         >>> [item**2 for item in x]
         [1, 4, 9]

       It is often used in combination with ``enumerate``::
         >>> keys = ['a','b','c']
         >>> for n, k in enumerate(keys):
         ...     print("Key %d: %s" % (n, k))
         ...
         Key 0: a
         Key 1: b
         Key 2: c

   itemsize
       The size of the dtype element in bytes.

   list
       A Python container that can hold any number of objects or items.
       The items do not have to be of the same type, and can even be
       lists themselves::

         >>> x = [2, 2.0, "two", [2, 2.0]]

       The list `x` contains 4 items, each which can be accessed individually::

         >>> x[2] # the string 'two'
         'two'

         >>> x[3] # a list, containing an integer 2 and a float 2.0
         [2, 2.0]

       It is also possible to select more than one item at a time,
       using *slicing*::

         >>> x[0:2] # or, equivalently, x[:2]
         [2, 2.0]

       In code, arrays are often conveniently expressed as nested lists::


         >>> np.array([[1, 2], [3, 4]])
         array([[1, 2],
                [3, 4]])

       For more information, read the section on lists in the `Python
       tutorial <https://docs.python.org/tutorial/>`_.  For a mapping
       type (key-value), see *dictionary*.

   little-endian
       When storing a multi-byte value in memory as a sequence of bytes, the
       sequence addresses/sends/stores the least significant byte first (lowest
       address) and the most significant byte last (highest address). Common in
       x86 processors.

   mask
       A boolean array, used to select only certain elements for an operation::

         >>> x = np.arange(5)
         >>> x
         array([0, 1, 2, 3, 4])

         >>> mask = (x > 2)
         >>> mask
         array([False, False, False, True,  True])

         >>> x[mask] = -1
         >>> x
         array([ 0,  1,  2,  -1, -1])

   masked array
       Array that suppressed values indicated by a mask::

         >>> x = np.ma.masked_array([np.nan, 2, np.nan], [True, False, True])
         >>> x
         masked_array(data = [-- 2.0 --],
                      mask = [ True False  True],
                fill_value = 1e+20)

         >>> x + [1, 2, 3]
         masked_array(data = [-- 4.0 --],
                      mask = [ True False  True],
                fill_value = 1e+20)


       Masked arrays are often used when operating on arrays containing
       missing or invalid entries.

   matrix
       A 2-dimensional ndarray that preserves its two-dimensional nature
       throughout operations.  It has certain special operations, such as ``*``
       (matrix multiplication) and ``**`` (matrix power), defined::

         >>> x = np.mat([[1, 2], [3, 4]])
         >>> x
         matrix([[1, 2],
                 [3, 4]])

         >>> x**2
         matrix([[ 7, 10],
               [15, 22]])

   method
       A function associated with an object.  For example, each ndarray has a
       method called ``repeat``::

         >>> x = np.array([1, 2, 3])
         >>> x.repeat(2)
         array([1, 1, 2, 2, 3, 3])

   ndarray
       See *array*.

   record array
       An :term:`ndarray` with :term:`structured data type` which has been
       subclassed as ``np.recarray`` and whose dtype is of type ``np.record``,
       making the fields of its data type to be accessible by attribute.

   reference
       If ``a`` is a reference to ``b``, then ``(a is b) == True``.  Therefore,
       ``a`` and ``b`` are different names for the same Python object.

   row-major
       A way to represent items in a N-dimensional array in the 1-dimensional
       computer memory. In row-major order, the rightmost index "varies
       the fastest": for example the array::

            [[1, 2, 3],
             [4, 5, 6]]

       is represented in the row-major order as::

           [1, 2, 3, 4, 5, 6]

       Row-major order is also known as the C order, as the C programming
       language uses it. New NumPy arrays are by default in row-major order.

   self
       Often seen in method signatures, ``self`` refers to the instance
       of the associated class.  For example:

         >>> class Paintbrush:
         ...     color = 'blue'
         ...
         ...     def paint(self):
         ...         print("Painting the city %s!" % self.color)
         ...
         >>> p = Paintbrush()