Skip to content

Commit

Permalink
update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@v923z
v923z committed Jan 13, 2024
1 parent 208adb2 commit c19f9c8
Show file tree
Hide file tree
Showing 10 changed files with 823 additions and 60 deletions.
10 changes: 7 additions & 3 deletions code/numpy/vector.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -609,9 +609,6 @@ static mp_obj_t vector_exp(mp_obj_t o_in) {
mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
mp_obj_t o_in = args[0].u_obj;
mp_obj_t out = args[1].u_obj;
if(out != mp_const_none) {
mp_raise_ValueError(MP_ERROR_TEXT("out keyword is not supported for complex dtype"));
}
#endif /* ULAB_MATH_FUNCTIONS_OUT_KEYWORD */

if(mp_obj_is_type(o_in, &mp_type_complex)) {
Expand All @@ -621,6 +618,13 @@ static mp_obj_t vector_exp(mp_obj_t o_in) {
return mp_obj_new_complex(exp_real * MICROPY_FLOAT_C_FUN(cos)(imag), exp_real * MICROPY_FLOAT_C_FUN(sin)(imag));
} else if(mp_obj_is_type(o_in, &ulab_ndarray_type)) {
ndarray_obj_t *source = MP_OBJ_TO_PTR(o_in);

#if ULAB_MATH_FUNCTIONS_OUT_KEYWORD
if((out != mp_const_none) && (source->dtype == NDARRAY_COMPLEX)){
mp_raise_ValueError(MP_ERROR_TEXT("out keyword is not supported for complex dtype"));
}
#endif /* ULAB_MATH_FUNCTIONS_OUT_KEYWORD */

if(source->dtype == NDARRAY_COMPLEX) {
uint8_t *sarray = (uint8_t *)source->array;
ndarray_obj_t *ndarray = ndarray_new_dense_ndarray(source->ndim, source->shape, NDARRAY_COMPLEX);
Expand Down
4 changes: 2 additions & 2 deletions docs/manual/source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@
# -- Project information -----------------------------------------------------

project = 'The ulab book'
copyright = '2019-2022, Zoltán Vörös and contributors'
copyright = '2019-2024, Zoltán Vörös and contributors'
author = 'Zoltán Vörös'

# The full version, including alpha/beta/rc tags
release = '5.1.0'
release = '6.5.0'


# -- General configuration ---------------------------------------------------
Expand Down
1 change: 1 addition & 0 deletions docs/manual/source/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@ Welcome to the ulab book!
numpy-universal
numpy-fft
numpy-linalg
numpy-random
scipy-linalg
scipy-optimize
scipy-signal
Expand Down
177 changes: 140 additions & 37 deletions docs/manual/source/numpy-functions.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,43 +12,48 @@ the firmware was compiled with complex support.
4. `numpy.argmin <#argmin>`__
5. `numpy.argsort <#argsort>`__
6. `numpy.asarray\* <#asarray>`__
7. `numpy.clip <#clip>`__
8. `numpy.compress\* <#compress>`__
9. `numpy.conjugate\* <#conjugate>`__
10. `numpy.convolve\* <#convolve>`__
11. `numpy.delete <#delete>`__
12. `numpy.diff <#diff>`__
13. `numpy.dot <#dot>`__
14. `numpy.equal <#equal>`__
15. `numpy.flip\* <#flip>`__
16. `numpy.imag\* <#imag>`__
17. `numpy.interp <#interp>`__
18. `numpy.isfinite <#isfinite>`__
19. `numpy.isinf <#isinf>`__
20. `numpy.load <#load>`__
21. `numpy.loadtxt <#loadtxt>`__
22. `numpy.max <#max>`__
23. `numpy.maximum <#maximum>`__
24. `numpy.mean <#mean>`__
25. `numpy.median <#median>`__
26. `numpy.min <#min>`__
27. `numpy.minimum <#minimum>`__
28. `numpy.nozero <#nonzero>`__
29. `numpy.not_equal <#equal>`__
30. `numpy.polyfit <#polyfit>`__
31. `numpy.polyval <#polyval>`__
32. `numpy.real\* <#real>`__
33. `numpy.roll <#roll>`__
34. `numpy.save <#save>`__
35. `numpy.savetxt <#savetxt>`__
36. `numpy.size <#size>`__
37. `numpy.sort <#sort>`__
38. `numpy.sort_complex\* <#sort_complex>`__
39. `numpy.std <#std>`__
40. `numpy.sum <#sum>`__
41. `numpy.trace <#trace>`__
42. `numpy.trapz <#trapz>`__
43. `numpy.where <#where>`__
7. `numpy.bitwise_and <#bitwise_and>`__
8. `numpy.bitwise_or <#bitwise_and>`__
9. `numpy.bitwise_xor <#bitwise_and>`__
10. `numpy.clip <#clip>`__
11. `numpy.compress\* <#compress>`__
12. `numpy.conjugate\* <#conjugate>`__
13. `numpy.convolve\* <#convolve>`__
14. `numpy.delete <#delete>`__
15. `numpy.diff <#diff>`__
16. `numpy.dot <#dot>`__
17. `numpy.equal <#equal>`__
18. `numpy.flip\* <#flip>`__
19. `numpy.imag\* <#imag>`__
20. `numpy.interp <#interp>`__
21. `numpy.isfinite <#isfinite>`__
22. `numpy.isinf <#isinf>`__
23. `numpy.left_shift <#left_shift>`__
24. `numpy.load <#load>`__
25. `numpy.loadtxt <#loadtxt>`__
26. `numpy.max <#max>`__
27. `numpy.maximum <#maximum>`__
28. `numpy.mean <#mean>`__
29. `numpy.median <#median>`__
30. `numpy.min <#min>`__
31. `numpy.minimum <#minimum>`__
32. `numpy.nozero <#nonzero>`__
33. `numpy.not_equal <#equal>`__
34. `numpy.polyfit <#polyfit>`__
35. `numpy.polyval <#polyval>`__
36. `numpy.real\* <#real>`__
37. `numpy.right_shift <#right_shift>`__
38. `numpy.roll <#roll>`__
39. `numpy.save <#save>`__
40. `numpy.savetxt <#savetxt>`__
41. `numpy.size <#size>`__
42. `numpy.sort <#sort>`__
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>`__

all
---
Expand Down Expand Up @@ -323,6 +328,58 @@ an alias for ``array``.
bitwise_and
-----------

``numpy``: https://numpy.org/doc/stable/reference/routines.bitwise.html

``numpy``:
https://numpy.org/doc/stable/reference/generated/numpy.bitwise_and.html

``numpy``:
https://numpy.org/doc/stable/reference/generated/numpy.bitwise_or.html

``numpy``:
https://numpy.org/doc/stable/reference/generated/numpy.bitwise_xor.html

Each of ``bitwise_and``, ``bitwise_or``, and ``bitwise_xor`` takes two
integer-type ``ndarray``\ s as arguments, and returns the element-wise
results of the ``AND``, ``OR``, and ``XOR`` operators. Broadcasting is
supported. If the ``dtype`` of the input arrays is not an integer, and
exception will be raised.

.. code::
# code to be run in micropython
from ulab import numpy as np
a = np.array(range(8), dtype=np.uint8)
b = a + 1
print(a)
print(b)
print('\nbitwise_and:\n', np.bitwise_and(a, b))
print('\nbitwise_or:\n', np.bitwise_or(a, b))
print('\nbitwise_xor:\n', np.bitwise_xor(a, b))
.. parsed-literal::
array([0, 1, 2, 3, 4, 5, 6, 7], dtype=uint8)
array([1, 2, 3, 4, 5, 6, 7, 8], dtype=uint8)
bitwise_and:
array([0, 0, 2, 0, 4, 4, 6, 0], dtype=uint8)
bitwise_or:
array([1, 3, 3, 7, 5, 7, 7, 15], dtype=uint8)
bitwise_xor:
array([1, 3, 1, 7, 1, 3, 1, 15], dtype=uint8)
clip
----

Expand Down Expand Up @@ -987,6 +1044,52 @@ positions, where the input is infinite. Integer types return the
left_shift
----------

``numpy``:
https://numpy.org/doc/stable/reference/generated/numpy.left_shift.html

``numpy``:
https://numpy.org/doc/stable/reference/generated/numpy.right_shift.html

``left_shift``, and ``right_shift`` both take two integer-type
``ndarray``\ s, and bit-wise shift the elements of the first array by an
amount given by the second array to the left, and right, respectively.
Broadcasting is supported. If the ``dtype`` of the input arrays is not
an integer, and exception will be raised.

.. code::
# code to be run in micropython
from ulab import numpy as np
a = np.ones(7, dtype=np.uint8)
b = np.zeros(7, dtype=np.uint8) + 255
c = np.array(range(7), dtype=np.uint8) + 1
print('a: ', a)
print('b: ', b)
print('c: ', c)
print('\na left shifted by c:\n', np.left_shift(a, c))
print('\nb right shifted by c:\n', np.right_shift(b, c))
.. parsed-literal::
a: array([1, 1, 1, 1, 1, 1, 1], dtype=uint8)
b: array([255, 255, 255, 255, 255, 255, 255], dtype=uint8)
c: array([1, 2, 3, 4, 5, 6, 7], dtype=uint8)
a left shifted by c:
array([2, 4, 8, 16, 32, 64, 128], dtype=uint8)
b right shifted by c:
array([127, 63, 31, 15, 7, 3, 1], dtype=uint8)
load
----

Expand Down
25 changes: 24 additions & 1 deletion docs/manual/source/numpy-universal.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,18 @@ operate on, or can return complex arrays):
``acos``, ``acosh``, ``arctan2``, ``around``, ``asin``, ``asinh``,
``atan``, ``arctan2``, ``atanh``, ``ceil``, ``cos``, ``degrees``,
``exp*``, ``expm1``, ``floor``, ``log``, ``log10``, ``log2``,
``radians``, ``sin``, ``sinh``, ``sqrt*``, ``tan``, ``tanh``.
``radians``, ``sin``, ``sinc``, ``sinh``, ``sqrt*``, ``tan``, ``tanh``.

These functions are applied element-wise to the arguments, thus, e.g.,
the exponential of a matrix cannot be calculated in this way, only the
exponential of the matrix entries.

In order to avoid repeated memory allocations, functions can take the
``out=None`` optional argument, which must be a floating point
``ndarray`` of the same size as the input ``array``. If these conditions
are not fulfilled, and exception will be raised. If ``out=None``, a new
array will be created upon each invocation of the function.

.. code::
# code to be run in micropython
Expand All @@ -47,6 +53,13 @@ exponential of the matrix entries.
c = np.array(range(9)).reshape((3, 3))
print('\n=============\nc:\n', c)
print('exp(c):\n', np.exp(c))
# using the `out` argument
d = np.array(range(9)).reshape((3, 3))
print('\nd before invoking the function:\n', d)
np.exp(c, out=d)
print('\nd afteri nvoking the function:\n', d)
.. parsed-literal::
Expand All @@ -69,6 +82,16 @@ exponential of the matrix entries.
[20.08553692318767, 54.59815003314424, 148.4131591025766],
[403.4287934927351, 1096.633158428459, 2980.957987041728]], dtype=float64)
d before invoking the function:
array([[0.0, 1.0, 2.0],
[3.0, 4.0, 5.0],
[6.0, 7.0, 8.0]], dtype=float64)
d afteri nvoking the function:
array([[1.0, 2.718281828459045, 7.38905609893065],
[20.08553692318767, 54.59815003314424, 148.4131591025766],
[403.4287934927351, 1096.633158428459, 2980.957987041728]], dtype=float64)
Expand Down
17 changes: 11 additions & 6 deletions docs/manual/source/ulab-ndarray.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1816,12 +1816,17 @@ Binary operators

``ulab`` implements the ``+``, ``-``, ``*``, ``/``, ``**``, ``<``,
``>``, ``<=``, ``>=``, ``==``, ``!=``, ``+=``, ``-=``, ``*=``, ``/=``,
``**=`` binary operators that work element-wise. Broadcasting is
available, meaning that the two operands do not even have to have the
same shape. If the lengths along the respective axes are equal, or one
of them is 1, or the axis is missing, the element-wise operation can
still be carried out. A thorough explanation of broadcasting can be
found under https://numpy.org/doc/stable/user/basics.broadcasting.html.
``**=`` binary operators, as well as the ``AND``, ``OR``, ``XOR``
bit-wise operators that work element-wise. Note that the bit-wise
operators will raise an exception, if either of the operands is of
``float`` or ``complex`` type.

Broadcasting is available, meaning that the two operands do not even
have to have the same shape. If the lengths along the respective axes
are equal, or one of them is 1, or the axis is missing, the element-wise
operation can still be carried out. A thorough explanation of
broadcasting can be found under
https://numpy.org/doc/stable/user/basics.broadcasting.html.

**WARNING**: note that relational operators (``<``, ``>``, ``<=``,
``>=``, ``==``, ``!=``) should have the ``ndarray`` on their left hand
Expand Down
Loading

0 comments on commit c19f9c8

Please sign in to comment.