---
title: "Objects `dx`, `dy`, and `dz` in the `stokes` package"
author: "Robin K. S. Hankin"
output: html_vignette
bibliography: stokes.bib
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 `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 start with 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
$\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}
dx^dy -7*dx^dz + 3*dy^dz
```

We see 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}$$

Armed with this familiar fact, we can interpret $dx$ as a map from
$\left(\mathbb{R}^3\right)^1$ to $\mathbb{R}$ with

$$\mathrm{d}x\left(\begin{pmatrix} u_1\\u_2\\u_3\end{pmatrix}
\right)=
\det\begin{pmatrix}u_1\end{pmatrix}=u_1$$

or, in other words, $\mathrm{d}x$ picks out the first component of its
vector (as the print method gives, albeit obscurely).  This is easily
shown in the package:

```{r coercedxtoafunction}
as.function(dx)(c(113,3,6))
```

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
```

# Elementary forms and 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.

## Other ways to create the elementary one-forms

It is possible to create these objects using package idiom:

```{r}
d(1) == dx
```

## Basis vectors 


### 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