% -*- mode: noweb; noweb-default-code-mode: R-mode; -*-
\documentclass[nojss]{jss}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%% just as usual
\author{Robin K. S. Hankin\\University of Stirling}
\title{The free group in \proglang{R}: introducing the \pkg{freegroup} package}
%\VignetteIndexEntry{The freegroup package}

%% for pretty printing and a nice hypersummary also set:
\Plainauthor{Robin K. S. Hankin}
\Plaintitle{The freegroup package}
\Shorttitle{The freegroup package}

%% an abstract and keywords
\Abstract{
Here I present the {\tt freegroup} package for working with the free
group on a finite set of symbols.  The package is vectorised;
internally it uses an efficient matrix-based representation for free
group objects but uses a configurable print method.  A range of
R-centric functionality is provided.  It is available on CRAN at
\url{https://CRAN.R-project.org/package=freegroup}.  To cite the
\pkg{freegroup} package, use \citet{hankin2022_freegroup}.
}

\Keywords{Free group, Tietze form}
\Plainkeywords{Free group, Tietze form}
  
%% publication information
%% NOTE: This needs to filled out ONLY IF THE PAPER WAS ACCEPTED.
%% If it was not (yet) accepted, leave them commented.
%% \Volume{13}
%% \Issue{9}
%% \Month{September}
%% \Year{2004}
%% \Submitdate{2004-09-29}
%% \Acceptdate{2004-09-29}
%% \Repository{https://github.com/RobinHankin/freegroup} %% this line for Tragula

%% The address of (at least) one author should be given
%% in the following format:
\Address{
  Robin K. S. Hankin\\%\orcid{https://orcid.org/0000-0001-5982-0415}\\
  University of Stirling\\
  E-mail: \email{hankin.robin@gmail.com}
}
%% It is also possible to add a telephone and fax number
%% before the e-mail in the following format:
%% Telephone: +43/1/31336-5053
%% Fax: +43/1/31336-734

%% for those who use Sweave please include the following line (with % symbols):
%% need no \usepackage{Sweave.sty}

%% end of declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%



\SweaveOpts{}
\usepackage{wrapfig}
\usepackage{tikz-cd}
\begin{document}




<<echo=FALSE,print=FALSE>>=
library("freegroup")
options(freegroup_symbols=letters) # should not be necessary
@ 

\section{Introduction}

\setlength{\intextsep}{0pt}
\begin{wrapfigure}{r}{0.2\textwidth}
\begin{center}
\includegraphics[width=1in]{\Sexpr{system.file("help/figures/freegroup.png",package="freegroup")}}
\end{center}
\end{wrapfigure}

The free group is an interesting and
instructive mathematical object with a rich structure that illustrates
many concepts of elementary group theory.  The \pkg{freegroup} package
provides some functionality for manipulating the free group on a
finite list of symbols.  Informally, the {\em free group}
$\left(X,\circ\right)$ on a set $S=\{a,b,c,\ldots,z\}$ is the set $X$
of {\em words} that are objects like $W=c^{-4}bb^2aa^{-1}ca$, with a
group operation of string juxtaposition.  Usually one works only with
words that are in ``reduced form'', which has successive powers of the
same symbol combined, so $W$ would be equal to $c^{-4}b^3ca$; see how
$b$ appears to the third power and the $a$ term in the middle has
vanished.  The group operation of juxtaposition is formally indicated
by $\circ$, but this is often omitted in algebraic notation; thus, for
example $a^2b^{-3}c^2\circ c^{-2}ba =a^2b^{-3}c^2c^{-2}ba
=a^2b^{-2}ba$.

\subsection{Formal definition}

If $X$ is a set, then a group $F$ is called {\em the free group on
$X$} if there is a set map $\Psi\colon X\longrightarrow F$, and for
any group $G$ and set map $\Phi\colon X\longrightarrow G$, there is a
unique homomorphism $\alpha\colon F\longrightarrow G$ such that
$\alpha\circ\Psi=\Phi$, that is, the diagram below commutes:

\begin{tikzcd}
X \arrow[r,"\Psi"] \arrow[dr,"\Phi"]
& F \arrow[d,"\alpha"]\\
& G
\end{tikzcd}

It can be shown that $F$ is unique up to group isomorphism; every
group is a quotient of a free group.

\subsection{Existing work}

Computational support for working with the free group is provided as
part of a number of algebra systems including \cite{GAP4},
Sage~\citep{sagemath2019}, and \proglang{sympy}~\citep{sympy2017}
although in those systems the emphasis is on finitely presented
groups, not in scope for the \pkg{freegroup} package.  There are also
a number of closed-source proprietary systems which are of no value
here.

\section{The package in use}

In the \pkg{freegroup} package, a word is represented by a two-row
integer matrix; the top row is the integer representation of the
symbol and the second row is the corresponding power.  For example, to
represent $a^2b^{-3}ac^2a^{-2}$ we would identify $a$ as 1, $b$ as 2,
etc and write

<<>>=
(M <- rbind(c(1,2,3,3,1),c(2,-3,2,3,-2)))
@

(see how negative entries in the second row correspond to negative
powers).  Then to convert to a more useful form we would have

<<>>=
library("freegroup")
(x <- free(M))
@

The representation for \proglang{R} object \code{x} is still a two-row
matrix, but the print method is active and uses a more visually
appealing scheme.  The default alphabet used is \code{letters}.  We
can coerce strings to free objects:


<<>>=
(y <- as.free("aabbbcccc"))
@

The free group operation is simply juxtaposition, represented here by
the plus symbol:


<<>>=
x+y
@

(see how the $a$ ``cancels out'' in the juxtaposition).  One motivation
for the use of ``\code{+}'' rather than ``\code{*}'' is that
\proglang{Python} uses ``\code{+}'' for appending strings:

\begin{verbatim}
>>> "a" + "abc"
'aabc'
>>> 
\end{verbatim}

However, note that the ``\code{+}'' symbol is usually reserved for
commutative and associative operations; string juxtaposition is
associative.  Multiplication by integers---denoted in \pkg{freegroup}
idiom by ``\code{*}''---is also defined.  Suppose we want to
concatenate 5 copies of \code{x}:

<<>>=
x*5
@

The package is vectorized:

<<>>=
x*(0:3)
@

There are a few methods for creating free objects, for example:

<<>>=
abc(1:9)
@

And we can also generate random free objects:

<<>>=
rfree(10,4)
@

Inverses are calculated using unary or binary minus:

<<>>=
(u <- rfree(10,4))
-u
u-u
@

We can take the ``sum'' of a vector of free objects simply by
juxtaposing the elements:

<<>>=
sum(u)
@

Powers are defined as per group conjugation: \code{x\string^y ==
y\string^\string{-1\string}xy} (or, written in additive notation,
\code{-y+x+y}):

<<>>=
u
z <- alpha(26)
u^z
@


Thus:

<<>>=
sum(u^z) == sum(u^z)
@

There is also a commutator bracket, defined as $[x,y]=x^{-1}y^{-1}xy$
or in package idiom \code{.[x,y]=-x-y+x+y}:

<<>>=
.[u,z]
@ 

If we have more than 26 symbols the print method runs out of letters:

<<>>=
alpha(1:30)
@

If this is a problem (it might not be: the print method might not be
important) it is possible to override the default symbol set:

<<>>=
options(freegroup_symbols = state.abb)
alpha(1:30)
@

\section{Conclusions and further work}

The \pkg{freegroup} package furnishes a consistent and documented
suite of reasonably efficient \proglang{R}-centric functionality.
Further work might include the finitely presented groups but it is not
clear whether this would be consistent with the precepts of
\proglang{R}.

<<echo=FALSE,print=FALSE>>=
options(freegroup_symbols=letters)
@ 

\bibliography{freegroup}
\end{document}