GroupJep - Exact arithmetic over the integers, rationals and other groups


The org.lsmp.djep.groupJep package offers:

This package is primarily a bit of a play thing, allowing the JEP parser and evaluator to be used with arbitrary groups. It should not be treated as a substitute for a dedicated computer algebra package but it does allow a bit of experimentation with different groups rings and fields.


Basic usage

The GroupJep package is relatively easy to use, all the standard JEP features are enabled. To create a version of JEP for a particular group the GroupJep(GroupI group) constructor should be called where the argument is the specification of a certain group. For example to work of arbitrary precision integers to calculate factorial 20 use: 
import org.lsmp.djep.groupJep.*;
import org.lsmp.djep.groupJep.groups.*;

JEP j = new GroupJep(new Integers());
Node node = j.parse("1*2*3*4*5*6*7*8*9*10*11*12*13*14*15*16*17*18*19*20");
Object value = j.evaluate(node);
System.out.println(value.toString());
// prints 2432902008176640000
A number of predefined groups are provided. These are all found in the org.lsmp.djep.groupJep.groups package. Examples of the use of these groups: 
import org.lsmp.djep.groupJep.*;
import org.lsmp.djep.groupJep.groups.*;

class GroupExamples {
public static void main(String args[])
{
JEP j = new GroupJep(new Integers());
Node node = j.parse("1*2*3*4*5*6*7*8*9*10*11*12*13*14*15*16*17*18*19*20");
Object value = j.evaluate(node);
System.out.println(value.toString());
// prints 2432902008176640000

j =  new GroupJep(new Rationals());
node = j.parse("(1/2)-(1/3)");
value = j.evaluate(node);
System.out.println(value.toString());
// prints 1/6

j = new GroupJep(new Zn(BigInteger.valueOf(5)));
node = j.parse("3+3");
value = j.evaluate(node);
System.out.println(value.toString()); // prints 1

node = j.parse("3*3");
value = j.evaluate(node);
System.out.println(value.toString()); // prints 4

Free groups

Any ring can be extended to form a FreeGroup with a single generator: 
import org.lsmp.djep.groupJep.interfaces.*;
import org.lsmp.djep.groupJep.*;
...
RingI ring = new Integers();
RingI freeGroup = new FreeGroup(ring,"t");
JEP j = new GroupJep(freeGroup);
// this line is needed to ensure the parser recognises the symbol t
j.addStandardConstants();	

Node node = j.parse("(t + 2)*(t+4)");
Object value = j.evaluate(node);
System.out.println(value.toString()); // prints t^2+5 t+6
Note that the addStandardConstants method of JEP must be called to ensure that the variable t is added to the parser. Free groups with more than one generator can be constructed by repeatedly extending a ring: 
RingI freeGroup = new FreeGroup(new FreeGroup(new Integers(),"t"),"s");

Algebraic Numbers

In a similar fashion a ring can be extended by an algebraic number t to form an AlgebraicExtension. The algebraic number is defined to be a root of a Polynomial equation with coefficients in the base ring. 
import org.lsmp.djep.groupJep.*;
import org.lsmp.djep.groupJep.interfaces.*;
import org.lsmp.djep.groupJep.groups.*;
import org.lsmp.djep.groupJep.values.*;
...
RingI ring = new Integers();
// specify the polynomial 1 x^2 + 0 x -2
Number coeffs[] = new Number[]{
			BigInteger.valueOf(-2),
			BigInteger.ZERO,
			BigInteger.ONE};
Polynomial p1 = new Polynomial(ring,"rt2",coeffs);

j = new GroupJep(new AlgebraicExtension(ring, p1));
j.addStandardConstants();

Node node = j.parse("(t+1)*(t+1)");
Object value = j.evaluate(node);
System.out.println(value.toString()); // prints 2 t+3
System.out.println(((HasComplexValueI) value).getComplexValue());
	// prints (5.82842712474619, 0.0)
Note in the last line the values can be converted to approximate complex numbers (in the group constructor if the polynomial is quadratic or an n-th root then an approximation to the complex value of a solution is calculate. The value returned by j.evaluate will be an object of type AlgebraicExtensionElement which implements org.lsmp.djep.groupJep.values.HasComplexValueI by providing a getComplexValue() method. This method will use the approximate value of the root to calculate the complex value of this element.

Creating your own groups

Creating a group class is fairly straight forward. The class must implement org.lsmp.djep.groupJep.GroupI or one of the other interfaces in the org.lsmp.djep.groupJep.interfaces package which give extra properties such as RingI, FieldI. Typically the group will subclass org.lsmp.djep.groupJep.groups.Group which provides a few default methods. All groups should provide the methods: 
public Number getZERO();
public Number getInverse(Number num);
public Number add(Number a,Number b);
public Number sub(Number a,Number b);
public boolean equals(Number a,Number b);
public Number valueOf(String s);

The different interfaces available and the methods they define are:

InterfaceMethods
GroupI public Number getZERO();
public Number getInverse(Number num);
public Number add(Number a,Number b);
public Number sub(Number a,Number b);
public boolean equals(Number a,Number b);
public Number valueOf(String s);
AbelianGroupI Same methods as GroupI.
implies group is commutative under +.
RingI methods for GroupI plus
public Number getONE();
public Number mul(Number a,Number b);
IntegralDomainI methods for RingI implies the group has an identity for multiplication *, it is commutative under * and cancellation is meaningful: if a is not 0 then a*b = a*c implies b = c.
HasDivI Group has some notion of division i.e. integers
public Number div(Number a,Number b);
FieldI Same methods as for RingI plus
public Number getMulInverse(Number num);
public Number div(Number a,Number b);
HasDivI Group has some notion of division, but is not necessary a Field. e.g the integers
public Number div(Number a,Number b);
HasModI The modulus function is defined:
public Number mod(Number a,Number b);
HasPowerI The power function is defined:
public Number pow(Number a,Number b);
OrderedSetI There is a natural ordering to the set
public int compare(Number a,Number b);
will return -1 if a<b, 0 if a=b, +1 if a>b.