---
title: "Objects `dx`, `dy`, and `dz` in the `stokes` package"
author: "Robin K. S. Hankin"
output: html_vignette
bibliography: stokes.bib
link-citations: true
vignette: >
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteIndexEntry{dx}
  %\usepackage[utf8]{inputenc}
---

```{r setup, include=FALSE}
set.seed(0)
library("stokes")
knitr::opts_chunk$set(echo = TRUE)
options(rmarkdown.html_vignette.check_title = FALSE)
```

```{r out.width='20%', out.extra='style="float:right; padding:10px"',echo=FALSE}
knitr::include_graphics(system.file("help/figures/stokes.png", package = "stokes"))
```

```{r label=definedxdydz}
dx <- d(1)
dy <- d(2)
dz <- d(3)
```

To cite the `stokes` package in publications, please use
@hankin2022_stokes.  Convenience objects `dx`, `dy`, and `dz`,
corresponding to elementary differential forms, are discussed here
(basis vectors $e_1$, $e_2$, $e_2$ are discussed in vignette
`ex.Rmd`).

@spivak1965, in a memorable passage, states:

<div class="warning" style='padding:0.1em; background-color:#E9D8FD; color:#69337A'>
<span>
<p style='margin-top:1em; text-align:center'>
<b>Fields and forms</b></p>
<p style='margin-left:1em;'>

If $f\colon\mathbb{R}^n\longrightarrow\mathbb{R}$ is differentiable,
then $Df(p)\in\Lambda^1(\mathbb{R}^n)$.  By a minor modification we
therefore obtain a $1$-form $\mathrm{d}f$, defined by

$$\mathrm{d}f(p)(v_p)=Df(p)(v).$$

Let us consider in particular the $1$-forms $\mathrm{d}\pi^i$ ^[Spivak
introduces the $\pi^i$ notation on page 11: "if
$\pi\colon\mathbb{R}^n\longrightarrow\mathbb{R}^n$ is the identity
function, $\pi(x)=x$, then [its components are] $\pi^i(x)=x^i$; the
function $\pi^i$ is called the $i^\mathrm{th}$ *projection
function*"].  It is customary to let $x^i$ denote the _function_
$\pi^i$ (on $\mathbb{R}^3$ we often denote $x^1$, $x^2$, and $x^3$ by
$x$, $y$, and $z$) $\ldots$ Since
$\mathrm{d}x^i(p)(v_p)=\mathrm{d}\pi^i(p)(v_p)=D\pi^i(p)(v)=v^i$, we
see that $\mathrm{d}x^1(p),\ldots,\mathrm{d}x^n(p)$ is just the dual
basis to $(e_1)_p,\ldots, (e_n)_p$.

</p>
<p style='margin-bottom:1em; margin-right:1em; text-align:right; font-family:Georgia'> <b>- Michael Spivak, 1969</b> <i>(Calculus on Manifolds, Perseus books).  Page 89</i>
</p></span>
</div>


Spivak goes on to observe that every $k$-form $\omega$ can be written
$\omega=\sum_{i_1 < \cdots < i_k}\omega_{i_1,\ldots,
i_k}\mathrm{d}x^{i_1}\wedge\cdots\wedge\mathrm{d}x^{i_k}$.  If working
in $\mathbb{R}^3$, we have three elementary forms $\mathrm{d}x$,
$\mathrm{d}y$, and $\mathrm{d}z$; in the package we have the
pre-defined objects `dx`, `dy`, and `dz`.  These are convenient for
reproducing textbook results.  

We conceptualise `dx` as "picking out" the $x$-component of a 3-vector
and similarly for `dy` and `dz`.  Recall that
$\mathrm{d}x\colon\mathbb{R}^3\longrightarrow\mathbb{R}$ and we have

$$
dx\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix} = u_1\qquad
dy\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix} = u_2\qquad
dz\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix} = u_3.
$$


Noting that $1$-forms are a vector space, we have in general

$$(a\cdot\mathrm{d}x + b\cdot\mathrm{d}y +c\cdot\mathrm{d}z)
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix} = au_1+bu_2+cu_3 $$

Numerically:


```{r}
v <- c(2,3,7)
c(as.function(dx)(v),as.function(dx+dy)(v),as.function(dx+100*dz)(v))
```

As Spivak says, `dx`, `dy` and `dz` are conjugate to $e_1,e_2,e_3$ and
these are defined using function `e()`.  In this case it is safer to
pass `n=3` to function `e()` in order to specify that we are working
in $\mathbb{R}^3$.

```{r}
e(1,3)
e(2,3)
e(3,3)
```

We will now verify numerically that `dx`, `dy` and `dz` are indeed
conjugate to $e_1,e_2,e_3$, but to do this we will define an
orthonormal set of vectors $u,v,w$:

```{r}
u <- e(1,3)
v <- e(2,3)
w <- e(3,3)
matrix(c(
    as.function(dx)(u), as.function(dx)(v), as.function(dx)(w),
    as.function(dy)(u), as.function(dy)(v), as.function(dy)(w),
    as.function(dz)(u), as.function(dz)(v), as.function(dz)(w)
),3,3)
```

Above we see the conjugacy clearly [obtaining $I_3$ as expected].


## Wedge products

The elementary forms may be combined with a wedge product.  We note
that
$\mathrm{d}x\wedge\mathrm{d}y\colon\left(\mathbb{R}^3\right)^2\longrightarrow\mathbb{R}$
and, for example,

$$
(\mathrm{d}x\wedge\mathrm{d}y)\left(
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix}
\right)
=
\det\begin{pmatrix}u_1&v_1\\u_2&v_2\end{pmatrix}
$$

and

$$
(\mathrm{d}x\wedge\mathrm{d}y\wedge\mathrm{d}z)
\left(
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix},
\begin{pmatrix}w_1\\w_2\\w_3\end{pmatrix}
\right)
=
\det\begin{pmatrix}u_1&v_1&w_1\\u_2&v_2&w_2\\u_3&v_3&w_3\end{pmatrix}
$$

Numerically:

```{r}
as.function(dx ^ dy)(cbind(c(2,3,5),c(4,1,2)))
```
Above we see the package correctly giving
$\det\begin{pmatrix}2&4\\3&1\end{pmatrix}=2-12=-10$.

# The print method 

Here I give some illustrations of the package print method.

```{r label=showdx}
dx
```

This is somewhat opaque and difficult to understand.  It is easier to
start with a more complicated example: take
$X=\mathrm{d}x\wedge\mathrm{d}y -7\mathrm{d}x\wedge\mathrm{d}z
+ 3\mathrm{d}y\wedge\mathrm{d}z$:

```{r label=morecomplicatedcombination}
(X <- dx^dy -7*dx^dz + 3*dy^dz)
```

We see that `X` has three rows for the three elementary components.
Taking the row with coefficient $-7$ [which would be
$-7\mathrm{d}x\wedge\mathrm{d}z$], this maps
$\left(\mathbb{R}^3\right)^2$ to $\mathbb{R}$ and we have

$$(-7\mathrm{d}x\wedge\mathrm{d}z)\left(\begin{pmatrix}
u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix}\right)=
-7\det\begin{pmatrix}u_1&v_1\\u_3&v_3\end{pmatrix}
$$


The other two rows would be 

$$(3\mathrm{d}y\wedge\mathrm{d}z)\left(
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix}
\right)
=
3\det\begin{pmatrix}u_2&v_2\\u_3&v_3\end{pmatrix}$$

and 

$$(1\mathrm{d}x\wedge\mathrm{d}y)\left(
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix}
\right)
=
\det\begin{pmatrix}u_1&v_1\\u_2&v_2\end{pmatrix}
$$

Thus form $X$ would be, by linearity

$$
X\left(
\begin{pmatrix}u_1\\u_2\\u_3\end{pmatrix},
\begin{pmatrix}v_1\\v_2\\v_3\end{pmatrix}
\right)
=
-7\det\begin{pmatrix}u_1&v_1\\u_3&v_3\end{pmatrix}
+3\det\begin{pmatrix}u_2&v_2\\u_3&v_3\end{pmatrix}
+\det\begin{pmatrix}u_1&v_1\\u_2&v_2\end{pmatrix}.
$$


We might want to verify that
$\mathrm{d}x\wedge\mathrm{d}y=-\mathrm{d}y\wedge\mathrm{d}x$:

```{r dxdyequalsminusdydx}
dx ^ dy == -dy ^ dx
```

# Configuring the print method

The print method is configurable and can display kforms in symbolic
form.  For working with `dx dy dz` we may set option
`kform_symbolic_print` to `dx`:

```{r setusedx}
options(kform_symbolic_print = 'dx')
```

Then the results of calculations are more natural:

```{r showdxwithusedx}
dx
dx^dy + 56*dy^dz
```

However, this setting can be confusing if we work with
$\mathrm{d}x^i,i>3$, for the print method runs out of alphabet:

```{r runsoutofalphabet}
rform()
```

Above, we see the use of `NA` because there is no defined symbol.


## The Hodge dual

Function `hodge()` returns the Hodge dual:

```{r hodgedxdydz}
hodge(dx^dy + 13*dy^dz)
```

Note that calling `hodge(dx)` can be confusing:

```{r hodgedx}
hodge(dx)
```

This returns a scalar because `dx` is interpreted as a one-form on
one-dimensional space, which is a scalar form.  One usually wants the
result in three dimensions:

```{r hodgedx3}
hodge(dx,3)
```

This is further discussed in the `dovs` vignette.

## Creating elementary one-forms

Package function `d()` will create elementary one-forms but it is
easier to interpret the output if we restore the default print method

```{r}
options(kform_symbolic_print = NULL)
d(8)
```

### Package dataset

Following lines create `dx.rda`, residing in the `data/` directory of
the package.

```{r,label=savedxdydz}
save(dx, dy, dz, file="dx.rda")
```

# References