Ticket #54: freegb.lib.diff3

====3
1:2c
2:2c
  version="$Id: freegb.lib,v 1.12 2008/10/06 17:04:27 Singular Exp $";
3:2c
  version="$Id: freegb.lib,v 1.16 2009/02/13 21:37:20 levandov Exp $";
====3
1:5c
2:5c
  LIBRARY: freegb.lib   Twosided Noncommutative Groebner bases in Free Algebras
3:5c
  LIBRARY: freegb.lib   Twosided Noncommutative Groebner bases in Free Algebras via Letterplace
====
1:8,10c
  PROCEDURES:
  freegbRing(int d);    creates a ring with d blocks of shifted original variables
  freegbasis(list L, int n);   compute two-sided Groebner basis of ideal, encoded via L, up to degree n
2:8,20c
  BACKGROUND: 
  TODO: WRITE DOWN SOME THEORY BEHIND (DIVISIBILITY, ORDERING ON FREE ASSOC. ALG., GB) 
  TODO: ADD REFERENCES
  TODO: EXPLAIN YOUR ASSUMPTIONS/IMPLICITE AGREEMENTS/INPUT, OUTPUT FORMATS ETC.
  TODO: BAD NAMES, SEE 3.9.1 Procedures in a library, 5^th rule. PLEASE RENAME!
  
  
  MAIN PROCEDURES: 
  
  freegbRing(int d);    creates a ring with d blocks of shifted original variables
  freegbasis(list L, int n); computes two-sided GB of an ideal up to degree n
  
  AUXILIARY PROCEDURES:
3:8,14c
  THEORY: See chapter 'Letterplace' in the Singular Manual.
  
  PROCEDURES:
  freegbRing(d);    creates a ring with d blocks of shifted original variables
  freegbasis(L, int n);   compute two-sided Groebner basis of ideal, encoded via L, up to degree n
  
  AUXILIARY PROCEDURES:
====
1:12c
  CONVERSION ROUTINES:
2:22,30c
  lp2lstr(ideal K, def save); converts letter-place ideal to a list of modules
  lst2str(list L[,int n]);    converts a list of modules into polys in free alg.
  mod2str(module M[,int n]);  converts a module into a polynomial in free algebra
  vct2str(module M[,int n]);  converts a vector into a word in free algebra
  "
  
  // TODO: LOTS OF GLOBAL UNLISTED PROCS WITHOUT HELP/EXAMPLES... ->
  // -> MAKE THEM STATIC OR DOCUMENT THEM!
  // TODO: AT LEAST SOME (E.G. Serre MUST BE LISTED IN THE HEADER)
3:16,24c
  lpMult(f,g);        letterplace multiplication of letterplace polynomials
  lp2lstr(K, s);      convert letter-place ideal to a list of modules
  lst2str(L[, n]);     convert a list (of modules) into polynomials in free algebra
  mod2str(M[, n]); convert a module into a polynomial in free algebra
  vct2str(M[, n]);   convert a vector into a word in free algebra
  Liebr(a,b[, N]);    compute Lie bracket ab-ba of two letterplace polynomials
  Serre(A,z);          compute the ideal of Serre's relations associated to a generalized Cartan matrix A
  isVar(p);             check whether p is a power of a single variable
  adem(i,j);            compute the ideal of Adem relations for i<2j in char 0
====
1:14,18c
  lp2lstr(ideal K, def save): converts letter-place ideal to a list of modules
  lst2str(list L[,int n]);            convert a list (of modules) into polynomials in free algebra
  mod2str(module M[,int n]);  convert a module into a polynomial in free algebra
  vct2str(module M[,int n]);  convert a vector into a word in free algebra
  "
2:32c
  // TODO: MOVE THE FOLLOWING TO THE ABOVE BACKGROUND...
3:26,27c
  SEE ALSO: Letterplace
  "
====2
1:26a
3:35a
2:41,44c
  
  
  
  
====3
1:29a
2:47a
3:39,53c
  proc testfreegblib()
  {
    example freegbRing;
    example freegbasis;
      "AUXILIARY PROCEDURES: ";
    example lpMult;
    example lp2lstr;
    example lst2str;
    example mod2str;
    example vct2str;
    example Liebr;
    example Serre;
    example isVar;
  }
  
====3
1:33c
2:51c
  proc lshift(module M, int s, string varing, def lpring)
3:57c
  static proc lshift(module M, int s, string varing, def lpring)
====3
1:78c
2:96c
  proc skip0(vector v)
3:102c
  static proc skip0(vector v)
====2
1:100a
3:124a
2:119,122c
  
  // TODO: ANY ASSUMPTIONS ON THE BASERING? 
  // TODO: EXPLAIN WHICH FREE ALGEBRA IS MEANT?
  
====2
1:103,104c
3:127,128c
  RETURN:  list (of strings)
  PURPOSE: convert a list (of modules) into polynomials in free algebra
2:125,127c
  RETURN:  list of strings
  PURPOSE: converts a list of modules into a list of strings representing 
           corresponding module as an element in the free algebra
====2
1:106c
3:130c
  NOTE: if an optional integer is not 0, stars signs are used in multiplication
2:129c
  NOTE:    if an optional integer is not 0, stars signs are used in multiplication
====2
1:115c
3:139c
      if (#[1])
2:138c
      if (typeof(#[1]) == "int")
====2
1:121c
3:145c
    int s    = size(L);
2:144c
    int s = size(L);
====2
1:131,132c
3:155,156c
        "module or matrix expected in the list";
        return(N);
2:154,156c
        ERROR("module or matrix expected in the list");
        brake;
  //      return(N);
====2
1:148a
3:172a
2:173,175c
  // TODO: ANY ASSUMPTIONS ON THE BASERING/INPUT!? 
  // TODO: EXPLAIN WHICH FREE ALGEBRA IS MEANT?
  
====2
1:152c
3:176c
  PURPOSE: convert a module into a polynomial in free algebra
2:179,180c
  PURPOSE: Converts the module M into a string representing M
           as an element in the free algebra
====2
1:163c
3:187c
      if (#[1])
2:191c
      if (typeof(#[1]) == "int")
====2
1:196a
3:220a
2:225,231c
    // TODO: WHAT ABOUT ZERO?
    M = 0;
    mod2str(M); // TODO: FIX BUG: MUST BE JUST A ZERO!
    M = [0], [0], [1], [0, x];
    mod2str(M); // TODO: FIX THIS BUGS!
    M = [1, x, y, z], [0, x], [2, y], [0];
    mod2str(M);
====2
1:198a
3:222a
2:234,236c
  // TODO: ANY ASSUMPTIONS ON THE BASERING/INPUT!? 
  // TODO: EXPLAIN WHICH FREE ALGEBRA IS MEANT?
  
====2
1:202c
3:226c
  PURPOSE: convert a vector into a word in free algebra
2:240c
  PURPOSE: Converts a vector into a string representing a word in the free alg.
====2
1:211c
3:235c
      if (#[1])
2:249c
      if (typeof(#[1]) == "int")
====3
1:226c
2:264c
      p     = IsVar(v[i+1]);
3:250c
      p     = isVar(v[i+1]);
====2
1:287a
3:311a
2:326,337c
    // TODO: WHAT ABOUT ZERO?
    vector M = 0;
    vct2str(M); 
    M = [0];
    vct2str(M);
    M = [0, x, y3, z(1)];
    vct2str(M,1); // TODO: FIX BUG: MUST BE ZERO!
    M = [1, x, 0, z(1)];
    vct2str(M,1);
    M = [1, 0, z(1), 0, 0, x*y3, 0, 666];
    vct2str(M,1); // TODO: FIX BUG: WHAT IS THIS???
  
====3
1:290c
2:340c
  proc IsVar(poly p)
3:314,320c
  proc isVar(poly p)
  "USAGE:  isVar(p);  poly p
  RETURN:  int
  PURPOSE: checks whether p is a power of a single variable from the basering.
  @* Returns the exponent or 0 is p is not a power of  a single variable.
  EXAMPLE: example isVar; shows examples
  "
====3
1:319c
2:369c
    IsVar(f);
3:349c
    isVar(f);
====3
1:321c
2:371c
    IsVar(g);
3:351c
    isVar(g);
====3
1:323c
2:373c
    IsVar(h);
3:353c
    isVar(h);
====3
1:325c
2:375c
    IsVar(i);
3:355c
    isVar(i);
====3
1:330c
2:380c
  proc id2words(ideal I, int d)
3:360c
  static proc id2words(ideal I, int d)
====3
1:373c
2:423c
  proc mono2word(poly p, int d)
3:403c
  static proc mono2word(poly p, int d)
====2
1:392a
3:422a
2:443,447c
  
  // TODO: BAD NAME -> RENAME!
  // TODO: NO ASSUMPTIONS? WHAT ABOUT NON-COMM. INPUT RING? NON-HOMOG. INPUT?
  // TODO: ADD STEP-BY-STEP COMMENTS.
  
====2
1:395,397c
3:425,427c
  RETURN:  ring
  PURPOSE: compute the two-sided Groebner basis of an ideal, encoded by L in
  the free associative algebra, up to degree d
2:450,461c
  RETURN:  ring, 
    TODO: EXPLAIN OUTPUT FORMAT
  PURPOSE: compute the two-sided Groebner basis of an ideal, encoded by L 
           (TODO: EXPLAIN FORMAT OF L)
           in the free associative algebra,
           (TODO: WHICH free associative algebra? SYMBOLS? GROUND FIELD?)
           up to degree d
  BACKGROUND: 
    TODO: EXPLAIN ALGORITHM, GIVE REFERENCES!
    TODO: WHAT ABOUT TERMINATION?
  DISPLAY: 
    TODO: EXPLAIN!
====2
1:424a
3:454a
2:489,493c
  
    // TODO: THE FOLLOWING SEEMS TO BE THE CONTENT OF 'freegbRing'!
    // AND THUS IS OVERSIMPLIFIED: WHAT IF VARIABLES/PARAMETERS HAVE BRACKETS?
    // SEE EXAMPLE FOR 'freegbRing'!
  
====2
1:477,478c
3:507,508c
    def @R = ring(L);
    setring @R;
2:546,553c
    def @R = ring(L); 
  
    // HERE END 'freegbRing'! ;-)
  
  
    // TODO: THE FOLLOWING CONVERSION DESERVES TO BE AN AUXILIARY PROCEDURE!
  
    setring @R; // !
====2
1:484c
3:514c
    setring save;
2:559c
    setring save; // !!
====2
1:492c
3:522c
    setring @R;
2:567c
    setring @R; // !!!
====2
1:494c
3:524c
    setring save;
2:569c
    setring save; // !!!! 
====2
1:513c
3:543c
        setring @R;
2:588c
        setring @R; // !!!!!
====2
1:515c
3:545c
        setring save;
2:590c
        setring save; // !!!!! !
====2
1:517c
3:547c
      setring @R;
2:592c
      setring @R; // !!!!! !!
====2
1:521c
3:551c
      setring save;
2:596c
      setring save; // !!!!! !!!
====2
1:525c
3:555c
    setring @R;
2:600,607c
    setring @R; // !!!!! !!!! 
  
    // TODO: UNBELIEVABLE PLENITUDE OF SETRING ABOVE!
    // YOU CAN DO BETTER AS FOLLOWS: 
    //  1. GENERATE ONLY 1 (ONE!!!!) STRING sp FOR THE WHOLE(!!!) L 
    //              BEFORE(!!!!) SWITCHING TO @R 
    //  2. EXECUTE IT IN @R 
  
====2
1:533a
3:563a
2:616,618c
  
    // TODO: THE FOLLOWING DESERVES TO BE AN AUXILIARY PROCEDURE AS WELL! IS IT lp2lstr?
  
====2
1:540a
3:570a
2:626,628c
  
    // YOU HAVE A LOT OF SETRINGS BELOW, ARE YOU SURE THAT YOU CANNOT ELIMINATE SOME...?
  
====2
1:547c
3:577c
    setring save;
2:635c
    setring save; // !
====2
1:553c
3:583c
    setring @R;
2:641c
    setring @R; // !!
====2
1:580a
3:610a
2:669c
  
====2
1:585c
3:615c
      setring @R;
2:674c
      setring @R; // !!!
====2
1:595c
3:625c
        setring save;
2:684c
        setring save; // !!!!
====2
1:624c
3:654c
        setring @R;
2:713c
        setring @R; // !!!!!
====2
1:628c
3:658c
      setring save;
2:717c
      setring save; // !!!!! !
====2
1:632c
3:662c
    setring save;
2:721c
    setring save; // !!!!! !!
====2
1:644a
3:674a
2:734,762c
    kill U;
    setring r; // non-homog. input:
    M = [-1,x,y],[-7,y,y,z],[3,x,x,x,z,z];
    N = [1,x,y,z,x],[-1,y,x,y];
    L[1] = M; L[2] = N;
    lst2str(L);
    def U = freegbasis(L,5);
    lst2str(U); // OK
    kill U,r;
    ring r = 0,(x,y,z),(dp(1),dp(2));
    def R = nc_algebra(1,0); setring R; // should be the same as 1st!
    module M = [-1,x,y],[-7,y,y],[3,x,x];
    module N = [1,x,y,x],[-1,y,x,y];
    list L; L[1] = M; L[2] = N;
    lst2str(L);
    def U = freegbasis(L,5);
    lst2str(U); // OK
    kill U, R;
    setring r;
    def R = nc_algebra(-1,1); setring R; // some non-commutativity
    R;
    module M = [-1,x,y],[-7,y,y],[3,x,x];
    module N = [1,x,y,x],[-1,y,x,y];
    list L; L[1] = M; L[2] = N;
    lst2str(L);
    def U = freegbasis(L,5);  
    lst2str(U);
  
  
====3
1:647c
2:765c
  proc crs(list LM, int d)
3:677c
  static proc crs(list LM, int d)
====3
1:796c
2:914c
  proc polylen(ideal I)
3:826c
  static proc polylen(ideal I)
====2
1:811a
3:841a
2:930,938c
  
  // TODO: ASSUMPTIONS? 
  // TODO: PROC FORGETS ABOUT NON-COMM. RELATIONS IN THE 
  //// BASERING! DOCUMENT IT OR FIX...
  // TODO: WRITE DOWN WHAT IS THE ORDERING IN THE OUTPUT RING?
  // TODO: OVERSIMPLIFIED: WHAT IF PARAMETERS HAVE BRACKETS
  //// AND COINCIDE WITH GENERATED VARIABLES? SEE EXAMPLE
  
  
====2
1:822c
3:852c
    int ppl = printlevel-voice+2;
2:949c
    int ppl = printlevel-voice+2; 
====2
1:885,886c
3:915,916c
    def A = freegbRing(2);
    setring A;
2:1012,1013c
    r;
    def A = freegbRing(2); setring A;
====2
1:887a
3:917a
2:1015,1032c
    kill A, r;
    ring r = 0,(x(1..3)),(dp(1),lp(2));
    r;
    def A = freegbRing(2); setring A;
    A; // OK
    kill A, r;
    ring r = (0,a(1),b(1)),(a, b),(lp(1),dp(1));
    r;
    def A = freegbRing(2); setring A; 
    A; // BUG: parameter should not be named as a variable and vice verse!
    a(1); typeof(a(1));
    kill A, r;
    ring r = 0,(x,y,z),dp;  
    def R = nc_algebra(-1, 1); setring R; 
    R;  
    def A = freegbRing(2); setring A;
    A; // NOTE: the putput is a purely commutative ring!
    kill A, R, r;
====3
1:890c
2:1035c
  proc ex_shift()
3:920,922c
  /* EXAMPLES:
  
  //static proc ex_shift()
====3
1:911c
2:1056c
  proc test_shrink()
3:943c
  //static proc test_shrink()
====3
1:938c
2:1083c
  proc ex2()
3:970c
  //static proc ex2()
====3
1:948c
2:1093c
  proc ex_nonhomog()
3:980c
  //static proc ex_nonhomog()
====3
1:966c
2:1111c
  proc ex_nonhomog_comm()
3:998c
  //static proc ex_nonhomog_comm()
====3
1:976c
2:1121c
  proc ex_nonhomog_h()
3:1008c
  //static proc ex_nonhomog_h()
====3
1:986c
2:1131c
  proc ex_nonhomog_h2()
3:1018c
  //static proc ex_nonhomog_h2()
====3
1:1005c
2:1150c
  proc ex_nonhomog_3()
3:1037c
  //static proc ex_nonhomog_3()
====3
1:1024c
2:1169c
  proc ex_densep_2()
3:1056c
  //static proc ex_densep_2()
====3
1:1039a
2:1184a
3:1072,1074c
  // END COMMENTED EXAMPLES
  
  */
====3
1:1048c
2:1193c
  proc freegbold(list LM, int d)
3:1083c
  static proc freegbold(list LM, int d)
====3
1:1306c
2:1451c
  proc sgb(ideal I, int d)
3:1341c
  static proc sgb(ideal I, int d)
====3
1:1329,1330c
2:1474,1475c
  
  
3:1363a
====3
1:1344,1345c
2:1489,1490c
  
  proc exHom1()
3:1377c
  static proc exHom1()
====3
1:1422c
2:1567c
  proc schur2-3()
3:1454c
  static proc schur2-3()
====3
1:1431a
2:1576a
3:1464,1470c
  "USAGE:  adem(i,j); i,j int
  RETURN:  ring and exports ideal
  ASSUME: there are at least i+j variables in the basering
  PURPOSE: compute the ideal of Adem relations for i<2j in characteristic 0
  @*  the ideal is exported under the name AdemRel in the output ring
  EXAMPLE: example adem; shows examples
  "
====3
1:1447c
2:1592c
    printf("k=0, term=%s",q);
3:1486c
    //  printf("k=0, term=%s",q);
====3
1:1453c
2:1598c
      printf("k=%s, term=%s",k,q);
3:1492c
      //    printf("k=%s, term=%s",k,q);
====3
1:1498,1501c
2:1643,1646c
  proc adem2mod(int n)
  {
    // Adem rels modulo 2
  }
3:1537c
    // Adem rels modulo 2 are interesting
====3
1:1503c
2:1648c
  proc stringpoly2lplace(string s)
3:1539c
  static proc stringpoly2lplace(string s)
====3
1:1649c
2:1794c
  proc addplaces(list L)
3:1685c
  static proc addplaces(list L)
====3
1:1677c
2:1822c
  proc sent2lplace(string s)
3:1713c
  static proc sent2lplace(string s)
====3
1:1696c
2:1841c
  proc testnumber(string s)
3:1732c
  static proc testnumber(string s)
====3
1:1746c
2:1891c
  proc str2lplace(string s)
3:1782c
  static proc str2lplace(string s)
====3
1:1823c
2:1968c
  proc strpower2rep(string s)
3:1859c
  static proc strpower2rep(string s)
====3
1:1933a
2:2078a
3:1970,1978c
  "USAGE:  Liebr(a,b[,N]); a,b letterplace polynomials, N an optional integer
  RETURN:  poly
  ASSUME: basering has a letterplace ring structure, like the one returned by freegbRing
  @*   Moreover, the variables 'uptodeg' (degree bound of the letterplace ring) and 'lV' (number of
  blocks of variables of the letterplace ring ) must be defined
  PURPOSE: compute the Lie bracket [a,b] = ab - ba between letterplace polynomials
  NOTE: if N>1 is specified, then the left normed bracket [a,[...[a,b]]]] is computed.
  EXAMPLE: example Liebr; shows examples
  "
====3
1:1934a
2:2079a
3:1980,1984c
  
    if (lpAssumeViolation())
    {
      ERROR("Either 'uptodeg' or 'lV' global variables are not set!");
    }
====3
1:1970a
2:2115a
3:2021c
    kill uptodeg, lV;
====3
1:1973c
2:2118c
  proc pmLiebr(poly a, poly b)
3:2024c
  static proc pmLiebr(poly a, poly b)
====3
1:1986c
2:2131c
  proc pshift(poly a, int i)
3:2037c
  static proc pshift(poly a, int i)
====3
1:1989a
2:2134a
3:2041,2044c
    if (deg(a) + i > uptodeg)
    {
      ERROR("degree bound violated by the shift!");
    }
====3
1:1993c
2:2138c
  proc mmLiebr(poly a, poly b)
3:2048c
  static proc mmLiebr(poly a, poly b)
====3
1:2014a
2:2159a
3:2070c
    kill uptodeg, lV;
====3
1:2017a
2:2162a
3:2074,2080c
  "USAGE:  Serre(A,z); A an intmat, z an int
  RETURN:  ideal
  ASSUME: basering has a letterplace ring structure and
  @*    A is a generalized Cartan matrix with integer entries
  PURPOSE: compute the ideal of Serre's relations associated to A
  EXAMPLE: example Serre; shows examples
  "
====3
1:2025c
2:2170c
    int i,j,k,l;
3:2088c
    int i,j,k,el;
====3
1:2032c
2:2177c
        l = 1 - A[i,j];
3:2095c
        el = 1 - A[i,j];
====3
1:2034c
2:2179c
        dbprint(ppl,"i, j, l: ",i,j,l);
3:2097c
        dbprint(ppl,"i, j, l: ",i,j,el);
====3
1:2037c
2:2182c
        if ((i!=j) && (l >0))
3:2100c
        if ((i!=j) && (el >0))
====3
1:2040c
2:2185c
          //        printf("first bracket: %s",q);
3:2102a
====3
1:2044c
2:2189c
            for (k=1; k<=l-1; k++)
3:2106c
            for (k=1; k<=el-1; k++)
====3
1:2047c
2:2192c
              //            printf("further bracket: %s",q);
3:2108a
====
1:2061,2063c
    intmat A[2][2] = 2, -1, -1, 2; // sl_3 == A_2
    ring r = 0,(f1,f2),dp;
    int uptodeg = 3; int lV = 2;
2:2206,2209c
    intmat A[2][2] = 2, -1, -1, 2; // sl_3 == A_2
    ring r = 0,(f1,f2),dp;
    int uptodeg = 3; 
    int lV = 2;
3:2122,2127c
    intmat A[3][3] =
      2, -1, 0,
      -1, 2, -3,
      0, -1, 2; // G^1_2 Cartan matrix
    ring r = 0,(f1,f2,f3),dp;
    int uptodeg = 5; int lV = 3;
====3
1:2067c
2:2213c
    ideal I = Serre(A,1);
3:2131c
    ideal I = Serre(A,1); I = simplify(I,1+2+8);
====3
1:2069c
2:2215c
    Serre(A,0);
3:2133c
    kill uptodeg, lV;
====
1:2071a
2:2218,2221c
  // TODO: EXPLAIN CONVERTION RULE, ENCODING OF 'LN'!
  // THIS SEEMS TO BE THE LAST PART OF FREEGBASIS?
  // TODO: ASSUMPTIONS! WHY NO SQUARES IN ELEMENTS FROM K?
  
3:2136,2141c
  /* setup for older example:
    intmat A[2][2] = 2, -1, -1, 2; // sl_3 == A_2
    ring r = 0,(f1,f2),dp;
    int uptodeg = 5; int lV = 2;
  */
  
====3
1:2073,2075c
2:2223,2225c
  "USAGE:  lp2lstr(K,save); K an ideal, save a ring
  RETURN:  nothing (exports object LN into save)
  PURPOSE: converts letter-place ideal to list of modules
3:2143,2147c
  "USAGE:  lp2lstr(K,s); K an ideal, s a ring
  RETURN:  nothing (exports object LN into s)
  ASSUME: basering has a letterplace ring structure
  PURPOSE: converts letterplace ideal to list of modules
  NOTE: useful as preprocessing to 'lst2str'
====2
1:2097a
3:2169a
2:2248,2250c
  
    // TODO: YOU CAN FOLD TWO FOLLOWING LOOPS TOGETHER! 
    // THE FOLLOWING CHECK/PREPROCESSING MIGHT BE EXPENSIVE!
====2
1:2180,2181c
3:2252,2253c
    int uptodeg = 3; int lV = 2;
    export uptodeg; export lV;
2:2333c
    int uptodeg = 3; 
====2
1:2184c
3:2256c
    ideal I = Serre(A,1);
2:2336,2341c
    ideal I = Serre(A,1); // TODO: BUG: WHY IS THIS FAILED??? HIDING ARGUMENTS IS A BAD STYLE!!!
  
    int lV = 2; // NOT CLEAR WHERE DO YOU NEED THIS?
    export uptodeg; export lV; // TODO: BUG: THEY WHERE NOR DEFINED BEFORE IN CODE!!!
    I = Serre(A,1); 
  
====2
1:2188c
3:2260c
    kill uptodeg; kill lV;
2:2345,2348c
  
  
    kill uptodeg; 
    kill lV;
====3
1:2191c
2:2351c
  proc strList2poly(list L)
3:2263c
  static proc strList2poly(list L)
====3
1:2231c
2:2391c
  proc file2lplace(string fname)
3:2303,2308c
  static proc file2lplace(string fname)
  "USAGE:  file2lplace(fnm);  fnm a string
  RETURN:  ideal
  PURPOSE: convert the contents of the file fnm into ideal of polynomials in free algebra
  EXAMPLE: example file2lplace; shows examples
  "
====3
1:2289c
2:2449c
  static proc get_ls3nilp()
3:2366,2367c
  /* EXAMPLES AGAIN:
  //static proc get_ls3nilp()
====3
1:2303c
2:2463c
  static proc doc_example
3:2381c
  //static proc doc_example()
====3
1:2320c
2:2480c
  
3:2398c
  */
====3
1:2325a
2:2485a
3:2404,2448c
  proc lpMult(poly f, poly g)
  "USAGE:  lpMult(f,g); f,g letterplace polynomials
  RETURN:  poly
  ASSUME: basering has a letterplace ring structure, like the one returned by freegbRing
  @*   Moreover, the variables 'uptodeg' (degree bound of the letterplace ring) and 'lV' (number of
  blocks of variables of the letterplace ring ) must be defined
  PURPOSE: compute the letterplace form of f*g
  EXAMPLE: example lpMult; shows examples
  "
  {
    if (lpAssumeViolation())
    {
      ERROR("Either 'uptodeg' or 'lV' global variables are not set!");
    }
    int sf = deg(f);
    int sg = deg(g);
    if (sf+sg > uptodeg)
    {
      ERROR("degree bound violated by the product!");
    }
    //  if (sf>1) { sf = sf -1; }
    poly v = f*pshift(g,sf);
    return(v);
  }
  example
  {
    "EXAMPLE:"; echo = 2;
    // define a ring in letterplace form as follows:
    ring r = 0,(x(1),y(1),x(2),y(2),x(3),y(3),x(4),y(4)),dp; 
    poly a = x(1)*y(2); poly b = y(1);
    int uptodeg=4; int lV=2;
    export uptodeg; export lV;
    lpMult(b,a);
    lpMult(a,b);
    kill uptodeg, lV;
  }
  
  static proc lpAssumeViolation()
  {
    // checks whether the global vars
    // uptodeg and lV are defined
    // returns Boolean : yes/no [for assume violation]
    int i = ( defined(uptodeg) && (defined(lV)) );
    return ( !i );
  }