Merge branch 'main' into test_quote_fix

Author: dmdunla

.github/workflows/markdown-check.yml

@@ -7,8 +7,14 @@ on:
     branches: [ "main" ]
 
 jobs:
-  markdown-link-check:
+  check-links:
+    name: runner / linkspector
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+      - uses: actions/checkout@v4
+      - name: Run linkspector
+        uses: umbrelladocs/action-linkspector@v1
+        with:
+          github_token: ${{ secrets.github_token }}
+          reporter: github-pr-review
+          fail_on_error: true

.pre-commit-config.yaml

@@ -13,3 +13,10 @@ repos:
             --extra-keys=metadata.language_info metadata.vscode metadata.kernelspec cell.metadata.vscode,
             --drop-empty-cells
         ]
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        args: [ --toml, "pyproject.toml"]
+        additional_dependencies:
+          - tomli

CHANGELOG.md

@@ -1,9 +1,18 @@
+# v1.8.2 (2025-01-06)
+- Fixed:
+    - Fixed layout and printing issues (https://github.com/sandialabs/pyttb/pull/354)
+    - Fixed tutorial hierarchy (https://github.com/sandialabs/pyttb/pull/343)
+- Improved:
+    - Improved `pyttb_utils` (https://github.com/sandialabs/pyttb/pull/353)
+    - Improved docs for coming from MATLAB (https://github.com/sandialabs/pyttb/pull/352)
+    - Improved shape support in data classes (https://github.com/sandialabs/pyttb/pull/348)
+
 # v1.8.1 (2024-11-11)
 - Fixed: 
   - Aligning comparison operator output for data classes (https://github.com/sandialabs/pyttb/pull/331)
 - Improved:
   - Getting starting documentation (https://github.com/sandialabs/pyttb/pull/324)
-  - Development enviroment (https://github.com/sandialabs/pyttb/pull/329, https://github.com/sandialabs/pyttb/pull/330)
+  - Development environment (https://github.com/sandialabs/pyttb/pull/329, https://github.com/sandialabs/pyttb/pull/330)
   - Documentation (https://github.com/sandialabs/pyttb/pull/328, https://github.com/sandialabs/pyttb/pull/334)
 
 # v1.8.0 (2024-10-23)
@@ -84,7 +93,7 @@
     - Addresses ambiguity of -0 by using `exclude_dims` (`numpy.ndarray`) parameter
   - `ktensor.ttv`, `sptensor.ttv`, `tensor.ttv`, `ttensor.ttv`
     - Use `exlude_dims` parameter instead of `-dims`
-    - Explicit nameing of dimensions to exclude
+    - Explicit naming of dimensions to exclude
   - `tensor.ttsv`
     - Use `skip_dim` (`int`) parameter instead of `-dims`
     - Exclude all dimensions up to and including `skip_dim`

CITATION.bib

@@ -1,7 +1,7 @@
 @misc{pyttb,
 	author = {Dunlavy, Daniel M. and Johnson, Nicholas T. and others},
-	month = nov,
-	title = {{pyttb: Python Tensor Toolbox, v1.8.1}},
+	month = jan,
+	title = {{pyttb: Python Tensor Toolbox, v1.8.2}},
 	url = {https://github.com/sandialabs/pyttb},
-	year = {2024}
+	year = {2025}
 }

CONTRIBUTING.md

@@ -35,19 +35,25 @@ current or filing a new [issue](https://github.com/sandialabs/pyttb/issues).
     ```
     git checkout -b my-new-feature-branch
     ```
-1. Formatters and linting
+1. Formatters and linting (These are checked in the full test suite as well)
    1. Run autoformatters and linting from root of project (they will change your code)
-       ```commandline
-       ruff check . --fix
-       ruff format
-       ```
+      ```commandline
+      ruff check . --fix
+      ruff format
+      ```
       1. Ruff's `--fix` won't necessarily address everything and may point out issues that need manual attention
       1. [We](./.pre-commit-config.yaml) optionally support [pre-commit hooks](https://pre-commit.com/) for this
          1. Alternatively, you can run `pre-commit run --all-files` from the command line if you don't want to install the hooks.
    1. Check typing
       ```commandline
       mypy pyttb/
       ```
+      1. Not included in our pre-commit hooks because of slow runtime.
+   1. Check spelling
+      ```commandline
+      codespell
+      ```
+      1. This is also included in the optional pre-commit hooks.
 
 1. Run tests (at desired fidelity)
    1. Just doctests (enabled by default)
@@ -70,6 +76,28 @@ current or filing a new [issue](https://github.com/sandialabs/pyttb/issues).
    ```
    2. Clear notebook outputs if run locally see `nbstripout` in our [pre-commit configuration](.pre-commit-config.yaml)
 
+### Adding tutorials
+
+1. Follow general setup from above
+   1. Checkout a branch to make your changes
+   1. Install from source with dev and doc dependencies
+   1. Verify you can build the existing docs with sphinx
+
+1. Create a new Jupyter notebook in [./docs/source/tutorial](./docs/source/tutorial)
+   1. Our current convention is to prefix the filename with the type of tutorial and all lower case
+
+1. Add a reference to your notebook in [./docs/source/tutorials.rst](./docs/source/tutorials.rst)
+
+1. Rebuild the docs, review locally, and iterate on changes until ready for review
+
+#### Tutorial References
+Generally, inspecting existing documentation or tutorials should provide a reasonable starting point for capabilities,
+but the following links may be useful if that's not sufficient.
+
+1. We use [sphinx](https://www.sphinx-doc.org/) to automatically build our docs and may be useful for `.rst` issues
+
+1. We use [myst-nb](https://myst-nb.readthedocs.io/) to render our notebooks to documentation
+
 ## GitHub Workflow
 
 ### Proposing Changes

README.md

@@ -32,7 +32,7 @@ low-rank tensor decompositions:
 [`cp_apr`](https://pyttb.readthedocs.io/en/stable/cpapr.html "CP decomposition via Alternating Poisson Regression"), 
 [`gcp_opt`](https://pyttb.readthedocs.io/en/stable/gcpopt.html "Generalized CP decomposition"), 
 [`hosvd`](https://pyttb.readthedocs.io/en/stable/hosvd.html "Tucker decomposition via Higher Order Singular Value Decomposition"),
-[`tucker_als`](https://pyttb.readthedocs.io/en/stable/tuckerals.html "Tucker decompostion via Alternating Least Squares")
+[`tucker_als`](https://pyttb.readthedocs.io/en/stable/tuckerals.html "Tucker decomposition via Alternating Least Squares")
 
 ## Quick Start
 
@@ -56,6 +56,19 @@ CP_ALS:
  Final f = 7.508253e-01
  ```
 
+### Memory layout
+For historical reasons we use Fortran memory layouts, where numpy by default uses C.
+This is relevant for indexing. In the future we hope to extend support for both.
+```python
+>>> import numpy as np
+>>> c_order = np.arange(8).reshape((2,2,2))
+>>> f_order = np.arange(8).reshape((2,2,2), order="F")
+>>> print(c_order[0,1,1])
+3
+>>> print(f_order[0,1,1])
+6
+```
+
 <!-- markdown-link-check-disable -->
 ### Getting Help
 - [Documentation](https://pyttb.readthedocs.io)

conftest.py

@@ -4,11 +4,13 @@
 # U.S. Government retains certain rights in this software.
 
 import numpy
+import numpy as np
 
 # content of conftest.py
 import pytest
 
 import pyttb
+import pyttb as ttb
 
 
 @pytest.fixture(autouse=True)
@@ -17,6 +19,12 @@ def add_packages(doctest_namespace):  # noqa: D103
     doctest_namespace["ttb"] = pyttb
 
 
+@pytest.fixture(params=[{"order": "F"}, {"order": "C"}])
+def memory_layout(request):
+    """Test C and F memory layouts."""
+    return request.param
+
+
 def pytest_addoption(parser):  # noqa: D103
     parser.addoption(
         "--packaging",
@@ -30,3 +38,126 @@ def pytest_addoption(parser):  # noqa: D103
 def pytest_configure(config):  # noqa: D103
     if not config.option.packaging:
         config.option.markexpr = "not packaging"
+
+
+@pytest.fixture()
+def sample_tensor_2way():  # noqa: D103
+    data = np.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]])
+    shape = (2, 3)
+    params = {"data": data, "shape": shape}
+    tensorInstance = ttb.tensor(data, shape)
+    return params, tensorInstance
+
+
+@pytest.fixture()
+def sample_tensor_3way():  # noqa: D103
+    data = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0, 11.0, 12.0])
+    shape = (2, 3, 2)
+    params = {"data": np.reshape(data, np.array(shape), order="F"), "shape": shape}
+    tensorInstance = ttb.tensor(data, shape)
+    return params, tensorInstance
+
+
+@pytest.fixture()
+def sample_ndarray_1way():  # noqa: D103
+    shape = (16,)
+    ndarrayInstance = np.reshape(np.arange(1, 17), shape, order="F")
+    params = {"data": ndarrayInstance, "shape": shape}
+    return params, ndarrayInstance
+
+
+@pytest.fixture()
+def sample_ndarray_2way():  # noqa: D103
+    shape = (4, 4)
+    ndarrayInstance = np.reshape(np.arange(1, 17), shape, order="F")
+    params = {"data": ndarrayInstance, "shape": shape}
+    return params, ndarrayInstance
+
+
+@pytest.fixture()
+def sample_ndarray_4way():  # noqa: D103
+    shape = (2, 2, 2, 2)
+    ndarrayInstance = np.reshape(np.arange(1, 17), shape, order="F")
+    params = {"data": ndarrayInstance, "shape": shape}
+    return params, ndarrayInstance
+
+
+@pytest.fixture()
+def sample_tenmat_4way():  # noqa: D103
+    shape = (4, 4)
+    data = np.reshape(np.arange(1, 17), shape, order="F")
+    tshape = (2, 2, 2, 2)
+    rdims = np.array([0, 1])
+    cdims = np.array([2, 3])
+    tenmatInstance = ttb.tenmat()
+    tenmatInstance.tshape = tshape
+    tenmatInstance.rindices = rdims.copy()
+    tenmatInstance.cindices = cdims.copy()
+    tenmatInstance.data = data.copy()
+    params = {
+        "data": data,
+        "rdims": rdims,
+        "cdims": cdims,
+        "tshape": tshape,
+        "shape": shape,
+    }
+    return params, tenmatInstance
+
+
+@pytest.fixture()
+def sample_tensor_4way():  # noqa: D103
+    data = np.arange(1, 17)
+    shape = (2, 2, 2, 2)
+    params = {"data": np.reshape(data, np.array(shape), order="F"), "shape": shape}
+    tensorInstance = ttb.tensor(data, shape)
+    return params, tensorInstance
+
+
+@pytest.fixture()
+def sample_ktensor_2way():  # noqa: D103
+    weights = np.array([1.0, 2.0])
+    fm0 = np.array([[1.0, 2.0], [3.0, 4.0]])
+    fm1 = np.array([[5.0, 6.0], [7.0, 8.0]])
+    factor_matrices = [fm0, fm1]
+    data = {"weights": weights, "factor_matrices": factor_matrices}
+    ktensorInstance = ttb.ktensor(factor_matrices, weights)
+    return data, ktensorInstance
+
+
+@pytest.fixture()
+def sample_ktensor_3way():  # noqa: D103
+    rank = 2
+    shape = (2, 3, 4)
+    vector = np.arange(1, rank * sum(shape) + 1).astype(float)
+    weights = 2 * np.ones(rank).astype(float)
+    vector_with_weights = np.concatenate((weights, vector), axis=0)
+    # vector_with_weights = vector_with_weights.reshape((len(vector_with_weights), 1))
+    # ground truth
+    fm0 = np.array([[1.0, 3.0], [2.0, 4.0]])
+    fm1 = np.array([[5.0, 8.0], [6.0, 9.0], [7.0, 10.0]])
+    fm2 = np.array([[11.0, 15.0], [12.0, 16.0], [13.0, 17.0], [14.0, 18.0]])
+    factor_matrices = [fm0, fm1, fm2]
+    data = {
+        "weights": weights,
+        "factor_matrices": factor_matrices,
+        "vector": vector,
+        "vector_with_weights": vector_with_weights,
+        "shape": shape,
+    }
+    ktensorInstance = ttb.ktensor(factor_matrices, weights)
+    return data, ktensorInstance
+
+
+@pytest.fixture()
+def sample_ktensor_symmetric():  # noqa: D103
+    weights = np.array([1.0, 1.0])
+    fm0 = np.array(
+        [[2.340431417384394, 4.951967353890655], [4.596069112758807, 8.012451489774961]]
+    )
+    fm1 = np.array(
+        [[2.340431417384394, 4.951967353890655], [4.596069112758807, 8.012451489774961]]
+    )
+    factor_matrices = [fm0, fm1]
+    data = {"weights": weights, "factor_matrices": factor_matrices}
+    ktensorInstance = ttb.ktensor(factor_matrices, weights)
+    return data, ktensorInstance

docs/source/index.rst

@@ -39,6 +39,18 @@ algorithms for computing low-rank tensor models.
 
 Getting Started
 ===============
+For historical reasons we use Fortran memory layouts, where numpy by default uses C.
+This is relevant for indexing. In the future we hope to extend support for both.
+
+.. code-block:: python
+
+    >>> import numpy as np
+    >>> c_order = np.arange(8).reshape((2,2,2))
+    >>> f_order = np.arange(8).reshape((2,2,2), order="F")
+    >>> print(c_order[0,1,1])
+    3
+    >>> print(f_order[0,1,1])
+    6
 
 .. toctree::
    :maxdepth: 1

docs/source/matlab/ktensor.rst

@@ -22,7 +22,5 @@ Methods
 +-----------------+----------------------+------------------------------------------------------------------------+
 | ``tensor``      | ``to_tensor``        | ``X.to_tensor()``                                                      |
 +-----------------+----------------------+------------------------------------------------------------------------+
-
-MATLAB methods not included in ``pyttb``
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* ``viz``
+| ``viz``         | ``viz``              | ``X.viz()``                                                            |
++-----------------+----------------------+------------------------------------------------------------------------+

docs/source/tutorial/algorithm_cp_als.ipynb

@@ -122,7 +122,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Increase the maximium number of iterations\n",
+    "## Increase the maximum number of iterations\n",
     "Note that the previous run kicked out at only 10 iterations, before reaching the specified convegence tolerance. Let's increase the maximum number of iterations and try again, using the same initial guess."
    ]
   },
@@ -337,7 +337,7 @@
    "source": [
     "## Recommendations\n",
     "* Run multiple times with different guesses and select the solution with the best fit.\n",
-    "* Try different ranks and choose the solution that is the best descriptor for your data based on the combination of the fit and the interpretaton of the factors, e.g., by visualizing the results."
+    "* Try different ranks and choose the solution that is the best descriptor for your data based on the combination of the fit and the interpretation of the factors, e.g., by visualizing the results."
    ]
   }
  ],

docs/source/tutorial/algorithm_gcp_opt.ipynb

@@ -19,7 +19,7 @@
     "tags": []
    },
    "source": [
-    "This document outlines usage and examples for the generalized CP (GCP) tensor decomposition implmented in `pyttb.gcp_opt`. GCP allows alternate objective functions besides sum of squared errors, which is the standard for CP. The code support both dense and sparse input tensors, but the sparse input tensors require randomized optimization methods.\n",
+    "This document outlines usage and examples for the generalized CP (GCP) tensor decomposition implemented in `pyttb.gcp_opt`. GCP allows alternate objective functions besides sum of squared errors, which is the standard for CP. The code support both dense and sparse input tensors, but the sparse input tensors require randomized optimization methods.\n",
     "\n",
     "GCP is described in greater detail in the manuscripts:\n",
     "* D. Hong, T. G. Kolda, J. A. Duersch, Generalized Canonical Polyadic Tensor Decomposition, SIAM Review, 62:133-163, 2020, https://doi.org/10.1137/18M1203626\n",

docs/source/tutorial/algorithm_hosvd.ipynb

@@ -94,7 +94,7 @@
    "metadata": {},
    "source": [
     "## Generate a core with different accuracies for different shapes\n",
-    "We will create a core `tensor` that has is nearly block diagonal. The blocks are expontentially decreasing in norm, with the idea that we can pick off one block at a time as we increate the prescribed accuracy of the HOSVD. To do this, we define and use a function `tenrandblk()`."
+    "We will create a core `tensor` that has is nearly block diagonal. The blocks are expontentially decreasing in norm, with the idea that we can pick off one block at a time as we increase the prescribed accuracy of the HOSVD. To do this, we define and use a function `tenrandblk()`."
    ]
   },
   {

docs/source/tutorial/class_sptensor.ipynb

@@ -17,7 +17,7 @@
    "metadata": {},
    "source": [
     "## Creating a `sptensor`\n",
-    "The `sptensor` class stores the data in coordinate format. A sparse `sptensor` can be created by passing in a list of subscripts and values. For example, here we pass in three subscripts and a scalar value. The resuling sparse `sptensor` has three nonzero entries, and the `shape` is the size of the largest subscript in each dimension."
+    "The `sptensor` class stores the data in coordinate format. A sparse `sptensor` can be created by passing in a list of subscripts and values. For example, here we pass in three subscripts and a scalar value. The resulting sparse `sptensor` has three nonzero entries, and the `shape` is the size of the largest subscript in each dimension."
    ]
   },
   {

docs/source/tutorial/class_sumtensor.ipynb

@@ -54,7 +54,7 @@
    "metadata": {},
    "source": [
     "## Creating sumtensors\n",
-    "A sumtensor `T` can only be delared as a sum of same-shaped tensors T1, T2,...,TN. The summand tensors are stored internally, which define the \"parts\" of the `sumtensor`. The parts of a `sumtensor` can be (dense) tensors (`tensor`), sparse tensors (` sptensor`), Kruskal tensors (`ktensor`), or Tucker tensors (`ttensor`). An example of the use of the sumtensor constructor follows."
+    "A sumtensor `T` can only be declared as a sum of same-shaped tensors T1, T2,...,TN. The summand tensors are stored internally, which define the \"parts\" of the `sumtensor`. The parts of a `sumtensor` can be (dense) tensors (`tensor`), sparse tensors (` sptensor`), Kruskal tensors (`ktensor`), or Tucker tensors (`ttensor`). An example of the use of the sumtensor constructor follows."
    ]
   },
   {