KroneckerProduct Basic Skeleton

Armed with information from the previous sections:

  • Where the function belongs: “Vector Space Operations”, and

  • Information from WMA and SymPy on what should be implemented and how it hooks into an existing library function

  • Wikipedia name of this function

we are now ready to being with a skeletal version from which we can fill out later.

As noted before, “Vector Space Operations” is located in directory mathics/builtin/vectors/vector_space_operations.py.

Down that the bottom of that file we have:

# TODO: Orthogonalize, KroneckerProduct

so we have noted the need for that here already. Good. Let’s remove KroneckerProduct from that list.

KroneckerProduct Title Line

Here is the the beginning of the Python code to implement KroneckerProduct:

class KroneckerProduct(SympyFunction):
    """
    <url>:Kronecker product: https://en.wikipedia.org/wiki/Kronecker_product</url> (<url>:SymPy: https://docs.sympy.org/latest/modules/physics/quantum/tensorproduct.html</url>, <url>:WMA: https://reference.wolfram.com/language/ref/KroneckerProduct.html</url>)
    ...
    """

We will go over the docstring entry a little more quickly than we did in describing Undefined. Consult First Skeletal version for a more detailed description of what goes in the docstring. Here we will cover aspects that were not covered there.

In contrast to the class definition in Undefined, which is a subclass of Builtin, here we use a SympyFunction which in turn is a subclass of Builtin. SympyFunction has been customized for built-in Mathics3 functions that are implemented via SymPy.

Also in contrast the title line for Undefined, the title line here is longer because there is a Wikipedia entry that corresponds to this function, and because there is a corresponding SymPy function as well.

KroneckerProduct Function Definition Description

class KroneckerProduct(SympyFunction):
    """
    ...
    <dl>
      <dt>'KroneckerProduct[$m1$, $m2$, ...]'
      <dd>returns the Kronecker product of the arrays $mi$
    </dl>
    """

In addition to the tags seen when we wrote Undefined, we have a new markup tag. This is the dollar signs that surround variable names. In particular, we have $m1$, $m2$ and $mi$.

The dollar signed around the names indicate that the text inside is a variable or parameter to the function.

Also notice that the word the entire form surrounded in quotes the <dt> tag, that is 'KroneckerProduct[$m1$, $m2$, ...]'

KroneckerProduct Examples

As we saw with Undefined, the last part of the docstring contains useful examples involving the function we are defining, KroneckerProduct:

class KroneckerProduct(SympyFunction):
    """
    ...
    <dl>
      <dt>'KroneckerProduct[$m1$, $m2$, ...]'
      <dd>returns the Kronecker product of the arrays $mi$
    </dl>

    Show symbolically how the Kronecker product works on two two-dimensional arrays:

    >> a = {{a11, a12}, {a21, a22}}; b = {{b11, b12}, {b21, b22}};
    >> KroneckerProduct[a, b]
     = {{a11 b11, a11 b12, a12 b11, a12 b12}, {a11 b21, a11 b22, a12 b21, a12 b22}, {a21 b11, a21 b12, a22 b11, a22 b12}, {a21 b21, a21 b22, a22 b21, a22 b22}}

    Now do the same with discrete values:

    >> a = {{0, 1}, {-1, 0}}; b = {{1, 2}, {3, 4}};

    >> KroneckerProduct[a, b] // MatrixForm
     = 0    0    1   2
     .
     .  0    0    3   4
     .
     . -1   -2   0   0
     .
     . -3   -4   0   0

    #> Clear[a, b];
    """

And here we encounter some new markup. First, there are lines that start with . These are used to indicate that the expected output has line breaks in them. The attach to the output that appears above them: either another line that starts . or a line that starts =.

Finally we have a line that starts #>. This indicates a Mathics statement that is to be run, but should not be shown in the Django documentation. We use this here as cleanup for the code that gets in the examples before: we had defined two variables a and b, and we now want to make sure these definitions get removed. Since we don’t really care about the output of Clear[] (which is None) we add the semicolon to suppress output. Notice that there is no = line after Clear because no output is expected.

Next: