Mapping of pyttb ttb functionality (#291)

* Created ttensor/reconstruct tutorial in master. * autoformat * Removed from main until completed in branch 248-tutorial-partial-reconstruction-of-a-tucker-tensor. * Initial commit * Basic matlab to pyttb mapping. TODOs: 1. insert hyperlinks to both ttb and pyttb documentation, 2. add algorithms. * nbstripout * Initial version ready. * Updates to ruff * Updates to ruff * Ruff fixes. * Ruff fixes. * Attempting pre-commit fixes with autoupdate. * Attempting pre-commit fixes with autoupdate: part two, running pre-commit hooks. * Attempting pre-commit fixes with autoupdate: attempt two, autoupdate black only. * Attempting to fix pre-commit issues and noqas * Pin ruff, fix precommit * Run precommit --------- Co-authored-by: Jeremy Myers <jermyer@sandia.gov>
sandialabs · Apr 3, 2024 · 42f1289 · 42f1289
1 parent 5751f02
commit 42f1289
Show file tree

Hide file tree

Showing 41 changed files with 409 additions and 131 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -5,7 +5,7 @@ repos:
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix ]
   - repo: https://github.com/psf/black
-    rev: 23.3.0
+    rev: 24.1.1
     hooks:
       - id: black
         language_version: python

diff --git a/docs/source/for_matlab_users.rst b/docs/source/for_matlab_users.rst
@@ -0,0 +1,14 @@
+pyttb for MATLAB users
+======================
+
+Already familiar with MATLAB Tensor Toolbox? To assist transitions from the
+Tensor Toolbox for MATLAB to pyttb, this guide documents some key differences.
+
+In the ``pyttb`` calling conventions below we'll use the following notation:
+    - ``pyttb.<TENSOR_TYPE>``: ``X`` (and ``Y`` for binary operators)
+    - ``<SCALAR_TYPE>``: ``a`` for scalars.
+
+.. toctree::
+   :glob:
+
+   matlab/*
diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -1,6 +1,18 @@
-:orphan:
-
 Getting Started
 ***************
 
-In construction
+Tutorials
+=========
+
+.. toctree::
+   :maxdepth: 1
+
+   tutorials.rst
+
+Coming from MATLAB
+==================
+
+.. toctree::
+   :maxdepth: 1
+
+   for_matlab_users.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -37,14 +37,13 @@ algorithms for computing low-rank tensor models.
 .. _Algorithms: algorithms.html
 
 
-Tutorials
-=========
+Getting Started
+===============
 
 .. toctree::
    :maxdepth: 1
 
-   tutorials.rst
-
+   getting_started.rst
 
 Python API
 ================

diff --git a/docs/source/matlab/common.rst b/docs/source/matlab/common.rst
@@ -0,0 +1,83 @@
+General key differences
+-----------------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``size``        | ``shape``            | ``X.shape``                                                            |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``and``         | ``logical_and``      | ``X.logical_and(Y)``                                                   |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``disp``        | ``__str__``          | ``X``                                                                  |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``display``     | ``__repr__``         | ``print(X)``                                                           |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``eq``          | ``__eq__``           | ``X == Y``                                                             |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``ge``          | ``__ge__``           | ``X >= Y``                                                             |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``gt``          | ``__gt__``           | ``X > Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``ldivide``     | ``__truediv__``      | ``X / Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``le``          | ``__le__``           | ``X <= Y``                                                             |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``lt``          | ``__lt__``           | ``X < Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``minus``       | ``__sub__``          | ``X - Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``mldivide``    | ``__truediv__``      | ``X / Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``mrdivide``    | ``__rtruediv__``     | ``X / Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``mtimes``      | ``__rmul__``         | ``a * X``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``ne``          | ``__ne__``           | ``X != Y``                                                             |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``not``         | ``logical_not``      | ``X.logical_not(Y)``                                                   |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``or``          | ``logical_or``       | ``X.logical_or(Y)``                                                    |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``plus``        | ``__add__``          | ``X + Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``power``       | ``__pow__``          | ``X ** a``                                                             |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``rdivide``     | ``__rtruediv__``     | ``X / Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``subsasgn``    | ``__setitem__``      | ``X[index] = a``                                                       |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``subsref``     | ``__getitem__``      | ``X[index]``                                                           |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tenfun``      | ``tt_tenfun``        | e.g., ``pyttb.tt_tenfun(lambda x: x + 1, A)``                          |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``times``       | ``__mul__``          | ``X * Y``                                                              |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``uminus``      | ``__neg__``          | ``-X``                                                                 |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``uplus``       | ``__pos__``          | ``+X``                                                                 |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``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``
+- ``isscalar``
+- ``transpose``
+- ``tocell``
diff --git a/docs/source/matlab/ktensor.rst b/docs/source/matlab/ktensor.rst
@@ -0,0 +1,28 @@
+``ktensor``
+-----------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``lambda``      | ``weights``          | ``X.weights``                                                          |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``U``           | ``factor_matrices``  | ``X.factor_matrices``                                                  |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+|                 | ``from_vector``      | ``ttb.ktensor.from_vector(data[:], shape)``                            |
+| ``ktensor``     +----------------------+------------------------------------------------------------------------+
+|                 | ``from_function``    | ``ttb.tensor.from_function(<function>, shape)``                        |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tensor``      | ``to_tensor``        | ``X.to_tensor()``                                                      |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+MATLAB methods not included in ``pyttb``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* ``viz``
diff --git a/docs/source/matlab/sptenmat.rst b/docs/source/matlab/sptenmat.rst
@@ -0,0 +1,30 @@
+``sptenmat``
+------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``size``        | ``shape``            | ``X.shape``                                                            |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tsize``       | ``tshape``           | ``X.tshape``                                                           |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+|                 | ``from_data``        | ``A = ttb.sptenmat.from_data(subs, vals, rdims, cdims, tshape)``       |
+|                 +----------------------+------------------------------------------------------------------------+
+| ``sptenmat``    | ``from_tensor_type`` | ``A = ttb.sptenmat.from_tensor_type(X, np.array([0]))``                |
+|                 +----------------------+------------------------------------------------------------------------+
+|                 | ``from_array``       | ``A = ttb.sptenmat.from_data(B, rdims, cdims, tshape)``                |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``sptensor``    | ``to_sptensor``      | ``X.to_sptensor()``                                                    |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+MATLAB methods not included in ``pyttb``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* ``aatx``
diff --git a/docs/source/matlab/sptensor.rst b/docs/source/matlab/sptensor.rst
@@ -0,0 +1,14 @@
+``sptensor``
+----------------
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+|                 | ``from_function``    | ``ttb.sptensor.from_function(<function>, shape)``                      |
+| ``sptensor``    +----------------------+------------------------------------------------------------------------+
+|                 | ``from_aggregator``  | ``ttb.sptensor.from_aggregator(subs, vals, shape, function_handle)``   |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tensor``      | ``to_tensor``        | ``X.to_tensor()``                                                      |
++-----------------+----------------------+------------------------------------------------------------------------+
diff --git a/docs/source/matlab/sumtensor.rst b/docs/source/matlab/sumtensor.rst
@@ -0,0 +1,10 @@
+``sumtensor``
+-------------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``part``        | ``parts``            | ``X.parts``                                                            |
++-----------------+----------------------+------------------------------------------------------------------------+
diff --git a/docs/source/matlab/symktensor.rst b/docs/source/matlab/symktensor.rst
@@ -0,0 +1,8 @@
+``symktensor``
+--------------------
+
+Data members
+^^^^^^^^^^^^
+
+Methods
+^^^^^^^
diff --git a/docs/source/matlab/symtensor.rst b/docs/source/matlab/symtensor.rst
@@ -0,0 +1,8 @@
+``symtensor``
+-------------------
+
+Data members
+^^^^^^^^^^^^
+
+Methods
+^^^^^^^
diff --git a/docs/source/matlab/tenmat.rst b/docs/source/matlab/tenmat.rst
@@ -0,0 +1,22 @@
+``tenmat``
+----------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``tsize``       | ``tshape``           | ``X.tshape``                                                           |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+|                 | ``from_data``        | ``B = ttb.tenmat.from_data(A.data, A.rindices, A.cindices, A.tshape)`` |
+| ``tenmat``      +----------------------+------------------------------------------------------------------------+
+|                 | ``from_tensor_type`` | ``A = ttb.tenmat.from_tensor_type(X, np.array([1]))``                  |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tensor``      | ``to_tensor``        | ``X.to_tensor()``                                                      |
++-----------------+----------------------+------------------------------------------------------------------------+
diff --git a/docs/source/matlab/tensor.rst b/docs/source/matlab/tensor.rst
@@ -0,0 +1,12 @@
+``tensor``
+------------------
+
+Methods
+^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``tensor``      | ``from_function``    | ``ttb.tensor.from_function(<function>, shape)``                        |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``sptensor``    | ``to_sptensor``      | ``X.to_sptensor()``                                                    |
++-----------------+----------------------+------------------------------------------------------------------------+
diff --git a/docs/source/matlab/ttensor.rst b/docs/source/matlab/ttensor.rst
@@ -0,0 +1,21 @@
+``ttensor``
+-----------------
+
+Data members
+^^^^^^^^^^^^
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``U``           | ``factors``          | ``X.factors``                                                          |
++-----------------+----------------------+------------------------------------------------------------------------+
+
+Methods
+^^^^^^^
+
++-----------------+----------------------+------------------------------------------------------------------------+
+| MATLAB name     | ``pyttb`` name       | Calling convention                                                     |
++=================+======================+========================================================================+
+| ``size``        | ``shape``            | ``X.shape()``                                                          |
++-----------------+----------------------+------------------------------------------------------------------------+
+| ``tensor``      | ``to_tensor``        | ``X.to_tensor()``                                                      |
++-----------------+----------------------+------------------------------------------------------------------------+