stokes

methods for exterior calculus

https://github.com/robinhankin/stokes

Repository

methods for exterior calculus

README.Rmd

---
title: "The stokes package: exterior calculus in R"
output:
  github_document:
    pandoc_args: --webtex
---



```{r setup, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# 


[![CRAN_Status_Badge](https://www.r-pkg.org/badges/version/stokes)](https://cran.r-project.org/package=stokes)
[![Codecov test coverage](https://codecov.io/gh/RobinHankin/stokes/graph/badge.svg)](https://app.codecov.io/gh/RobinHankin/stokes)


# Overview

The `stokes` package provides functionality for working with the
exterior calculus.  It includes tensor products and wedge products and
a variety of use-cases.  The canonical reference would be Spivak (see
references).  A detailed vignette is provided in the package.

The package deals with $k$-tensors and $k$-forms.  A $k$-tensor is a
multilinear map $S\colon V^k\longrightarrow\mathbb{R}$, where
$V=\mathbb{R}^n$ is considered as a vector space.  Given two
$k$-tensors $S,T$ the package can calculate their outer product
$S\otimes T$ using natural R idiom (see below and the vignette for
details).

A $k$-form is an alternating $k$-tensor, that is a $k$-tensor $\omega$
with the property that linear dependence of $x_1,\ldots,x_n$ implies
that $\omega\left(x_1,\ldots,x_n\right)=0$.  Given $k$-forms
$\omega,\eta$, the package provides R idiom for calculating
their wedge product $\omega\wedge\eta$.

# Installation

You can install the released version of `stokes` from
[CRAN](https://CRAN.R-project.org) with:

```{r, message=FALSE}
# install.packages("stokes")  # uncomment this to install the package
library("stokes")
set.seed(0)
```

# The `stokes` package in use

The package has two main classes of objects, `kform` and `ktensor`.
In the package, we can create a $k$-tensor by supplying function
`as.ktensor()` a matrix of indices and a vector of coefficients, for
example:

```{r ktensor}
jj <- as.ktensor(rbind(1:3,2:4),1:2)
jj
```

Above, object `jj` is equal to $dx_1\otimes dx_2\otimes dx_3 +
2dx_2\otimes dx_3\otimes dx_4$ (see Spivak, p76 for details).

We can coerce tensors to a function and then evaluate it:

```{r evaluatektensor}
KT <- as.ktensor(cbind(1:4,2:5),1:4)
f <- as.function(KT)
E <- matrix(rnorm(10),5,2)
f(E)
```

Tensor products are implemented:

```{r tensorprod}
KT %X% KT
```

Above we see ${\mathrm KT}\otimes{\mathrm KT}$.

## Alternating forms

An alternating form (or $k$-form) is an antisymmetric $k$-tensor; the
package can convert a general $k$-tensor to alternating form using the
`Alt()` function:


```{r showalt}
Alt(KT)
```

However, the package provides a bespoke and efficient representation
for $k$-forms as objects with class `kform`.  Such objects may be
created using the `as.kform()` function:

```{r example}

M <- matrix(c(4,2,3,1,2,4),2,3,byrow=TRUE)
M
KF <- as.kform(M,c(1,5))
KF
```

Above, we see that `KF` is equal to $dx_2\wedge dx_3\wedge dx_4 +
5dx_1\wedge dx_2\wedge dx_4$.  We may coerce `KF` to functional form:

```{r e2}
f <- as.function(KF)
E <- matrix(rnorm(12),4,3)
f(E)
```

Above, we evaluate `KF` at a point in $\left({\mathbb R^4}\right)^3$
[the three columns of matrix `E` are each interpreted as vectors in
${\mathbb R}^4$].

# The wedge product

The wedge product of two $k$-forms is implemented as `^` or
`wedge()`:

```{r definekf2}
KF2 <- kform_general(6:9,2,1:6)
KF2
KF ^ KF2
```

The package can accommodate a number of results from the exterior
calculus such as elementary forms:

```{r dxdyxz}
dx <- as.kform(1)
dy <- as.kform(2)
dz <- as.kform(3)
dx ^ dy ^ dz  # element of volume 
```

A number of useful functions from the exterior calculus are provided,
such as the gradient of a scalar function:

```{r grad}
grad(1:6)
```

The package takes the leg-work out of the exterior calculus:

```{r legwork}
grad(1:4) ^ grad(1:6)
```


# References

The most concise reference is

  - Spivak 1971. _Calculus on manifolds_, Addison-Wesley.

But a more leisurely book would be

  - Hubbard and Hubbard 2015. _Vector calculus, linear algebra, and differential forms: a unified approach_.  Matrix Editions

# Further information

For more detail, see the package vignette

`vignette("stokes")`

Owner

GitHub Events

Committers

Last synced: over 2 years ago

Issues and Pull Requests

Last synced: 11 months ago

Packages