HoriAsso  Documentation
Contents 
Installation and Setup for using Java in Mathematica
Java Class Documentation (not formatted yet)
How to use the Free Lie Algebra (first part in the HoriAsso) package
The space of the direct sum of free Lie algebras with 1,2, and 3 generators with an extended Lie Bracket is needed to calculate the Horizontal associator. This first package sets up the free Lie Algebras with 1,2, and 3 generators.
This package uses Java Classes and a Mathematica interface. You could use the package from Mathematica following the below instructions or build your own Java application using the Classes directly using the Java Class Documentation.
Installation
Please download the FreeLieAlgebra folder from our repository. This folder includes the compiled Java Class files, and the Mathematica/Java interface HoriAssoInterface.m; otherwise, if you are online during the Mathematica session, enter the path to the repository during the initialization steps according to the section Necessary Initialization Stepsbelow.
Note: This will be archived once the package is more complete.
Demo Mathematica NoteBook
A Mathematica notebook file named HoriAssoFLnSpaceDemo.nb to demonstrate the usage of this Free Lie Algebra package is included in the FreeLieAlgebra folder that you just downloaded from the repository. After installation (as above), simply open the notebook in Mathematica, follow the simple initialization steps below, (i.e., modifying path names and parameters in the demo file), and evaluate the cells as you wish.
Usage
The HoriAsso Mathematica interface is set up to do computations only in Free Lie Algebras with 1,2, and 3 generators, named FL2, FL3, FL4 respectively, with the suffix being (1 + number of generators).
Note: You could do computations in Free Lie Algebras with more generators if you use the Java classes directly.
Necessary Initialization Steps
1. In a Mathematica session, load the Java/Mathematica interface by:
In[1]:=

<<"/path_to_interface_folder/HoriAssoInterface.m"

 where "path_to_interface_folder" is the path to folder containing the downloaded HoriAssoInterface.m file or the FreeLieAlgebra folder of this project's repository.
2. (Optional) For faster and bigger calculations, reinstall the Java runtime with the option to use as much memory as designated:
In[2]:=

ReinstallJava[CommandLine > "path_to_Java Xmx800M"]

 where 800M in the last argument can be replaced by your choice of maximum memory to use according to your computer specs.
3. Let Mathematica know where to look for the necessary Java class files:
In[3]:=

SetHoriAssoPath["/path_to_Java_Class_folder"];

 where "path_to_Java_Class_folder" is the path to the folder that contains the downloaded Java Class files, or simply the path to the FreeLieAlgebra folder in our repository.
4. Create the Lyndon bases for all three Free Lie Algebras with 1, 2, and 3 generators respectively by:
In[4]:=

InitializeHoriAssoSpace[12];

 or Create the Lyndon basis for the different Free Lie Algebras separately by:
In[5]:=

CreateFL2Basis[any_number];

In[6]:=

CreateFL3Basis[any_num_<=_20];

In[7]:=

CreateFL4Basis[any_num_<=_14_(12_is_safe)];

 where the argument controls the word length up to which the Lyndon bases will contain elements of. Please read the Algebraic Operations section below for its impact.
 Performance note: For the default Java runtime on a computer with 1G RAM, a maximum word e Notelength of 12 in "InitializeHoriAssoSpace" or "CreateFL4Basis" seems to be quite safe. You can choose up to 14 if you have chosen to run Java with 800M memory in Step 2.
 To check the dimension of the Free Lie Algebras at a given length (less than the maximum word length used in creating the basis):
In[8]:=

GetFLnDimension[4,14]

Out[8]=

341484

 where the first argument is n in FLn, i.e., the number of generators + 1, and the second is the wordlength at which the basis dimension is returned.
Notation
Any Free Lie Algebra element is a linear combination of Lie trees, which are nested Lie Brackets of the generators, e.g. [a,[[a,b],[a,c]]] where the square brackets are the Lie Brackets.
In the HoriAsso setup:
1. Letters starting with lower case "a" are used as generators, i.e., a Lie tree in Free Lie Algebra with 3 generators (FL4) will/should contain only a's, b's, and/or c's.
2. Only two tree structures are used and allowed, the right Comb, and the Lyndon Word.
 RightCombs represent the tree structure [a,[a,[a,[a,[a,[a,[a,[a...[a,b]]]]]]]]] and is represented, for example, by:
In[9]:=

RCombExample = RComb[a,a,a,a,a,a,a,a,...a,b]

 Lyndon Words are words that are smaller by alphabetical order than any of its right subwords. Since they are Hall Words, each word implies a unique tree structure. They are represented, for example, by
In[10]:=

LyndonWordExample = LW[a,a,b,a,b,a,b,a,b]

 You can check to see if a word satisfies the definition of a Lyndon Word:
In[11]:=

IsLyndon[LW[a,b,a]]

Out[11]=

False

 Important note: In Java, you could replace the left or right subtree of a Lie tree by any tree, resulting in tree structures that are neither rightcombs or Lyndon. However, this Mathematica interface assumes that if a Lie tree is not a Lyndon Word, it would be a rightcomb; using those Java methods (namely javatree@setLeft(or right)Subtree(new_left(or_right)_subtree)) directly in Mathematica will cause errors in calculations.
3. Free Lie Algebra elements are represented as a linear combination of Lyndon Words (LW) and RightCombs (RComb) with an enveloping head FLn, where n is the number of generators + 1, e.g.:
In[12]:=

LieAlgebraElementExample = FL3[LW[a,a,b,a,b,a,b,a,b]+3RComb[a,b,a]]

Algebraic Operation
1. Scalar multiplication and Addition
You could form either linear combinations of words (RComb and LW) as you would with other Mathematica expressions, or form the linear combinations and give them context by putting them under the head of FL2, FL3, FL4. The difference is that in the first case, the sum and scalar multiplication are simply formal and is the original Mathematica Plus/Times functions, but in the case with FL2, 3 or 4 heads, the sum is done in Java and reduced into the linear combination of the Lyndon basis elements.
At the moment the coefficients for the FLn elements need to be Integers. This will be replaced with rational numbers soon.
Linear combination of Words:
In[13]:=

LinCombOfWords = 2 RComb[a, b, a, b] + LW[a, b, b, a, b, b, b]
 4LW[a, b, a, b, a, b, b]  RComb[a, b, a, b] + LW[a, b, b, a, b, b, b]

Out[13]=

4 LW[a, b, a, b, a, b, b] + 2 LW[a, b, b, a, b, b, b] + RComb[a, b, a, b]

Sum of Free Lie Algebra elements (linear combination of words wrapped with the FLn head)
In[14]:=

SumOfFL3Elements = FL3[ 4 LW[a, b, a, b, a, b, b]]
+ FL3[2LW[a, b, b, a, b, b, b] +RComb[a, b, a, b]]

Out[14]=

FL3[LW[a, a, b, b]  4 LW[a, b, a, b, a, b, b] + 2 LW[a, b, b, a, b, b, b]]

Note that the FLn elements itself is not automatically reduced to the Lyndon basis form, but a sum of the FLn elements is.
2. Reduce to linear combination of Lyndon basis elements
You could reduce a single word (RComb and LW) or a Free Lie Algebra elements into a linear combination of Lyndon basis elements.
For reducing a word to Lyndon form, the word length is only limited by performance. For a good size example:
In[15]:=

ReduceToLyndon[RComb[a, b, b, a, a, b, a, b, a, b, b, a, b]]

Out[15]=

LW[a, a, a, a, a, a, b, b, b, b, b, b, b] + 4 LW[a, a, a, a, a, b, a, b, b, b, b, b, b]
+ 6 LW[a, a, a, a, a, b, b, a, b, b, b, b, b] + 3 LW[a, a, a, a, a, b, b, b, a, b, b, b, b]
 LW[a, a, a, a, a, b, b, b, b, a, b, b, b]  5 LW[a, a, a, a, a, b, b, b, b, b, a, b, b]
 7 LW[a, a, a, a, a, b, b, b, b, b, b, a, b]  4 LW[a, a, a, a, b, a, a, b, b, b, b, b, b]
+ 9 LW[a, a, a, a, b, a, b, a, b, b, b, b, b] + 9 LW[a, a, a, a, b, a, b, b, a, b, b, b, b]
 LW[a, a, a, a, b, a, b, b, b, a, b, b, b]  10 LW[a, a, a, a, b, a, b, b, b, b, a, b, b]
12 LW[a, a, a, a, b, a, b, b, b, b, b, a, b]  2 LW[a, a, a, a, b, b, a, a, b, b, b, b, b]
 4 LW[a, a, a, a, b, b, a, b, a, b, b, b, b] + 3 LW[a, a, a, a, b, b, a, b, b, a, b, b, b]
 2 LW[a, a, a, a, b, b, a, b, b, b, a, b, b]  12 LW[a, a, a, a, b, b, a, b, b, b, b, a, b]
+ 2 LW[a, a, a, a, b, b, b, b, a, b, a, b, b] + 6 LW[a, a, a, a, b, b, b, b, a, b, b, a, b]
+ LW[a, a, a, a, b, b, b, b, b, a, a, b, b] + 10 LW[a, a, a, a, b, b, b, b, b, a, b, a, b]
+ 2 LW[a, a, a, a, b, b, b, b, b, b, a, a, b]  6 LW[a, a, a, b, a, a, b, a, b, b, b, b, b]
 6 LW[a, a, a, b, a, a, b, b, a, b, b, b, b] + 2 LW[a, a, a, b, a, a, b, b, b, b, a, b, b]
+ 8 LW[a, a, a, b, a, a, b, b, b, b, b, a, b] + 2 LW[a, a, a, b, a, b, a, a, b, b, b, b, b]
+ 8 LW[a, a, a, b, a, b, a, b, a, b, b, b, b] + 4 LW[a, a, a, b, a, b, a, b, b, a, b, b, b]
 4 LW[a, a, a, b, a, b, a, b, b, b, a, b, b]  8 LW[a, a, a, b, a, b, a, b, b, b, b, a, b]
 2 LW[a, a, a, b, a, b, b, a, b, a, b, b, b]  4 LW[a, a, a, b, a, b, b, a, b, b, b, a, b]
+ 2 LW[a, a, a, b, a, b, b, b, a, b, b, a, b] + 2 LW[a, a, a, b, a, b, b, b, b, a, a, b, b]
+ 4 LW[a, a, a, b, a, b, b, b, b, a, b, a, b]  LW[a, a, a, b, b, a, a, b, b, a, b, b, b]
+ LW[a, a, a, b, b, a, a, b, b, b, b, a, b]  LW[a, a, a, b, b, a, b, a, b, a, b, b, b]
+ 2 LW[a, a, a, b, b, a, b, b, b, a, b, a, b]  2 LW[a, a, a, b, b, b, b, a, b, a, b, a, b]
+ 2 LW[a, a, b, a, b, a, b, a, b, a, b, b, b]

For reducing an FLn element to Lyndon form, the word length has to be smaller than the maximum word length specified in "initializeHoriAssoSpace(maxWordLength)":
In[16]:=

ReduceToLyndon[FL3[LW[a, a, b, a, b] + 4RComb[a, b, a, b, a, b, a]]]

Out[16]=

FL3[LW[a, a, b, a, b]  4 LW[a, a, a, a, b, b, b]
 4 LW[a, a, a, b, a, b, b] + 4 LW[a, a, a, b, b, a, b]]

Note: the two notations will probably merge.
3. Lie Brackets
Finally, you could compute the Lie bracket of two individual words (RComb and/or LW) or two Free Lie Algebra elements (FL2,3,4 elements), the results of which are reduced into the Linear combinations of lyndon words already:
In[17]:=

Bracket[RComb[a, b, b, a], RComb[b, a, a, b, a]]

Out[17]=

LW[a, a, a, b, b, a, a, b, b] + LW[a, a, b, a, b, a, a, b, b]

In[18]:=

Bracket[ FL4[LW[a, b, c, a, c] + 2RComb[a, b, c, b]],
FL4[2RComb[a, b, b, c, a, b] + 4RComb[b, a, c]]]

Out[18]=

FL4[ 8 LW[a, b, b, c, a, c, b]  4 LW[a, b, c, a, c, a, c, b]
 4 LW[a, b, c, a, c, b, a, c] + 4 LW[a, a, b, c, b, b, a, b, b, c]
+ 4 LW[a, a, c, b, b, b, a, b, b, c]  2 LW[a, a, b, c, b, b, a, b, c, a, c]
 2 LW[a, a, c, b, b, b, a, b, c, a, c]]
