sandialabs · tgkolda · Dec 14, 2024 · Dec 14, 2024 · Dec 14, 2024 · Dec 14, 2024
diff --git a/.github/workflows/markdown-check.yml b/.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
diff --git a/.gitignore b/.gitignore
@@ -6,6 +6,7 @@ dist/
 tests/__pycache__
 pyttb/__pycache__
 build/
+_build/
 .coverage
 .ipynb_checkpoints
 htmlcov

diff --git a/.pre-commit-config.yaml b/.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
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,7 +3,7 @@
   - 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 +84,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`

diff --git a/CONTRIBUTING.md b/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

diff --git a/README.md b/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
 

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -4,16 +4,25 @@ pyttb: Python Tensor Toolbox
 ****************************
 Tensors (also known as multidimensional arrays or N-way arrays) are used
 in a variety of applications ranging from chemometrics to network
-analysis.
+analysis. This Python package is an adaptation of the 
+`Tensor Toolbox for MATLAB <https://www.tensortoolbox.org>`_.
 
--  Install the latest release from pypi (``pip install pyttb``).
 -  This is open source software. Please see `LICENSE`_ for the
    terms of the license (2-clause BSD).
 -  For more information or for feedback on this project, please `contact us`_.
 
 .. _`LICENSE`: ../../../LICENSE
 .. _contact us: #contact
 
+Installing
+==========
+
+* Via pypi
+   -  Install the latest release from pypi (``pip install pyttb``).
+* From source
+   -  Clone the repository from `github <https://github.com/sandialabs/pyttb>`_.
+   -  Install the package with ``pip install .`` from the pyttb root directory.
+
 Functionality
 ==============
 pyttb provides the following classes and functions

diff --git a/docs/source/tensor.rst b/docs/source/tensor.rst
@@ -1,8 +1,8 @@
 pyttb.tensor
 --------------------
 
-.. autoclass:: pyttb.tensor
+.. automodule:: pyttb.tensor
     :members:
     :special-members:
-    :exclude-members: __dict__, __weakref__, __slots__, __init__
+    :exclude-members: __dict__, __weakref__, __slots__, __init__, mttv_left, mttv_mid, mttv_right, min_split
     :show-inheritance:
diff --git a/docs/source/tensor_classes.rst b/docs/source/tensor_classes.rst
@@ -2,14 +2,14 @@ Tensor Classes
 ==============
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
-    ktensor.rst
-    sptenmat.rst
-    sptensor.rst
-    sumtensor.rst
-    tensor.rst
-    ttensor.rst
-    tenmat.rst
-    pyttb_utils.rst
+    tensor
+    sptensor
+    ktensor
+    ttensor
+    sumtensor
+    tenmat
+    sptenmat
+    pyttb_utils
 
diff --git a/docs/source/tutorial/algorithm_cp_als.ipynb b/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."
    ]
   }
  ],

diff --git a/docs/source/tutorial/algorithm_gcp_opt.ipynb b/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",

diff --git a/docs/source/tutorial/algorithm_hosvd.ipynb b/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()`."
    ]
   },
   {

diff --git a/docs/source/tutorial/class_sptensor.ipynb b/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."
    ]
   },
   {

diff --git a/docs/source/tutorial/class_sumtensor.ipynb b/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."
    ]
   },
   {

diff --git a/docs/source/tutorial/class_tenmat.ipynb b/docs/source/tutorial/class_tenmat.ipynb
@@ -16,7 +16,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We show how to convert a `tensor` to a 2D numpy array stored with extra information so that it can be converted back to a `tensor`. Converting to a 2D numpy array requies an ordered mapping of the `tensor` indices to the rows and the columns of the 2D numpy array."
+    "We show how to convert a `tensor` to a 2D numpy array stored with extra information so that it can be converted back to a `tensor`. Converting to a 2D numpy array requires an ordered mapping of the `tensor` indices to the rows and the columns of the 2D numpy array."
    ]
   },
   {