Add some intro articles. Shorten the readme as it now needs to cover …

…less ground, point to doc articles instead.
Ivorforce · Sep 17, 2024 · 4aeb58b · 4aeb58b
1 parent 30b6d81
commit 4aeb58b
Show file tree

Hide file tree

Showing 5 changed files with 88 additions and 43 deletions.
diff --git a/Readme.md b/Readme.md
@@ -2,51 +2,17 @@
 
 A tensor math and scientific computation library for the [Godot](https://godotengine.org) game engine. The project is still in its early stages. [Contributions are welcome](https://github.com/Ivorforce/NumDot/blob/main/CONTRIBUTING.md)!
 
-NumDot uses [xtensor](https://github.com/xtensor-stack/xtensor) under the hood.
+NumDot is inspired by the python tensor math library, [NumPy](https://numpy.org), and uses [xtensor](https://github.com/xtensor-stack/xtensor) under the hood.
 
-### What and Why?
+**Quick Start:**
+- [Motivation (why use NumDot?)](https://numdot.readthedocs.io/en/latest/index.html#motivation)
+- [How to install](https://numdot.readthedocs.io/en/latest/how-to-install/how-to-install.html)
+- [Getting Started](https://numdot.readthedocs.io/en/latest/how-to-use/getting_started.html)
+- [NumPy, xtensor and NumDot](https://numdot.readthedocs.io/en/latest/how-to-use/numpy-xtensor-numdot.html)
+- [Class Reference](https://numdot.readthedocs.io/en/latest/classes/index.html)
+- [How to contribute](https://github.com/Ivorforce/NumDot/blob/main/CONTRIBUTING.md)
 
-A tensor (or nd-array) is essentially a multi-dimensional array. You can run mathematical operations on the _whole tensor_ at once, making these operations very fast. Currently, common math operations can run up to 200 times faster than a conventional for-loop in gdscript.
-
-Operations with tensors are also very easy to write and read, once you're familiar with them. Vectorization reduces boilerplate a ton, and allows you to focus on the actual operations taking place.
-
-NumDot is inspired by the python tensor math library, [NumPy](https://numpy.org), and thus shares many semantics with it. If you are unfamiliar with tensor operations in general, we recommend taking a numpy tutorial or two first. That being said, here are some direct comparison examples:
-
-| NumPy                             | NumDot                                                                                                                           |
-| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `x[a, b, c]`                      | `x.get(a, b, c)` ([syntax discussion](https://github.com/Ivorforce/NumDot/issues/6))                                             |
-| `x[...]` can return single values | `x.get(...)` always returns a tensor, use `x.get_float(...)` and `x.get_int(...)` to get values.                                 |
-| `x[a, b, c] = d`                  | `x.set(d, a, b, c)`                                                                                                              |
-| `x[1:]`                           | `x.get(nd.from(1))`                                                                                                              |
-| `x[:1]`                           | `x.get(nd.to(1))`                                                                                                                |
-| `x[1:2]`                          | `x.get(nd.range(1, 2))`                                                                                                          |
-| `x[0:5:2]`                        | `x.get(nd.range(0, 5, 2))`                                                                                                       |
-| `x[..., 5]`                       | `x.get(&"...", 5)`                                                                                                               |
-| `x[np.newaxis, 5]`                | `x.get(nd.newaxis(), 5)`                                                                                                         |
-| `np.array([2, 3, 4])`             | `nd.array([2, 3, 4])`                                                                                                            |
-| `np.ones((2, 3, 4))`              | `nd.ones([2, 3, 4])`                                                                                                             |
-| `a + b`                           | `nd.add(a, b)` ([operator overloads are not yet supported by godot](https://github.com/godotengine/godot-proposals/issues/8383)) |
-| `np.sin(a)`                       | `nd.sin(a)`                                                                                                                      |
-| `np.mean(a, [1, -1])`             | `nd.mean(a, [1, -1])`                                                                                                            |
-| `np.reshape(a, (50, -1))`         | `nd.reshape(a, [50, -1])`                                                                                                        |
-| `np.transpose(a, (2, 0, 1))`      | `nd.transpose(a, [2, 0, 1])`                                                                                                     |
-
-Keep in mind these semantics are yet subject to change.
-
-#### Godot Interoperability
-
-Godot types are automatically converted to NumDot types for operations. You can also convert it back to godot types:
-```gdscript
-var a = nd.array(PackedFloat32Array([1, 2, 3]))
-a = nd.add(a, 5)
-var b: PackedFloat32Array = a.to_packed_float32_array()
-```
-
-### Adding the extension to your Godot project
-
-Download the [latest release](https://github.com/Ivorforce/NumDot/releases) and place it into your project folder.
-
-### What Now?
+## What Now?
 
 NumDot is still in its early stages. If you want to keep up to date, come by and chat with us on our [Discord Server](https://discord.gg/hxuWcAXF).
 

diff --git a/docs/how-to-use/godot-interop.rst b/docs/how-to-use/godot-interop.rst
@@ -0,0 +1,28 @@
+.. _doc_godot_interop:
+
+Godot Interoperability
+======================
+
+Explicit Adaptations
+--------------------
+
+NumDot can adapt most `Variant <https://docs.godotengine.org/en/stable/classes/class_variant.html>`__ objects explicitly. The objects are copied on conversion:
+
+.. code-block:: gdscript
+
+    var packed := PackedFloat32Array([1, 2, 3])
+    var a := nd.add(packed, 5)
+    packed = a.to_packed_float32_array()
+    print(packed)  # [6, 7, 8]
+
+In-Place Views
+--------------
+
+In the future, we want to support in-place modification without copying. This is not yet implemented.
+
+.. code-block:: gdscript
+
+    var packed := PackedFloat32Array([1, 2, 3])
+    var a := nd.as_array(packed)
+    a.add(a, 5)
+    print(packed)  # [6, 7, 8]
diff --git a/docs/how-to-use/numpy-xtensor-numdot.csv b/docs/how-to-use/numpy-xtensor-numdot.csv
@@ -0,0 +1,22 @@
+NumPy;xtensor;NumDot;Notes
+``a[0]``;``xt::view(a, { 0 })``;``a.get(0)``;Create a view.
+``a[:]``;``xt::view(a, { xt::all() })``;``a.get(null)``;Select all elements.
+``a[None]``;``xt::view(a, { xt::newaxis() })``;"``a.get(&""newaxis"")``";Insert new axis.
+``a[..., 0]``;``xt::view(a, { xt::ellipsis(), 0 })``;"``a.get(&""..."", 0)``";Ellipsis stands in for all other dimensions.
+``a[2:]``;``xt::view(a, { 2|_ })``;``a.get(nd.from(2))``;Select elements starting at index 2.
+``a[:2]``;``xt::view(a, { _|2 })``;``a.get(nd.to(2))``;Select elements ending at index 2.
+``a[2:4]``;``xt::view(a, { 2|4 })``;``a.get(nd.range(2, 4))``;Select elements starting at index 2, ending at index 4.
+``a[2:40:2]``;``xt::view(a, { 2|40|2 })``;``a.get(nd.range(2, 40, 2))``;Select every second element, starting at index 2, ending at index 4.
+"| ``a + b``
+| ``np.add(a, b)``";``a + b``;``nd.add(a, b)``;
+"| ``a - b``
+| ``np.subtract(a, b)``";``a - b``;``nd.subtract(a, b)``;
+"| ``a * b``
+| ``np.multiply(a, b)``";``a * b``;``nd.multiply(a, b)``;
+"| ``a / b``
+| ``np.divide(a, b)``";``a / b``;``nd.divide(a, b)``;
+``np.sin(a)``;``xt::sin(a)``;``nd.sin(a)``;Analogous for all trig functions.
+"| ``np.degrees``
+| ``np.deg2rad``";``xt::deg2rad``;``nd.deg2rad``;
+"| ``np.radians``
+| ``np.rad2deg``";``xt::rad2deg``;``nd.rad2deg``;
diff --git a/docs/how-to-use/numpy-xtensor-numdot.rst b/docs/how-to-use/numpy-xtensor-numdot.rst
@@ -0,0 +1,27 @@
+.. _doc_numpy_xtensor_numdot:
+
+NumPy, xtensor, and NumDot
+==========================
+
+NumDot attempts to recreate `NumPy <https://numpy.org>`_-like behavior, and uses `xtensor <https://github.com/xtensor-stack/xtensor>`_ under the hood.
+While most things are consistent across all three libraries, differences exist.
+
+Fundamental Comparison
+----------------------
+
+- NumDot functions always return tensors, to avoid accidentally promoting dtypes. NumPy returned types like ``np.float32`` can be used like primitive numbers.
+- NumDot does not overload operators like ``+`` and ``*``, due to a `gdscript limitation <https://github.com/godotengine/godot-proposals/issues/8383>`_.
+- NumDot does not support subscripts (``a[start:stop:step]``, due to a `gdscript limitation <https://github.com/Ivorforce/NumDot/issues/6>`_. Instead, use ``a.get(nd.range(start, stop, step)``.
+- NumPy supports keyword arguments. NumDot only supports ordered arguments, due to a `gdscript limitation <https://github.com/Ivorforce/NumDot/issues/10>`_.
+- ``xtensor`` operations are lazy views. NumPy and NumDot operations evaluate immediately, with the exception of strideable views.
+
+Function Cheat Sheet
+--------------------
+
+.. csv-table:: NumPy, xtensor and NumDot Cheat Sheet
+   :file: numpy-xtensor-numdot.csv
+   :widths: 25, 25, 25, 25
+   :delim: ;
+   :header-rows: 1
+
+Haven't found what you need? Try :ref:`nd <class_nd>`!
diff --git a/docs/index.rst b/docs/index.rst
@@ -39,6 +39,8 @@ Table of Contents
 
    how-to-use/getting_started
    how-to-use/tensors
+   how-to-use/godot-interop
+   how-to-use/numpy-xtensor-numdot
 
 .. toctree::
    :maxdepth: 2