GAP (DeepThought) - Chapter 2: Using Deep Thought functions

In the following sections, functions provided for computing Deep Thought polynomials and using them for calculations are listed.

2.1 Computing Deep Thought polynomials

2.1-1 DTP_DTapplicability

Checks the collector coll for applicability of Deep Thought functions. Note that depending on confluency some functions may be applicable, while others are not. Information on the applicability and which type of Deep Thought polynomials are suggested is printed to the terminal. Here, "+" means that the following property is fulfilled, otherwise there is a "-". The function returns false if Deep Thought is not applicable to the collector coll and true otherwise. Anyway, even if true is returned, not all functions need to be applicable (in case of inconfluencies).

2.1-2 DTP_DTObjFromCollector

Computes a DTObj for the collector coll, either with polynomials of type f_{rs} (if rs_flag = true) or with polynomials of type f_r, if rs_flag = false. If the optional argument rs_flag is not provided, polynomials of type f_{rs} are computed. The function checks whether the collector coll is confluent. If not, a warning is displayed. Note that the function assumes the collector coll to be suitable for Deep Thought, see function DTP_DTapplicability.

gap> G := UnitriangularPcpGroup(10, 0);;
gap> coll := Collector(G);;
gap> DTP_DTapplicability(coll);
Checking collector for DT-applicability. "+" means the following property
is fulfilled.
+   conjugacy relations
+   power relations
+   confluent
Suggestion: Call DTP_DTObjFromColl with rs_flag = true.
true
# calling DTP_DTObjFromCollector without rs_flag implies rs_flag = true:
gap> DTObj := DTP_DTObjFromCollector(coll);
<DTObj>

2.2 Computations with Deep Thought polynomials

2.2-1 DTP_Exp

Computes the exponent vector of expvec^{int}. If IsConfluent(DTObj) = true, then the result is in normal form.

2.2-2 DTP_Inverse

Computes the exponent vector of the inverse of the element corresponding to expvec. If IsConfluent(DTObj) = true, then the result is in normal form.

2.2-3 DTP_IsInNormalForm

Checks whether expvec is in normal form or not. If yes, the return value is true. Otherwise the return value is the smallest generator index for which the normal form condition is violated, i.e. for which the relative order RelativeOrder(coll)[i] is non-zero, and expvec[i] < 0 or expvec[i] \geq RelativeOrder(coll)[i].

2.2-4 DTP_Multiply

Computes the exponent vector of the product expvec1 * expvec2 using the Deep Thought polynomials. If IsConfluent(DTObj) = true, then the result is returned in normal form. DTP_Multiply either calls DTP_Multiply_r or DTP_Multiply_rs depending on which type of polynomials are stored in DTObj.

2.2-5 DTP_Multiply_r

Computes the exponent vector of the product expvec1 * expvec2 using the Deep Thought polynomials of type f_r stored in DT_Obj. If IsConfluent(DTObj) = true, then the result is returned in normal form.

2.2-6 DTP_Multiply_rs

Computes the exponent vector of the product expvec1 * expvec2 using the Deep Thought polynomials of type f_{rs} stored in DT_Obj. If IsConfluent(DTObj) = true, then the result is returned in normal form.

2.2-7 DTP_NormalForm

Computes the exponent vector of the normal form of expvec. For this function to be applicable, we need IsConfluent(DTObj) = true.

2.2-8 DTP_Order

Computes the order of the element described by expvec. For this function to be applicable, we need IsConfluent(DTObj) = true.

2.2-9 DTP_SolveEquation

Computes the exponent vector of the element corresponding to expvec1^{-1} * expvec2, i.e. the result solves the equation expvec1 * result = expvec2. If IsConfluent(DTObj) = true, then the result describes a normal form.

gap> G := PcGroupToPcpGroup(SmallGroup(23^5, 2));
Pcp-group with orders [ 23, 23, 23, 23, 23 ]
gap> coll := Collector(G);
<<from the left collector with 5 generators>>
gap> DTObj := DTP_DTObjFromCollector(coll);
<DTObj>
gap> g := [100, 134, -31, 52, 5235];
[ 100, 134, -31, 52, 5235 ]
gap> DTP_IsInNormalForm(g, DTObj);
1
gap> g := DTP_NormalForm(g, DTObj);
[ 8, 19, 15, 10, 19 ]
gap> DTP_IsInNormalForm(g, DTObj);
true
gap> DTP_Inverse(g, DTObj);
[ 15, 4, 22, 12, 3 ]
gap> DTP_Order(g, DTObj);
529
gap> h := [142, 2, -41, 23, 1];
[ 142, 2, -41, 23, 1 ]
gap> DTP_Multiply(g, h, DTObj);
[ 12, 21, 4, 16, 20 ]

2.3 Computations with pcp-elements

When Deep Thought polynomials are available, certain computations allow different approaches which may be faster than the methods used by default. In this section, computations for which such extra functions taking pcp-elements as input are available are listed. All of these functions expect the collector belonging to the pcp-elements to be a DTObj.

2.3-1 DTP_PCP_Exp

Returns the pcp-element pcp-element^{int}. If IsConfluent(DTObj) = true, then the result is in normal form.

2.3-2 DTP_PCP_Inverse

Returns the pcp-elment pcp-element^-1. If IsConfluent(DTObj) = true, then the result is in normal form.

2.3-3 DTP_PCP_NormalForm

Returns a pcp-element which is the normal form of the input pcp-element. For this function to be applicable, we need IsConfluent(DTObj) = true.

2.3-4 DTP_PCP_Order

Computes the order of the pcp-element. For this function to be applicable, we need IsConfluent(DTObj) = true.

2.3-5 DTP_PCP_SolveEquation

Returns the pcp-element pcp-element1^{-1} * pcp-element2, i.e. the result solves the equation pcp-element1 * pcp-element = pcp-element2. If IsConfluent(DTObj) = true, then the result describes a normal form.

gap> G := HeisenbergPcpGroup(7);;
gap> coll := Collector(G);;
gap> DTObj := DTP_DTObjFromCollector(coll);;
gap> H := PcpGroupByCollector(DTObj);;
gap> g := Random(H);; h := Random(H);;
gap> DTP_PCP_SolveEquation(g, h);
g1^-3*g2^-1*g3^-7*g4*g5^-6*g6*g7*g8^2*g9^3*g11^-4*g12^5*g14^-2*g15^7
g1^-3*g2^-1*g3^-7*g4*g5^-6*g6*g7*g8^2*g9^3*g11^-4*g12^5*g14^-2*g15^7
infinity
gap> g^-1;
g1^-2*g3^-3*g4^-1*g5^-4*g6^2*g7*g8^-3*g10^-3*g11^-1*g12^4*g14^-2*g15^-3
gap> DTP_PCP_Inverse(h);
g1*g2*g3^4*g4^-2*g5^2*g6*g8^-5*g9^-3*g10^-3*g11^3*g12^-1*g15^-33

2.4 Accessing Deep Thought polynomials

In this section, functions which can be used to display the content of a DTObj are documented. Furthermore, Deep Thought polynomials stored in a DTObj can be converted to GAP polynomials.

2.4-1 DTP_Display_DTObj

Prints information about DTObj to the terminal. In particular, the Deep Thought polynomials are printed in human-readable form. This function is also called by the method of Display for a DTObj.

2.4-2 DTP_pols2GAPpols

Converts the Deep Thought polynomials stored in DTObj[PC_DTPPolynomials] to GAP polynomials and returns them in a list together with their polynomial ring.

gap> coll := FromTheLeftCollector(4);;
gap> SetConjugate(coll, 2, 1, [2, 1, 3, 2]);
gap> SetConjugate(coll, 3, 1, [3, 1, 4, 1]);
gap> SetConjugate(coll, 3, 2, [3, 1, 4, 5]);
gap> UpdatePolycyclicCollector(coll);
gap> DTObj := DTP_DTObjFromCollector(coll);
<DTObj>
gap> Display(DTObj);
Polynomials f_rs for s = 1:
f_1,s = X_1 + Y_1
f_2,s = X_2
f_3,s = X_3 + 2 * X_2 Y_1
f_4,s = X_4 + X_3 Y_1 + 2 * X_2 Binomial(Y_1, 2) + 10 * Binomial(X_2, 2) Y_1
Polynomials f_rs for s = 2:
f_1,s = X_1
f_2,s = X_2 + Y_2
f_3,s = X_3
f_4,s = X_4 + 5 * X_3 Y_2
Polynomials f_rs for s = 3:
f_1,s = X_1
f_2,s = X_2
f_3,s = X_3 + Y_3
f_4,s = X_4
Polynomials f_rs for s = 4:
f_1,s = X_1
f_2,s = X_2
f_3,s = X_3
f_4,s = X_4 + Y_4
gap> DTObj := DTP_DTObjFromCollector(coll, false);
<DTObj>
gap> Display(DTObj);
f_1 = X_1 + Y_1
f_2 = X_2 + Y_2
f_3 = X_3 + Y_3 + 2 * X_2 Y_1
f_4 = X_4 + Y_4 + X_3 Y_1 + 2 * X_2 Binomial(Y_1, 2) +
10 * Binomial(X_2, 2) Y_1 + 5 * X_3 Y_2 + 10 * X_2 Y_1 Y_2
gap> DTP_pols2GAPpols(DTObj);
 [ [ x1+y1, x2+y2, 2*x2*y1+x3+y3,
5*x2^2*y1+x2*y1^2+10*x2*y1*y2-6*x2*y1+x3*y1+5*x3*y2+x4+y4 ],
Rationals[x1,x2,x3,x4,y1,y2,y3,y4] ]

2 Using Deep Thought functions