diff --git a/docs/manual/source/conf.py b/docs/manual/source/conf.py index 4a2cea6e..83f03d43 100644 --- a/docs/manual/source/conf.py +++ b/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 --------------------------------------------------- diff --git a/docs/manual/source/numpy-functions.rst b/docs/manual/source/numpy-functions.rst index a2a3e410..252f5a57 100644 --- a/docs/manual/source/numpy-functions.rst +++ b/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 ----- diff --git a/docs/numpy-functions.ipynb b/docs/numpy-functions.ipynb index 2ef884a2..d13278cf 100644 --- a/docs/numpy-functions.ipynb +++ b/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, diff --git a/docs/ulab-change-log.md b/docs/ulab-change-log.md index 9f885936..91f86c28 100644 --- a/docs/ulab-change-log.md +++ b/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 diff --git a/docs/ulab-convert.ipynb b/docs/ulab-convert.ipynb index bd587912..53eba42c 100644 --- a/docs/ulab-convert.ipynb +++ b/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,