Start adding some more details to the coming from matlab docs (#352)

* Start adding some more details to the coming from matlab docs * MATLAB: Move the copying details to the top of the doc * This is a python detail so prefer referring outwards for more details. * DOCS: Generate docs for the pyttb_utils. They are mostly internal but it couldn't hurt to have them visible on the web hosted docs. --------- Co-authored-by: Danny Dunlavy <[email protected]>
sandialabs · Dec 13, 2024 · ab5ac5c · ab5ac5c
1 parent 605dd28
commit ab5ac5c
Show file tree

Hide file tree

Showing 4 changed files with 26 additions and 9 deletions.
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -24,7 +24,7 @@ algorithms for computing low-rank tensor models.
 
    pyttb supports multiple tensor types, including
    dense and sparse, as well as specially structured tensors, such as
-   the Krusal format (stored as factor matrices).
+   the Kruskal format (stored as factor matrices).
 
 - `Algorithms`_
 

diff --git a/docs/source/matlab/common.rst b/docs/source/matlab/common.rst
@@ -1,6 +1,22 @@
 General key differences
 -----------------------
 
+Python Conventions
+^^^^^^^^^^^^^^^^^^
+We make extensive use of NumPy throughout the library so please see their
+`documentation for MATLAB users <https://numpy.org/doc/stable/user/numpy-for-matlab-users.html>`_.
+Otherwise some highlights are:
+
+* 0-indexing in python vs 1-indexing in MATLAB
+
+Copying
+^^^^^^^^^^^^^^^^^^^^
+Copying a ``pyttb`` tensor works differently than MATLAB. For example in MATLAB, copying a tensor ``Y``
+as  ``Y = X`` returns a tensor ``Y`` that is independent of ``X``. Changing the value of ``Y`` does not
+change the value of ``X``. However, the same syntax in ``pyttb``, ``Y = X``, returns a *shallow copy* of ``X``;
+the shallow copy ``Y`` is a *reference* to ``X``. For that reason, each ``pyttb`` tensor class provides a ``copy()``
+method that returns a *deep copy* ``Y`` that is independent of ``X``, which is called as ``Y = X.copy()``.
+
 Data members
 ^^^^^^^^^^^^
 +-----------------+----------------------+------------------------------------------------------------------------+
@@ -67,14 +83,6 @@ Methods
 | ``xor``         | ``logical_xor``      | ``X.logical_xor(Y)``                                                   |
 +-----------------+----------------------+------------------------------------------------------------------------+
 
-Copying
-^^^^^^^^^^^^^^^^^^^^
-Copying a ``pyttb`` tensor works differently than MATLAB. For example in MATLAB, copying a tensor ``Y``
-as  ``Y = X`` returns a tensor ``Y`` that is independent of ``X``. Changing the value of ``Y`` does not
-change the value of ``X``. However, the same syntax in ``pyttb``, ``Y = X``, returns a *shallow copy* of ``X``;
-the shallow copy ``Y`` is a *reference* to ``X``. For that reason, each ``pyttb`` tensor class provides a ``copy()``
-method that returns a *deep copy* ``Y`` that is independent of ``X``, which is called as ``Y = X.copy()``.
-
 MATLAB methods not included in ``pyttb``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 - ``datadisp``

diff --git a/docs/source/pyttb_utils.rst b/docs/source/pyttb_utils.rst
@@ -0,0 +1,8 @@
+pyttb.pyttb_utils
+--------------------
+
+.. automodule:: pyttb.pyttb_utils
+    :members:
+    :special-members:
+    :exclude-members: __dict__, __weakref__, __slots__, __init__
+    :show-inheritance:
diff --git a/docs/source/tensor_classes.rst b/docs/source/tensor_classes.rst
@@ -11,4 +11,5 @@ Tensor Classes
     tensor.rst
     ttensor.rst
     tenmat.rst
+    pyttb_utils.rst