This is PathSignatures.info, produced by Macaulay2, version 1.25.11

PathSignatures -- a package for working with signatures of algebraic paths
**************************************************************************

Description
===========

PathSignatures is a package for studying the signature of piecewise polynomial
paths.

The package heavily simplifies the process of obtaining data related to
signature varieties, e.g. as in [1] (see #ref1 ). See Computing Path Varieties.

A polynomial path is a path $X: [0,1] \to \mathbb R^d$ whose coordinate
functions are given by polynomials. A piecewise polynomial path is a path $X:
[0,1] \to \mathbb R^d$ which is polynomial on each interval in a partition of
$[0,1]$.

Given such a path $X$, its signature is the linear form $\sigma:
T((\mathbb{R}^d)^*)\rightarrow \mathbb{R}$ on the tensor algebra of the dual of
$\mathbb{R}^d$, whose image on a decomposable tensor $\alpha_1\otimes
\dots\otimes \alpha_k$ is the iterated integral $$ \alpha_1\otimes \dots\otimes
\alpha_k\overset{\sigma}{\mapsto}
\int_0^1\int_0^{t_k}\dots\int_0^{t_2}\partial(\alpha_1 X)\dots \partial
(\alpha_k X) d t_1\dots dt_k. $$ This form is invariant under translation,
reparametrization and tree-like equivalence of $X$ and characterizes $X$
uniquely up to these relations.

In this package, we identify $T((\mathbb{R}^d)^*)$ with the free associative
algebra over the alphabet $\{\texttt{1},\dots,\texttt{d}\}$ via $\texttt{i}
\mapsto e_i^*$ where $e_1^*, \dots, e_d^*$ is the dual of the canonical basis
of $\mathbb{R}^d$. For example, the word $\texttt{12}$ corresponds to $e_1^*
\otimes e_2^*$.

It is easy to create a polynomial path:

+-----------------------------------------------------------+
|i1 : R = QQ[t];                                            |
+-----------------------------------------------------------+
|i2 : X = polyPath({t + t^2, t^3})                          |
|                                                           |
|o2 = Path in 2-dimensional space with 1 polynomial segment:|
|                                                           |
|        2       3                                          |
|     {{t  + t, t }}                                        |
|                                                           |
|o2 : Path                                                  |
+-----------------------------------------------------------+

A piecewise polynomial path is obtained by concatenating polynomial paths:

+------------------------------------------------------------+
|i3 : Y = X ** X                                             |
|                                                            |
|o3 = Path in 2-dimensional space with 2 polynomial segments:|
|                                                            |
|        2       3     2       3                             |
|     {{t  + t, t }, {t  + t, t }}                           |
|                                                            |
|o3 : Path                                                   |
+------------------------------------------------------------+

Any NCPolynomialRing (NCAlgebra), can serve as a tensor
algebra. Use wordAlgebra, to quickly create one in variables
$\texttt{Lt}_i$. The package introduces a convenient notation for words in this
algebra.

+-----------------------------+
|i4 : A2 = wordAlgebra(2)     |
|                             |
|o4 = A2                      |
|                             |
|o4 : NCPolynomialRing        |
+-----------------------------+
|i5 : [1,2]_A2 -- the word 12.|
|                             |
|o5 = Lt Lt                   |
|       1  2                  |
|                             |
|o5 : A2                      |
+-----------------------------+

To evaluate the signature of $\mathtt{X}$ at a tensor $\mathtt{w}$, use
sig. The following computes the signed volume of the path; also see
sgnVolTensor.

+-----------------------------+
|i6 : sig(X,[1,2]_A2-[2,1]_A2)|
|                             |
|      7                      |
|o6 = --                      |
|     10                      |
|                             |
|o6 : QQ                      |
+-----------------------------+

See sig, can also be used to obtain the $k$-th level signature tensor.
Use wordFormat, or tensorArray, to display
the tensor in a nicer way.

+------------------------------------------------+
|i7 : T = sig(X,2)                               |
|                                                |
|     1   2 13       27           2              |
|o7 = -Lt  +--Lt Lt +--Lt Lt +2Lt                |
|     2  2  20  2  1 20  1  2    1               |
|                                                |
|o7 : QQ{Lt , Lt }                               |
|          1    2                                |
+------------------------------------------------+
|i8 : T // wordFormat                            |
|                                                |
|     1          13          27                  |
|o8 = - [2, 2] + -- [2, 1] + -- [1, 2] + 2 [1, 1]|
|     2          20          20                  |
+------------------------------------------------+
|i9 : T // tensorArray                           |
|                                                |
|                   27    13  1                  |
|o9 = {{0, 0}, {{2, --}, {--, -}}}               |
|                   20    20  2                  |
|                                                |
|o9 : List                                       |
+------------------------------------------------+

The package allows for the computation of signatures for parametrized families
of paths.

+-------------------------------------------------------------+
|i10 : S = QQ[a,b,c]                                          |
|                                                             |
|o10 = S                                                      |
|                                                             |
|o10 : PolynomialRing                                         |
+-------------------------------------------------------------+
|i11 : R = S[t]                                               |
|                                                             |
|o11 = R                                                      |
|                                                             |
|o11 : PolynomialRing                                         |
+-------------------------------------------------------------+
|i12 : X = polyPath({a*t+b*t^2,c*t^3})                        |
|                                                             |
|o12 = Path in 2-dimensional space with 1 polynomial segment: |
|                                                             |
|           2           3                                     |
|      {{b*t  + a*t, c*t }}                                   |
|                                                             |
|o12 : Path                                                   |
+-------------------------------------------------------------+
|i13 : Y = X ** X                                             |
|                                                             |
|o13 = Path in 2-dimensional space with 2 polynomial segments:|
|                                                             |
|           2           3       2           3                 |
|      {{b*t  + a*t, c*t }, {b*t  + a*t, c*t }}               |
|                                                             |
|o13 : Path                                                   |
+-------------------------------------------------------------+
|i14 : sig(X, sgnVolTensor(A2))                               |
|                                                             |
|      1       1                                              |
|o14 = -a*c + --b*c                                           |
|      4      10                                              |
|                                                             |
|o14 : S                                                      |
+-------------------------------------------------------------+

References
==========

[1] Améndola, C., Friz, P., & Sturmfels, B. (2019, January). Varieties of
signature tensors. In Forum of Mathematics, Sigma (Vol. 7, p. e10). Cambridge
University Press.

Authors
=======

  * Felix Lotter (see https://felixlotter.gitlab.io )
  * Oriol Reig
  * Angelo El Saliby
  * Carlos Amendola

Version
=======

This documentation describes version 1.0 of PathSignatures.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{PathSignaturesSource,                                                  |
|  title = {{PathSignatures: working with algebraic path signatures. Version~1|
|  author = {Felix Lotter and Oriol Reig and Angelo El Saliby and Carlos Amend|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/stable/M2/Macaulay2/packages}} |
|}                                                                            |
|-----------------------------------------------------------------------------|
|.0}},                                                                        |
|ola},                                                                        |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * NCPolynomialRing (NCAlgebra) -- Type of a
        noncommutative polynomial ring
      * NCRingElement (NCAlgebra) -- Type of an element in
        a noncommutative ring
      * Path
  * Functions and commands
      * adjointWord -- image of a word through the shuffle
        algebra homomorphism induced by a polynomial map
      * CAxisTensor -- the signature tensor of the
        canonical axis path at a given level
      * CMonTensor -- the signature tensor of the canonical
        monomial path at a given level
      * concatPath -- concatenation of paths
      * halfshuffle -- compute the half-shuffle of an
        ordered pair of words
      * inner -- compute the inner product of two tensors.
      * lie -- lie bracket of two elements
      * lieBasis -- basis element corresponding to a Lyndon
        word in a Lie algebra
      * linPath -- constructor of single piece polynomial path
      * lyndonShuffle -- compute the representation of a
        tensor as a shuffle polynomial in Lyndon words
      * lyndonWords -- compute all Lyndon words of at most
        a given length on a given number of letters
      * matrixAction -- Diagonal matrix action on a
        tensor.
      * "getCoefficientRing" -- see Path,
      * "getDimension" -- see Path,
      * "getNumberOfPieces" -- see Path,
      * "getPieces" -- see Path,
      * polyPath -- constructor of single piece polynomial
        path
      * pwLinPath -- constructor of a piecewise linear path
        from a matrix
      * sgnVolTensor -- The signed volume tensor in a free
        associative algebra.
      * shuffle -- shuffle product of two words
      * sig -- compute the signature of a piecewise polynomial
        path.
      * tensorArray -- k-th level component of a tensor.
      * tensorExp -- Compute a component of the exponential
        of a tensor.
      * tensorLog -- Compute a component of the logarithm of
        a tensor.
      * tensorParametrization -- Constructs the
        morphism that maps a word to its coefficient in the given tensor.
      * wordAlgebra -- create a free algebra over a given
        alphabet
      * wordFormat -- display a tensor in word notation
      * wordString -- a string representing a word in
        wordFormat
  * Methods
      * "adjointWord(NCRingElement,NCPolynomialRing,List)" -- see
        adjointWord, -- image of a word through the shuffle
        algebra homomorphism induced by a polynomial map
      * "ambient(NCPolynomialRing)" -- see ambient, -- exported
        from the NCALgebra package.
      * antipode(NCRingElement) -- The
        antipode of a tensor
      * Array _ NCPolynomialRing -- create a
        word from an array
      * "CAxisTensor(ZZ,NCPolynomialRing)" -- see CAxisTensor,
        -- the signature tensor of the canonical axis path at a
        given level
      * "CMonTensor(ZZ,NCPolynomialRing)" -- see CMonTensor,
        -- the signature tensor of the canonical monomial path at a given level
      * "concatPath(Path,Path)" -- see concatPath, --
        concatenation of paths
      * "Path ** Path" -- see concatPath, -- concatenation of
        paths
      * "halfshuffle(NCRingElement,NCRingElement)" -- see halfshuffle,
        -- compute the half-shuffle of an ordered pair of words
      * "NCRingElement >> NCRingElement" -- see halfshuffle,
        -- compute the half-shuffle of an ordered pair of words
      * "inner(NCRingElement,NCRingElement)" -- see inner, --
        compute the inner product of two tensors.
      * "NCRingElement @ NCRingElement" -- see inner, -- compute
        the inner product of two tensors.
      * "lieBasis(Array,NCPolynomialRing)" -- see lieBasis, --
        basis element corresponding to a Lyndon word in a Lie algebra
      * "lieBasis(List,NCPolynomialRing)" -- see lieBasis, --
        basis element corresponding to a Lyndon word in a Lie algebra
      * "linPath(List)" -- see linPath, -- constructor of single
        piece polynomial path
      * "lyndonShuffle(NCRingElement)" -- see lyndonShuffle,
        -- compute the representation of a tensor as a shuffle
        polynomial in Lyndon words
      * "lyndonWords(ZZ,ZZ)" -- see lyndonWords, -- compute
        all Lyndon words of at most a given length on a given number of letters
      * "Matrix * NCRingElement" -- see matrixAction, --
        Diagonal matrix action on a tensor.
      * "matrixAction(Matrix,NCRing,NCRing)" -- see matrixAction,
        -- Diagonal matrix action on a tensor.
      * "matrixAction(Matrix,NCRingElement,NCRing)" -- see matrixAction,
        -- Diagonal matrix action on a tensor.
      * "coefficientRing(Path)" -- see Path,
      * "dim(Path)" -- see Path,
      * "getCoefficientRing(Path)" -- see Path,
      * "getDimension(Path)" -- see Path,
      * "getNumberOfPieces(Path)" -- see Path,
      * "getPieces(Path)" -- see Path,
      * "net(Path)" -- see Path,
      * "Path ^ ZZ" -- see Path,
      * "Path _ List" -- see Path,
      * "Path _ Sequence" -- see Path,
      * "Path _ ZZ" -- see Path,
      * "polyPath(List)" -- see polyPath, -- constructor of
        single piece polynomial path
      * "pwLinPath(Matrix)" -- see pwLinPath, -- constructor
        of a piecewise linear path from a matrix
      * "sgnVolTensor(NCPolynomialRing)" -- see sgnVolTensor,
        -- The signed volume tensor in a free associative
        algebra.
      * "NCRingElement ** NCRingElement" -- see shuffle, --
        shuffle product of two words
      * "NCRingElement ⧢ NCRingElement" -- see shuffle, --
        shuffle product of two words
      * "shuffle(NCRingElement,NCRingElement)" -- see shuffle,
        -- shuffle product of two words
      * "sig(Path,List)" -- see sig, -- compute the signature of a
        piecewise polynomial path.
      * "sig(Path,NCRingElement)" -- see sig, -- compute the
        signature of a piecewise polynomial path.
      * "sig(Path,ZZ)" -- see sig, -- compute the signature of a
        piecewise polynomial path.
      * "sig(Path,ZZ,NCRing)" -- see sig, -- compute the signature
        of a piecewise polynomial path.
      * substitute(Path,Ring) -- changes
        the coefficient ring of a path
      * "NCRingElement @ ZZ" -- see tensorArray, -- k-th
        level component of a tensor.
      * "tensorArray(NCRingElement)" -- see tensorArray, --
        k-th level component of a tensor.
      * "tensorArray(NCRingElement,ZZ)" -- see tensorArray,
        -- k-th level component of a tensor.
      * "tensorExp(NCRingElement,ZZ)" -- see tensorExp, --
        Compute a component of the exponential of a tensor.
      * "tensorLog(NCRingElement,ZZ)" -- see tensorLog, --
        Compute a component of the logarithm of a tensor.
      * "tensorParametrization(NCRingElement)" -- see
        tensorParametrization, -- Constructs the
        morphism that maps a word to its coefficient in the given tensor.
      * "wordAlgebra(List)" -- see wordAlgebra, -- create a
        free algebra over a given alphabet
      * "wordAlgebra(ZZ)" -- see wordAlgebra, -- create a
        free algebra over a given alphabet
      * "wordFormat(NCRingElement)" -- see wordFormat, --
        display a tensor in word notation
      * "wordString(NCRingElement)" -- see wordString, -- a
        string representing a word in wordFormat
  * Symbols
      * "VarWordTable" -- see tensorParametrization,
        -- Constructs the morphism that maps a word to
        its coefficient in the given tensor.

For the programmer
==================

The object PathSignatures, is a package (Macaulay2Doc),
defined in PathSignatures.m2, with auxiliary files in
PathSignatures/.

-------------------------------------------------------------------------------

The source of this document is in PathSignatures.m2:337:0.

adjointWord -- image of a word through the shuffle algebra homomorphism induced by a polynomial map
***************************************************************************************************

  * Usage:
        adjointWord (g, T, L)
  * Inputs:
      * g, an instance of the type NCRingElement (NCAlgebra),
        the word to compute the image of;
      * T, an instance of the type NCPolynomialRing (NCAlgebra),
        the shuffle algebra of the image;
      * L, a list (Macaulay2Doc), the components of the polynomial
        map. each entry should be a polynomial;

Description
===========

This computes the image of g through the map $M_p$ described in Theorem 1 and
Theorem 7 of [1] (see #ref1 ). Its importance is evidenced by Theorem 2 of the
same paper:

Let $X:[0,1]\rightarrow \mathbb{R}^d$ be a piecewise continuously
differentiable path with $X(0) = 0$ and let $p : \mathbb{R}^n \rightarrow
\mathbb{R}^m$ be a polynomial map with $p(0) = 0$. Then, for all $w ∈
T(\mathbb{R}^m)$ one has $$  \sigma(p(X)) = M_p^*(\sigma(X))$$ (where
$\sigma(X)$ is the signature of $X$ and $M_p^*$ is the dual map of $M_p$).

As a use example, we verify this in a particular case. First we define a
transformation of affine spaces and create the word algebra where our tensors
live

+-----------------------------------------------------------------------------+
|i1 : S = QQ[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : p = {x^2,x*y,y^2} -- A map of affine spaces, the degree 2 Veronese      |
|                                                                             |
|       2        2                                                            |
|o2 = {x , x*y, y }                                                           |
|                                                                             |
|o2 : List                                                                    |
|-----------------------------------------------------------------------------|
|morphism R^2 -> R^3                                                          |
+-----------------------------------------------------------------------------+
|i3 : wA2 = wordAlgebra(2); -- signatures of paths in dimension 2             |
+-----------------------------------------------------------------------------+
|i4 : wA3 = wordAlgebra(3); -- signatures of paths in dimension 3             |
+-----------------------------------------------------------------------------+

Then we define a path in the domain space and explicitly compute its image
under the polynomial map above:

+--------------------------------------------------------------------+
|i5 : R = QQ[t];                                                     |
+--------------------------------------------------------------------+
|i6 : X = polyPath({t,t^2}) -- A path in 2 dimensional space         |
|                                                                    |
|o6 = Path in 2-dimensional space with 1 polynomial segment:         |
|                                                                    |
|           2                                                        |
|     {{t, t }}                                                      |
|                                                                    |
|o6 : Path                                                           |
+--------------------------------------------------------------------+
|i7 : PP = apply(p, q -> sub(q, {x=>t, y=>t^2}));                    |
+--------------------------------------------------------------------+
|i8 : Y = polyPath(PP) -- the transformed path in 3 dimensional space|
|                                                                    |
|o8 = Path in 3-dimensional space with 1 polynomial segment:         |
|                                                                    |
|        2   3   4                                                   |
|     {{t , t , t }}                                                 |
|                                                                    |
|o8 : Path                                                           |
+--------------------------------------------------------------------+

Finally we compute the signature of the transformed path along the
sgnVolTensor, tensor of $\mathbb{R}^3$ and verify the formula in
Theorem 2 above:

+-----------------------------------------------------------------------------+
|i9 : vol = sgnVolTensor(wA3); vol // wordFormat -- consider the signed volume|
|                                                                             |
|        1             1             1             1             1            |
|o10 = - - [3, 2, 1] + - [3, 1, 2] + - [2, 3, 1] - - [2, 1, 3] - - [1, 3, 2] +|
|        6             6             6             6             6            |
|      -----------------------------------------------------------------------|
|      1                                                                      |
|      - [1, 2, 3]                                                            |
|      6                                                                      |
|-----------------------------------------------------------------------------|
|in R^3 and display it in word format                                         |
+-----------------------------------------------------------------------------+
|i11 : adw = adjointWord(vol, wA2, p); adw // wordFormat -- we compute its ima|
|                                                                             |
|                               2                      2                      |
|o12 = - 2 [2, 2, 2, 1, 1, 1] + - [2, 2, 1, 2, 1, 1] + - [2, 2, 1, 1, 2, 1] + |
|                               3                      3                      |
|      -----------------------------------------------------------------------|
|      2                      2                      2                      2 |
|      - [2, 2, 1, 1, 1, 2] + - [2, 1, 2, 2, 1, 1] + - [2, 1, 2, 1, 2, 1] + - |
|      3                      3                      3                      3 |
|      -----------------------------------------------------------------------|
|                           2                      2                      2   |
|      [2, 1, 2, 1, 1, 2] - - [2, 1, 1, 2, 2, 1] - - [2, 1, 1, 2, 1, 2] - -   |
|                           3                      3                      3   |
|      -----------------------------------------------------------------------|
|                           2                      2                      2   |
|      [2, 1, 1, 1, 2, 2] + - [1, 2, 2, 2, 1, 1] + - [1, 2, 2, 1, 2, 1] + -   |
|                           3                      3                      3   |
|      -----------------------------------------------------------------------|
|                           2                      2                      2   |
|      [1, 2, 2, 1, 1, 2] - - [1, 2, 1, 2, 2, 1] - - [1, 2, 1, 2, 1, 2] - -   |
|                           3                      3                      3   |
|      -----------------------------------------------------------------------|
|                           2                      2                      2   |
|      [1, 2, 1, 1, 2, 2] - - [1, 1, 2, 2, 2, 1] - - [1, 1, 2, 2, 1, 2] - -   |
|                           3                      3                      3   |
|      -----------------------------------------------------------------------|
|      [1, 1, 2, 1, 2, 2] + 2 [1, 1, 1, 2, 2, 2]                              |
|-----------------------------------------------------------------------------|
|ge through the induced homomorphism on algebras                              |
+-----------------------------------------------------------------------------+
|i13 : sig(Y, vol)  -- the signed volume of the transformed path              |
|                                                                             |
|       1                                                                     |
|o13 = ---                                                                    |
|      630                                                                    |
|                                                                             |
|o13 : QQ                                                                     |
+-----------------------------------------------------------------------------+
|i14 : sig(X, adw)  -- is given by evaluating at adw for the original path.   |
|                                                                             |
|       1                                                                     |
|o14 = ---                                                                    |
|      630                                                                    |
|                                                                             |
|o14 : QQ                                                                     |
+-----------------------------------------------------------------------------+

References
==========

[1] Signatures of paths transformed by polynomial maps
(doi.org/10.1007/s13366-020-00493-9) (see
https://doi.org/10.1007/s13366-020-00493-9 )

Ways to use adjointWord:
========================

  * "adjointWord(NCRingElement,NCPolynomialRing,List)"

For the programmer
==================

The object adjointWord, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

ambient -- exported from the NCALgebra package.
***********************************************

Ways to use ambient:
====================

  * "ambient(NCPolynomialRing)"
  * ambient(GaloisField) (Macaulay2Doc), --
    corresponding quotient ring
  * ambient(Matrix) (Macaulay2Doc) -- get the map
    between the ambient free modules
  * ambient(Module) (Macaulay2Doc) -- ambient free
    module
  * ambient(NCQuotientRing) (NCAlgebra), --
    Ambient ring of an NCQuotientRing
  * ambient(NCRingMap) (NCAlgebra) -- Extends an
    NCRingMap to the ambient ring of the source.
  * "ambient(PolynomialRing)" -- see ambient(Ring) (Macaulay2Doc),
    -- ambient polynomial ring
  * "ambient(QuotientRing)" -- see ambient(Ring) (Macaulay2Doc),
    -- ambient polynomial ring
  * ambient(Ring) (Macaulay2Doc) -- ambient polynomial
    ring

For the programmer
==================

The object ambient (Macaulay2Doc), is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

antipode(NCRingElement) -- The antipode of a tensor
***************************************************

  * Function: antipode (Macaulay2Doc),

Description
===========

Consider a free associative algebra $\mathtt{R}$ on the letters $\mathtt{1},
\dots, \mathtt{d}$. We define the antipode map
$\mathtt{a}:\mathtt{R}\rightarrow \mathtt{R}$ first on a word
$w:=\mathtt{i_1}\cdot\dots \cdot\mathtt{i_k}$ to be $$ \mathtt{a}(w) := (-1)^k
\mathtt{i_k}\cdot\dots\cdot \mathtt{i_1}$$ and then extending it by linearity
to the whole algebra.

+----------------------------------------------+
|i1 : R = wordAlgebra(3)                       |
|                                              |
|o1 = R                                        |
|                                              |
|o1 : NCPolynomialRing                         |
+----------------------------------------------+
|i2 : f = [1,2,3]_R + 2* [3,2]_R; f//wordFormat|
|                                              |
|o3 = 2 [3, 2] + [1, 2, 3]                     |
+----------------------------------------------+
|i4 : antipode(f) //wordFormat                 |
|                                              |
|o4 = - [3, 2, 1] + 2 [2, 3]                   |
+----------------------------------------------+

Ways to use this method:
========================

  * antipode(NCRingElement) -- The antipode
    of a tensor
-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

Array _ NCPolynomialRing -- create a word from an array
*******************************************************

  * Operator: _ (Macaulay2Doc),
  * Usage:
        w = a_R
  * Inputs:
      * a, an array (Macaulay2Doc), In the form [i_1,...i_k] where
        0 < i_j< d+1, where d is the number of generators of R;
      * R, an instance of the type NCPolynomialRing (NCAlgebra),
  * Outputs:
      * w, an instance of the type NCRingElement (NCAlgebra),
        The element of R corresponding to
        R_(i_1)*...R_(i_k);

Description
===========

This method allows to create a monomial in a free associative algebra $R$. It
follows the same convention of wordFormat. Let $Lt_1,\dots,
Lt_d$ be the generators of $R$, then an array of integers $[i_1,\dots, i_k]$
such that $0<i_l<d+1, \forall 1\leq l\leq k$ yields the element $$Lt_{i_1}
Lt_{i_2}\cdot\dots\cdot Lt_{i_{k-1}} Lt_{i_k}$$ of $R$.

+-----------------------------------------------------------------------------+
|i1 : d = 5;                                                                  |
+-----------------------------------------------------------------------------+
|i2 : R = wordAlgebra(d); -- create a free associative algebra over Lt_1,..., |
|-----------------------------------------------------------------------------|
|Lt_d                                                                         |
+-----------------------------------------------------------------------------+
|i3 : a = new Array from for i from 1 to d list i; -- The array [1,...,d]     |
+-----------------------------------------------------------------------------+
|i4 : f = a_R  -- The word associated to a                                    |
|                                                                             |
|o4 = Lt Lt Lt Lt Lt                                                          |
|       1  2  3  4  5                                                         |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : g = product gens R -- The word Lt_1*...Lt_d                             |
|                                                                             |
|o5 = Lt Lt Lt Lt Lt                                                          |
|       1  2  3  4  5                                                         |
|                                                                             |
|o5 : R                                                                       |
+-----------------------------------------------------------------------------+
|i6 : f === product gens R                                                    |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * wordAlgebra -- create a free algebra over a given
    alphabet
  * wordFormat -- display a tensor in word notation

Ways to use this method:
========================

  * Array _ NCPolynomialRing -- create a
    word from an array
-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

CAxisTensor -- the signature tensor of the canonical axis path at a given level
*******************************************************************************

  * Usage:
        s = CAxisTensor(k, R)
  * Inputs:
      * k, an integer (Macaulay2Doc), the level of the signature
        tensor to compute;
      * R, an instance of the type NCPolynomialRing (NCAlgebra),
        the output tensor space;
  * Outputs:
      * s, an instance of the type NCRingElement (NCAlgebra),
        an element of R; the k-th level signature of
        the canonical axis path in $\mathbb R^d$, where $d$ is the number of
        generators of R;

Description
===========

The canonical axis path in $\mathbb{R}^d$ is the path from $(0, \dots, 0)$ to
$(1, \dots, 1)$ given by $d$ linear steps in the unit directions $e_1, \dots,
e_d$, in this order. The $k$-th level signature tensor of such a path has a
combinatorial closed-form description (see the reference below) and can be
obtained as follows:

+-----------------------------------------------------------------------------+
|i1 : d = 2;                                                                  |
+-----------------------------------------------------------------------------+
|i2 : k = 3;                                                                  |
+-----------------------------------------------------------------------------+
|i3 : R = wordAlgebra(d);                                                     |
+-----------------------------------------------------------------------------+
|i4 : Cd = CAxisTensor(k, R); Cd // wordFormat -- k-th level signature of the |
|                                                                             |
|     1             1             1             1                             |
|o5 = - [2, 2, 2] + - [1, 2, 2] + - [1, 1, 2] + - [1, 1, 1]                   |
|     6             2             2             6                             |
|-----------------------------------------------------------------------------|
|canonical axis path in R^d                                                   |
+-----------------------------------------------------------------------------+

To expand on the example, we verify that the result agrees with the one
obtained from sig. Notice that the matrix of increments for the
canonical axis path in dimension $d$ is the $d \times d$ identity matrix.

+---------------------------------------------------------------------------+
|i6 : M = id_(QQ^d); -- identity matrix                                     |
|                                                                           |
|              2       2                                                    |
|o6 : Matrix QQ  <-- QQ                                                     |
+---------------------------------------------------------------------------+
|i7 : CAxisPath = pwLinPath(M) -- the canonical axis path in dimension d    |
|                                                                           |
|o7 = Path in 2-dimensional space with 2 polynomial segments:               |
|                                                                           |
|     {{t, 0}, {0, t}}                                                      |
|                                                                           |
|o7 : Path                                                                  |
+---------------------------------------------------------------------------+
|i8 : Cd2 = sig(CAxisPath, k); Cd2 // wordFormat -- the k-th level signature|
|                                                                           |
|     1             1             1             1                           |
|o9 = - [2, 2, 2] + - [1, 2, 2] + - [1, 1, 2] + - [1, 1, 1]                 |
|     6             2             2             6                           |
+---------------------------------------------------------------------------+

References
==========

Varieties Of Signature Tensors (doi.org/10.1017/fms.2019.3) (see
https://doi.org/10.1017/fms.2019.3 )

Ways to use CAxisTensor:
========================

  * "CAxisTensor(ZZ,NCPolynomialRing)"

For the programmer
==================

The object CAxisTensor, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:1174:0.

CMonTensor -- the signature tensor of the canonical monomial path at a given level
**********************************************************************************

  * Usage:
        s = CAxisTensor(k, R)
  * Inputs:
      * k, an integer (Macaulay2Doc), the level of the signature
        tensor to compute;
      * R, an instance of the type NCPolynomialRing (NCAlgebra),
        the output tensor space;
  * Outputs:
      * s, an instance of the type NCRingElement (NCAlgebra),
        an element of R; the k-th level signature of
        the canonical monomial path in $\mathbb R^d$, where $d$ is the number
        of generators of R;

Description
===========

The canonical monomial path in $\mathbb{R}^d$ is the path from $(0, \dots, 0)$
to $(1, \dots, 1)$ given by $t\mapsto (t, t^2, \dots, t^d)$. Its $k$-th level
signature has a closed-form description (see the reference below) and can be
obtained as follows:

+-----------------------------------------------------------------------------+
|i1 : d = 2;                                                                  |
+-----------------------------------------------------------------------------+
|i2 : k = 3;                                                                  |
+-----------------------------------------------------------------------------+
|i3 : R = wordAlgebra(d);                                                     |
+-----------------------------------------------------------------------------+
|i4 : Cd = CMonTensor(k, R); Cd // wordFormat --k-th level signature of the ca|
|                                                                             |
|     1              1              2              1              4           |
|o5 = - [2, 2, 2] + -- [2, 2, 1] + -- [2, 1, 2] + -- [2, 1, 1] + -- [1, 2, 2] |
|     6             10             15             12             15           |
|     ------------------------------------------------------------------------|
|       1             1             1                                         |
|     + - [1, 2, 1] + - [1, 1, 2] + - [1, 1, 1]                               |
|       6             4             6                                         |
|-----------------------------------------------------------------------------|
|nonical monomial path in R^d                                                 |
+-----------------------------------------------------------------------------+

To expand on the example, we verify that the result agrees with the one
obtained from sig.

+-----------------------------------------------------------------------------+
|i6 : R=QQ[t];                                                                |
+-----------------------------------------------------------------------------+
|i7 : CMonPath = polyPath(for i from 1 to d list t^i) -- The canonical axis   |
|                                                                             |
|o7 = Path in 2-dimensional space with 1 polynomial segment:                  |
|                                                                             |
|           2                                                                 |
|     {{t, t }}                                                               |
|                                                                             |
|o7 : Path                                                                    |
|-----------------------------------------------------------------------------|
|path in dimension d                                                          |
+-----------------------------------------------------------------------------+
|i8 : Cd2 = sig(CMonPath, k); Cd2 // wordFormat --The k-th level signature    |
|                                                                             |
|     1              1              2              1              4           |
|o9 = - [2, 2, 2] + -- [2, 2, 1] + -- [2, 1, 2] + -- [2, 1, 1] + -- [1, 2, 2] |
|     6             10             15             12             15           |
|     ------------------------------------------------------------------------|
|       1             1             1                                         |
|     + - [1, 2, 1] + - [1, 1, 2] + - [1, 1, 1]                               |
|       6             4             6                                         |
+-----------------------------------------------------------------------------+

References
==========

Varieties Of Signature Tensors (doi.org/10.1017/fms.2019.3) (see
https://doi.org/10.1017/fms.2019.3 )

Ways to use CMonTensor:
=======================

  * "CMonTensor(ZZ,NCPolynomialRing)"

For the programmer
==================

The object CMonTensor, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:1174:0.

Computing Path Varieties
************************

See PathSignatures, simplifies the computation of varieties coming from
signature tensors. We showcase this in a number of examples:

-------------------------------------------------------------------------------

The source of this document is in PathSignatures.m2:337:0.

Polynomial paths of degree m
****************************

We reproduce a computation from [1] (see #ref1 ). We briefly recall the setting
for this computation. We are interested in paths $X:[0,1]\rightarrow
\mathbb{R}^\mathtt{d}$ whose coordinates are polynomials of degree
$\mathtt{m}$. These can be represented by a $\mathtt{d}\times \mathtt{m}$
matrix with real entries whose coordinates are determined by the expressions $$
X_i(t) = x_{i,1}t+x_{i,2}t^2+\dots+ x_{i,m}t^m$$ When we restrict to the
$\mathtt{k}$-th level signature of $X$, $\sigma:= \sigma^{(\mathtt{k})}(X)$,
each of its coordinates $\sigma_{i_1, \dots, i_{\mathtt{k}}}$ is a homogeneous
polynomial of degree $\mathtt{k}$ in the $\mathtt{d}\cdot \mathtt{m}$ unknowns
$x_{i,j}$ corresponding to the matrix representation of the path $X$. Let
$\mathtt{CMon}$ be the canonical monomial path in $\mathbb{R}^{\mathtt{m}}$
introduced in CMonTensor. Then $\sigma$ can be computed
through the matrixAction, of $X$ on
$\sigma^{(k)}(\mathtt{CMon})$. Moreover, we can view the entries of $X$ as
coordinates in the projective space $\mathbb{P}^{\mathtt{d}\cdot \mathtt{m}-1}$
over some algebraically closed field $\mathbb{K}$ containing $\mathbb{R}$. Then
the matrix action just described gives rise to a rational map $$
\sigma^{(\mathtt{k})}:\mathbb{P}^{\mathtt{d}\cdot \mathtt{m}-1}\rightarrow
\mathbb{P}^{\mathtt{d}^{\mathtt{k}}-1}$$ determined by $X\mapsto
\sigma^{(\mathtt{k})}(X)$, of degree $\mathtt{k}$. The polynomial signature
variety, denoted $\mathcal{P}_{\mathtt{d},\mathtt{k},\mathtt{m}}$, is then
defined to be the Zariski closure of the image of this map (informally, the
closure of the space of all tensors of order $\mathtt{k}$ that arise as
signatures of paths of the specified type), while its homogeneous prime ideal
is called polynomial signature ideal and denoted
$P_{{\mathtt{d},\mathtt{k},\mathtt{m}}}$.

We set up the procedure to compute the ideal
$P_{\mathtt{d},\mathtt{k},\mathtt{m}}$.

+-------------------------+
|i1 : d = 2; k = 3; m = 2;|
+-------------------------+

We create a ring $\mathtt{R}$ with $\mathtt{d}\cdot\mathtt{m}$ variables,
corresponding to the entries of a path. Then we create the free algebra
$\mathtt{A}$ over $\mathtt{R}$ with $\mathtt{m}$ generators, where we can
compute the $\mathtt{k}$-th level signature of the canonical monomial path in
$\mathbb{R}^{\mathtt{m}}$.

+-----------------------------------------------------------------------------+
|i4 : R = CC[x_1..x_(d*m)]; --x_1, ..., x_(d*m) are the entries of the degree |
|-----------------------------------------------------------------------------|
|m paths in d-dimensional space, seen as matrices                             |
+-----------------------------------------------------------------------------+
|i5 : A = wordAlgebra(m, CoefficientRing => R); --Signatures in m-dimensional |
|-----------------------------------------------------------------------------|
|space, where the signature of CMon lives.                                    |
+-----------------------------------------------------------------------------+
|i6 : sigmaCMon = CMonTensor(k, A); sigmaCMon // wordFormat -- The 2nd level s|
|                                                                             |
|o7 = .166667 [2, 2, 2] + .1 [2, 2, 1] + .133333 [2, 1, 2] + .0833333 [2, 1,  |
|     ------------------------------------------------------------------------|
|     1] + .266667 [1, 2, 2] + .166667 [1, 2, 1] + .25 [1, 1, 2] + .166667 [1,|
|     ------------------------------------------------------------------------|
|     1, 1]                                                                   |
|-----------------------------------------------------------------------------|
|ignature of CMon                                                             |
+-----------------------------------------------------------------------------+

Next we create the genericMatrix (Macaulay2Doc), with
$\mathtt{d}\times \mathtt{m}$ variables.

+--------------------------------+
|i8 : M = genericMatrix (R, d, m)|
|                                |
|o8 = | x_1 x_3 |                |
|     | x_2 x_4 |                |
|                                |
|             2      2           |
|o8 : Matrix R  <-- R            |
+--------------------------------+

Finally we compute the matrix action on $\sigma^{(k)}(\mathtt{CMon})$ with
Matrix * NCRingElement, and then compute the corresponding
map on rings using tensorParametrization.

+-----------------------------------------------------------------------------+
|i9 : f = M * sigmaCMon;                                                      |
+-----------------------------------------------------------------------------+
|i10 : sigVarietyParam = tensorParametrization(f, CoefficientRing => CC);     |
|                                                                             |
|o10 : RingMap R <-- CC  [b         , b         , b         , b         , b   |
|                      53  [2, 2, 2]   [2, 1, 1]   [2, 1, 2]   [1, 2, 2]   [1,|
|-----------------------------------------------------------------------------|
|     , b         , b         , b         ]                                   |
|2, 1]   [1, 1, 2]   [1, 1, 1]   [2, 2, 1]                                    |
+-----------------------------------------------------------------------------+

Now that we have the map, any tool for implicitization can be used. We compute
its dimension and degree with NumericalImplicitization.

+-----------------------------------------------------------------------+
|i11 : needsPackage "NumericalImplicitization";                         |
+-----------------------------------------------------------------------+
|i12 : numericalImageDim(sigVarietyParam,ideal 0_R)                     |
|                                                                       |
|o12 = 4                                                                |
+-----------------------------------------------------------------------+
|i13 : numericalImageDegree(sigVarietyParam,ideal 0_R, Verbose => false)|
|                                                                       |
|o13 = 6                                                                |
+-----------------------------------------------------------------------+

This agrees with the result in Table 3 of [1] (see #ref1 ), where dimension and
degree of the corresponding projective variety is computed.

References
==========

[1] Améndola, C., Friz, P., & Sturmfels, B. (2019, January). Varieties of
signature tensors. In Forum of Mathematics, Sigma (Vol. 7, p. e10). Cambridge
University Press.

-------------------------------------------------------------------------------

The source of this document is in PathSignatures.m2:337:0.

A family of paths on a cone
***************************

We consider the following family of polynomial paths of degree 6:

+-------------------------------------------------+
|i1 : S = QQ[a_1..a_6]                            |
|                                                 |
|o1 = S                                           |
|                                                 |
|o1 : PolynomialRing                              |
+-------------------------------------------------+
|i2 : R = S[t]                                    |
|                                                 |
|o2 = R                                           |
|                                                 |
|o2 : PolynomialRing                              |
+-------------------------------------------------+
|i3 : u = a_1*t + a_2*t^2 + a_3*t^3;              |
+-------------------------------------------------+
|i4 : v = a_4*t + a_5*t^2 + a_6*t^3;              |
+-------------------------------------------------+
|i5 : X = polyPath({u^2 - v^2, 2*u*v, u^2 + v^2});|
+-------------------------------------------------+

Let us take a look at its signature matrix variety. We obtain its
parametrization as follows:

+-----------------------------------------------------------------------------+
|i6 : sigMatrix = sig(X,2);                                                   |
+-----------------------------------------------------------------------------+
|i7 : S = QQ[s_(1,1)..s_(3,3)]                                                |
|                                                                             |
|o7 = S                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : vwtable = hashTable apply(gens S, i-> (i, new Array from last baseName  |
|                                                                             |
|o8 = HashTable{s    => [1, 1]}                                               |
|                1,1                                                          |
|               s    => [1, 2]                                                |
|                1,2                                                          |
|               s    => [1, 3]                                                |
|                1,3                                                          |
|               s    => [2, 1]                                                |
|                2,1                                                          |
|               s    => [2, 2]                                                |
|                2,2                                                          |
|               s    => [2, 3]                                                |
|                2,3                                                          |
|               s    => [3, 1]                                                |
|                3,1                                                          |
|               s    => [3, 2]                                                |
|                3,2                                                          |
|               s    => [3, 3]                                                |
|                3,3                                                          |
|                                                                             |
|o8 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|i))                                                                          |
+-----------------------------------------------------------------------------+
|i9 : m = tensorParametrization(sigMatrix, VarWordTable => vwtable);          |
|                                                                             |
|o9 : RingMap QQ[a ..a ] <-- S                                                |
|                 1   6                                                       |
+-----------------------------------------------------------------------------+

Let us use numericalImplicitization to obtain information about the dimension
of the image.

+-----------------------------------------------------------------------------+
|i10 : needsPackage "NumericalImplicitization";                               |
+-----------------------------------------------------------------------------+
|i11 : Snum = CC[a_1..a_6];                                                   |
+-----------------------------------------------------------------------------+
|i12 : Rnum = Snum[t];                                                        |
+-----------------------------------------------------------------------------+
|i13 : unum = sub(u, Rnum);                                                   |
+-----------------------------------------------------------------------------+
|i14 : vnum = sub(v, Rnum);                                                   |
+-----------------------------------------------------------------------------+
|i15 : Xnum = polyPath({unum^2 - vnum^2, 2*unum*vnum, unum^2 + vnum^2});      |
+-----------------------------------------------------------------------------+
|i16 : sigMatrixnum = sig(Xnum,2);                                            |
+-----------------------------------------------------------------------------+
|i17 : mnum = tensorParametrization(sigMatrixnum,CoefficientRing => CC);      |
|                                                                             |
|o17 : RingMap Snum <-- CC  [b      , b      , b      , b      , b      , b   |
|                         53  [2, 3]   [2, 2]   [3, 2]   [3, 1]   [2, 1]   [3,|
|-----------------------------------------------------------------------------|
|  , b      , b      , b      ]                                               |
|3]   [1, 3]   [1, 1]   [1, 2]                                                |
+-----------------------------------------------------------------------------+
|i18 : numericalImageDim(mnum,ideal 0_Snum)                                   |
|                                                                             |
|o18 = 5                                                                      |
+-----------------------------------------------------------------------------+

The universal variety has dimension 6, so we expect at least one additional
relation. We use MultigradedImplicitization:

+-----------------------------------------------------------------------------+
|i19 : needsPackage "MultigradedImplicitization";                             |
+-----------------------------------------------------------------------------+
|i20 : I = sub(ideal flatten values componentsOfKernel(2, m, Grading =>       |
|warning: computation begun over finite field. resulting polynomials may      |
|computing total degree: 1                                                    |
|number of monomials = 9                                                      |
|number of distinct multidegrees = 1                                          |
| -- .0123958s elapsed                                                        |
|WARNING: There are linear relations. You may want to reduce the number       |
|computing total degree: 2                                                    |
|number of monomials = 45                                                     |
|number of distinct multidegrees = 1                                          |
| -- .724834s elapsed                                                         |
|                                                                             |
|o20 : Ideal of S                                                             |
|-----------------------------------------------------------------------------|
|matrix {toList(9:1)}), S);                                                   |
| not lie in the ideal                                                        |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|of variables to speed up the computation.                                    |
+-----------------------------------------------------------------------------+
|i21 : dim I                                                                  |
|                                                                             |
|o21 = 5                                                                      |
+-----------------------------------------------------------------------------+
|i22 : isPrime I                                                              |
|                                                                             |
|o22 = true                                                                   |
+-----------------------------------------------------------------------------+
|i23 : betti mingens I                                                        |
|                                                                             |
|             0 1                                                             |
|o23 = total: 1 7                                                             |
|          0: 1 1                                                             |
|          1: . 6                                                             |
|                                                                             |
|o23 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i24 : degree I                                                               |
|                                                                             |
|o24 = 4                                                                      |
+-----------------------------------------------------------------------------+

We conclude that our variety is cut out by one linear relation and 6 quadrics.
Let us take a look at the linear relation:

+-----------------------------------------------------------------+
|i25 : lin = select(flatten entries gens I, i-> (degree i == {1}))|
|                                                                 |
|o25 = {- s    - s    + s   }                                     |
|          1,1    2,2    3,3                                      |
|                                                                 |
|o25 : List                                                       |
+-----------------------------------------------------------------+

We recognize it as a shuffle polynomial in the letters
$\mathtt{1},\mathtt{2},\mathtt{3}$. It corresponds to the constraint $X(1) -
X(0) \in V(x^2 + y^2 - z^2)$ for paths in our family.

Recall that the universal variety is cut out by the 2-minors of the symmetric
part of the matrix. We check if the linear relation is the only additional one
on our path family:

+------------------------------------------+
|i26 : A = genericMatrix(S,3,3)            |
|                                          |
|o26 = | s_(1,1) s_(2,1) s_(3,1) |         |
|      | s_(1,2) s_(2,2) s_(3,2) |         |
|      | s_(1,3) s_(2,3) s_(3,3) |         |
|                                          |
|              3      3                    |
|o26 : Matrix S  <-- S                     |
+------------------------------------------+
|i27 : univI = minors(2, A + transpose(A));|
|                                          |
|o27 : Ideal of S                          |
+------------------------------------------+
|i28 : I == univI + ideal lin              |
|                                          |
|o28 = true                                |
+------------------------------------------+
-------------------------------------------------------------------------------

The source of this document is in PathSignatures.m2:337:0.

The universal variety and toric coordinates
*******************************************

Recall that $K \langle \mathtt{1}, \ldots, \mathtt{d} \rangle$ is isomorphic to
the free commutative algebra over the Lyndon words and if we grade each word by
its length, the algebra homomorphism $$\phi: K[\mathtt{w} \ | \ \mathtt{w} \
\mathrm{Lyndon}] \cong K \langle \mathtt{1}, \ldots, \mathtt{d} \rangle, \
\mathtt{w} \mapsto \mathtt{w}$$ is an isomorphism of graded vector spaces. The
inverse $\psi$ of this isomorphism is computed by lyndonShuffle.
Dually, we have the isomorphism of graded vector spaces
$$\psi^*: K[\mathtt{w} \ | \ \mathtt{w} \ \mathrm{Lyndon}]^* \cong K \langle
\mathtt{1}, \ldots, \mathtt{d} \rangle^*, \ \alpha \mapsto \alpha \circ \psi.$$

We view the two vector spaces $K\langle \mathtt{1}, \ldots,
\mathtt{d}\rangle^*$ and $K[\mathtt{w} \ | \ \mathtt{w} \ \mathrm{Lyndon}]^*$
as infinite-dimensional affine spaces. We are interested in the subset
$\mathcal U_d$ of those points of $K\langle \mathtt{1}, \ldots,
\mathtt{d}\rangle^*$ that define shuffle algebra homomorphisms. This is a
Zariski closed set. As $\psi$ is an algebra homomorphism, they correspond to
the points of $K[\mathtt{w} \ | \ \mathtt{w} \ \mathrm{Lyndon}]^*$ under
$\psi^*$ that define algebra homomorphisms; these are parametrized by the
points of the vector space $K^{\mathcal L}$, where $\mathcal L$ is the set of
Lyndon words, via the map $$\eta: K^{\mathcal L} \to K[\mathtt{w} \ | \
\mathtt{w} \ \mathrm{Lyndon}]^*, \ x \mapsto ev_x.$$ In particular, $\mathcal
U_d$ is parametrized by $\psi^* \circ \eta, \ x \mapsto (\mathtt{w} \mapsto
\psi(\mathtt{w})(x))$.

Projecting $\mathcal U_d$ to the degree $k$ component, we obtain a subvariety
of $((K^d)^{\otimes k})^* \cong (K^d)^{\otimes k}$, called the universal
variety, $\mathcal U_{d,k}$.

As the map $\psi$ is compatible with the projection, $\psi^* \circ \eta$
restricts to a parametrization of $\mathcal U_{d,k}$: it is the image of the
induced morphism $$K^{\mathcal L_k} \to (K\langle \mathtt{1}, \ldots,
\mathtt{d}\rangle_k)^* \cong (K^d)^{\otimes k}, \ x \mapsto
(\psi(\mathtt{w})(x) \cdot \mathtt{w})$$ where $\mathcal L_k$ is the set of
Lyndon words of length at most $k$.

As usual, we can compute the ideal that cuts out the image variety as the
kernel of the corresponding ring map $$K[x_{\mathtt w} \ | \ \mathtt{w} \text{
of length } k] \to K[y_{\mathtt w} \ | \ \mathtt{w} \text{ Lyndon of length }
\leq k].$$ This map can be computed via lyndonShuffle.
Let us do this in the example $d=3, k=3$.

+-----------------------------------------------------------------------------+
|i1 : words = toList apply((3:1)..(3:3), i -> new Array from i);              |
+-----------------------------------------------------------------------------+
|i2 : lwords = lyndonWords(3,3)                                               |
|                                                                             |
|o2 = {[1], [1, 1, 2], [1, 1, 3], [1, 2], [1, 2, 2], [1, 2, 3], [1, 3], [1, 3,|
|     ------------------------------------------------------------------------|
|     2], [1, 3, 3], [2], [2, 2, 3], [2, 3], [2, 3, 3], [3]}                  |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : R = QQ new Array from apply(words, i->x_i);                             |
+-----------------------------------------------------------------------------+
|i4 : Q = QQ new Array from (apply(lwords,i->y_i) | {Degrees => apply(lwords, |
|-----------------------------------------------------------------------------|
|i->length(i))});                                                             |
+-----------------------------------------------------------------------------+
|i5 : A3 = wordAlgebra(3);                                                    |
+-----------------------------------------------------------------------------+
|i6 : lpolyHT = apply(words, i -> lyndonShuffle(i_A3));                       |
+-----------------------------------------------------------------------------+
|i7 : lpols = apply(lpolyHT, f -> sum(pairs f, (term,coef) -> coef *          |
|-----------------------------------------------------------------------------|
|product(pairs term, (word,ex)-> y_word^ex)));                                |
+-----------------------------------------------------------------------------+
|i8 : lpols_{0..4}                                                            |
|                                                                             |
|      1 3                                                                    |
|o8 = {-y   , y         , y         , - 2y          + y   y      , y         }|
|      6 [1]   [1, 1, 2]   [1, 1, 3]      [1, 1, 2]    [1] [1, 2]   [1, 2, 2] |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : m = map(Q,R,lpols);                                                     |
|                                                                             |
|o9 : RingMap Q <-- R                                                         |
+-----------------------------------------------------------------------------+

Let us compute the kernel.

+-----------------------------------------------------------------------------+
|i10 : I = ker m;                                                             |
|                                                                             |
|o10 : Ideal of R                                                             |
+-----------------------------------------------------------------------------+
|i11 : dim I                                                                  |
|                                                                             |
|o11 = 14                                                                     |
+-----------------------------------------------------------------------------+
|i12 : degree I                                                               |
|                                                                             |
|o12 = 24                                                                     |
+-----------------------------------------------------------------------------+
|i13 : betti mingens I                                                        |
|                                                                             |
|             0  1                                                            |
|o13 = total: 1 81                                                            |
|          0: 1  .                                                            |
|          1: . 81                                                            |
|                                                                             |
|o13 : BettiTally                                                             |
+-----------------------------------------------------------------------------+
|i14 : (mingens I)_(0,0)                                                      |
|                                                                             |
|                              2                                              |
|o14 = x         x          + x          + 2x         x          + 3x         |
|       [2, 3, 3] [3, 2, 3]    [3, 2, 3]     [2, 3, 3] [3, 3, 2]     [3, 2,   |
|      -----------------------------------------------------------------------|
|                       2                                                     |
|        x          + 2x          - 3x         x          - 6x         x      |
|      3] [3, 3, 2]     [3, 3, 2]     [2, 3, 2] [3, 3, 3]     [3, 2, 2] [3, 3,|
|      -----------------------------------------------------------------------|
|      3]                                                                     |
|                                                                             |
|o14 : R                                                                      |
+-----------------------------------------------------------------------------+

This agrees with the result in Table 2 of [1] (see #ref1 ).

As $\phi$ is an isomorphism of graded vector spaces, we see that the variety
$\mathcal U_{d,k}$ is parametrized by the vector of degree $k$ monomials in
Lyndon words after a linear coordinate change on $(K^d)^{\otimes k}$. We can
use this to simplify the computation of the universal variety.

+----------------------------------------+
|i15 : mons = flatten entries basis(3,Q);|
+----------------------------------------+
|i16 : S = QQ[z_1..z_(length mons)];     |
+----------------------------------------+
|i17 : m = map(Q,S,mons);                |
|                                        |
|o17 : RingMap Q <-- S                   |
+----------------------------------------+
|i18 : I = ker m;                        |
|                                        |
|o18 : Ideal of S                        |
+----------------------------------------+
|i19 : dim I                             |
|                                        |
|o19 = 14                                |
+----------------------------------------+
|i20 : degree I                          |
|                                        |
|o20 = 24                                |
+----------------------------------------+
|i21 : betti mingens I                   |
|                                        |
|             0  1                       |
|o21 = total: 1 81                       |
|          0: 1  .                       |
|          1: . 81                       |
|                                        |
|o21 : BettiTally                        |
+----------------------------------------+

Let us compute the matrix of the coordinate change for $d=2, k=4$.

+-----------------------------------------------------------------------------+
|i22 : words = toList apply((4:1)..(4:2), i-> new Array from i);              |
+-----------------------------------------------------------------------------+
|i23 : lwords = lyndonWords(2,4);                                             |
+-----------------------------------------------------------------------------+
|i24 : R = QQ new Array from apply(words,i->x_i);                             |
+-----------------------------------------------------------------------------+
|i25 : Q = QQ new Array from (apply(lwords,i->y_i) | {Degrees => apply(lwords,|
|-----------------------------------------------------------------------------|
|i->length(i))});                                                             |
+-----------------------------------------------------------------------------+
|i26 : A2 = wordAlgebra(2);                                                   |
+-----------------------------------------------------------------------------+
|i27 : lpolyHT = apply(words, i -> lyndonShuffle(i_A2));                      |
+-----------------------------------------------------------------------------+
|i28 : lpols = apply(lpolyHT, f -> sum(pairs f, (term,coef) -> coef *         |
|-----------------------------------------------------------------------------|
|product(pairs term, (word,ex)-> y_word^ex)));                                |
+-----------------------------------------------------------------------------+
|i29 : mons = basis(4,Q)                                                      |
|                                                                             |
|o29 = | y_[1]^4 y_[1]^3y_[2] y_[1]^2y_[1, 2] y_[1]^2y_[2]^2 y_[1]y_[1, 1, 2] |
|      -----------------------------------------------------------------------|
|      y_[1]y_[1, 2]y_[2] y_[1]y_[1, 2, 2] y_[1]y_[2]^3 y_[1, 1, 1, 2] y_[1,  |
|      -----------------------------------------------------------------------|
|      1, 2]y_[2] y_[1, 1, 2, 2] y_[1, 2]^2 y_[1, 2]y_[2]^2 y_[1, 2, 2]y_[2]  |
|      -----------------------------------------------------------------------|
|      y_[1, 2, 2, 2] y_[2]^4 |                                               |
|                                                                             |
|              1      16                                                      |
|o29 : Matrix Q  <-- Q                                                        |
+-----------------------------------------------------------------------------+
|i30 : M = sub(matrix apply(lpols, i -> (flatten entries (coefficients(i,     |
|                                                                             |
|o30 = | 1/24 0   0    0   0  0  0  0   0  0  0  0    0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   1  0  0  0    0    0  0  0    |       |
|      | 0    0   0    0   1  0  0  0   -3 0  0  0    0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  1  0    0    0  0  0    |       |
|      | 0    0   1/2  0   -2 0  0  0   3  0  0  0    0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  -2 1/2  0    0  0  0    |       |
|      | 0    0   0    0   0  0  1  0   0  0  0  -1/2 0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  0  0    0    0  1  0    |       |
|      | 0    1/6 -1/2 0   1  0  0  0   -1 0  0  0    0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  1  0  -1/2 0    0  0  0    |       |
|      | 0    0   0    0   0  1  -2 0   0  -2 2  1/2  0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  0  0    0    1  -3 0    |       |
|      | 0    0   0    1/4 0  -1 1  0   0  1  -1 0    0    0  0  0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  0  0    1/2  -2 3  0    |       |
|      | 0    0   0    0   0  0  0  1/6 0  0  0  0    -1/2 1  -1 0    |       |
|      | 0    0   0    0   0  0  0  0   0  0  0  0    0    0  0  1/24 |       |
|                                                                             |
|               16       16                                                   |
|o30 : Matrix QQ   <-- QQ                                                     |
|-----------------------------------------------------------------------------|
|Monomials => mons))#1) ),QQ)                                                 |
+-----------------------------------------------------------------------------+
|i31 : M^(-1)                                                                 |
|                                                                             |
|o31 = | 24 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  6 6 0 6 0 0 0 6 0 0 0 0 0 0 0  |                                  |
|      | 0  6 4 0 2 0 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 4 0 4 4 0 0 4 4 0 4 0 0 0  |                                  |
|      | 0  3 1 0 0 0 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 4 0 3 2 0 0 2 1 0 0 0 0 0  |                                  |
|      | 0  0 0 2 0 1 1 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 0 0 0 0 6 0 0 0 6 0 6 6 0  |                                  |
|      | 0  1 0 0 0 0 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 2 0 1 0 0 0 1 0 0 0 0 0 0  |                                  |
|      | 0  0 0 1 0 0 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 4 0 2 0 0 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 0 0 0 0 6 0 0 0 4 0 2 0 0  |                                  |
|      | 0  0 0 0 0 0 0 3 0 0 0 1 0 0 0 0  |                                  |
|      | 0  0 0 0 0 0 0 1 0 0 0 0 0 0 0 0  |                                  |
|      | 0  0 0 0 0 0 0 0 0 0 0 0 0 0 0 24 |                                  |
|                                                                             |
|               16       16                                                   |
|o31 : Matrix QQ   <-- QQ                                                     |
+-----------------------------------------------------------------------------+

Note that the coordinate change differs from the one described in Example 21 of
[2] (see #ref2 ) as our toric parametrization does not arise from the
exponential map on the Lie algebra. We can easily construct this coordinate
change as well, by using lieBasis, and tensorExp,:

+-----------------------------------------------------------------------------+
|i32 : A2 = wordAlgebra(2, CoefficientRing => Q)                              |
|                                                                             |
|o32 = A2                                                                     |
|                                                                             |
|o32 : NCPolynomialRing                                                       |
+-----------------------------------------------------------------------------+
|i33 : lbasis = apply(lwords, i -> lieBasis(i,A2));                           |
+-----------------------------------------------------------------------------+
|i34 : lT = sum(0..length(lbasis)-1, i-> Q_i * lbasis_i);                     |
+-----------------------------------------------------------------------------+
|i35 : gT = tensorExp(lT,4);                                                  |
+-----------------------------------------------------------------------------+
|i36 : lpols = apply(words, i-> gT @ i_A2)                                    |
|                                                                             |
|        1 4                    1                 1 2             1 3         |
|o36 = {--y   , y             + -y   y          + -y   y       + --y   y   , -|
|       24 [1]   [1, 1, 1, 2]   2 [1] [1, 1, 2]   6 [1] [1, 2]   24 [1] [2]   |
|      -----------------------------------------------------------------------|
|                       1                  1 3                                |
|      3y             - -y   y          + --y   y   , y             +         |
|        [1, 1, 1, 2]   2 [1] [1, 1, 2]   24 [1] [2]   [1, 1, 2, 2]           |
|      -----------------------------------------------------------------------|
|      1                 1                 1                   1 2   2        |
|      -y   y          + -y         y    + -y   y      y    + --y   y   ,     |
|      2 [1] [1, 2, 2]   2 [1, 1, 2] [2]   6 [1] [1, 2] [2]   24 [1] [2]      |
|      -----------------------------------------------------------------------|
|                       1                  1 3                           1 2  |
|      3y             - -y   y          + --y   y   , - 2y             + -y   |
|        [1, 1, 1, 2]   2 [1] [1, 1, 2]   24 [1] [2]      [1, 1, 2, 2]   2 [1,|
|      -----------------------------------------------------------------------|
|                                             1                   1 2   2     |
|         - y   y          - y         y    + -y   y      y    + --y   y   , -|
|      2]    [1] [1, 2, 2]    [1, 1, 2] [2]   6 [1] [1, 2] [2]   24 [1] [2]   |
|      -----------------------------------------------------------------------|
|      1 2                          1 2   2                    1              |
|      -y       + y   y          + --y   y   , y             + -y         y   |
|      2 [1, 2]    [1] [1, 2, 2]   24 [1] [2]   [1, 2, 2, 2]   2 [1, 2, 2] [2]|
|      -----------------------------------------------------------------------|
|        1        2      1     3                      1                       |
|      + -y      y    + --y   y   , - y             + -y   y          -       |
|        6 [1, 2] [2]   24 [1] [2]     [1, 1, 1, 2]   2 [1] [1, 1, 2]         |
|      -----------------------------------------------------------------------|
|      1 2             1 3          1 2                          1 2   2      |
|      -y   y       + --y   y   , - -y       + y         y    + --y   y   ,   |
|      6 [1] [1, 2]   24 [1] [2]    2 [1, 2]    [1, 1, 2] [2]   24 [1] [2]    |
|      -----------------------------------------------------------------------|
|                       1 2                                          1        |
|      2y             + -y       - y   y          - y         y    - -y   y   |
|        [1, 1, 2, 2]   2 [1, 2]    [1] [1, 2, 2]    [1, 1, 2] [2]   6 [1] [1,|
|      -----------------------------------------------------------------------|
|                1 2   2                       1                  1     3     |
|        y    + --y   y   , - 3y             - -y         y    + --y   y   , -|
|      2] [2]   24 [1] [2]      [1, 2, 2, 2]   2 [1, 2, 2] [2]   24 [1] [2]   |
|      -----------------------------------------------------------------------|
|                      1                 1                 1                  |
|      y             + -y   y          + -y         y    - -y   y      y    + |
|       [1, 1, 2, 2]   2 [1] [1, 2, 2]   2 [1, 1, 2] [2]   6 [1] [1, 2] [2]   |
|      -----------------------------------------------------------------------|
|       1 2   2                     1                  1     3                |
|      --y   y   , 3y             - -y         y    + --y   y   , - y         |
|      24 [1] [2]    [1, 2, 2, 2]   2 [1, 2, 2] [2]   24 [1] [2]     [1, 2, 2,|
|      -----------------------------------------------------------------------|
|           1                 1        2      1     3     1 4                 |
|         + -y         y    - -y      y    + --y   y   , --y   }              |
|      2]   2 [1, 2, 2] [2]   6 [1, 2] [2]   24 [1] [2]  24 [2]               |
|                                                                             |
|o36 : List                                                                   |
+-----------------------------------------------------------------------------+
|i37 : M = sub(matrix apply(lpols, i -> (flatten entries (coefficients(i,     |
|                                                                             |
|               16       16                                                   |
|o37 : Matrix QQ   <-- QQ                                                     |
|-----------------------------------------------------------------------------|
|Monomials => mons))#1) ),QQ);                                                |
+-----------------------------------------------------------------------------+
|i38 : M^(-1)                                                                 |
|                                                                             |
|o38 = | 24 0   0    0   0    0    0    0   0   0    0    0    0    0    0    |
|      | 0  6   6    0   6    0    0    0   6   0    0    0    0    0    0    |
|      | 0  3   1    0   -1   0    0    0   -3  0    0    0    0    0    0    |
|      | 0  0   0    4   0    4    4    0   0   4    4    0    4    0    0    |
|      | 0  1/2 -1/2 0   -1/2 0    0    0   1/2 0    0    0    0    0    0    |
|      | 0  0   0    2   0    1    0    0   0   0    -1   0    -2   0    0    |
|      | 0  0   0    1/3 0    -1/6 1/3  0   0   -2/3 -1/6 0    1/3  0    0    |
|      | 0  0   0    0   0    0    0    6   0   0    0    6    0    6    6    |
|      | 0  0   -1/6 0   1/6  0    0    0   0   0    0    0    0    0    0    |
|      | 0  0   0    1/3 0    -1/6 -2/3 0   0   1/3  -1/6 0    1/3  0    0    |
|      | 0  0   0    1/6 0    -1/6 0    0   0   0    1/6  0    -1/6 0    0    |
|      | 0  0   0    1   0    0    -1   0   0   -1   0    0    1    0    0    |
|      | 0  0   0    0   0    0    0    3   0   0    0    1    0    -1   -3   |
|      | 0  0   0    0   0    0    0    1/2 0   0    0    -1/2 0    -1/2 1/2  |
|      | 0  0   0    0   0    0    0    0   0   0    0    -1/6 0    1/6  0    |
|      | 0  0   0    0   0    0    0    0   0   0    0    0    0    0    0    |
|      -----------------------------------------------------------------------|
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      0  |                                                                   |
|      24 |                                                                   |
|                                                                             |
|               16       16                                                   |
|o38 : Matrix QQ   <-- QQ                                                     |
+-----------------------------------------------------------------------------+

This is the matrix from Example 21 in [2] (see #ref2 ). Note that while we
obtained the coordinate change by inverting the map that sends a word to its
coefficient in the exponential (which is a linear combination of Lyndon word
monomials), in [2] (see #ref2 ) the coordinate change is obtained directly
without computing the exponential. Both strategies yield the same result by
Lemma 18 in loc. cit..

References
==========

[1] Améndola, C., Friz, P., & Sturmfels, B. (2019, January). Varieties of
signature tensors. In Forum of Mathematics, Sigma (Vol. 7, p. e10). Cambridge
University Press.

[2] Galuppi, F. (2019). The rough Veronese variety. Linear algebra and its
applications, 583, 282-299.

-------------------------------------------------------------------------------

The source of this document is in PathSignatures.m2:337:0.

concatPath -- concatenation of paths
************************************

  * Usage:
        concatPath(X,Y)
        X**Y

Description
===========

This allows for concatenation of paths. The concatenation is formal, no
parametrization is chosen.

+------------------------------------------------------------+
|i1 : R = QQ[t];                                             |
+------------------------------------------------------------+
|i2 : X = polyPath({t,t^2}) ** polyPath({t^3 + 3*t, t^2 - 1})|
|                                                            |
|o2 = Path in 2-dimensional space with 2 polynomial segments:|
|                                                            |
|           2     3        2                                 |
|     {{t, t }, {t  + 3t, t }}                               |
|                                                            |
|o2 : Path                                                   |
+------------------------------------------------------------+

See also
========

  * polyPath -- constructor of single piece polynomial path
  * linPath -- constructor of single piece polynomial path

Ways to use concatPath:
=======================

  * "concatPath(Path,Path)"

For the programmer
==================

The object concatPath, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

halfshuffle -- compute the half-shuffle of an ordered pair of words
*******************************************************************

  * Usage:
        h = f >> g
  * Inputs:
      * f, an instance of the type NCRingElement (NCAlgebra),
      * g, an instance of the type NCRingElement (NCAlgebra),
  * Outputs:
      * h, an instance of the type NCRingElement (NCAlgebra),
        the half-shuffle f>>g of the two words;

Description
===========

We start with the mathematical definition, based on [1] (see #ref1 ) (where the
operation is called right half-shuffle). Let $T^{\geq 1}(\mathbb{R}^d)$ be the
vector space spanned by the non empty words on $d$ letters. Then the half
shuffle $>>$ is defined recursively to be $$ w >> i := wi$$ for $w$ a word and
$i$ a letter and $$ w >> vi := (w >> v + v >> w)\bullet i$$ for $w, v$ words
and $i$ a letter, where $\bullet$ is the concatenation product on words.

As stated in the reference, the shuffle, on non empty words can
be seen as a symmetrization of the half-shuffle. As a usage example, we verify
this in a particular instance.

+-----------------------------------------------------------------------------+
|i1 : R = wordAlgebra(3);                                                     |
+-----------------------------------------------------------------------------+
|i2 : w = [1]_R                                                               |
|                                                                             |
|o2 = Lt                                                                      |
|       1                                                                     |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : v = [1,2,3]_R                                                           |
|                                                                             |
|o3 = Lt Lt Lt                                                                |
|       1  2  3                                                               |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : s = w ** v --shuffle product of w, v                                    |
|                                                                             |
|                                   2                                         |
|o4 = Lt Lt Lt Lt +Lt Lt Lt Lt +2Lt  Lt Lt                                    |
|       1  2  3  1   1  2  1  3    1   2  3                                   |
|                                                                             |
|o4 : R                                                                       |
+-----------------------------------------------------------------------------+
|i5 : hsSymm = (w >> v) + (v >> w)--half-shuffle product symmetrization of w, |
|                                                                             |
|                                   2                                         |
|o5 = Lt Lt Lt Lt +Lt Lt Lt Lt +2Lt  Lt Lt                                    |
|       1  2  3  1   1  2  1  3    1   2  3                                   |
|                                                                             |
|o5 : R                                                                       |
|-----------------------------------------------------------------------------|
|v                                                                            |
+-----------------------------------------------------------------------------+
|i6 : s == hsSymm                                                             |
|                                                                             |
|o6 = true                                                                    |
+-----------------------------------------------------------------------------+

References
==========

[1] Signatures of paths transformed by polynomial maps
(doi.org/10.1007/s13366-020-00493-9) (see
https://doi.org/10.1007/s13366-020-00493-9 )

See also
========

  * shuffle -- shuffle product of two words
  * Array _ NCPolynomialRing (missing documentation)

Ways to use halfshuffle:
========================

  * "halfshuffle(NCRingElement,NCRingElement)"

For the programmer
==================

The object halfshuffle, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

inner -- compute the inner product of two tensors.
**************************************************

  * Usage:
        c = inner(f,g)
        c = f @ g
  * Inputs:
      * f, an instance of the type NCRingElement (NCAlgebra),
      * g, an instance of the type NCRingElement (NCAlgebra),

Description
===========

The inner product of two words $\mathtt{w}$ and $\mathtt{v}$ in a free
associative algebra is defined as $1$ if $\mathtt{w} = \mathtt{v}$ and $0$
otherwise. This extends bilinearly to an inner product on the whole associative
algebra.

The inner product can be used to access the coefficient of a tensor over a
single word.

+----------------------------------------------------------------+
|i1 : R = wordAlgebra(3);                                        |
+----------------------------------------------------------------+
|i2 : t = 2*[1,2,3]_R + [2,3,1]_R + 4*[3,3,3,3]_R; t //wordFormat|
|                                                                |
|o3 = 4 [3, 3, 3, 3] + [2, 3, 1] + 2 [1, 2, 3]                   |
+----------------------------------------------------------------+
|i4 : [1,2,3]_R @ t                                              |
|                                                                |
|o4 = 2                                                          |
|                                                                |
|o4 : QQ                                                         |
+----------------------------------------------------------------+
|i5 : [3,3,3,3]_R @ t                                            |
|                                                                |
|o5 = 4                                                          |
|                                                                |
|o5 : QQ                                                         |
+----------------------------------------------------------------+
|i6 : ([1,2,3]_R @ t) == (t @ [1,2,3]_R)                         |
|                                                                |
|o6 = true                                                       |
+----------------------------------------------------------------+

It is also a convenient way to evaluate linear combinations of tensor entries:

+-----------------------------------------------------------------------------+
|i7 : A = CAxisTensor(3,R);                                                   |
+-----------------------------------------------------------------------------+
|i8 : vol = sgnVolTensor(R);                                                  |
+-----------------------------------------------------------------------------+
|i9 : A @ vol -- the signed volume of the canonical axis path in 3 dimensions.|
|                                                                             |
|     1                                                                       |
|o9 = -                                                                       |
|     6                                                                       |
|                                                                             |
|o9 : QQ                                                                      |
+-----------------------------------------------------------------------------+

Ways to use inner:
==================

  * "inner(NCRingElement,NCRingElement)"

For the programmer
==================

The object inner, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

lie -- lie bracket of two elements
**********************************

  * Usage:
        c = lie(a, b)
  * Inputs:
      * a, an instance of the type NCRingElement (NCAlgebra),
      * b, an instance of the type NCRingElement (NCAlgebra),
  * Outputs:
      * c, an instance of the type NCRingElement (NCAlgebra),
        The commutator of a, b;

Description
===========

A non-commutative algebra $(R, +, \cdot)$ is naturally a Lie algebra with the
commutator $a\cdot b - b\cdot a$ as the Lie bracket. The commutator of two
non-commutative polynomials can be computed as follows:

+-------------------------+
|i1 : R = wordAlgebra (3);|
+-------------------------+
|i2 : a = [1]_R           |
|                         |
|o2 = Lt                  |
|       1                 |
|                         |
|o2 : R                   |
+-------------------------+
|i3 : b = [2]_R           |
|                         |
|o3 = Lt                  |
|       2                 |
|                         |
|o3 : R                   |
+-------------------------+
|i4 : lie(a,b)            |
|                         |
|o4 = -Lt Lt +Lt Lt       |
|        2  1   1  2      |
|                         |
|o4 : R                   |
+-------------------------+

For the programmer
==================

The object lie, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

lieBasis -- basis element corresponding to a Lyndon word in a Lie algebra
*************************************************************************

  * Usage:
        b = lieBasis(w, R)
  * Inputs:
      * w, an array (Macaulay2Doc), a Lyndon word in
        wordFormat, notation;
      * R, an instance of the type NCPolynomialRing (NCAlgebra),
        The algebra where the output lives;
  * Outputs:
      * b, an instance of the type NCRingElement (NCAlgebra),
        An element of R;

Description
===========

A word $l$ on the alphabet $\{1,\dots, d\}$ is a Lyndon word if it is strictly
smaller, in lexicographic order, than all of its rotations. To any Lyndon word
we can associate an iterated Lie bracketing $b(l)\in T(\mathbb{R}^d)$ defined
iteratively as follows. If $l$ is a letter $i\in \{1,\dots, d\}$ we simply
define $$ b(i) := e_i$$ where as ever $e_i$ is the $i-th$ vector in the
canonical basis of $\mathbb{R}^d$. For the length of $l$ greater than 1 we
define $$ b(I) := [b(I_1), b(I_2)]$$ where $I_1, I_2$ are such that their
concatenation $I_1 I_2$ is $I$ and $I_2$ is the longest Lyndon word appearing
as a proper right factor of $I$.

This method computes $b(l)$ for a given Lyndon word. To illustrate its usage,
we replicate Example 4.9 of the reference paper.

+-----------------------------------------------------------------------------+
|i1 : R = wordAlgebra(2);                                                     |
+-----------------------------------------------------------------------------+
|i2 : lieBasis([1,1,1,2], R) == [1,1,1,2]_R - 3 * [1,1,2,1]_R + 3 *           |
|                                                                             |
|o2 = true                                                                    |
|-----------------------------------------------------------------------------|
|[1,2,1,1]_R - [2,1,1,1]_R                                                    |
+-----------------------------------------------------------------------------+
|i3 : lieBasis([1,1,2,2], R) == [1,1,2,2]_R - 2 * [1,2,1,2]_R + 2 *           |
|                                                                             |
|o3 = true                                                                    |
|-----------------------------------------------------------------------------|
|[2,1,2,1]_R - [2,2,1,1]_R                                                    |
+-----------------------------------------------------------------------------+
|i4 : lieBasis([1,2,2,2], R) == [1,2,2,2]_R - 3 * [2,1,2,2]_R + 3 *           |
|                                                                             |
|o4 = true                                                                    |
|-----------------------------------------------------------------------------|
|[2,2,1,2]_R - [2,2,2,1]_R                                                    |
+-----------------------------------------------------------------------------+

The word can also be given as a List (Macaulay2Doc).

+--------------------------------------------------------------------+
|i5 : lieBasis({1,1,1,2}, R) // wordFormat                           |
|                                                                    |
|o5 = - [2, 1, 1, 1] + 3 [1, 2, 1, 1] - 3 [1, 1, 2, 1] + [1, 1, 1, 2]|
+--------------------------------------------------------------------+

References
==========

Varieties Of Signature Tensors (doi.org/10.1017/fms.2019.3) (see
https://doi.org/10.1017/fms.2019.3 )

Ways to use lieBasis:
=====================

  * "lieBasis(Array,NCPolynomialRing)"
  * "lieBasis(List,NCPolynomialRing)"

For the programmer
==================

The object lieBasis, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

linPath -- constructor of single piece polynomial path
******************************************************

  * Usage:
        linPath(v)
  * Inputs:
      * v, a list (Macaulay2Doc), A list of elements of a ring, the
        endpoints of the linear path.;
  * Outputs:
      * X, an instance of the type Path,

Description
===========

Takes as input a list of elements in the same ring. Constructs a Path,
object with one piece equal to the list given in input. Automatically
sets the dimension attribute of the object to the length of the list given as
input.

+-----------------------------------------------------------+
|i1 : R = QQ[x_1..x_5];                                     |
+-----------------------------------------------------------+
|i2 : X = linPath({x_1, x_2, x_3, x_4, x_5^2})              |
|                                                           |
|o2 = Path in 5-dimensional space with 1 polynomial segment:|
|                                                           |
|                            2                              |
|     {{x t, x t, x t, x t, x t}}                           |
|        1    2    3    4    5                              |
|                                                           |
|o2 : Path                                                  |
+-----------------------------------------------------------+
|i3 : X // getDimension                                     |
|                                                           |
|o3 = 5                                                     |
+-----------------------------------------------------------+

See also
========

  * Path
  * polyPath -- constructor of single piece polynomial path
  * Path ** Path -- concatenation of paths

Ways to use linPath:
====================

  * "linPath(List)"

For the programmer
==================

The object linPath, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

lyndonShuffle -- compute the representation of a tensor as a shuffle polynomial in Lyndon words
***********************************************************************************************

  * Usage:
        f = lyndonShuffle(T)
  * Inputs:
      * T, an instance of the type NCRingElement (NCAlgebra),
      * f, a hash table (Macaulay2Doc), representing the
        shuffle polynomial in Lyndon words;

Description
===========

The free associative algebra $k \langle \texttt{1}, \dots, \texttt{d} \rangle$
is isomorphic to the free commutative algebra over the Lyndon words when
equipped with the shuffle product $\char"29E2$. This method represents the
corresponding isomorphism $$k \langle \texttt{1}, \dots, \texttt{d}
\rangle_{\char"29E2} \to k[x_w \ | \ w \text{ Lyndon}].$$

+----------------------------------------------+
|i1 : A3 = wordAlgebra(3);                     |
+----------------------------------------------+
|i2 : T = [3,2,1]_A3;                          |
+----------------------------------------------+
|i3 : f = lyndonShuffle(T)                     |
|                                              |
|o3 = HashTable{HashTable{[1, 2, 3] => 1} => 1}|
|               HashTable{[1, 2] => 1} => -1   |
|                         [3] => 1             |
|               HashTable{[1] => 1   } => -1   |
|                         [2, 3] => 1          |
|               HashTable{[1] => 1} => 1       |
|                         [2] => 1             |
|                         [3] => 1             |
|                                              |
|o3 : HashTable                                |
+----------------------------------------------+

The polynomial is represented as in standard form (Macaulay2Doc),
with the variable index replaced by the respective
Lyndon word. One easily obtains an actual polynomial from this:

+-----------------------------------------------------------------------------+
|i4 : var = new Array from apply(lyndonWords(3,3), i->x_i)                    |
|                                                                             |
|o4 = [x   , x         , x         , x      , x         , x         , x      ,|
|       [1]   [1, 1, 2]   [1, 1, 3]   [1, 2]   [1, 2, 2]   [1, 2, 3]   [1, 3] |
|     ------------------------------------------------------------------------|
|     x         , x         , x   , x         , x      , x         , x   ]    |
|      [1, 3, 2]   [1, 3, 3]   [2]   [2, 2, 3]   [2, 3]   [2, 3, 3]   [3]     |
|                                                                             |
|o4 : Array                                                                   |
+-----------------------------------------------------------------------------+
|i5 : R = QQ var;                                                             |
+-----------------------------------------------------------------------------+
|i6 : pol = sum(pairs f, (term,coef) -> coef * product(pairs term, (word,ex)->|
|                                                                             |
|o6 = x   x   x    - x   x       - x      x    + x                            |
|      [1] [2] [3]    [1] [2, 3]    [1, 2] [3]    [1, 2, 3]                   |
|                                                                             |
|o6 : R                                                                       |
|-----------------------------------------------------------------------------|
|x_word^ex))                                                                  |
+-----------------------------------------------------------------------------+

Indeed, we check:

+-----------------------------------------------------------------------------+
|i7 : ([1]_A3**[2]_A3**[3]_A3 - [1]_A3**[2,3]_A3 - [1,2]_A3**[3]_A3 +         |
|                                                                             |
|o7 = [3, 2, 1]                                                               |
|-----------------------------------------------------------------------------|
|[1,2,3]_A3) // wordFormat                                                    |
+-----------------------------------------------------------------------------+

In general, one can "shuffle out" a polynomial like $\texttt{pol}$ in two steps
as follows:

+-----------------------------------------------------------------------------+
|i8 : polh = applyKeys(standardForm pol, i-> applyKeys(i,j-> last baseName    |
|-----------------------------------------------------------------------------|
|R_j));                                                                       |
+-----------------------------------------------------------------------------+
|i9 : sum(pairs polh, (term,coef) -> coef * fold(flatten apply(pairs term,    |
|                                                                             |
|o9 = [3, 2, 1]                                                               |
|-----------------------------------------------------------------------------|
|(word,ex)-> toList (ex:(word_A3))),(i,j)->i**j)) // wordFormat               |
+-----------------------------------------------------------------------------+

Ways to use lyndonShuffle:
==========================

  * "lyndonShuffle(NCRingElement)"

For the programmer
==================

The object lyndonShuffle, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

lyndonWords -- compute all Lyndon words of at most a given length on a given number of letters
**********************************************************************************************

  * Usage:
        L = lyndonWords(d, k)
  * Inputs:
      * d, an integer (Macaulay2Doc), The number of letters;
      * k, an integer (Macaulay2Doc), The maximum length;
  * Outputs:
      * L, a list (Macaulay2Doc), of all Lyndon words of length at
        most k in d letters;

Description
===========

A word $l$ on the alphabet $\{1,\dots, d\}$ is a Lyndon word if it is strictly
smaller, in lexicographic order, than all of its rotations.

This method generates a list containing all Lyndon words of length at most $k$
on $d$ letters. The Lyndon words are given as Array (Macaulay2Doc),
in the same convention of wordFormat.

+---------------------------------------------+
|i1 : words = lyndonWords (2,3)               |
|                                             |
|o1 = {[1], [1, 1, 2], [1, 2], [1, 2, 2], [2]}|
|                                             |
|o1 : List                                    |
+---------------------------------------------+
|i2 : R = wordAlgebra(2);                     |
+---------------------------------------------+
|i3 : apply(words, i-> i_R)                   |
|                                             |
|              2                   2          |
|o3 = {Lt , Lt  Lt , Lt Lt , Lt Lt  , Lt }    |
|        1    1   2    1  2    1  2     2     |
|                                             |
|o3 : List                                    |
+---------------------------------------------+

Ways to use lyndonWords:
========================

  * "lyndonWords(ZZ,ZZ)"

For the programmer
==================

The object lyndonWords, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

matrixAction -- Diagonal matrix action on a tensor.
***************************************************

  * Usage:
        Mf = M * f -- Computes the matrix action on f in a new algebra
        F = matrixAction(M, A, B) -- Gives the map A->B corresponding to the action
        Mf = matrixAction(M, f, B) -- Computes the matrix action on f, as an element in B
  * Inputs:
      * M, a matrix (Macaulay2Doc), A matrix acting on a tensor;
      * f, an instance of the type NCRingElement (NCAlgebra),
        The tensor to act on;
      * A, an instance of the type NCRing (NCAlgebra), The domain
        of the action;
      * B, an instance of the type NCRing (NCAlgebra), The
        codomain of the action;
  * Outputs:
      * F, an instance of the type NCRingMap (NCAlgebra), The
        action A->B of M;
      * Mf, an instance of the type NCRingElement (NCAlgebra),
        The action of M on f;

Description
===========

Let $\mathtt{A} := R\langle\mathtt{e_1}, \dots, \mathtt{e_a}\rangle$ be a free
associative algebra on $\mathtt{a}$ letters and $\mathtt{B}:=
\mathtt{R}\langle\mathtt{f_1}, \dots, \mathtt{f_b}\rangle$ be a free
associative algebra on $\mathtt{b}$ letters, both with coefficient in a ring
$\mathtt{R}$. Let $\mathtt{M}$ be a $\mathtt{b}\times \mathtt{a}$ matrix with
entries in $\mathtt{R}$. Then the matrix action of $\mathtt{M}$ from
$\mathtt{A}$ to $\mathtt{B}$ is defined on the generators of $\mathtt{A}$ by $$
\mathtt{e_j}\mapsto \sum_{i=1}^{\mathtt{a}}\mathtt{M}_{ij}\mathtt{f_i},
\,\,\forall 0<j\leq \mathtt{a}, $$ and then extended by linearity to the whole
of $\mathtt{A}$.

For example if we consider $\mathtt{A}= \mathbb{Q}\langle
\mathtt{e_1},\mathtt{e_2}, \mathtt{e_3}, \mathtt{e_4}\rangle$, $\mathtt{B}=
\mathbb{Q}\langle \mathtt{f_1},\mathtt{f_2}, \mathtt{f_3}\rangle$ and the
matrix $$ \mathtt{M} := \begin{pmatrix} 0 & 0 & 1 & 1\\ 0 & 1 & 0 & 0\\ 1 & 0 &
0 & 1 \end{pmatrix}$$ we get the map defined by $\mathtt{e_1}\mapsto
\mathtt{f_3}$, $\mathtt{e_2}\mapsto \mathtt{f_2}$, $\mathtt{e_3}\mapsto
\mathtt{f_1}$, $\mathtt{e_4}\mapsto \mathtt{f_1}+\mathtt{f_3}$. The action of
$\mathtt{M}$ on $\mathtt{w}:=\mathtt{e_1}\mathtt{e_2}+2\mathtt{e_4}$ is $$
\mathtt{M*w} = \mathtt{f_3 f_2}+ 2 \mathtt{f_1}+2 \mathtt{f_3} $$

To get the map from $\mathtt{A}$ to $\mathtt{B}$ use
matrixAction(Matrix,NCRing,NCRing).

+-------------------------------------------------+
|i1 : M = matrix {{0,0,1,1}, {0,1,0,0}, {1,0,0,1}}|
|                                                 |
|o1 = | 0 0 1 1 |                                 |
|     | 0 1 0 0 |                                 |
|     | 1 0 0 1 |                                 |
|                                                 |
|              3       4                          |
|o1 : Matrix ZZ  <-- ZZ                           |
+-------------------------------------------------+
|i2 : A = wordAlgebra(4);                         |
+-------------------------------------------------+
|i3 : B = wordAlgebra(3);                         |
+-------------------------------------------------+
|i4 : F = matrixAction(M, A, B)                   |
|                                                 |
|o4 = NCRingMap B <--- A                          |
|                                                 |
|o4 : NCRingMap                                   |
+-------------------------------------------------+

To compute the action of $\mathtt{M}$ on a tensor $\mathtt{w}$ as an element of
$\mathtt{B}$ use matrixAction(Matrix,NCRingElement,NCRing).

+-------------------------------+
|i5 : w = [1,2]_A + 2* [4]_A    |
|                               |
|o5 = 2Lt +Lt Lt                |
|        4   1  2               |
|                               |
|o5 : A                         |
+-------------------------------+
|i6 : Mw = matrixAction(M, w, B)|
|                               |
|o6 = Lt Lt +2Lt +2Lt           |
|       3  2    3    1          |
|                               |
|o6 : B                         |
+-------------------------------+
|i7 : F(w) == Mw                |
|                               |
|o7 = true                      |
+-------------------------------+

To compute the action of $\mathtt{M}$ on a tensor $\mathtt{w}$ in a new algebra
created automatically, use Matrix * NCRingElement.

+----------------------+
|i8 : M * w            |
|                      |
|o8 = Lt Lt +2Lt +2Lt  |
|       3  2    3    1 |
|                      |
|o8 : QQ{Lt , Lt , Lt }|
|          1    2    3 |
+----------------------+

Ways to use matrixAction:
=========================

  * "matrixAction(Matrix,NCRing,NCRing)"
  * "matrixAction(Matrix,NCRingElement,NCRing)"

For the programmer
==================

The object matrixAction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

NCPolynomialRing -- exported from the NCAlgebra package, used to encode tensor algebras
***************************************************************************************

Methods that use an object of class NCPolynomialRing:
=====================================================

  * "adjointWord(NCRingElement,NCPolynomialRing,List)" -- see
    adjointWord, -- image of a word through the shuffle algebra
    homomorphism induced by a polynomial map
  * "ambient(NCPolynomialRing)" -- see ambient, -- exported from
    the NCALgebra package.
  * Array _ NCPolynomialRing -- create a
    word from an array
  * "CAxisTensor(ZZ,NCPolynomialRing)" -- see CAxisTensor,
    -- the signature tensor of the canonical axis path at a given level
  * "CMonTensor(ZZ,NCPolynomialRing)" -- see CMonTensor, --
    the signature tensor of the canonical monomial path at a given level
  * "gbFromOutputFile(NCPolynomialRing,String)" -- see gbFromOutputFile (NCAlgebra),
    -- Read in a NCGroebnerBasis from a Bergman
    output file.
  * ideal(NCPolynomialRing) (NCAlgebra), --
    The defining ideal of an NCPolynomialRing
  * "lieBasis(Array,NCPolynomialRing)" -- see lieBasis, --
    basis element corresponding to a Lyndon word in a Lie algebra
  * "lieBasis(List,NCPolynomialRing)" -- see lieBasis, -- basis
    element corresponding to a Lyndon word in a Lie algebra
  * NCPolynomialRing / NCIdeal (NCAlgebra), --
    Construct a NCQuotientRing
  * "sgnVolTensor(NCPolynomialRing)" -- see sgnVolTensor,
    -- The signed volume tensor in a free associative algebra.

For the programmer
==================

The object NCPolynomialRing (NCAlgebra), is a
type (Macaulay2Doc), with ancestor classes NCRing (NCAlgebra),
< Ring (Macaulay2Doc) < Type (Macaulay2Doc)
< MutableHashTable (Macaulay2Doc) <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

NCRingElement -- exported from the NCAlgebra package, used to encode tensors
****************************************************************************

Functions and methods returning an object of class NCRingElement:
=================================================================

  * "CAxisTensor(ZZ,NCPolynomialRing)" -- see CAxisTensor,
    -- the signature tensor of the canonical axis path at a given level
  * "CMonTensor(ZZ,NCPolynomialRing)" -- see CMonTensor, --
    the signature tensor of the canonical monomial path at a given level
  * "matrixAction(Matrix,NCRing,NCRing)" -- see matrixAction,
    -- Diagonal matrix action on a tensor.
  * "matrixAction(Matrix,NCRingElement,NCRing)" -- see matrixAction,
    -- Diagonal matrix action on a tensor.

Methods that use an object of class NCRingElement:
==================================================

  * "adjointWord(NCRingElement,NCPolynomialRing,List)" -- see
    adjointWord, -- image of a word through the shuffle algebra
    homomorphism induced by a polynomial map
  * antipode(NCRingElement) -- The antipode
    of a tensor
  * baseName(NCRingElement) (NCAlgebra), --
    Returns the base name of a generator of an NCRing
  * "coordinates(NCRingElement)" -- see coordinates (NCAlgebra),
    -- Computes coordinates relative to a given basis
  * degree(NCRingElement) (NCAlgebra), --
    Returns the degree of an NCRingElement
  * "halfshuffle(NCRingElement,NCRingElement)" -- see halfshuffle,
    -- compute the half-shuffle of an ordered pair of words
  * "NCRingElement >> NCRingElement" -- see halfshuffle, --
    compute the half-shuffle of an ordered pair of words
  * "inner(NCRingElement,NCRingElement)" -- see inner, -- compute
    the inner product of two tensors.
  * "NCRingElement @ NCRingElement" -- see inner, -- compute the
    inner product of two tensors.
  * "isCentral(NCRingElement)" -- see isCentral (NCAlgebra), --
    Determines if an element is central
  * "isCentral(NCRingElement,NCGroebnerBasis)" -- see isCentral (NCAlgebra),
    -- Determines if an element is central
  * isConstant(NCRingElement) (NCAlgebra),
    -- Returns whether the NCRingElement is constant
  * "isHomogeneous(NCRingElement)" -- see isHomogeneous(NCIdeal) (NCAlgebra),
    -- Determines whether the input
    defines a homogeneous object
  * "isLeftRegular(NCRingElement,ZZ)" -- see isLeftRegular (NCAlgebra),
    -- Determines if a given (homogeneous) element is
    regular in a given degree
  * "isRightRegular(NCRingElement,ZZ)" -- see isLeftRegular (NCAlgebra),
    -- Determines if a given (homogeneous) element is
    regular in a given degree
  * isNormal(NCRingElement) (NCAlgebra), --
    Determines if a given NCRingElement is normal
  * leadCoefficient(NCRingElement) (NCAlgebra)
    -- Returns the lead monomial
    of an NCRingElement
  * leadMonomial(NCRingElement) (NCAlgebra)
    -- Returns the lead monomial of
    an NCRingElement
  * leadTerm(NCRingElement) (NCAlgebra), --
    Returns the lead term of an NCRingElement
  * "leftMultiplicationMap(NCRingElement,List,List)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * "leftMultiplicationMap(NCRingElement,ZZ)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * "leftMultiplicationMap(NCRingElement,ZZ,ZZ)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * "rightMultiplicationMap(NCRingElement,List,List)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * "rightMultiplicationMap(NCRingElement,ZZ)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * "rightMultiplicationMap(NCRingElement,ZZ,ZZ)" -- see
    leftMultiplicationMap (NCAlgebra), -- Computes a
    matrix for left or right multiplication by a homogeneous element
  * List * NCRingElement (NCAlgebra) -- Scales a
    list by an NCRingElement on the right
  * "lyndonShuffle(NCRingElement)" -- see lyndonShuffle,
    -- compute the representation of a tensor as a shuffle polynomial in Lyndon
    words
  * "Matrix * NCRingElement" -- see matrixAction, --
    Diagonal matrix action on a tensor.
  * monomials(NCRingElement) (NCAlgebra), --
    Returns the monomials appearing in the NCRingElement
  * "ncIdeal(NCRingElement)" -- see ncIdeal (NCAlgebra), --
    Define a two-sided ideal in a noncommutative ring
  * "ncLeftIdeal(NCRingElement)" -- see ncLeftIdeal (NCAlgebra),
    -- Define a left ideal in a noncommutative ring
  * NCMatrix * NCRingElement (NCAlgebra), --
    Product of NCMatrices
  * "ncRightIdeal(NCRingElement)" -- see ncRightIdeal (NCAlgebra),
    -- Define a right ideal in a noncommutative ring
  * NCRingElement % NCGroebnerBasis (NCAlgebra)
    -- Reduces a NCRingElement by a NCGroebnerBasis
  * NCRingElement * List (NCAlgebra) -- Scales a
    list by an NCRingElement on the left
  * NCRingElement * NCMatrix (NCAlgebra), --
    Product of NCMatrices
  * NCRingMap NCRingElement (NCAlgebra) -- Apply
    an NCRingMap to an element or matrix
  * "normalAutomorphism(NCRingElement)" -- see normalAutomorphism (NCAlgebra),
    -- Computes the automorphism determined by a
    normal homogeneous element
  * "normalFormBergman(NCRingElement,NCGroebnerBasis)" -- see
    normalFormBergman (NCAlgebra), -- Calls Bergman for a
    normal form calculation
  * "oreExtension(NCRing,NCRingMap,NCRingElement)" -- see oreExtension (NCAlgebra),
    -- Creates an Ore extension of a noncommutative
    ring
  * "oreExtension(NCRing,NCRingMap,NCRingMap,NCRingElement)" -- see
    oreExtension (NCAlgebra), -- Creates an Ore extension of a
    noncommutative ring
  * "oreIdeal(NCRing,NCRingMap,NCRingElement)" -- see oreIdeal (NCAlgebra),
    -- Creates the defining ideal of an Ore extension of a
    noncommutative ring
  * "oreIdeal(NCRing,NCRingMap,NCRingMap,NCRingElement)" -- see oreIdeal (NCAlgebra),
    -- Creates the defining ideal of an Ore extension of a
    noncommutative ring
  * ring(NCRingElement) (NCAlgebra) -- Returns
    the NCRing of an NCRingElement
  * "NCRingElement ** NCRingElement" -- see shuffle, -- shuffle
    product of two words
  * "NCRingElement ⧢ NCRingElement" -- see shuffle, -- shuffle
    product of two words
  * "shuffle(NCRingElement,NCRingElement)" -- see shuffle, --
    shuffle product of two words
  * "sig(Path,NCRingElement)" -- see sig, -- compute the signature
    of a piecewise polynomial path.
  * size(NCRingElement) (NCAlgebra) -- Returns
    the number of terms of an NCRingElement
  * "sparseCoeffs(NCRingElement)" -- see sparseCoeffs (NCAlgebra),
    -- Converts ring elements into vectors over the
    coefficient ring
  * support(NCRingElement) (NCAlgebra), --
    Returns the variables appearing in the NCRingElement
  * "NCRingElement @ ZZ" -- see tensorArray, -- k-th level
    component of a tensor.
  * "tensorArray(NCRingElement)" -- see tensorArray, -- k-th
    level component of a tensor.
  * "tensorArray(NCRingElement,ZZ)" -- see tensorArray, --
    k-th level component of a tensor.
  * "tensorExp(NCRingElement,ZZ)" -- see tensorExp, -- Compute
    a component of the exponential of a tensor.
  * "tensorLog(NCRingElement,ZZ)" -- see tensorLog, -- Compute
    a component of the logarithm of a tensor.
  * "tensorParametrization(NCRingElement)" -- see tensorParametrization,
    -- Constructs the morphism that maps a word to its
    coefficient in the given tensor.
  * terms(NCRingElement) (NCAlgebra) -- Returns
    the terms of an NCRingElement
  * toString(NCRingElement) (NCAlgebra), --
    Converts an NCRingElement to a string
  * "wordFormat(NCRingElement)" -- see wordFormat, -- display
    a tensor in word notation
  * "wordString(NCRingElement)" -- see wordString, -- a
    string representing a word in wordFormat

For the programmer
==================

The object NCRingElement (NCAlgebra), is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

Path
****

Description
===========

A polynomial path is a map $[0,1] \to \mathbb R^d$ whose coordinate functions
are given by polynomials. A piecewise polynomial path is a concatenation of
polynomial paths.

To create a polynomial path, use polyPath, which takes a list
of polynomials as input. These can be given as elements of a commutative
polynomial ring with one generator or directly in listForm (Macaulay2Doc).

+-----------------------------------------------------------+
|i1 : R = QQ[t];                                            |
+-----------------------------------------------------------+
|i2 : X = polyPath({t,2*t^2,3*t^3})                         |
|                                                           |
|o2 = Path in 3-dimensional space with 1 polynomial segment:|
|                                                           |
|            2    3                                         |
|     {{t, 2t , 3t }}                                       |
|                                                           |
|o2 : Path                                                  |
+-----------------------------------------------------------+
|i3 : Y = polyPath({{({1},1)},{({2},2)},{({3},3)}})         |
|                                                           |
|o3 = Path in 3-dimensional space with 1 polynomial segment:|
|                                                           |
|            2    3                                         |
|     {{t, 2t , 3t }}                                       |
|                                                           |
|o3 : Path                                                  |
+-----------------------------------------------------------+

While the polynomials must be chosen from a polynomial ring with one generator,
the coefficient ring of the polynomials can be chosen arbitrarily.

+-----------------------------------------------------------+
|i4 : R = QQ[a][t]; --QQ[a,t] will not work!                |
+-----------------------------------------------------------+
|i5 : X = polyPath({t,2*a*t^2,3*a^2*t^3})                   |
|                                                           |
|o5 = Path in 3-dimensional space with 1 polynomial segment:|
|                                                           |
|              2    2 3                                     |
|     {{t, 2a*t , 3a t }}                                   |
|                                                           |
|o5 : Path                                                  |
+-----------------------------------------------------------+

An important special case of polynomial paths are linear paths. These can be
constructed directly from their increment using linPath.

+-----------------------------------------------------------+
|i6 : Y = linPath({2,3,4})                                  |
|                                                           |
|o6 = Path in 3-dimensional space with 1 polynomial segment:|
|                                                           |
|     {{2t, 3t, 4t}}                                        |
|                                                           |
|o6 : Path                                                  |
+-----------------------------------------------------------+

Paths can be concatenated using Path ** Path. This
concatenation is formal: the new Path object encodes the polynomial pieces and
their order, but no parametrization is chosen. The concatenation Path ** Path,
will automatically select a bigger coefficient ring for all
polynomial pieces if an obvious choice is available.

+------------------------------------------------------------+
|i7 : Z = X ** Y                                             |
|                                                            |
|o7 = Path in 3-dimensional space with 2 polynomial segments:|
|                                                            |
|              2    2 3                                      |
|     {{t, 2a*t , 3a t }, {2t, 3t, 4t}}                      |
|                                                            |
|o7 : Path                                                   |
+------------------------------------------------------------+

A piecewise linear path can be constructed directly from the increments of its
segments using pwLinPath.

+------------------------------------------------------------+
|i8 : A = matrix {{1,2,3},{2,3,4},{4,5,6}};                  |
|                                                            |
|              3       3                                     |
|o8 : Matrix ZZ  <-- ZZ                                      |
+------------------------------------------------------------+
|i9 : W = pwLinPath(A)                                       |
|                                                            |
|o9 = Path in 3-dimensional space with 3 polynomial segments:|
|                                                            |
|     {{t, 2t, 4t}, {2t, 3t, 5t}, {3t, 4t, 6t}}              |
|                                                            |
|o9 : Path                                                   |
+------------------------------------------------------------+

To read out the ambient dimension of a path, use getDimension(Path),
or dim(Path). To get the pieces of the path in
listForm (Macaulay2Doc), use getPieces(Path). To get the
coefficient ring of the coordinate polynomials, use
getCoefficientRing(Path), or coefficientRing(Path). Finally,
see getNumberOfPieces(Path), returns the number of pieces of the path.

+-----------------------------------------------------------------------------+
|i10 : getDimension(Z) --The ambient dimension of the path                    |
|                                                                             |
|o10 = 3                                                                      |
+-----------------------------------------------------------------------------+
|i11 : getPieces(Z) --The polynomial pieces of the path, in listForm          |
|                                                                             |
|                                          2                                  |
|o11 = {{{({1}, 1)}, {({2}, 2a)}, {({3}, 3a )}}, {{({1}, 2)}, {({1}, 3)},     |
|      -----------------------------------------------------------------------|
|      {({1}, 4)}}}                                                           |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+
|i12 : getCoefficientRing(Z) -- The coefficient ring of the polynomial        |
|                                                                             |
|o12 = QQ[a]                                                                  |
|                                                                             |
|o12 : PolynomialRing                                                         |
|-----------------------------------------------------------------------------|
|components of the path                                                       |
+-----------------------------------------------------------------------------+
|i13 : getNumberOfPieces(Z) -- The number of polynomial pieces of the path    |
|                                                                             |
|o13 = 2                                                                      |
+-----------------------------------------------------------------------------+

To extract the pieces of a concatenated path one can use Path _ ZZ,
see Path _ List, and Path _ Sequence.

+------------------------------------------------------------------------+
|i14 : Z_0                                                               |
|                                                                        |
|o14 = Path in 3-dimensional space with 1 polynomial segment:            |
|                                                                        |
|               2    2 3                                                 |
|      {{t, 2a*t , 3a t }}                                               |
|                                                                        |
|o14 : Path                                                              |
+------------------------------------------------------------------------+
|i15 : Z2 = Z^2                                                          |
|                                                                        |
|o15 = Path in 3-dimensional space with 4 polynomial segments:           |
|                                                                        |
|               2    2 3                         2    2 3                |
|      {{t, 2a*t , 3a t }, {2t, 3t, 4t}, {t, 2a*t , 3a t }, {2t, 3t, 4t}}|
|                                                                        |
|o15 : Path                                                              |
+------------------------------------------------------------------------+
|i16 : Z2_{0,-1}                                                         |
|                                                                        |
|o16 = Path in 3-dimensional space with 2 polynomial segments:           |
|                                                                        |
|               2    2 3                                                 |
|      {{t, 2a*t , 3a t }, {2t, 3t, 4t}}                                 |
|                                                                        |
|o16 : Path                                                              |
+------------------------------------------------------------------------+

When considering the set of paths modulo tree-like equivalence, concatenation
turns it into a groupoid. Use Path ^ ZZ, to compute powers and the
inverse of a path in this groupoid. Note that the inverse of a path is just
given by reversing its parametrization.

+-----------------------------------------------------------------------------+
|i17 : X^4                                                                    |
|                                                                             |
|o17 = Path in 3-dimensional space with 4 polynomial segments:                |
|                                                                             |
|               2    2 3           2    2 3           2    2 3           2    |
|      {{t, 2a*t , 3a t }, {t, 2a*t , 3a t }, {t, 2a*t , 3a t }, {t, 2a*t ,   |
|                                                                             |
|o17 : Path                                                                   |
|-----------------------------------------------------------------------------|
|  2 3                                                                        |
|3a t }}                                                                      |
+-----------------------------------------------------------------------------+
|i18 : X^(-1)                                                                 |
|                                                                             |
|o18 = Path in 3-dimensional space with 1 polynomial segment:                 |
|                                                                             |
|                2             2 3     2 2     2                              |
|      {{-t, 2a*t  - 4a*t, - 3a t  + 9a t  - 9a t}}                           |
|                                                                             |
|o18 : Path                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * polyPath -- constructor of single piece polynomial path
  * linPath -- constructor of single piece polynomial path

Functions and methods returning an object of class Path:
========================================================

  * "concatPath(Path,Path)" -- see concatPath, --
    concatenation of paths
  * "Path ** Path" -- see concatPath, -- concatenation of
    paths
  * "linPath(List)" -- see linPath, -- constructor of single
    piece polynomial path
  * "Path ^ ZZ"
  * "Path _ List"
  * "Path _ Sequence"
  * "Path _ ZZ"
  * "polyPath(List)" -- see polyPath, -- constructor of single
    piece polynomial path
  * "pwLinPath(Matrix)" -- see pwLinPath, -- constructor of a
    piecewise linear path from a matrix
  * substitute(Path,Ring) -- changes the
    coefficient ring of a path

Methods that use an object of class Path:
=========================================

  * "coefficientRing(Path)"
  * "dim(Path)"
  * "getCoefficientRing(Path)"
  * "getDimension(Path)"
  * "getNumberOfPieces(Path)"
  * "getPieces(Path)"
  * "net(Path)"
  * "sig(Path,List)" -- see sig, -- compute the signature of a
    piecewise polynomial path.
  * "sig(Path,NCRingElement)" -- see sig, -- compute the signature
    of a piecewise polynomial path.
  * "sig(Path,ZZ)" -- see sig, -- compute the signature of a
    piecewise polynomial path.
  * "sig(Path,ZZ,NCRing)" -- see sig, -- compute the signature of a
    piecewise polynomial path.

For the programmer
==================

The object Path, is a type (Macaulay2Doc), with
ancestor classes MutableHashTable (Macaulay2Doc), <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

polyPath -- constructor of single piece polynomial path
*******************************************************

  * Usage:
        polyPath(polyPathList)
  * Inputs:
      * polyPathList, a list (Macaulay2Doc), A list of elements of
        the same ring, the components of the polynomial path.;
  * Outputs:
      * X, an instance of the type Path,

Description
===========

Takes as input a list of polynomials in the same ring. Constructs a Path,
object with one piece equal to the list of normalForm of the polynomial
components of the path given in input. Automatically sets the dimension
attribute of the object to the length of the list given as input.

+-----------------------------------------------------------+
|i1 : R = QQ[t];                                            |
+-----------------------------------------------------------+
|i2 : X = polyPath({t,t^2})                                 |
|                                                           |
|o2 = Path in 2-dimensional space with 1 polynomial segment:|
|                                                           |
|           2                                               |
|     {{t, t }}                                             |
|                                                           |
|o2 : Path                                                  |
+-----------------------------------------------------------+
|i3 : X // getDimension                                     |
|                                                           |
|o3 = 2                                                     |
+-----------------------------------------------------------+

See also
========

  * Path
  * linPath -- constructor of single piece polynomial path
  * Path ** Path -- concatenation of paths

Ways to use polyPath:
=====================

  * "polyPath(List)"

For the programmer
==================

The object polyPath, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

pwLinPath -- constructor of a piecewise linear path from a matrix
*****************************************************************

  * Usage:
        pwLinPath(pwlMatrix)
  * Inputs:
      * pwlMatrix, a matrix (Macaulay2Doc), A matrix containing
        on its columns the articulation points (or increments) of the path;
  * Outputs:
      * X, an instance of the type Path, A piecewise linear path
        of dimension the number of rows of the input and with the same number
        of pieces as the columns of the input;

Description
===========

Creates a piecewise linear Path, whose increments are the columns
of the given matrix.

+------------------------------------------------------------+
|i1 : M = id_(QQ^3)                                          |
|                                                            |
|o1 = | 1 0 0 |                                              |
|     | 0 1 0 |                                              |
|     | 0 0 1 |                                              |
|                                                            |
|              3       3                                     |
|o1 : Matrix QQ  <-- QQ                                      |
+------------------------------------------------------------+
|i2 : pwLinPath(M)                                           |
|                                                            |
|o2 = Path in 3-dimensional space with 3 polynomial segments:|
|                                                            |
|     {{t, 0, 0}, {0, t, 0}, {0, 0, t}}                      |
|                                                            |
|o2 : Path                                                   |
+------------------------------------------------------------+

See also
========

  * Path

Ways to use pwLinPath:
======================

  * "pwLinPath(Matrix)"

For the programmer
==================

The object pwLinPath, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

sgnVolTensor -- The signed volume tensor in a free associative algebra.
***********************************************************************

Description
===========

Given a free associative algebra $K \langle \mathtt{1}, \dots, \mathtt{d}
\rangle$ over a field $K$, the signed volume tensor is
$$\frac{1}{d!}\sum_{\sigma} (-1)^{\operatorname{sign}(\sigma)}
\mathtt{\sigma(1)}\dots \mathtt{\sigma(d)}$$ where the sum is taken over all
permutations of ${1, \dots, d}$. Under the isomorphism $\mathbb R \langle
\mathtt{1}, \dots, \mathtt{d} \rangle \to T(\mathbb{R}^d), \ \mathtt{i} \mapsto
e_i^*$ it corresponds to the determinant $e_1^* \wedge \dots \wedge e_d^*$.

This method computes the signed volume tensor of the given
NCPolynomialRing (NCAlgebra). The output is in the same ring.

+-----------------------------------------------------------------------------+
|i1 : d = 3;                                                                  |
+-----------------------------------------------------------------------------+
|i2 : R = wordAlgebra(d)                                                      |
|                                                                             |
|o2 = R                                                                       |
|                                                                             |
|o2 : NCPolynomialRing                                                        |
+-----------------------------------------------------------------------------+
|i3 : sgnVolTensor(R) // wordFormat                                           |
|                                                                             |
|       1             1             1             1             1             |
|o3 = - - [3, 2, 1] + - [3, 1, 2] + - [2, 3, 1] - - [2, 1, 3] - - [1, 3, 2] + |
|       6             6             6             6             6             |
|     ------------------------------------------------------------------------|
|     1                                                                       |
|     - [1, 2, 3]                                                             |
|     6                                                                       |
+-----------------------------------------------------------------------------+

The paper [1] (see #ref1 ) explores under what conditions the value of the
signature at the signed volume tensor computes the volume of the convex hull of
a path. One instance where this is true is the case of canonical axis paths
(see CAxisTensor). For example, for $\mathtt{d}=3$ the
convex hull of the canonical axis path in $\mathbb{R}^{\mathtt{d}}$ is a
tetrahedron, whose volume is $\frac{1}{6}$. We verify this.

+-------------------------------------------------------------------------+
|i4 : X = linPath({1,0,0})**linPath({0,1,0})**linPath({0,0,1})            |
|                                                                         |
|o4 = Path in 3-dimensional space with 3 polynomial segments:             |
|                                                                         |
|     {{t, 0, 0}, {0, t, 0}, {0, 0, t}}                                   |
|                                                                         |
|o4 : Path                                                                |
+-------------------------------------------------------------------------+
|i5 : R = wordAlgebra(3) -- where the signature of X lives                |
|                                                                         |
|o5 = R                                                                   |
|                                                                         |
|o5 : NCPolynomialRing                                                    |
+-------------------------------------------------------------------------+
|i6 : v = sgnVolTensor(R);                                                |
+-------------------------------------------------------------------------+
|i7 : sig(X, v) -- computes the signature of X at the signed volume tensor|
|                                                                         |
|     1                                                                   |
|o7 = -                                                                   |
|     6                                                                   |
|                                                                         |
|o7 : QQ                                                                  |
+-------------------------------------------------------------------------+

References
==========

[1] Convex Hulls of Curves: Volumes and Signatures
(doi.org/10.1007/978-3-031-38271-0_45) (see
https://doi.org/10.1007/978-3-031-38271-0_45 )

Ways to use sgnVolTensor:
=========================

  * "sgnVolTensor(NCPolynomialRing)"

For the programmer
==================

The object sgnVolTensor, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

shuffle -- shuffle product of two words
***************************************

  * Usage:
        v = shuffle(w1, w2, R)
  * Inputs:
      * w1, an instance of the type NCRingElement (NCAlgebra),
      * w2, an instance of the type NCRingElement (NCAlgebra),
      * R, an instance of the type NCPolynomialRing (NCAlgebra),
        The non-commutative polynomial where the
        operation ought to be carried out;
  * Outputs:
      * v, an instance of the type NCRingElement (NCAlgebra),
        The shuffle product of w1 and w2;

Description
===========

We start with the mathematical definition of this operation, based on [1] (see
#ref1 ). Consider $T(\mathbb{R}^d)$, the free algebra on the symbols $1,\dots,
d$. Denote by $\bullet$ its concatenation product and by $e$ the neutral
element with respect to the concatenation (the empty word). The shuffle product
of two words is defined recursively as follows. Let $w, w_1, w_2$ be three
words and $a, b$ bet two letters, i.e. $w, w_1, w_2\in T(\mathbb{R}^d)$ and
$a,b\in \{1,\dots, d\}$. Then the shuffle product $\char"29E2$ is defined to be
$$ e \char"29E2 w := w =: w\char"29E2 e$$ and $$(w_1\bullet a) \char"29E2
(w_2\bullet b) = (w_1 \char"29E2 (w_2\bullet b))\bullet a + ((w_1\bullet
a)\char"29E2 w_2)\bullet b$$

The easiest way to compute a shuffle product is through NCRingElement ** NCRingElement,
which is equivalent to
shuffle(NCRingElement,NCRingElement),:

+-----------------------------------------------------------------------------+
|i1 : R = wordAlgebra(2); -- create a free associative algebra over two       |
|-----------------------------------------------------------------------------|
|letters Lt_1, Lt_2                                                           |
+-----------------------------------------------------------------------------+
|i2 : f = [1,2]_R; -- [i_1,...,i_k]_R defines a word                          |
+-----------------------------------------------------------------------------+
|i3 : wordFormat f -- display the polynomial in word notation                 |
|                                                                             |
|o3 = [1, 2]                                                                  |
+-----------------------------------------------------------------------------+
|i4 : f = ([1,2]_R ** [1,2]_R); -- compute the shuffle product                |
+-----------------------------------------------------------------------------+
|i5 : f // wordFormat --display the result in word notation                   |
|                                                                             |
|o5 = 2 [1, 2, 1, 2] + 4 [1, 1, 2, 2]                                         |
+-----------------------------------------------------------------------------+

References
==========

[1] Signatures of paths transformed by polynomial maps
(doi.org/10.1007/s13366-020-00493-9) (see
https://doi.org/10.1007/s13366-020-00493-9 )

See also
========

  * wordAlgebra -- create a free algebra over a given
    alphabet
  * wordFormat -- display a tensor in word notation
  * Array _ NCPolynomialRing (missing documentation)

Ways to use shuffle:
====================

  * "shuffle(NCRingElement,NCRingElement)"

For the programmer
==================

The object shuffle, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

sig -- compute the signature of a piecewise polynomial path.
************************************************************

Description
===========

Given a Path, $X(t):[0,1]\rightarrow \mathbb{R}^d$, its signature
is the linear form $\sigma: T((\mathbb{R}^d)^*)\rightarrow \mathbb{R}$ on the
tensor algebra of the dual of $\mathbb{R}^d$, whose image on a decomposable
tensor $\alpha_1\otimes \dots\otimes \alpha_k$ is the iterated integral $$
\alpha_1\otimes \dots\otimes \alpha_k\overset{\sigma}{\mapsto}
\int_0^1\int_0^{t_k}\dots\int_0^{t_2}\partial(\alpha_1 X)\dots \partial
(\alpha_k X) d t_1\dots dt_k. $$ This form does not depend on the
parametrization of $X$. In this package, we identify $T((\mathbb{R}^d)^*)$ with
the free associative algebra over the alphabet
$\{\texttt{1},\dots,\texttt{d}\}$ via $\texttt{i} \mapsto e_i^*$ where $e_1^*,
\dots, e_d^*$ is the dual of the canonical basis of $\mathbb{R}^d$. See also
wordAlgebra.

+-----------------------------------------------------------------------------+
|i1 : d = 4;                                                                  |
+-----------------------------------------------------------------------------+
|i2 : R = QQ[t];                                                              |
+-----------------------------------------------------------------------------+
|i3 : X = polyPath(for i from 1 to d list t^i) -- the moment path in dimension|
|                                                                             |
|o3 = Path in 4-dimensional space with 1 polynomial segment:                  |
|                                                                             |
|           2   3   4                                                         |
|     {{t, t , t , t }}                                                       |
|                                                                             |
|o3 : Path                                                                    |
|-----------------------------------------------------------------------------|
|d                                                                            |
+-----------------------------------------------------------------------------+
|i4 : A = wordAlgebra(d) -- create the free associative algebra over d letters|
|                                                                             |
|o4 = A                                                                       |
|                                                                             |
|o4 : NCPolynomialRing                                                        |
+-----------------------------------------------------------------------------+
|i5 : w = (new Array from (1..d))_A -- the word 1..d                          |
|                                                                             |
|o5 = Lt Lt Lt Lt                                                             |
|       1  2  3  4                                                            |
|                                                                             |
|o5 : A                                                                       |
+-----------------------------------------------------------------------------+

In the example above, the word $\texttt{w}$ corresponds to the simple tensor
$e_1^*\otimes\dots  \otimes e_d^*$. The signature of $X$ on this word can be
computed using sig(Path,NCRingElement).

+-------------------+
|i6 : sig(X, w)     |
|                   |
|      2            |
|o6 = --            |
|     15            |
|                   |
|o6 : QQ            |
+-------------------+
|i7 : sig(X,[1]_A)  |
|                   |
|o7 = 1             |
|                   |
|o7 : QQ            |
+-------------------+
|i8 : sig(X,[2,3]_A)|
|                   |
|     3             |
|o8 = -             |
|     5             |
|                   |
|o8 : QQ            |
+-------------------+

One can also compute the k-th level signature tensor for $k\in \mathbb{N}$ by
using sig(Path,ZZ). This returns the tensor as a non-commutative
polynomial in symbols Lt_1, ..., Lt_d.

+-----------------------------------------------------------------------------+
|i9 : T = sig(X, 2)                                                           |
|                                                                             |
|     1   2 3       1       1       4       1   2 2       1       2       3   |
|o9 = -Lt  +-Lt Lt +-Lt Lt +-Lt Lt +-Lt Lt +-Lt  +-Lt Lt +-Lt Lt +-Lt Lt +-Lt |
|     2  4  7  4  3 3  4  2 5  4  1 7  3  4 2  3  5  3  2 4  3  1 3  2  4 5  2|
|                                                                             |
|o9 : QQ{Lt , Lt , Lt , Lt }                                                  |
|          1    2    3    4                                                   |
|-----------------------------------------------------------------------------|
|    1   2 1       4       3       2       1   2                              |
|Lt +-Lt  +-Lt Lt +-Lt Lt +-Lt Lt +-Lt Lt +-Lt                                |
|  3 2  2  3  2  1 5  1  4 4  1  3 3  1  2 2  1                               |
+-----------------------------------------------------------------------------+
|i10 : T // wordFormat                                                        |
|                                                                             |
|      1          3          1          1          4          1          2    |
|o10 = - [4, 4] + - [4, 3] + - [4, 2] + - [4, 1] + - [3, 4] + - [3, 3] + - [3,|
|      2          7          3          5          7          2          5    |
|      -----------------------------------------------------------------------|
|           1          2          3          1          1          4          |
|      2] + - [3, 1] + - [2, 4] + - [2, 3] + - [2, 2] + - [2, 1] + - [1, 4] + |
|           4          3          5          2          3          5          |
|      -----------------------------------------------------------------------|
|      3          2          1                                                |
|      - [1, 3] + - [1, 2] + - [1, 1]                                         |
|      4          3          2                                                |
+-----------------------------------------------------------------------------+

Note however that neither the symbols nor the ring of this polynomial are made
available to the user, in particular they can not be added or multiplied. To
obtain the tensor as a NCPolynomial in a given NCRing, use
sig(Path,ZZ,NCRing), instead. The following example demonstrates Chen's
identity:

+----------------------------------------------------------------+
|i11 : T = 1 + sig(X, 1, A) + sig(X, 2, A);                      |
+----------------------------------------------------------------+
|i12 : S = T * T;                                                |
+----------------------------------------------------------------+
|i13 : Ma = matrix (S@2) -- the second component of S as a matrix|
|                                                                |
|o13 = | 2   7/3 5/2  13/5 |                                     |
|      | 5/3 2   11/5 7/3  |                                     |
|      | 3/2 9/5 2    15/7 |                                     |
|      | 7/5 5/3 13/7 2    |                                     |
|                                                                |
|               4       4                                        |
|o13 : Matrix QQ  <-- QQ                                         |
+----------------------------------------------------------------+
|i14 : Y = X ** X -- X concatenated with itself                  |
|                                                                |
|o14 = Path in 4-dimensional space with 2 polynomial segments:   |
|                                                                |
|            2   3   4        2   3   4                          |
|      {{t, t , t , t }, {t, t , t , t }}                        |
|                                                                |
|o14 : Path                                                      |
+----------------------------------------------------------------+
|i15 : Mb = matrix (sig(Y, 2, A)@2) -- the signature matrix of Y |
|                                                                |
|o15 = | 2   7/3 5/2  13/5 |                                     |
|      | 5/3 2   11/5 7/3  |                                     |
|      | 3/2 9/5 2    15/7 |                                     |
|      | 7/5 5/3 13/7 2    |                                     |
|                                                                |
|               4       4                                        |
|o15 : Matrix QQ  <-- QQ                                         |
+----------------------------------------------------------------+
|i16 : (Ma == Mb)                                                |
|                                                                |
|o16 = true                                                      |
+----------------------------------------------------------------+

Ways to use sig:
================

  * "sig(Path,List)"
  * "sig(Path,NCRingElement)"
  * "sig(Path,ZZ)"
  * "sig(Path,ZZ,NCRing)"

For the programmer
==================

The object sig, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:1174:0.

substitute(Path,Ring) -- changes the coefficient ring of a path
***************************************************************

  * Function: substitute (Macaulay2Doc),
  * Usage:
        Y = substitute(X,R)
  * Inputs:
      * X, an instance of the type Path,
      * R, a ring (Macaulay2Doc), an algebra over the coefficient
        ring of the polynomials defining X;
  * Outputs:
      * Y, an instance of the type Path, a path with the same
        pieces as X but whose coordinate functions are now polynomials with
        coefficients in R;

Description
===========

Tries to substitute the coefficients of the polynomials defining the given path
into the given ring, producing a new path.

+-----------------------------------------------------------+
|i1 : R = QQ[t];                                            |
+-----------------------------------------------------------+
|i2 : X = polyPath({t,t^2})                                 |
|                                                           |
|o2 = Path in 2-dimensional space with 1 polynomial segment:|
|                                                           |
|           2                                               |
|     {{t, t }}                                             |
|                                                           |
|o2 : Path                                                  |
+-----------------------------------------------------------+
|i3 : coefficientRing X                                     |
|                                                           |
|o3 = QQ                                                    |
|                                                           |
|o3 : Ring                                                  |
+-----------------------------------------------------------+
|i4 : A = QQ[a];                                            |
+-----------------------------------------------------------+
|i5 : Y = substitute(X,A)                                   |
|                                                           |
|o5 = Path in 2-dimensional space with 1 polynomial segment:|
|                                                           |
|           2                                               |
|     {{t, t }}                                             |
|                                                           |
|o5 : Path                                                  |
+-----------------------------------------------------------+
|i6 : coefficientRing Y                                     |
|                                                           |
|o6 = A                                                     |
|                                                           |
|o6 : PolynomialRing                                        |
+-----------------------------------------------------------+

Ways to use this method:
========================

  * substitute(Path,Ring) -- changes the
    coefficient ring of a path
-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:380:0.

tensorArray -- k-th level component of a tensor.
************************************************

  * Usage:
        sk = tensorArray(s,k)
        sk = s@k
        L = tensorArray(s)
  * Inputs:
      * s, an instance of the type NCRingElement (NCAlgebra),
      * k, an integer (Macaulay2Doc), The level to extract;
  * Outputs:
      * sk, a list (Macaulay2Doc), The k-th level of s, as a
        multi-dimensional array;
      * L, a list (Macaulay2Doc), The list of all levels of s, as
        multi-dimensional arrays;

Description
===========

Returns the $k$-level component of a tensor as multi-dimensional array,
represented by a nested List (Macaulay2Doc).

+-----------------------------------------------------------------------------+
|i1 : R = QQ[t];                                                              |
+-----------------------------------------------------------------------------+
|i2 : X = polyPath({t,t^2});                                                  |
+-----------------------------------------------------------------------------+
|i3 : sig(X,2)@2 -- signature matrix at depth 2                               |
|                                                                             |
|       1  2    1  1                                                          |
|o3 = {{-, -}, {-, -}}                                                        |
|       2  3    3  2                                                          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : A = sig(X,3)@3 -- third level signature as multi-dimensional array      |
|                                                                             |
|        1  1    1   4       1   2     1  1                                   |
|o4 = {{{-, -}, {-, --}}, {{--, --}, {--, -}}}                                |
|        6  4    6  15      12  15    10  6                                   |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : i = 0; j = 0; k = 0;                                                    |
+-----------------------------------------------------------------------------+
|i8 : A#i#j#k == (Lt_(i+1)*Lt_(j+1)*Lt_(k+1))@(sig(X, 3)) --The coefficient of|
|                                                                             |
|o8 = true                                                                    |
|-----------------------------------------------------------------------------|
|(Lt_1)^3 in sig(X, 3)                                                        |
+-----------------------------------------------------------------------------+

If the integer $k$ is not provided, returns a list of all non trivial levels
(in nested list form).

+-------------------------------------------------------------------------+
|i9 : L = tensorArray(sig(X, 3))                                          |
|                                                                         |
|                                   1  1    1   4       1   2     1  1    |
|o9 = {{0, 0}, {{0, 0}, {0, 0}}, {{{-, -}, {-, --}}, {{--, --}, {--, -}}}}|
|                                   6  4    6  15      12  15    10  6    |
|                                                                         |
|o9 : List                                                                |
+-------------------------------------------------------------------------+
|i10 : L#2 == A                                                           |
|                                                                         |
|o10 = true                                                               |
+-------------------------------------------------------------------------+

See also
========

  * NCRingElement @ NCRingElement (missing documentation)

Ways to use tensorArray:
========================

  * "tensorArray(NCRingElement)"
  * "tensorArray(NCRingElement,ZZ)"

For the programmer
==================

The object tensorArray, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

tensorExp -- Compute a component of the exponential of a tensor.
****************************************************************

Description
===========

Let $T((\mathbb{R}^d))$ denote the dual of the tensor algebra on
$\mathbb{R}^d$, i.e., the space $\prod_k (\mathbb{R}^d)^{\otimes k}$. Given $x
\in T(\mathbb{R}^d)$ its exponential is $$\exp(x) := \sum_{k \geq 0}
\frac{1}{k!} x^{\otimes k} \in T((\mathbb{R}^d)). $$ $\texttt{tensorExp(x,k)}$
computes the degree $k$ component of $\exp(x)$.

If the constant term of the input is not $0$, the exponential can not be
expressed with algebraic coefficients. To avoid this case, the method is only
implemented for tensors with constant term equal to $0$.

+------------------------+
|i1 : R = wordAlgebra(2);|
+------------------------+
|i2 : x = [1]_R + [1,2]_R|
|                        |
|o2 = Lt Lt +Lt          |
|       1  2   1         |
|                        |
|o2 : R                  |
+------------------------+
|i3 : tensorExp(x, 2)    |
|                        |
|            1   2       |
|o3 = Lt Lt +-Lt         |
|       1  2 2  1        |
|                        |
|o3 : R                  |
+------------------------+

Caveat
======

The method is implemented only for tensors with constant term $0$.

See also
========

  * lieBasis -- basis element corresponding to a Lyndon word
    in a Lie algebra
  * tensorLog -- Compute a component of the logarithm of a
    tensor.

Ways to use tensorExp:
======================

  * "tensorExp(NCRingElement,ZZ)"

For the programmer
==================

The object tensorExp, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

tensorLog -- Compute a component of the logarithm of a tensor.
**************************************************************

Description
===========

Let $T((\mathbb{R}^d))$ denote the dual of the tensor algebra on
$\mathbb{R}^d$, i.e., the space $\prod_k (\mathbb{R}^d)^{\otimes k}$. Given $x
\in T(\mathbb{R}^d)$ with constant term $1$, its logarithm is $$\log(x) := -
\sum_{k \geq 0} \frac{1}{k} (1-x)^{\otimes k} \in T((\mathbb{R}^d)). $$
$\texttt{tensorLog(x,k)}$ computes the degree $k$ component of $\log(x)$.

+--------------------------------------------------------+
|i1 : A2 = wordAlgebra(2);                               |
+--------------------------------------------------------+
|i2 : x = 1 + [1]_A2 + 1/2 * [1,1]_A2 + 1/6 * [1,1,1]_A2;|
+--------------------------------------------------------+
|i3 : sum(0..3, i -> tensorLog(x, i))                    |
|                                                        |
|o3 = Lt                                                 |
|       1                                                |
|                                                        |
|o3 : A2                                                 |
+--------------------------------------------------------+

Caveat
======

The method is implemented only for tensors with constant term $1$.

See also
========

  * tensorExp -- Compute a component of the exponential of a
    tensor.

Ways to use tensorLog:
======================

  * "tensorLog(NCRingElement,ZZ)"

For the programmer
==================

The object tensorLog, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

tensorParametrization -- Constructs the morphism that maps a word to its coefficient in the given tensor.
*********************************************************************************************************

  * Usage:
        m = tensorParametrization(f)
  * Inputs:
      * T, an instance of the type NCRingElement (NCAlgebra),
        the tensor encoding the parametrization;
  * Optional inputs (Macaulay2Doc),:
      * CoefficientRing => a rational number (Macaulay2Doc), default
        value null, the coefficient ring of the domain polynomial ring;
      * VarWordTable => ..., default value null, a hash table that assigns
        variables of a free polynomial ring to words. If provided, the ring is
        used as the domain of the map;
  * Outputs:
      * m, a ring map (Macaulay2Doc), the parametrization
        encoded by T;

Description
===========

Given some $k$-algebra $A$, a tensor $f = \sum_{\mathtt{w} \in I} a_w
\mathtt{w} \in A \langle\texttt{1},\ldots,\texttt{d}\rangle$ can be viewed as a
morphism $\mathrm{Spec} \ A \to k^I$. This method constructs the associated map
of coordinate rings, that is, the morphism $k[b_w \ | \ w\in I] \to A$ that
maps $b_\mathtt{w}$ to $a_\mathtt{w}$. Here $k$ is the $\texttt{baseRing}$ of
$A$. If $\texttt{CoefficientRing}$ is provided, it replaces $k$. If
$\texttt{VarWordTable}$ is provided, the map above is precomposed with the
morphism induced by the assignments in the hash table.

+-----------------------------------------------------------+
|i1 : R = QQ[a,b];                                          |
+-----------------------------------------------------------+
|i2 : A2 = wordAlgebra(2, CoefficientRing => R);            |
+-----------------------------------------------------------+
|i3 : T = a^2 * [1,1]_A2 + a * b * [1,2]_A2 + b^2 * [2,2]_A2|
|                                                           |
|      2   2            2   2                               |
|o3 = b Lt  +a*bLt Lt +a Lt                                 |
|         2       1  2     1                                |
|                                                           |
|o3 : A2                                                    |
+-----------------------------------------------------------+
|i4 : tensorParametrization(T); wordFormat T                |
|                                                           |
|o4 : RingMap R <-- QQ[b      , b      , b      ]           |
|                       [1, 2]   [1, 1]   [2, 2]            |
|                                                           |
|      2                        2                           |
|o5 = b  [2, 2] + a*b [1, 2] + a  [1, 1]                    |
+-----------------------------------------------------------+
|i6 : S = QQ[x,y,z];                                        |
+-----------------------------------------------------------+
|i7 : vwtable = hashTable({(x,[1,1]),(y,[1,2]),(z,[2,2])})  |
|                                                           |
|o7 = HashTable{x => [1, 1]}                                |
|               y => [1, 2]                                 |
|               z => [2, 2]                                 |
|                                                           |
|o7 : HashTable                                             |
+-----------------------------------------------------------+
|i8 : m = tensorParametrization(T, VarWordTable => vwtable) |
|                                                           |
|                  2        2                               |
|o8 = map (R, S, {a , a*b, b })                             |
|                                                           |
|o8 : RingMap R <-- S                                       |
+-----------------------------------------------------------+
|i9 : kernel m                                              |
|                                                           |
|            2                                              |
|o9 = ideal(y  - x*z)                                       |
|                                                           |
|o9 : Ideal of S                                            |
+-----------------------------------------------------------+

For a key use example see Computing Path Varieties.

Ways to use tensorParametrization:
==================================

  * "tensorParametrization(NCRingElement)"

For the programmer
==================

The object tensorParametrization, is a
method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

wordAlgebra -- create a free algebra over a given alphabet
**********************************************************

Description
===========

In this package, tensors are represented as elements of free associative
algebras, using the package NCAlgebra. More precisely,
the free associative algebra on the alphabet $\{\texttt 1,...,\texttt d\}$ is
isomorphic to the tensor algebra $T(\mathbb R^d)$ via the algebra homomorphism
induced by $\texttt i \mapsto e_i$. This allows us to interpret tensors as
non-commutative polynomials, or equivalently, linear combinations of words.
Given an alphabet $l$, the free associative algebra over it can be obtained by
using wordAlgebra, where the letter corresponding to $x \in
l$ is represented by $\texttt{Lt}_x$.

+--------------------------------------------------------+
|i1 : d = 5;                                             |
+--------------------------------------------------------+
|i2 : l1 = {getSymbol "a", getSymbol "b", getSymbol "c"};|
+--------------------------------------------------------+
|i3 : A = wordAlgebra(l1)                                |
|                                                        |
|o3 = A                                                  |
|                                                        |
|o3 : NCPolynomialRing                                   |
+--------------------------------------------------------+
|i4 : gens A                                             |
|                                                        |
|o4 = {Lt , Lt , Lt }                                    |
|        a    b    c                                     |
|                                                        |
|o4 : List                                               |
+--------------------------------------------------------+
|i5 : l2 = toList(1..d);                                 |
+--------------------------------------------------------+
|i6 : B = wordAlgebra(l2)                                |
|                                                        |
|o6 = B                                                  |
|                                                        |
|o6 : NCPolynomialRing                                   |
+--------------------------------------------------------+
|i7 : gens B                                             |
|                                                        |
|o7 = {Lt , Lt , Lt , Lt , Lt }                          |
|        1    2    3    4    5                           |
|                                                        |
|o7 : List                                               |
+--------------------------------------------------------+

The algebra B in the example can also be directly obtained for a given d using
wordAlgebra(ZZ),:

+------------------------------+
|i8 : B = wordAlgebra(d);      |
+------------------------------+
|i9 : gens B                   |
|                              |
|o9 = {Lt , Lt , Lt , Lt , Lt }|
|        1    2    3    4    5 |
|                              |
|o9 : List                     |
+------------------------------+

By default, see wordAlgebra, creates a non-commutative algebra
over QQ (Macaulay2Doc). The coefficient ring can be changed via the
CoefficientRing option:

+-----------------------------------------------+
|i10 : coefficientRing B                        |
|                                               |
|o10 = QQ                                       |
|                                               |
|o10 : Ring                                     |
+-----------------------------------------------+
|i11 : C = wordAlgebra(d, CoefficientRing => CC)|
|                                               |
|o11 = C                                        |
|                                               |
|o11 : NCPolynomialRing                         |
+-----------------------------------------------+
|i12 : coefficientRing C                        |
|                                               |
|o12 = CC                                       |
|        53                                     |
|                                               |
|o12 : ComplexField                             |
+-----------------------------------------------+

An element of the algebra can be obtained by using the generator symbols, or
(more conveniently) by using word notation, see Array _ NCPolynomialRing,:

+-----------------------------------------------------------------------------+
|i13 : d = 5;                                                                 |
+-----------------------------------------------------------------------------+
|i14 : R = wordAlgebra(d); -- create a free associative algebra over two      |
|-----------------------------------------------------------------------------|
|letters Lt_1, Lt_2                                                           |
+-----------------------------------------------------------------------------+
|i15 : f = 2 * [1,d]_R - [2,d]_R  -- [i_1,...,i_k]_R defines a word.          |
|                                                                             |
|o15 = -Lt Lt +2Lt Lt                                                         |
|         2  5    1  5                                                        |
|                                                                             |
|o15 : R                                                                      |
+-----------------------------------------------------------------------------+
|i16 : f === 2 * Lt_1 * Lt_d - Lt_2 * Lt_d                                    |
|                                                                             |
|o16 = true                                                                   |
+-----------------------------------------------------------------------------+

Note that for two words (equivalently, monomials) $\texttt{w}$ and
$\texttt{v}$, $\texttt{w} * \texttt{v}$ is the concatenation.

To display a non-commutative polynomial in word notation, one can use
wordFormat, or wordString,:

+-----------------------------------------------------------------------------+
|i17 : f^3 // wordFormat                                                      |
|                                                                             |
|o17 = - [2, 5, 2, 5, 2, 5] + 2 [2, 5, 2, 5, 1, 5] + 2 [2, 5, 1, 5, 2, 5] - 4 |
|      -----------------------------------------------------------------------|
|      [2, 5, 1, 5, 1, 5] + 2 [1, 5, 2, 5, 2, 5] - 4 [1, 5, 2, 5, 1, 5] - 4   |
|      -----------------------------------------------------------------------|
|      [1, 5, 1, 5, 2, 5] + 8 [1, 5, 1, 5, 1, 5]                              |
+-----------------------------------------------------------------------------+
|i18 : f^3 // wordString                                                      |
|                                                                             |
|o18 = - [2, 5, 2, 5, 2, 5] + 2 [2, 5, 2, 5, 1, 5] + 2 [2, 5, 1, 5, 2, 5] - 4 |
|      [2, 5, 1, 5, 1, 5] + 2 [1, 5, 2, 5, 2, 5] - 4 [1, 5, 2, 5, 1, 5] - 4   |
|      [1, 5, 1, 5, 2, 5] + 8 [1, 5, 1, 5, 1, 5]                              |
+-----------------------------------------------------------------------------+

There are more interesting algebraic structures on non-associative algebras; of
particular importance in the context of path signatures is the shuffle product
and the half-shuffle product:

+-----------------------------------------------------------------------------+
|i19 : a = [1]_R ** [2]_R; wordFormat a -- the shuffle product                |
|                                                                             |
|o20 = [2, 1] + [1, 2]                                                        |
+-----------------------------------------------------------------------------+
|i21 : b = [1,2]_R ** [3,4]_R; wordFormat b                                   |
|                                                                             |
|o22 = [3, 4, 1, 2] + [3, 1, 4, 2] + [3, 1, 2, 4] + [1, 3, 4, 2] + [1, 3, 2,  |
|      -----------------------------------------------------------------------|
|      4] + [1, 2, 3, 4]                                                      |
+-----------------------------------------------------------------------------+
|i23 : c = [1]_R >> [2,3]_R; wordFormat c -- the half-shuffle product         |
|                                                                             |
|o24 = [2, 1, 3] + [1, 2, 3]                                                  |
+-----------------------------------------------------------------------------+

See NCRingElement ** NCRingElement, and NCRingElement >> NCRingElement,
for more information on the shuffle and
half-shuffle product.

See also
========

  * Array _ NCPolynomialRing (missing documentation)

Ways to use wordAlgebra:
========================

  * "wordAlgebra(List)"
  * "wordAlgebra(ZZ)"

For the programmer
==================

The object wordAlgebra, is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:918:0.

wordFormat -- display a tensor in word notation
***********************************************

Description
===========

A more readable display of tensors can be obtained through the following
convention. Let $Lt_1,\dots, Lt_d$ be the generators of $R$, then an array of
integers $[i_1,\dots, i_k]$ such that $0<i_l<d+1, \forall 1\leq l\leq k$ yields
the decomposable tensor $$Lt_{i_1} Lt_{i_2}\cdot\dots\cdot Lt_{i_{k-1}}
Lt_{i_k}$$ of $R$. This notation can then be extended linearly to any tensor.

+-----------------------------------------------------------------------------+
|i1 : R = wordAlgebra(2);                                                     |
+-----------------------------------------------------------------------------+
|i2 : f = ([1,2]_R ** [1,2]_R) -- shuffle product of Lt_1*Lt_1 with itself    |
|                                                                             |
|                       2   2                                                 |
|o2 = 2Lt Lt Lt Lt +4Lt  Lt                                                   |
|        1  2  1  2    1   2                                                  |
|                                                                             |
|o2 : R                                                                       |
|-----------------------------------------------------------------------------|
|displayed as a non commutative polynomial                                    |
+-----------------------------------------------------------------------------+
|i3 : f // wordFormat -- f displayed in the above notation                    |
|                                                                             |
|o3 = 2 [1, 2, 1, 2] + 4 [1, 1, 2, 2]                                         |
+-----------------------------------------------------------------------------+

See also
========

  * wordAlgebra -- create a free algebra over a given
    alphabet
  * Array _ NCPolynomialRing (missing documentation)

Ways to use wordFormat:
=======================

  * "wordFormat(NCRingElement)"

For the programmer
==================

The object wordFormat, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.

wordString -- a string representing a word in wordFormat
********************************************************

  * Usage:
        w // wordString
  * Inputs:
      * w, an instance of the type NCRingElement (NCAlgebra),
  * Outputs:
      * s, a string (Macaulay2Doc), A string representing the
        word 2 in word format;

Description
===========

Returns a string representing the word as described in wordFormat.

+---------------------------------------------------+
|i1 : R = wordAlgebra(3);                           |
+---------------------------------------------------+
|i2 : w = [1,2,3]_R + 2 * [3,2,1]_R; w // wordFormat|
|                                                   |
|o3 = 2 [3, 2, 1] + [1, 2, 3]                       |
+---------------------------------------------------+
|i4 : w // wordString                               |
|                                                   |
|o4 = 2 [3, 2, 1] + [1, 2, 3]                       |
+---------------------------------------------------+

See also
========

  * wordAlgebra -- create a free algebra over a given
    alphabet
  * wordFormat -- display a tensor in word notation
  * Array _ NCPolynomialRing (missing documentation)

Ways to use wordString:
=======================

  * "wordString(NCRingElement)"

For the programmer
==================

The object wordString, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in PathSignatures/documentation.m2:159:0.