add take documentation, update change log

docs/manual/source/conf.py

@@ -27,7 +27,7 @@
 author = 'Zoltán Vörös'
 
 # The full version, including alpha/beta/rc tags
-release = '6.5.0'
+release = '6.6.0'
 
 
 # -- General configuration ---------------------------------------------------

docs/manual/source/numpy-functions.rst

@@ -3,8 +3,8 @@ Numpy functions
 ===============
 
 This section of the manual discusses those functions that were adapted
-from ``numpy``. Starred functions accept complex arrays as arguments, if
-the firmware was compiled with complex support.
+from ``numpy``. Functions with an asterisk accept complex arrays as
+arguments, if the firmware was compiled with complex support.
 
 1.  `numpy.all\* <#all>`__
 2.  `numpy.any\* <#any>`__
@@ -51,9 +51,10 @@ the firmware was compiled with complex support.
 43. `numpy.sort_complex\* <#sort_complex>`__
 44. `numpy.std <#std>`__
 45. `numpy.sum <#sum>`__
-46. `numpy.trace <#trace>`__
-47. `numpy.trapz <#trapz>`__
-48. `numpy.where <#where>`__
+46. `numpy.take\* <#take>`__
+47. `numpy.trace <#trace>`__
+48. `numpy.trapz <#trapz>`__
+49. `numpy.where <#where>`__
 
 all
 ---
@@ -1985,6 +1986,66 @@ array. Otherwise, the calculation is along the given axis.
     
 
 
+take
+----
+
+``numpy``:
+https://numpy.org/doc/stable/reference/generated/numpy.take.html
+
+The ``take`` method takes elements from an array along an axis. The
+function accepts two positional arguments, the array, and the indices,
+which is either a ``python`` iterable, or a one-dimensional ``ndarray``,
+as well as three keyword arguments, the ``axis``, which can be ``None``,
+or an integer, ``out``, which can be ``None``, or an ``ndarray`` with
+the proper dimensions, and ``mode``, which can be one of the strings
+``raise``, ``wrap``, or ``clip``. This last argument determines how
+out-of-bounds indices will be treated. The default value is ``raise``,
+which raises an exception. ``wrap`` takes the indices modulo the length
+of the ``axis``, while ``clip`` pegs the values at the 0, and the length
+of the ``axis``. If ``axis`` is ``None``, then ``take`` operates on the
+flattened array.
+
+The function can be regarded as a method of advanced slicing: as opposed
+to standard slicing, where the indices are distributed uniformly and in
+either increasing or decreasing order, ``take`` can take indices in an
+arbitrary order.
+
+.. code::
+        
+    # code to be run in micropython
+    
+    from ulab import numpy as np
+    
+    a = np.array(range(12)).reshape((3, 4))
+    print('\na:', a)
+    
+    print('\nslices taken along first axis')
+    print(np.take(a, (0, 2, 2, 1), axis=0))
+    
+    print('\nslices taken along second axis')
+    print(np.take(a, (0, 2, 2, 1), axis=1))
+
+.. parsed-literal::
+
+    
+    a: array([[0.0, 1.0, 2.0, 3.0],
+           [4.0, 5.0, 6.0, 7.0],
+           [8.0, 9.0, 10.0, 11.0]], dtype=float64)
+    
+    slices taken along first axis
+    array([[0.0, 1.0, 2.0, 3.0],
+           [8.0, 9.0, 10.0, 11.0],
+           [8.0, 9.0, 10.0, 11.0],
+           [4.0, 5.0, 6.0, 7.0]], dtype=float64)
+    
+    slices taken along second axis
+    array([[0.0, 2.0, 2.0, 1.0],
+           [2.0, 3.0, 4.0, 5.0],
+           [6.0, 7.0, 8.0, 9.0]], dtype=float64)
+    
+    
+
+
 trace
 -----
 

docs/numpy-functions.ipynb

@@ -31,7 +31,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 1,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2022-02-01T17:37:25.505687Z",
@@ -49,7 +49,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 2,
    "metadata": {
     "ExecuteTime": {
      "end_time": "2022-02-01T17:37:25.717714Z",
@@ -230,7 +230,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This section of the manual discusses those functions that were adapted from `numpy`. Starred functions accept complex arrays as arguments, if the firmware was compiled with complex support.\n",
+    "This section of the manual discusses those functions that were adapted from `numpy`. Functions with an asterisk accept complex arrays as arguments, if the firmware was compiled with complex support.\n",
     "\n",
     "1. [numpy.all*](#all)\n",
     "1. [numpy.any*](#any)\n",
@@ -277,6 +277,7 @@
     "1. [numpy.sort_complex*](#sort_complex)\n",
     "1. [numpy.std](#std)\n",
     "1. [numpy.sum](#sum)\n",
+    "1. [numpy.take*](#take)\n",
     "1. [numpy.trace](#trace)\n",
     "1. [numpy.trapz](#trapz)\n",
     "1. [numpy.where](#where)"
@@ -2682,6 +2683,63 @@
     "print('std, vertical: ', np.sum(a, axis=0))"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## take\n",
+    "\n",
+    "`numpy`: https://numpy.org/doc/stable/reference/generated/numpy.take.html\n",
+    "\n",
+    "The `take` method takes elements from an array along an axis. The function accepts two positional arguments, the array, and the indices, which is either a `python` iterable, or a one-dimensional `ndarray`, as well as three keyword arguments, the `axis`, which can be `None`, or an integer, `out`, which can be `None`, or an `ndarray` with the proper dimensions, and `mode`, which can be one of the strings `raise`, `wrap`, or `clip`. This last argument determines how out-of-bounds indices will be treated. The default value is `raise`, which raises an exception. `wrap` takes the indices modulo the length of the `axis`, while `clip` pegs the values at the 0, and the length of the `axis`. If `axis` is `None`, then `take` operates on the flattened array.\n",
+    "\n",
+    "The function can be regarded as a method of advanced slicing: as opposed to standard slicing, where the indices are distributed uniformly and in either increasing or decreasing order, `take` can take indices in an arbitrary order."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "a: array([[0.0, 1.0, 2.0, 3.0],\n",
+      "       [4.0, 5.0, 6.0, 7.0],\n",
+      "       [8.0, 9.0, 10.0, 11.0]], dtype=float64)\n",
+      "\n",
+      "slices taken along first axis\n",
+      "array([[0.0, 1.0, 2.0, 3.0],\n",
+      "       [8.0, 9.0, 10.0, 11.0],\n",
+      "       [8.0, 9.0, 10.0, 11.0],\n",
+      "       [4.0, 5.0, 6.0, 7.0]], dtype=float64)\n",
+      "\n",
+      "slices taken along second axis\n",
+      "array([[0.0, 2.0, 2.0, 1.0],\n",
+      "       [2.0, 3.0, 4.0, 5.0],\n",
+      "       [6.0, 7.0, 8.0, 9.0]], dtype=float64)\n",
+      "\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "%%micropython -unix 1\n",
+    "\n",
+    "from ulab import numpy as np\n",
+    "\n",
+    "a = np.array(range(12)).reshape((3, 4))\n",
+    "print('\\na:', a)\n",
+    "\n",
+    "print('\\nslices taken along first axis')\n",
+    "print(np.take(a, (0, 2, 2, 1), axis=0))\n",
+    "\n",
+    "print('\\nslices taken along second axis')\n",
+    "print(np.take(a, (0, 2, 2, 1), axis=1))\n"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -2900,7 +2958,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.11.7"
   },
   "toc": {
    "base_numbering": 1,

docs/ulab-change-log.md

@@ -1,3 +1,9 @@
+Tue, 8 Oct 2024
+
+version 6.6.0
+
+    add numpy.take
+
 Wed, 6 Mar 2024
 
 version 6.5.2

docs/ulab-convert.ipynb

@@ -57,11 +57,11 @@
     "# -- Project information -----------------------------------------------------\n",
     "\n",
     "project = 'The ulab book'\n",
-    "copyright = '2019-2022, Zoltán Vörös and contributors'\n",
+    "copyright = '2019-2024, Zoltán Vörös and contributors'\n",
     "author = 'Zoltán Vörös'\n",
     "\n",
     "# The full version, including alpha/beta/rc tags\n",
-    "release = '5.1.0'\n",
+    "release = '6.6.0'\n",
     "\n",
     "\n",
     "# -- General configuration ---------------------------------------------------\n",
@@ -263,7 +263,40 @@
      "start_time": "2022-02-09T06:27:36.109093Z"
     }
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n",
+      "/home/v923z/anaconda3/lib/python3.11/site-packages/nbconvert/exporters/exporter.py:349: MissingIDFieldWarning: Code cell is missing an id field, this will become a hard error in future nbformat versions. You may want to use `normalize()` on your notebooks before validations (available since nbformat 5.1.4). Previous versions of nbformat are fixing this issue transparently, and will stop doing so in the future.\n",
+      "  _, nbc = validator.normalize(nbc)\n"
+     ]
+    }
+   ],
    "source": [
     "files = ['ulab-intro',\n",
     "         'ulab-ndarray',\n",
@@ -449,7 +482,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.5"
+   "version": "3.11.7"
   },
   "toc": {
    "base_numbering": 1,