% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-


% ------------------------------------------------------------------------
% bjourdoc.tex for birkjour.cls: Last revised April 3, 2021, by R.A.****
% ------------------------------------------------------------------------
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\documentclass{birkjour}
%%%Optional but convenient to use is the package ``cite''. If you do not want to use it, remark the next line by placing the percent sign % in front of it:
\usepackage[noadjust]{cite}
\usepackage{xcolor}
\usepackage{wrapfig}
\usepackage{amssymb}
\usepackage{Sweave}
\usepackage{doi}
\usepackage{url}
\RequirePackage[all]{xy}

%\include{Tmacros}

%
% THEOREM Environments (Examples)-----------------------------------------
%
\newtheorem{thm}{Theorem}[section]
\newtheorem{cor}[thm]{Corollary}
\newtheorem{lem}[thm]{Lemma}
\newtheorem{prop}[thm]{Proposition}
\theoremstyle{definition}
\newtheorem{defn}[thm]{Definition}
\theoremstyle{remark}
\newtheorem{rem}[thm]{Remark}
\newtheorem{comment}[thm]{Comment}
\newtheorem*{ex}{Example}
\numberwithin{equation}{section}
\newtheorem*{warning}{\textbf{Warning!}}


\newcommand{\BibTeX}{B\kern-0.1emi\kern-0.017emb\kern-0.15em\TeX}
\newcommand{\XYpic}{$\mathrm{X\kern-0.3em\raisebox{-0.18em}{Y}}$-$\mathrm{pic}\,$}
\newcommand{\TexnicCenter}{\TeX nicCenter}

%%%Clifford algebra macros
\newcommand{\cl}{C \kern -0.1em \ell}  %%Clifford algebra

\DeclareMathOperator{\JJ}{\mathbin{\raisebox{0.25ex}%
                       {\mbox{\scriptsize$
                       \rm\vphantom{I}%
                       \_\hskip -0.25em\_%
                       \vrule width 0.6pt$}}}}           %left contraction

\DeclareMathOperator{\LL}{\mathbin{\raisebox{0.25ex}%
                        {\mbox{\scriptsize$
                        \rm\vphantom{I}%
                        \vrule width 0.6pt \hskip -0.5pt%
                        \_\hskip -0.25em\_$}}}}          %right contraction

\newcommand{\JJB}[1]{\JJ_{#1}}
\newcommand{\LLB}[1]{\LL_{#1}}


\newcommand{\w}{\wedge}
\newcommand{\bigw}{\bigwedge}
\newcommand{\dw}{\mathbin{\dot\wedge}}
\newcommand{\dwedge}{\mathbin{\dot\wedge}}

\DeclareMathOperator{\hotimes}{\Hat{\otimes}}
\DeclareMathOperator{\chr}{\mathrm{char}}

\newcommand{\bx}{\mathbf{x}}
\newcommand{\by}{\mathbf{y}}
\newcommand{\ba}{\mathbf{a}}
\newcommand{\bb}{\mathbf{b}}


%
\newcommand{\BF}{\mathbb{F}}
\newcommand{\BZ}{\mathbb{Z}}
\newcommand{\BR}{\mathbb{R}}
\newcommand{\BC}{\mathbb{C}}
\newcommand{\BH}{\mathbb{H}}

\newcommand{\ed}{\end{document}}
\begin{document}

%-------------------------------------------------------------------------
% editorial commands: to be inserted by the editorial office
%
%\firstpage{1} \volume{228} \Copyrightyear{2004} \DOI{003-0001}
%
%
%\seriesextra{Just an add-on}
%\seriesextraline{This is the Concrete Title of this Book\br H.E. R and S.T.C. W, Eds.}
%
% for journals:
%
%\firstpage{1}
%\issuenumber{1}
%\Volumeandyear{1 (2004)}
%\Copyrightyear{2004}
%\DOI{003-xxxx-y}
%\Signet
%\commby{inhouse}
%\submitted{March 14, 2003}
%\received{March 16, 2000}
%\revised{June 1, 2000}
%\accepted{July 22, 2000}
%
%
%
%---------------------------------------------------------------------------
%Insert here the title, affiliations and abstract:
%

\title[Clifford algebra in R]{
 Clifford algebra in R: introducing the {\tt clifford} package}
%----------Author 1
\author[Hankin]{Robin K. S. Hankin}
\address{%
  University of Stirling\\
  Stirling FK9 4LH\\
  United Kingdom
}
%
\email{hankin.robin@gmail.com}
%
%----------classification, keywords, date
\subjclass{Primary 15A66, 16W50, 20C05, 20C40, 20D15; Secondary 68W30}
%
\keywords{Class file, HTML, journal}
%
\date{\today}
%----------additions
\dedicatory{Last Revised:\\ \today}
%%% ----------------------------------------------------------------------
\begin{abstract}

Here I present the {\tt clifford} package for working with Clifford
algebras in the R programming language.  Algebras of arbitrary
dimension and signature can be manipulated, and a range of different
multiplication operators is provided.  The algebra is described and
package idiom is given; it obeys {\tt disordR} discipline.  The
package is available on CRAN at
\tt{https://CRAN.R-project.org/package=clifford}.


\end{abstract}
\label{page:firstblob}
%%% ----------------------------------------------------------------------
\maketitle
%%% ----------------------------------------------------------------------
\tableofcontents

<<setup,echo=FALSE,print=FALSE>>=
library("clifford")
@ 


\section{Introduction}

\setlength{\intextsep}{0pt}
\begin{wrapfigure}{r}{0.2\textwidth}
  \begin{center}
\includegraphics[width=1in]{clifford.png}
  \end{center}
\end{wrapfigure}
Clifford algebras are interesting and instructive mathematical
objects.  The class has a rich structure that has varied applications
to physics.  Computational support for working with the Clifford
algebras is part of a number of algebra systems including
Sage~\cite{sagemath2019} and \textit{sympy}~\cite{sympy2017}.  Here
I introduce the {\tt clifford} package, written in the R computing
language~\cite{rcore2022}, which furnishes functionality for working
with Clifford algebras.  Notation follows Snygg~\cite{snygg2010}.

\newcommand{\ei}[1]{\ensuremath{{\bf e}_{#1}}}


Suppose we consider a $n$-dimensional vector space spanned by
$\ei{1},\ldots,\ei{n}$.  Then an arbitrary vector in this space will
be $a^1\ei{1}+\cdots+a^n\ei{n}$.  The associated Clifford algebra will
be of dimension $2^n$, spanned by formal products
$\ei{i_1}\ei{i_2}\ldots\ei{i_r}$, $1\leqslant i_1<\cdots<i_r\leqslant
n$.  We write this as $\ei{i_1\ldots i_r}$ for brevity.  The defining
relations would be $\ei{i}\ei{j}=-\ei{j}\ei{i}$ for $i\neq j$ and
\begin{equation}\label{posdefcliff2}
\ei{i}\ei{i} = \begin{cases}
    +1, & 1\leqslant i\leqslant p\\
    -1, & p < i\leqslant p+q\\
    0   & \mbox{otherwise}
  \end{cases}
\end{equation}

The Clifford algebra ${\mathcal C}_{p,q}$ (other notations include
$Cl(p,q)$) is then the algebra formed by $\mathbb{R}_{p,q}$ together
with formal products of basis vectors.  One special case would be
$p=q=0$, implying that $\ei{i}\ei{i}=0$; geometric products become
wedge products.  

\section{Computational implementation and {\tt disordR} discipline}

The package represents basis blades using dynamic bitset objects from
the {\tt boost} library.  A bitset emulates an array of Boolean
elements, but is optimized for space allocation and
access/modification times.  The set bits specify the basis blades
present in a term; using bitsets allows products to use fast Boolean
operators.  An object such as $\ei{2}\ei{5}\ei{6}$ [or $\ei{256}$]
will be a bitset with bits 2, 5, and 6 set [note the off-by-one
  issue].  Dynamic objects are needed here as the number of bits in
the set is specified at runtime.
A {\tt clifford} object is an element of a Clifford algebra; this is
set of basis blades, each with a real coefficient.  The {\tt stl} map
class~\cite{musser2009} is used:

{\ }\\[10pt]
\begin{verbatim}
typedef boost::dynamic_bitset<> blade;
typedef map<blade, long double> clifford;
\end{verbatim}

{\ }\\[10pt]

A ``map'' is a sorted associative container that contains key-value
pairs with unique keys~\cite{musser2009}.  A {\tt clifford} object
thus maps dynamic bitsets (basis blades) to long doubles.  The {\tt
  STL map} class is used for efficiency: search and insertion
operations have only logarithmic complexity.  Similar techniques are
used in the {\tt spray} and {\tt mvp}
packages~\cite{hankin2022_mvp,hankin2022_spray} which furnish
functionality for multivariate polynomials.

Clifford objects are thus considered to be the sum of a finite number
of blades, each multiplied by a coefficient.  One reason why the {\tt
  map} class is fast is that the order in which the keys are stored is
undefined: the compiler may store them in the order which it regards
as most propitious.  This is not an issue for the maps considered here
as addition and multiplication are commutative and associative.  The
package uses {\tt disordR} discipline, discussed in the appendix.


\section{The package in use}

Suppose we want to work with Clifford object
$1+2\ei{1}+3\ei{2}+4\ei{2}\ei{3}$.  In R idiom this would be

<<simpleexample>>=
(x <- 1 + 2*e(1) + 3*e(2) + 4*e(2:3))
@

Here we have used function {\tt e()} which takes an integer vector that
specifies the term.  Addition and subtraction work as expected:

<<xminusy>>=
y <- e(1) + 55*e(1:5)
x-y
@ 

In the above, see how the $\ei{1}$ term has vanished.  We can
multiply Clifford elements using natural R idiom:

<<xtimesy>>=
x*x
@ 

(Multiplication that Snygg denotes by juxtaposition is here indicated
with a {\tt *}).  We can consider arbitrarily high dimensional data:

<<ztimesx>>=
(z <- as.1vector(1:7))
z*x
@ 

In the above, we coerce a vector to a Clifford 1-vector.  The package
includes many functions to generate Clifford objects:

<<firstuseofrcliff>>=
rcliff()
@ 

The defaults for {\tt rcliff()} specify that the object is a sum of
grade-4 terms but this can be altered:

<<anotherrcliff>>=
(x <- rcliff(d=7,g=5,include.fewer=TRUE))
grades(x)
@ 


\section{Pseudo-Euclidean spaces}

The signature of the metric may be altered.  Starting with the
Euclidean case we have:
    
<<e1e2cliff>>=
e1 <- e(1)
e2 <- e(2)
e1*e1
e2*e2
@ 

(function {\tt e(i)} returns $\ei{i}$).  However, if we wish to
consider $n=\begin{bmatrix}1&0\\0&-1\end{bmatrix}$, the package idiom
is to use the {\tt signature()} function:

<<trysig>>=
signature(1,1)  # signature +-
e1*e1 # as before, returns +1
e2*e2 # should return -1
@ 

Suppose we wish to use a signature $+++-$, corresponding to the
Minkowski metric in special relativity; this would be indicated in
package idiom by {\tt signature(3,1)}.  Note that the clifford objects
themselves do not store the signature; it is used only by the product
operation {\tt *}.

<<sigthree1>>=
x <- rcliff(d=4,g=3,include.fewer=TRUE)
y <- rcliff(d=4,g=3,include.fewer=TRUE)
@ 

Then we may multiply these two clifford objects using either the
default positive-definite inner product, or the Minkowski metric:

<<sigthree2>>=
x*y
signature(3,1)  # switch to signature +++-
x*y
@ 

In the above, see how the products are different using the two inner
products.  

\section{Grassmann algebra}

A Grassmann algebra corresponds to a Clifford algebra with identically
zero inner product.  Package idiom is to use a zero signature:

<<grassmannalgebra,results=hide>>=
signature(0,0)  # specify null inner product
<<print=TRUE,results=verbatim>>=
is.zero(e(5)^2)     # should be TRUE
@ 

This is a somewhat clunky way of reproducing the functionality of the
{\tt stokes} package~\cite{hankin2022_stokes_arxiv}.
If we have

<<reproducewedge>>=
x <- clifford(list(1:3, c(2,3,7)), coeffs=3:4)
y <- clifford(list(1:3, c(1,4,5), c(4,5,6)), coeffs=1:3)
x %^% y
@ 

then the {\tt stokes} idiom for this would be:

\begin{Schunk}
\begin{Sinput}
> (x <- as.kform(rbind(1:3,c(2,3,7)),3:4))
\end{Sinput}
\begin{Soutput}
           val
 2 3 7  =    4
 1 2 3  =    3
\end{Soutput}
\begin{Sinput}
> (y <- as.kform(rbind(1:3,c(1,4,5),4:6),1:3))
\end{Sinput}
\begin{Soutput}
           val
 1 2 3  =    1
 1 4 5  =    2
 4 5 6  =    3
\end{Soutput}
\begin{Sinput}
> x %^% y
\end{Sinput}
\begin{Soutput}
                 val
 1 2 3 4 5 6  =    9
 2 3 4 5 6 7  =  -12
 1 2 3 4 5 7  =   -8
\end{Soutput}
\end{Schunk}


\section{Positive-definite inner product}

Function {\tt signature()} takes an infinite argument to make the
inner product positive-definite:

<<sigzero>>=
signature(Inf)
@ 

(internally the package sets the signature to
{\tt .Machine\$integer.max}, a near-infinite integer).  With this,
$\ei{i}\ei{i}=+1$ for any $i$:

<<>>=
e(53)^2
@ 


\section{Left and right contractions}

\cite{dorst2002} defines the left contraction $A\rfloor B$ and right
contraction $A\lfloor B$ (\cite{chisholm2012} calls these left and
right inner products) as follows:

\begin{eqnarray}
\displaystyle A\rfloor B = \sum_{r,s}\left\langle\left\langle
A\right\rangle_r\left\langle B\right\rangle_s\right\rangle_{s-r}\\
\displaystyle A\lfloor B = \sum_{r,s}\left\langle\left\langle
A\right\rangle_r\left\langle B\right\rangle_s\right\rangle_{r-s}
\end{eqnarray}


Package idiom for these would be {\tt A\%\_|\%B} and {\tt A\%|\_\%B}
---or {\tt lefttick(A,B)} and {\tt righttick(A,B)}---respectively.
Thus:

<<>>=
(A <- rcliff())
(B <- rcliff())
A %_|% B
A %|_% B
@ 

One thing to be wary of is the order of operations.  Thus
$\ei{2}\rfloor\ei{12}=-\ei{1}$ (in a positive-definite space) but

<<>>=
e(2) %_|% e(1)*e(2)
@ 

because this is parsed as $(\ei{2}\rfloor\ei{1})\ei{2}=0\ei{2}=0$.  To
evaluate this as intended we need to include brackets:

<<>>=
e(2) %_|% (e(1)*e(2))
@ 

although in this case it might be preferable to create the terms directly:

<<>>=
e(2) %_|% e(1:2)
@ 


\subsection{Numerical verification of left and right inner product identities}

Chisholm gives a number of identities for these products including

\begin{eqnarray}
  A\rfloor(B\lfloor C) &=& (A\rfloor B)\lfloor C\\
  A\rfloor(B\rfloor C) &=& (A\wedge B)\rfloor C\\
  A\lfloor(B\wedge  C) &=& (A\lfloor B)\lfloor C
\end{eqnarray}

In package idiom:

<<>>=
A <- rcliff();  B <- rcliff();  C <- rcliff()
A %_|% (B %|_% C) == (A %_|% B) %|_% C
A %_|% (B %_|% C) == (A %^%  B) %_|% C
A %|_% (B %^%  C) == (A %|_% B) %|_% C
@ 
\section{Higher dimensional spaces}

Ab\l{}amowicz and Fauser~\cite{ablamowicz2012} consider
high-dimensional Clifford algebras and consider the following two
elements of the 1024-dimensional Clifford algebra which we may treat
as ${\mathcal C}_{7,3}$ spanned by $\ei{1},\ldots,\ei{10}$ and perform
a calculation which I reproduce below (although these authors
exploited Bott periodicity, a feature not considered here).

Firstly we change the default print method slightly:

<<printmethodchange>>=
options("basissep" = ",")
@ 

(this separates the subscripts of the basis vectors with a comma,
which is useful for clarity if $n>9$).  We then define clifford
elements $x,y$:

<<abramandfauser>>=
(x <- clifford(list(1:3,c(1,5,7,8,10)),c(4,-10)) + 2)
(y <- clifford(list(c(1,2,3,7),c(1,5,6,8),c(1,4,6,7)),c(4,1,-3)) - 1)
@ 

Their geometric product is given in the package as

<<geomprod>>=
signature(7)
x*y
@ 

in agreement with \cite{ablamowicz2012}, although the terms appear in
a different order.

\section{Conclusions and further work}

The {\tt clifford} package furnishes a consistent and documented suite
of reasonably efficient {\tt R}-centric functionality.  Further work
might include closer integration with the {\tt stokes}
package~\cite{hankin2022_stokes_arxiv}.

\bibliographystyle{plain}
\bibliography{clifford}

\end{document}

