  
  [1m[4m[31m1. [1msingular[1m[4m[31m: the [1mGAP[1m[4m[31m interface to [1mSingular[1m[4m[31m[0m
  
  
  [1m[4m[31m1.1 Introduction[0m
  
  This  is  the  manual  of  the  [1mGAP[0m  package  ``[1msingular[0m''  that provides an
  interface  from  the  [1mGAP[0m  computer  algebra system to the [1mSingular[0m computer
  algebra system.
  
  This package allows the [1mGAP[0m user to access functions of [1mSingular[0m from within
  [1mGAP[0m, and to apply these functions to the [1mGAP[0m objects. With this package, the
  user  keeps working with [1mGAP[0m and, if he needs a function of [1mSingular[0m that is
  not  present  in  [1mGAP[0m,  he  can use this function via the interface; see the
  function [1m[34mSingularInterface[0m ([1m1.3-8[0m).
  
  This package provides also a function that computes Groebner bases of ideals
  in  polynomial rings of [1mGAP[0m. This function uses the [1mSingular[0m implementation,
  which is very fast; see the function [1m[34mGroebnerBasis[0m ([1m1.5-1[0m).
  
  The  interface  is  expected to work with every version of [1mGAP[0m 4, every (not
  very  old) version of [1mSingular[0m, and on every platform, on which both [1mGAP[0m and
  [1mSingular[0m run; see paragraph [1m1.7-1[0m for details.
  
  If  you  have used this package in the preparation of a paper please cite it
  as described in [34mhttp://www.gap-system.org/Contacts/cite.html[0m.
  
  If  [1mGAP[0m,  [1mSingular[0m,  and  the [1mGAP[0m package [1msingular[0m are already installed and
  working  on  his computer, the user of this interface needs to read only the
  subsection  [1m[34msing_exec[0m  ([1m1.2-4[0m), the section [1m1.4[0m, and in case of problems the
  subsection [1m1.7-4[0m.
  
  
  [1m[4m[31m1.1-1 Package evolution[0m
  
  The  work for the package [1msingular[0m has been started by Willem de Graaf, that
  planned  this  package  as  an  interface  to  the function of [1mSingular[0m that
  calculates  the  Groebner  bases. To this purpose, Willem de Graaf wrote the
  code  for  the  conversion of rings and ideals from [1mGAP[0m to [1mSingular[0m, and the
  code for the conversion of numbers and polynomials in both directions.
  
  Marco  Costantini  has widened the aim of the package, in order to make it a
  general  interface  to each possible function of [1mSingular[0m: with the function
  [1m[34mSingularInterface[0m ([1m1.3-8[0m) it is possible to use from within [1mGAP[0m any function
  of [1mSingular[0m, including user-defined ones and future implementations. To this
  purpose,  Marco  Costantini  has  generalized  the  previous  code  for  the
  conversion  of objects in the new more general context, has written the code
  for  the  conversion  of the various other types of objects, and has written
  the code for the low-level communication between [1mGAP[0m and [1mSingular[0m.
  
  David  Joyner  has  developed  the  code  for  the algebraic-geometric codes
  functions, and has written the corresponding section [1m1.6[0m of this manual.
  
  Gema M. Diaz has helped with some testing and reports.
  
  
  [1m[4m[31m1.1-2 The system [1mSingular[1m[4m[31m[0m
  
  [1mSingular[0m   is  "A  Computer  Algebra  System  for  Polynomial  Computations"
  developed  by  G.-M.  Greuel, G. Pfister, and H. Sch\"onemann, at Centre for
  Computer  Algebra,  University  of  Kaiserslautern.  The  authors of the [1mGAP[0m
  package [1msingular[0m are not involved in the development of the system [1mSingular[0m,
  and vice versa.
  
  [1mSingular[0m  is not included in this package, and can be obtained for free from
  [34mhttp://www.singular.uni-kl.de[0m.  There,  one can find also its documentation,
  installing  instructions,  the source code if wanted, and support if needed.
  [1mSingular[0m is available for several platforms.
  
  A   description  of  [1mSingular[0m,  copied  from  its  manual  (paragraph  ``2.1
  Background''), version 2-0-5, is the following:
  
  "  [1mSingular[0m  is  a  Computer Algebra system for polynomial computations with
  emphasis  on  the  special needs of commutative algebra, algebraic geometry,
  and singularity theory. [1mSingular[0m's main computational objects are ideals and
  modules  over  a  large  variety  of baserings. The baserings are polynomial
  rings  or  localizations  thereof  over  a  field  (e.g., finite fields, the
  rationals,  floats,  algebraic  extensions,  transcendental  extensions)  or
  quotient  rings  with  respect  to  an  ideal.  [1mSingular[0m features one of the
  fastest and most general implementations of various algorithms for computing
  Groebner  resp.  standard  bases.  The  implementation includes Buchberger's
  algorithm  (if the ordering is a well ordering) and Mora's algorithm (if the
  ordering  is  a  tangent  cone  ordering)  as special cases. Furthermore, it
  provides  polynomial  factorizations,  resultant, characteristic set and gcd
  computations, syzygy and free-resolution computations, and many more related
  functionalities.  Based  on  an  easy-to-use  interactive shell and a C-like
  programming  language,  [1mSingular[0m's  internal  functionality is augmented and
  user-extendible by libraries written in the [1mSingular[0m programming language. A
  general  and efficient implementation of communication links allows [1mSingular[0m
  to   make   its   functionality  available  to  other  programs.  [1mSingular[0m's
  development  started  in  1984 with an implementation of Mora's Tangent Cone
  algorithm  in  Modula-2 on an Atari computer (K.P. Neuendorf, G. Pfister, H.
  Schnemann; Humboldt-Universitt zu Berlin). The need for a new system arose
  from  the  investigation  of  mathematical  problems coming from singularity
  theory  which none of the existing systems was able to compute. In the early
  1990s  [1mSingular[0m's  ``home-town'' moved to Kaiserslautern, a general standard
  basis  algorithm  was  implemented  in  C,  and [1mSingular[0m was ported to Unix,
  MS-DOS,  Windows  NT,  and  MacOS.  Continuous  extensions  (like polynomial
  factorization,  gcd  computations, links) and refinements led in 1997 to the
  release  of  [1mSingular[0m  version 1.0 and in 1998 to the release of version 1.2
  (much  faster  standard  and  Groebner  bases  computations based on Hilbert
  series  and  on  improved  implementations  of the algorithms, libraries for
  primary decomposition, ring normalization, etc.) "
  
  .
  
  
  [1m[4m[31m1.1-3 The system [1mGAP[1m[4m[31m[0m
  
  [1mGAP[0m  stands  for  "Groups, Algorithms, and Programming", and is developed by
  several people ("The [1mGAP[0m Group").
  
  [1mGAP[0m  is  not  included  in  this  package, and can be obtained for free from
  [34mhttp://www.gap-system.org/[0m.  There,  one  can  find  also its documentation,
  installing  instructions,  the  source  code, and support if needed. The [1mGAP[0m
  system  will run on any machine with an Unix-like or recent Windows or MacOS
  operating system and with a reasonable amount of ram and disk space.
  
  A  description of [1mGAP[0m, copied from its web site, is the following: "[1mGAP[0m is a
  system  for  computational  discrete  algebra,  with  particular emphasis on
  Computational  Group  Theory. [1mGAP[0m provides a programming language, a library
  of  thousands  of functions implementing algebraic algorithms written in the
  [1mGAP[0m  language  as well as large data libraries of algebraic objects. See the
  web  site the overview and the description of the mathematical capabilities.
  [1mGAP[0m  is  used  in  research  and  teaching  for  studying  groups  and their
  representations,  rings,  vector spaces, algebras, combinatorial structures,
  and more. The system, including source, is distributed freely. You can study
  and easily modify or extend it for your special use."
  
  
  [1m[4m[31m1.2 Installation[0m
  
  In order to use this interface one must have both [1mGAP[0m version 4 and [1mSingular[0m
  installed.
  
  
  [1m[4m[31m1.2-1 Installing the system [1mSingular[1m[4m[31m[0m
  
  Follow the [1mSingular[0m installing instructions.
  
  However, for a Unix system, one needs to download two files:
  
  --    [1mSingular-<version>-share.tar.gz[0m,     that     contains    architecture
        independent data like documentation and libraries;
  
  --    [1mSingular-<version>-<uname>.tar.gz[0m,    that    contains    architecture
        dependent   executables,  like  the  [1mSingular[0m  program  (precompiled).
        <uname>  is  a  description  of the processor and operating system for
        which [1mSingular[0m is compiled.
  
  [1mSingular[0m specific subdirectories will be created in such a way that multiple
  versions and multiple architecture dependent files of [1mSingular[0m can peaceably
  coexist under the same [1m/usr/local/[0m tree.
  
  Before  trying  the  interface,  make  sure  that  [1mSingular[0m is installed and
  working as stand-alone program.
  
  
  [1m[4m[31m1.2-2 Installing the system [1mGAP[1m[4m[31m[0m
  
  Follow the [1mGAP[0m installing instructions.
  
  However, the basic steps of a [1mGAP[0m installation are:
  
  --    Choose your preferred archive format and download the archives.
  
  --    Unpack the archives.
  
  --    On Unix: Compile [1mGAP[0m. (Compiled executables for Windows and Mac are in
        the archives.)
  
  --    On   Unix:   Some   packages   need   further  installation  for  full
        functionality (which is not available on Windows or Mac).
  
  --    Adjust some links/scripts/icons ..., depending on your system, to make
        the new version of [1mGAP[0m available to the users of your machine.
  
  --    Optional: Run a few tests.
  
  --    Optional, but appreciated: Give some feedback on your installation.
  
  There   is  also  an  experimental  Linux  binary  distribution  via  remote
  synchronization  with  a reference installation, which includes all packages
  and  some  optimizations.  Furthermore,  the  Debian  GNU/Linux distribution
  contains  .deb-packages  with  the  core  part  of  [1mGAP[0m  and some of the [1mGAP[0m
  packages.
  
  
  [1m[4m[31m1.2-3 Installing the package [1msingular[1m[4m[31m[0m
  
  The  package  [1msingular[0m  is installed and loaded as a normal [1mGAP[0m package: see
  the [1mGAP[0m documentation [1m`Reference: GAP Packages'[0m.
  
  Starting  with  version  4.4  of  [1mGAP[0m,  the  package [1msingular[0m is distributed
  together  with  [1mGAP[0m.  Hence,  if  [1mGAP[0m  is  already  installed  with  all the
  distributed  packages, then also the package [1msingular[0m is installed. However,
  if  the package [1msingular[0m is not included in your [1mGAP[0m installation, it can be
  downloaded  and  unpacked  in the [1mpkg/[0m directory of the [1mGAP[0m installation. If
  you  don't  have  write  access  to  the  [1mpkg/[0m  directory  in  your main [1mGAP[0m
  installation  you  can  use  private  directories  as  explained  in the [1mGAP[0m
  documentation  [1m`Reference: GAP Root Directory'[0m. The package [1msingular[0m doesn't
  require compilation.
  
  [1m[4m[31m1.2-4 sing_exec[0m
  
  [1m[34m> sing_exec__________________________________________________[0mglobal variable
  [1m[34m> sing_exec_options__________________________________________[0mglobal variable
  [1m[34m> SingularTempDirectory______________________________________[0mglobal variable
  
  In  order  to  use the interface, [1mGAP[0m has to be told where to find [1mSingular[0m.
  This can be done in three ways. First, if the [1mSingular[0m executable file is in
  the  search  path,  then  [1mGAP[0m  will  find it. Second, it is possible to edit
  (before   loading   the  package)  one  of  the  first  lines  of  the  file
  [1msingular/gap/singular.g[0m  (that  comes  with  this  package).  Third,  it  is
  possible  to  give  the path of the [1mSingular[0m executable file directly during
  each  [1mGAP[0m session assigning it to the variable [22m[34msing_exec[0m (after this package
  has been loaded, and before starting [1mSingular[0m), as in the example below.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> LoadPackage( "singular" );[0m
    [22m[35mThe GAP interface to Singular, by Marco Costantini and Willem de Graaf[0m
    [22m[35mtrue[0m
    [22m[35mgap> sing_exec:= "/home/wdg/Singular/2-0-3/ix86-Linux/Singular";;[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The  directory separator is always '[1m/[0m', even under DOS/Windows or MacOS. The
  value  of  [22m[34msing_exec[0m  must  refer  to  the  text-only  version  of  [1mSingular[0m
  ([22m[34mSingular[0m),  and  not  to the Emacs version ([22m[34mESingular[0m), nor to the terminal
  window version ([22m[34mTSingular[0m).
  
  In  a  similar way, it is possible to supply [1mSingular[0m with some command line
  options (or files to read containing user defined functions), assigning them
  to  the  variable  [22m[34msing_exec_options[0m.  This  can  be done by editing (before
  loading    the   package)   one   of   the   first   lines   of   the   file
  [1msingular/gap/singular.g[0m  (that  comes with this package), or directly during
  each  [1mGAP[0m  session  (after this package has been loaded, and before starting
  [1mSingular[0m), as in the example below.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> Add( sing_exec_options, "--no-rc" );[0m
    [22m[35mgap> Add( sing_exec_options, "/full_path/my_file" );[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The  variable [22m[34msing_exec_options[0m is initialized to [22m[34m[ "-t" ][0m; the user can add
  further options, but must keep [22m[34m"-t"[0m, which is required. The possible options
  are  described in the [1mSingular[0m documentation, paragraph ``3.1.6 Command line
  options''.
  
  [1mSingular[0m  is  not executed in the current directory, but in a user-specified
  one,  or  in  a  temporary  one.  It  is  possible  to supply this directory
  assigning  it  to  the  variable  [22m[34mSingularTempDirectory[0m. This can be done by
  editing  (before  loading  the  package)  one of the first lines of the file
  [1msingular/gap/singular.g[0m  (that  comes with this package), or directly during
  each  [1mGAP[0m  session  (after this package has been loaded, and before starting
  [1mSingular[0m),  as  in  the  example  below.  If  [22m[34mSingularTempDirectory[0m  is  not
  assigned,  [1mGAP[0m  will  create  and  use  a temporary directory, which will be
  removed when [1mGAP[0m quits.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> SingularTempDirectory := Directory( "/tmp" );[0m
    [22m[35mdir("/tmp/")[0m
  [22m[35m------------------------------------------------------------------[0m
  
  On  Windows,  [1mSingular[0m  version  3  may be not executed directly, but may be
  executed   as   [22m[34mbash  Singular[0m.  In  this  case,  the  variables  [22m[34msing_exec[0m,
  [22m[34msing_exec_options[0m,   [22m[34mSingularTempDirectory[0m   must  reflect  this,  otherwise
  Windows  complains  that [22m[34mcygwin1.dll[0m is not found. The following works on my
  Windows machine.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> LoadPackage("singular");[0m
    [22m[35mtrue[0m
    [22m[35mgap> SingularTempDirectory := Directory("c:/cygwin/bin");[0m
    [22m[35mdir("c:/cygwin/bin/")[0m
    [22m[35mgap> sing_exec := "c:/cygwin/bin/bash.exe";[0m
    [22m[35m"c:/cygwin/bin/bash.exe"[0m
    [22m[35mgap> sing_exec_options := [ "Singular", "-t" ];[0m
    [22m[35m[ "Singular", "-t" ][0m
    [22m[35mgap> StartSingular();[0m
  [22m[35m------------------------------------------------------------------[0m
  
  Another  possibility  is  to  run  Gap from within the Cygwin shell. In this
  case,  with  a  standard  installation  of Cygwin and [1mSingular[0m, no change is
  required,
  
  
  [1m[4m[31m1.3 Interaction with [1mSingular[1m[4m[31m[0m
  
  The  user  must  load  the  package  [1msingular[0m  with  [1m[34mLoadPackage[0m ([1mReference:
  LoadPackage[0m)  (or  with  [1m[34mRequirePackage[0m ([1mReference: RequirePackage[0m) if using
  [1mGAP[0m version 4.x, x < 4).
  
  [1m[4m[31m1.3-1 StartSingular[0m
  
  [1m[34m> StartSingular( [0m[22m[34m[0m[1m[34m ) ________________________________________________[0mfunction
  [1m[34m> CloseSingular( [0m[22m[34m[0m[1m[34m ) ________________________________________________[0mfunction
  
  After   the   package   [1msingular[0m   has  been  loaded,  [1mSingular[0m  is  started
  automatically  when  one  of  the  functions  of  the  interface  is called.
  Alternatively, one can start [1mSingular[0m with the command [22m[34mStartSingular[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> StartSingular();[0m
  [22m[35m------------------------------------------------------------------[0m
  
  See  [1m1.7-1[0m  for  technical  details.  Explicit  use  of [22m[34mStartSingular[0m is not
  necessary.  If  [22m[34mStartSingular[0m  is called when a previous [1mSingular[0m session is
  running, than session will be closed, and a new session will be started.
  
  If  at  some  point  [1mSingular[0m is no longer needed, then it can be closed (in
  order to save system resources) with the command [22m[34mCloseSingular[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> CloseSingular();[0m
  [22m[35m------------------------------------------------------------------[0m
  
  However,  when  [1mGAP[0m  exits, it is expected to close Singular, and remove any
  temporary directory, except in the case of abnormal [1mGAP[0m termination.
  
  [1m[4m[31m1.3-2 SingularHelp[0m
  
  [1m[34m> SingularHelp( [0m[22m[34mtopic[0m[1m[34m ) ____________________________________________[0mfunction
  
  Here  [22m[34mtopic[0m  is  a  string  containing  the  name  of a [1mSingular[0m topic. This
  function provides help on that topic using the [1mSingular[0m help system: see the
  [1mSingular[0m  documentation,  paragraphs  ``3.1.3  The  online help system'' and
  ``5.1.43  help''. If [22m[34mtopic[0m is the empty string "", then the title/index page
  of the manual is displayed.
  
  This  function  can be used to display the [1mSingular[0m documentation referenced
  in this manual; [22m[34mtopic[0m must be given without the leading numbers.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> SingularHelp( "" ); # a Mozilla window appears[0m
    [22m[35m#I  // ** Displaying help in browser 'mozilla'.[0m
    [22m[35m// ** Use 'system("--browser", <browser>);' to change browser,[0m
    [22m[35m// ** where <browser> can be: "mozilla", "xinfo", "info", "builtin", "dummy", \[0m
    [22m[35m"emacs".[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The   [1mSingular[0m   function   [22m[34msystem[0m   can   be   accessed  via  the  function
  [1m[34mSingularInterface[0m  ([1m1.3-8[0m).  Some only-text browsers may be not supported by
  the interface.
  
  
  [1m[4m[31m1.3-3 Rings and orderings[0m
  
  All  non-trivial  algorithms  in  [1mSingular[0m require the prior definition of a
  (polynomial)  ring,  that  will  be called the ``base-ring''. Any polynomial
  (respectively vector) in [1mSingular[0m is ordered with respect to a term ordering
  (or,  monomial  ordering),  that  has  to  be  specified  together  with the
  declaration  of  a  ring. See the documentation of [1mSingular[0m, paragraph ``3.3
  Rings and orderings'', for further information.
  
  After  defining  in  [1mGAP[0m a ring, a term ordering can be assigned to it using
  the  function  [1m[34mSetTermOrdering[0m  ([1m1.3-5[0m),  and  [22m[36mafter[0m  the  term  ordering is
  assigned,  the  interface  and  [1mSingular[0m can be told to use this ring as the
  base-ring, with the function [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m).
  
  
  [1m[4m[31m1.3-4 Supported coefficients fields[0m
  
  Let  [22m[34mp[0m  be  a  prime,  [22m[34mpol[0m an irreducible polynomial, and [22m[34marg[0m an appropriate
  argument for the given function. The coefficient fields of the base-ring may
  be of the following form:
  
  --    [22m[34mRationals[0m,
  
  --    [22m[34mCyclotomicField( arg )[0m,
  
  --    [22m[34mAlgebraicExtension( Rationals, pol )[0m,
  
  --    [22m[34mGaloisField( arg )[0m (both prime and non-prime),
  
  --    [22m[34mAlgebraicExtension( GaloisField( p ), pol )[0m.
  
  For some example see those for the function [1m[34mSetTermOrdering[0m ([1m1.3-5[0m).
  
  Let  us  remember  that  [22m[34mCyclotomicField[0m  and [22m[34mGaloisField[0m can be abbreviated
  respectively  to  [22m[34mCF[0m  and  [22m[34mGF[0m;  these  forms  are  used also when [1mGAP[0m prints
  cyclotomic  or Galois fields. See the [1mGAP[0m documentation about the functions:
  [1m[34mCyclotomicField[0m   ([1mReference:   CyclotomicField[0m),   [1m[34mGaloisField[0m  ([1mReference:
  GaloisField[0m),  [1m[34mAlgebraicExtension[0m  ([1mReference:  AlgebraicExtension[0m), and the
  chapters: [1m`Reference: Rational Numbers'[0m, [1m`Reference: Abelian Number Fields'[0m,
  [1m`Reference: Finite Fields'[0m, [1m`Reference: Algebraic extensions of fields'[0m.
  
  [1m[4m[31m1.3-5 SetTermOrdering[0m
  
  [1m[34m> SetTermOrdering( [0m[22m[34mR[0m[1m[34m ) _____________________________________________[0mfunction
  [1m[34m> TermOrdering( [0m[22m[34mR[0m[1m[34m ) _______________________________________________[0mattribute
  
  Let  [22m[34mR[0m  be  a  polynomial ring. The value of [22m[34mTermOrdering( R )[0m describes the
  term  ordering  of [22m[34mR[0m, and can be a string, a list, or a monomial ordering of
  [1mGAP[0m.  (The  term  orderings  of [1mSingular[0m are explained in its documentation,
  paragraphs   ``3.3.3   Term   orderings''   and   ``B.2.1   Introduction  to
  orderings''.)
  
  If  this  value  is  a string, for instance [22m[34m"lp"[0m (lexicographical ordering),
  [22m[34m"dp"[0m   (degree   reverse   lexicographical   ordering),   or   [22m[34m"Dp"[0m  (degree
  lexicographical  ordering),  this  value  will be passed to [1mSingular[0m without
  being interpreted or parsed by the interface.
  
  If  this  value  is a list, it must be of the form [22m[34m[ str_1, d_1, str_2, d_2,
  ...  ][0m,  where each [22m[34mstr_i[0m is a [1mSingular[0m ordering given as a string. Each [22m[34md_i[0m
  must  be  a  number,  and  specifies  the  number  of  variables having that
  ordering; however, if [22m[34mstr_i[0m is a weighted order, like [22m[34m"wp"[0m (weighted reverse
  lexicographical  ordering) or [22m[34m"Wp"[0m (weighted lexicographical ordering), then
  the corresponding [22m[34md_i[0m must be a list of positive integers that specifies the
  weight  of  each  variable.  The  sum  of the [22m[34md_i[0m's (if numbers) or of their
  lengths (if lists) must be equal to the number of variables of the ring [22m[34mR[0m.
  
  This  value  can also be a monomial ordering of [1mGAP[0m: currently supported are
  [22m[34mMonomialLexOrdering[0m,   [22m[34mMonomialGrevlexOrdering[0m,   and  [22m[34mMonomialGrlexOrdering[0m
  [1m`Reference: Monomial Orderings'[0m.
  
  [22m[34mTermOrdering[0m   is   a  mutable  attribute,  see  the  [1mGAP[0m  documentation  of
  [1m[34mDeclareAttribute[0m  ([1mPrg  Tutorial: DeclareAttribute[0m); if it is changed on the
  [1mGAP[0m side, it is necessary thereafter to send again the ring to [1mSingular[0m with
  [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m).
  
  [22m[34mSetTermOrdering[0m  can  be  used to set the term ordering of a ring. It is not
  mandatory  to  assign  a term ordering: if no term ordering is set, then the
  default  [22m[34m"dp"[0m  will  be  used.  If  it is set, the term ordering must be set
  [22m[36mbefore[0m  the  ring  is  sent  to  [1mSingular[0m  with [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m),
  otherwise,  [1mSingular[0m  will  ignore  that  term  ordering,  and  will use the
  previous value if any, or the default [22m[34m"dp"[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R1:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> SetTermOrdering( R1, "lp" );[0m
    [22m[35mgap> R2:= PolynomialRing( GaloisField(9), 3 );;[0m
    [22m[35mgap> SetTermOrdering( R2, [ "wp", [1,1,2] ] );[0m
    [22m[35mgap> R3:= PolynomialRing( CyclotomicField(25), ["x","y","z"] : old );;[0m
    [22m[35mgap> SetTermOrdering( R3, MonomialLexOrdering() );[0m
    [22m[35mgap> x:=Indeterminate(Rationals);;[0m
    [22m[35mgap> F:=AlgebraicExtension(Rationals, x^5+4*x+1);;[0m
    [22m[35mgap> R4:= PolynomialRing( F, 6 );;[0m
    [22m[35mgap> SetTermOrdering( R4, [ "dp", 1, "wp", [1,1,2], "lp", 2 ] );[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.3-6 SingularSetBaseRing[0m
  
  [1m[34m> SingularSetBaseRing( [0m[22m[34mR[0m[1m[34m ) _________________________________________[0mfunction
  [1m[34m> SingularBaseRing___________________________________________[0mglobal variable
  
  Here  [22m[34mR[0m  is  a  polynomial  ring.  [22m[34mSingularSetBaseRing[0m sets the base-ring in
  [1mSingular[0m  equal  to  [22m[34mR[0m.  This  ring will be also kept in [1mGAP[0m in the variable
  [22m[34mSingularBaseRing[0m.  After this assignment, all the functions of the interface
  will  work  with this ring. However, for some functions (those having rings,
  ideals,  or  modules as arguments) it is not necessary to explicitly set the
  base  ring  first,  because  in these cases the functions arguments contains
  information  about  a  ring  that  will be used as a base-ring. This will be
  specified  for  each  function  in the corresponding section of this manual.
  (Unnecessary  use  of  [22m[34mSingularSetBaseRing[0m  doesn't  harm; forgetting to use
  [22m[34mSingularSetBaseRing[0m  produces the problem described in the paragraph [1m1.7-4[0m.)
  The  results  of the computations may depend on the choice of the base-ring:
  see  an  example at [1m[34mFactorsUsingSingular[0m ([1m1.5-6[0m), in which the factorization
  of x^2 + y^2 is calculated.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The  value of [22m[34mSingularBaseRing[0m when the package is loaded is [22m[34mPolynomialRing(
  GF( 32003 ), 3 )[0m, in order to match the default base-ring of [1mSingular[0m.
  
  [1m[4m[31m1.3-7 SingularLibrary[0m
  
  [1m[34m> SingularLibrary( [0m[22m[34mstring[0m[1m[34m ) ________________________________________[0mfunction
  
  In  [1mSingular[0m  some functionality is provided by separate libraries that must
  be  explicitly  loaded  in order to be used (see the [1mSingular[0m documentation,
  chapter  ``D.  SINGULAR  libraries''),  see the example in [1m[34mSingularInterface[0m
  ([1m1.3-8[0m).
  
  The  argument  [22m[34mstring[0m is a string containing the name of a [1mSingular[0m library.
  This function makes sure that this library is loaded into [1mSingular[0m.
  
  The functions provided by the library [22m[34mring.lib[0m could be not yet supported by
  the interface.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> SingularLibrary( "general.lib" );[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.3-8 SingularInterface[0m
  
  [1m[34m> SingularInterface( [0m[22m[34msingcom, arguments, type_output[0m[1m[34m ) _____________[0mfunction
  
  The  function  [22m[34mSingularInterface[0m provides the general interface that enables
  to  apply  the  [1mSingular[0m functions to the [1mGAP[0m objects. Its arguments are the
  following:
  
  --    [22m[34msingcom[0m is a [1mSingular[0m command or function (given as a string).
  
  --    [22m[34marguments[0m  is  a list of [1mGAP[0m objects, O_1, O_2, ..., O_n, that will be
        used as arguments of [22m[34msingcom[0m (it may be the empty list). [22m[34marguments[0m may
        also  be  a string: in this case it is assumed that it contains one or
        more   [1mSingular[0m  identifiers,  or  a  [1mSingular[0m  valid  expression,  or
        something  else  meaningful for [1mSingular[0m, and it is passed to [1mSingular[0m
        without parsing or checking on the [1mGAP[0m side.
  
  --    [22m[34mtype_output[0m  is  the  data type (given as a string) in [1mSingular[0m of the
        output.   The   data   types  are  the  following  (see  the  [1mSingular[0m
        documentation,  chapter  ``4. Data types''): "bigint", "def", "ideal",
        "int",  "intmat", "intvec", "link", "list", "map", "matrix", "module",
        "number",  "poly",  "proc",  "qring",  "resolution", "ring", "string",
        "vector"  (some  of  them  were  not available in previous versions of
        [1mSingular[0m).  The  empty string "" can be used if no output is expected.
        If  in  doubt  you  can  use  "def"  (see  the [1mSingular[0m documentation,
        paragraph ``4.1 def''). Usually, in the documentation of each [1mSingular[0m
        function is given its output type.
  
  Of  course,  the  objects  in the list [22m[34marguments[0m and the [22m[34mtype_output[0m must be
  appropriate for the function [22m[34msingcom[0m: no check is done by the interface.
  
  The function [22m[34mSingularInterface[0m does the following:
  
  (1)   converts  each  object  O_1,  O_2,  ...,  O_n  in  [22m[34marguments[0m  into the
        corresponding object P_1, P_2, ..., P_n, of [1mSingular[0m,
  
  (2)   sends  to  [1mSingular[0m  the command to calculate singcom ( P_1, P_2, ...,
        P_n ),
  
  (3)   gets the output (of type [22m[34mtype_output[0m) from [1mSingular[0m,
  
  (4)   converts  it  to  the  corresponding Gap object, and returns it to the
        user.
  
  The     function     [22m[34mSingularInterface[0m     is     oriented    towards    the
  kind-of-objects/data-types, and not to the functions of [1mSingular[0m, because in
  this  way  it  is  much  more general. The user can use ``all'' the existing
  functions  of  [1mSingular[0m  and  the  interface  is not bounded to the state of
  implementation of [1mSingular[0m: future functions and user-defined functions will
  be automatically supported.
  
  The  conversion  of  objects from Gap to [1mSingular[0m and from it back to Gap is
  done  using  some  `ad  hoc' functions. Currently, the conversion of objects
  from [1mGAP[0m to [1mSingular[0m is implemented for the following types: "ideal", "int",
  "intmat",  "intvec",  "list",  "matrix", "module", "number", "poly", "ring",
  "string",  "vector".  Objects  of other types are not supported, or are even
  not yet implemented in [1mGAP[0m.
  
  The  conversion of objects from [1mSingular[0m to [1mGAP[0m is currently implemented for
  the  following  types:  "bigint", "def", "ideal", "int", "intmat", "intvec",
  "list",   "matrix",   "module",  "number",  "poly",  "proc"  (experimental),
  "string", "vector". Objects of other types are returned as strings.
  
  Before passing polynomials (or numbers, vectors, matrices, or lists of them)
  to [1mSingular[0m, it is necessary to have sent the base-ring to [1mSingular[0m with the
  function [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m), in order to ensure that [1mSingular[0m knows
  about them. This is not necessary if in the input there is a ring, an ideal,
  or  a  module  (before  the  polynomials),  because  these  objects  contain
  information  about  the  ring to be used as base-ring. All the input must be
  relative to at most one ring; furthermore, at most one object of type "ring"
  can be in the input.
  
  As SingularInterface is a rather general function, it is not guaranteed that
  it  always  works,  and  some  functions are not supported. For instance, in
  [1mSingular[0m  there  is  the  function  [22m[34mpause[0m  that  waits  until a keystroke is
  pressed;  but  the  interface  instead  waits for the [1mSingular[0m prompt before
  sending it any new keystroke, and so calling [22m[34mpause[0m would hang the interface.
  However,  the  unsupported  functions like [22m[34mpause[0m are only a few, and are not
  mathematically  useful.  SingularInterface  tries  to  block  calls to known
  unsupported functions.
  
  Some  [1mSingular[0m  functions  may  return more than one value, see the [1mSingular[0m
  documentation,  paragraph  ``6.2.7  Return type of procedures''. In order to
  use  one of these functions via [22m[34mSingularInterface[0m, the type [22m[34mtype_output[0m must
  be  "list".  The output in [1mGAP[0m will be a list containing the values returned
  by the [1mSingular[0m function.
  
  In  the  next example we compute the primary decomposition of an ideal. Note
  that for that we need to load the [1mSingular[0m library [22m[34mprimdec.lib[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> i:= IndeterminatesOfPolynomialRing(R);;[0m
    [22m[35mgap> x:= i[1];; y:= i[2];; z:= i[3];;[0m
    [22m[35mgap> f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);;[0m
    [22m[35mgap> g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);;[0m
    [22m[35mgap> I:= Ideal( R, [f,g] );;[0m
    [22m[35mgap> SingularLibrary( "primdec.lib" );[0m
    [22m[35mgap> SingularInterface( "primdecGTZ", [ I ], "def" );[0m
    [22m[35m#I  Singular output of type "list"[0m
    [22m[35m[ [ <two-sided ideal in Rationals[x,y,z], (1 generators)>,[0m
    [22m[35m      <two-sided ideal in Rationals[x,y,z], (1 generators)> ],[0m
    [22m[35m  [ <two-sided ideal in Rationals[x,y,z], (1 generators)>,[0m
    [22m[35m      <two-sided ideal in Rationals[x,y,z], (1 generators)> ],[0m
    [22m[35m  [ <two-sided ideal in Rationals[x,y,z], (2 generators)>,[0m
    [22m[35m      <two-sided ideal in Rationals[x,y,z], (2 generators)> ],[0m
    [22m[35m  [ <two-sided ideal in Rationals[x,y,z], (3 generators)>,[0m
    [22m[35m      <two-sided ideal in Rationals[x,y,z], (2 generators)> ] ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  In  the next example are calculated the first syzygy module of an ideal, and
  the  resultant of two polynomials with respect a variable. Note that in this
  case  it  is  not  necessary  to  set the base-ring with [1m[34mSingularSetBaseRing[0m
  ([1m1.3-6[0m),  in  the  first case because the input [22m[34mI[0m is of type "ideal", and in
  the  second  case  because the base-ring was already sent to [1mSingular[0m in the
  former case.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> i:= IndeterminatesOfPolynomialRing( R );;[0m
    [22m[35mgap> x:= i[1];; y:= i[2];; z:= i[3];;[0m
    [22m[35mgap> f:= 3*(x+2)^3+y;;[0m
    [22m[35mgap> g:= x+y+z;;[0m
    [22m[35mgap> I:= Ideal( R, [f,g] );;[0m
    [22m[35mgap> M := SingularInterface( "syz", [ I ], "module" );;[0m
    [22m[35mgap> GeneratorsOfLeftOperatorAdditiveGroup( M );[0m
    [22m[35m[ [ -x-y-z, 3*x^3+18*x^2+36*x+y+24 ] ][0m
    [22m[35mgap> SingularInterface( "resultant", [ f, g, z ], "poly");[0m
    [22m[35m3*x^3+18*x^2+36*x+y+24[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.3-9 SingularType[0m
  
  [1m[34m> SingularType( [0m[22m[34mobj[0m[1m[34m ) ______________________________________________[0mfunction
  
  to be written
  
  
  [1m[4m[31m1.4 Interaction with [1mSingular[1m[4m[31m at low level[0m
  
  [1m[4m[31m1.4-1 SingularCommand[0m
  
  [1m[34m> SingularCommand( [0m[22m[34mprecommand, command[0m[1m[34m ) ___________________________[0mfunction
  
  to be written
  
  [1m[4m[31m1.4-2 GapInterface[0m
  
  [1m[34m> GapInterface( [0m[22m[34mfunc, arg, out[0m[1m[34m ) ___________________________________[0mfunction
  
  to be written
  
  
  [1m[4m[31m1.5 Other mathematical functions of the package[0m
  
  [1m[4m[31m1.5-1 GroebnerBasis[0m
  
  [1m[34m> GroebnerBasis( [0m[22m[34mI[0m[1m[34m ) ______________________________________________[0moperation
  
  Here  [22m[34mI[0m  is an ideal of a polynomial ring. This function computes a Groebner
  basis  of  [22m[34mI[0m  (that  will  be  returned  as a list of polynomials). For this
  function  it  is [22m[36mnot[0m necessary to set the base-ring with [1m[34mSingularSetBaseRing[0m
  ([1m1.3-6[0m).
  
  As term ordering, [1mSingular[0m will use the value of [1m[34mTermOrdering[0m ([1m1.3-5[0m) of the
  polynomial  ring  containing  [22m[34mI[0m.  Again,  if this value is not set, then the
  degree reverse lexicographical ordering ([22m[34m"dp"[0m) will be used.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> x := R.1;; y := R.2;; z := R.3;;[0m
    [22m[35mgap> r:= [ x*y*z -x^2*z, x^2*y*z-x*y^2*z-x*y*z^2, x*y-x*z-y*z ];;[0m
    [22m[35mgap> I:= Ideal( R, r );[0m
    [22m[35m<two-sided ideal in Rationals[x,y,z], (3 generators)>[0m
    [22m[35mgap> GroebnerBasis( I );[0m
    [22m[35m[ x*y-x*z-y*z, x^2*z-x*z^2-y*z^2, x*z^3+y*z^3, -x*z^3+y^2*z^2-y*z^3 ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-2 SINGULARGBASIS[0m
  
  [1m[34m> SINGULARGBASIS_____________________________________________[0mglobal variable
  
  This  variable  is a record containing the component [22m[34mGroebnerBasis[0m. When the
  variable  SINGULARGBASIS is assigned to the [1mGAP[0m global variable [22m[34mGBASIS[0m, then
  the  computations  of  Groebner  bases via [1mGAP[0m's internal function for that,
  [1m[34mGroebnerBasis[0m ([1mReference: GroebnerBasis[0m), are done by [1mSingular[0m.
  
  [1mSingular[0m  claims  that  it  "features  one  of  the fastest and most general
  implementations  of  various  algorithms  for computing Groebner bases". The
  [1mGAP[0m's  internal  function  claims  to  be  "a  na{\"\i}ve  implementation of
  Buchberger's  algorithm  (which  is  mainly intended as a teaching tool): it
  might not be sufficient for serious problems."
  
  (Note in the following example that the Groebner bases calculated by the [1mGAP[0m
  internal  function are in general not reduced; for reduced bases see the [1mGAP[0m
  function [1m[34mReducedGroebnerBasis[0m ([1mReference: ReducedGroebnerBasis[0m).)
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, 3 );;[0m
    [22m[35mgap> i:= IndeterminatesOfPolynomialRing( R );;[0m
    [22m[35mgap> pols:= [i[1]+i[2]+i[3], i[1]*i[2]+i[1]*i[3]+i[2]*i[3], i[1]*i[2]*i[3]];;[0m
    [22m[35mgap> o:= MonomialLexOrdering();;[0m
    [22m[35mgap> GBASIS:= GAPGBASIS;;[0m
    [22m[35mgap> GroebnerBasis( pols, o ); # This is the internal GAP method.[0m
    [22m[35m[ x+y+z, x*y+x*z+y*z, x*y*z, -y^2-y*z-z^2, z^3 ][0m
    [22m[35mgap> GBASIS:= SINGULARGBASIS;;[0m
    [22m[35mgap> GroebnerBasis( pols, o ); # This uses Singular via the interface.[0m
    [22m[35m[ z^3, y^2+y*z+z^2, x+y+z ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-3 HasTrivialGroebnerBasis[0m
  
  [1m[34m> HasTrivialGroebnerBasis( [0m[22m[34mI[0m[1m[34m ) _____________________________________[0mfunction
  
  The  function  [22m[34mHasTrivialGroebnerBasis[0m returns [22m[34mtrue[0m if the Groebner basis of
  the  ideal [22m[34mI[0m is trivial, false otherwise. This function can be used if it is
  not  necessary  to  know  the Groebner basis of an ideal, but it suffices to
  know only whether it is trivial or not.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> x:= Indeterminate( Rationals, "x" : old );;[0m
    [22m[35mgap> y:= Indeterminate( Rationals, "y", [ x ] : old );;[0m
    [22m[35mgap> z:= Indeterminate( Rationals, "z", [ x, y ] : old );;[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, [ x, y, z] );;[0m
    [22m[35mgap> f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);;[0m
    [22m[35mgap> g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);;[0m
    [22m[35mgap> I:= Ideal( R, [f,g] );;[0m
    [22m[35mgap> HasTrivialGroebnerBasis( I );[0m
    [22m[35mfalse[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-4 GcdUsingSingular[0m
  
  [1m[34m> GcdUsingSingular( [0m[22m[34mpol_1, pol_2, ..., pol_n[0m[1m[34m ) _____________________[0mfunction
  [1m[34m> GcdUsingSingular( [0m[22m[34m[pol_1, pol_2, ..., pol_n][0m[1m[34m ) ___________________[0mfunction
  
  The  arguments  of  this  function  are  (possibly multivariate) polynomials
  separated  by  commas, or it is a list of polynomials. This function returns
  the  greatest  common  divisor of these polynomials. For this function it is
  [22m[36mnecessary[0m   for  the  polynomials  to  lie  in  the  base-ring,  as  set  by
  [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
    [22m[35mgap> i:= IndeterminatesOfPolynomialRing(R);;[0m
    [22m[35mgap> x:= i[1];; y:= i[2];; z:= i[3];;[0m
    [22m[35mgap> f:= (x*y-z)*(x*y*z+y^2*z+x^2*z);[0m
    [22m[35mx^3*y*z+x^2*y^2*z+x*y^3*z-x^2*z^2-x*y*z^2-y^2*z^2[0m
    [22m[35mgap> g:= (x*y-z)*(x*y*z^2+x*y^2*z+x^2*y*z);[0m
    [22m[35mx^3*y^2*z+x^2*y^3*z+x^2*y^2*z^2-x^2*y*z^2-x*y^2*z^2-x*y*z^3[0m
    [22m[35mgap> GcdUsingSingular( f, g );[0m
    [22m[35m-x*y*z+z^2[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-5 FactorsUsingSingularNC[0m
  
  [1m[34m> FactorsUsingSingularNC( [0m[22m[34mf[0m[1m[34m ) ______________________________________[0mfunction
  
  Here  [22m[34mf[0m  is  a (possibly multivariate) polynomial. This function returns the
  factorization of [22m[34mf[0m into irreducible factors. The first element in the output
  is  a constant coefficient, and the others may be monic (with respect to the
  term ordering) polynomials, as returned by [1mSingular[0m. For this function it is
  [22m[36mnecessary[0m  that  [22m[34mf[0m  lies  in  the  base-ring,  as set by [1m[34mSingularSetBaseRing[0m
  ([1m1.3-6[0m).
  
  The  function  does not check that the product of these factors gives [22m[34mf[0m (for
  that  use  [1m[34mFactorsUsingSingular[0m  ([1m1.5-6[0m)): [1mSingular[0m version 2-0-3 contains a
  bug  so  that  the  [1mSingular[0m  function  [22m[34mfactorize[0m  may  give  wrong  results
  (therefore [1mSingular[0m version at least 2-0-4 is recommended).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y","z"] : old );;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
    [22m[35mgap> i:= IndeterminatesOfPolynomialRing( R );;[0m
    [22m[35mgap> x:= i[1];; y:= i[2];; z:= i[3];;[0m
    [22m[35mgap> f:= (x*y-z)*(3*x*y*z+4*y^2*z+5*x^2*z);[0m
    [22m[35m5*x^3*y*z+3*x^2*y^2*z+4*x*y^3*z-5*x^2*z^2-3*x*y*z^2-4*y^2*z^2[0m
    [22m[35mgap> FactorsUsingSingularNC( f );[0m
    [22m[35m[ 1, -5*x^2-3*x*y-4*y^2, -x*y+z, z ][0m
    [22m[35mgap> f:= (x*y-z)*(5/3*x*y*z+4*y^2*z+6*x^2*z);[0m
    [22m[35m6*x^3*y*z+5/3*x^2*y^2*z+4*x*y^3*z-6*x^2*z^2-5/3*x*y*z^2-4*y^2*z^2[0m
    [22m[35mgap> FactorsUsingSingularNC( f );[0m
    [22m[35m[ 1/3, -18*x^2-5*x*y-12*y^2, -x*y+z, z ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-6 FactorsUsingSingular[0m
  
  [1m[34m> FactorsUsingSingular( [0m[22m[34mf[0m[1m[34m ) ________________________________________[0mfunction
  
  This does the same as [1m[34mFactorsUsingSingularNC[0m ([1m1.5-5[0m), except that on the [1mGAP[0m
  level  it  is checked that the product of these factors gives [22m[34mf[0m. Again it is
  [22m[36mnecessary[0m  that  [22m[34mf[0m  lies  in  the  base-ring,  as set by [1m[34mSingularSetBaseRing[0m
  ([1m1.3-6[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> R:= PolynomialRing( Rationals, ["x","y"] : old );;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
    [22m[35mgap> x := R.1;; y := R.2;;[0m
    [22m[35mgap> FactorsUsingSingular( x^2 + y^2 );[0m
    [22m[35m[ 1, x^2+y^2 ][0m
    [22m[35mgap> R:= PolynomialRing( GaussianRationals, ["x","y"] : old);;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
    [22m[35mgap> x := R.1;; y := R.2;;[0m
    [22m[35mgap> FactorsUsingSingular( x^2 + y^2 );[0m
    [22m[35m[ 1, x+E(4)*y, x-E(4)*y ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.5-7 GeneratorsOfInvariantRing[0m
  
  [1m[34m> GeneratorsOfInvariantRing( [0m[22m[34mR, G[0m[1m[34m ) ________________________________[0mfunction
  
  Here  [22m[34mR[0m is a polynomial ring, and [22m[34mG[0m a finite group, which is either a matrix
  group  or  a permutation group. If [22m[34mG[0m is a matrix group, then its degree must
  be  less  than  or  equal  to  the  number of indeterminates of [22m[34mR[0m. If [22m[34mG[0m is a
  permutation  group,  then its maximal moved point must be less than or equal
  to  the  number  of  indeterminates  of  [22m[34mR[0m. This function computes a list of
  generators  of  the  invariant  ring of [22m[34mG[0m, corresponding to its action on [22m[34mR[0m.
  This action is taken to be from the left.
  
  For   this   function  it  is  [22m[36mnot[0m  necessary  to  set  the  base-ring  with
  [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m).
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> m:=[[1,1,1],[0,1,1],[0,0,1]] * One( GF(3) );;[0m
    [22m[35mgap> G:= Group( [m] );;[0m
    [22m[35mgap> R:= PolynomialRing( GF(3), 3 );;[0m
    [22m[35mgap> GeneratorsOfInvariantRing( R, G );[0m
    [22m[35m[ x_3, x_1*x_3+x_2^2+x_2*x_3, x_1^3+x_1^2*x_3-x_1*x_2^2-x_1*x_2*x_3 ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m1.6 Algebraic-geometric codes functions[0m
  
  This  section  of  [1mGAP[0m's  [1msingular[0m  package  and the corresponding code were
  written  by  David  Joyner,  [34mmailto:wdj@usna.edu[0m,  (with help from Christoph
  Lossen  and  Marco  Costantini).  It  has been tested with [1mSingular[0m versrion
  2.0.x.
  
  To  start  off,  several new [1mSingular[0m commands must be loaded. The following
  command loads the necessary [1mSingular[0m and [1mGAP[0m commands, the packages [1msingular[0m
  and [1mGUAVA[0m (if not already loaded), and (re)starts [1mSingular[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> ReadPackage("singular", "contrib/agcode.g");;[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.6-1 AllPointsOnCurve[0m
  
  [1m[34m> AllPointsOnCurve( [0m[22m[34mf, F[0m[1m[34m ) _________________________________________[0mfunction
  
  Let  F  be  a  finite and prime field. The function [22m[34mAllPointsOnCurve( f, F )[0m
  computes  a  list  of  generators  of  maximal ideals representing rationals
  points on a curve X defined by f(x,y)=0.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> F:=GF(7);;[0m
    [22m[35mgap> R2:= PolynomialRing( F, 2 );;[0m
    [22m[35mgap> SetTermOrdering( R2, "lp" );; # --- the term ordering must be "lp"[0m
    [22m[35mgap> indet:= IndeterminatesOfPolynomialRing(R2);;[0m
    [22m[35mgap> x:= indet[1];; y:= indet[2];;[0m
    [22m[35mgap> f:=x^7-y^2-x;;[0m
    [22m[35mgap> AllPointsOnCurve(f,F);[0m
    [22m[35m[ [ x_1 ], [ x_1-Z(7)^0 ], [ x_1+Z(7)^4 ], [ x_1+Z(7)^5 ], [ x_1+Z(7)^0 ], [0m
    [22m[35m  [ x_1+Z(7) ], [ x_1+Z(7)^2 ] ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.6-2 AGCode[0m
  
  [1m[34m> AGCode( [0m[22m[34mf, G, D[0m[1m[34m ) ________________________________________________[0mfunction
  
  Let f be a polynomial in x,y over F=GF(p) representing plane curve X defined
  by  f(x,y)=0,  where p is a prime (prime powers are not yet supported by the
  underlying  [1mSingular[0m function). Let G, D be disjoint rational divisors on X,
  where  D  is  a  sum  of distinct points, supp(D)=P_1, ..., P_n. The AG code
  associated to f, G, D is the F defined to be the image of the evaluation map
  f  ->  (f(P_1),...,f(P_n)).  The  function  [22m[34mAGCode[0m computes a list of length
  three,  [G,  n, k], where G is a generator matrix of the AG code C, n is its
  length, and k is its dimension.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> F:=GF(7);;[0m
    [22m[35mgap> R2:= PolynomialRing( F, 2 );;[0m
    [22m[35mgap> SetTermOrdering( R2, "lp" );; # --- the term ordering must be "lp"[0m
    [22m[35mgap> SingularSetBaseRing(R2);[0m
    [22m[35mgap> indet:= IndeterminatesOfPolynomialRing(R2);;[0m
    [22m[35mgap> x:= indet[1];; y:= indet[2];;[0m
    [22m[35mgap> f:=x^7-y^2-x;;[0m
    [22m[35mgap> G:=[2,2,0,0,0,0,0]; D:=[4..8];[0m
    [22m[35m[ 2, 2, 0, 0, 0, 0, 0 ][0m
    [22m[35m[ 4 .. 8 ][0m
    [22m[35mgap> agc:=AGCode(f,G,D);[0m
    [22m[35m[ [ [ Z(7)^3, Z(7), 0*Z(7), Z(7)^4, Z(7)^5 ],[0m
    [22m[35m      [ 0*Z(7), Z(7)^4, Z(7)^0, Z(7)^5, Z(7)^3 ],[0m
    [22m[35m      [ 0*Z(7), 0*Z(7), Z(7)^3, Z(7), Z(7)^2 ] ], 5, 3 ][0m
  [22m[35m------------------------------------------------------------------[0m
  
  This  generator  matrix  can  be fed into the [1mGUAVA[0m command [1m[34mGeneratorMatCode[0m
  ([1mGUAVA:  GeneratorMatCode[0m) to create a linear code in [1mGAP[0m, which in turn can
  be  fed  into  the [1mGUAVA[0m command [1m[34mMinimumDistance[0m ([1mGUAVA: MinimumDistance[0m) to
  compute the minimum distance of the code.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> ag_mat:=agc[1];;[0m
    [22m[35mgap> C := GeneratorMatCode( ag_mat, GF(7) );[0m
    [22m[35ma linear [5,3,1..3]2 code defined by generator matrix over GF(7)[0m
    [22m[35mgap> MinimumDistance(C);[0m
    [22m[35m3[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m1.7 Troubleshooting and technical stuff[0m
  
  
  [1m[4m[31m1.7-1 Supported platforms and underlying [1mGAP[1m[4m[31m functions[0m
  
  This package has been developed mainly on a Linux platform, with [1mGAP[0m version
  4.4,  and  [1mSingular[0m version 2-0-4. A reasonable work has been done to ensure
  backward  compatibility  with  previous versions of [1mGAP[0m 4, but some features
  may  be  missing. This package has been tested also with some other versions
  of  Singular,  including 2-0-3, 2-0-5, and 2-0-6, and on other Unix systems.
  It  has been tested also on Windows, but it is reported to be slower that on
  Linux.
  
  There  is  an  extension of [1mSingular[0m, named [1mPlural[0m, which deals with certain
  noncommutative  polynomial  rings;  see  the [1mSingular[0m documentation, section
  ``7.   PLURAL''.   Currently,   [1mGAP[0m  doesn't  support  these  noncommutative
  polynomial rings. The user of the [1mSingular[0m may use the features of [1mPlural[0m by
  calling the [1mSingular[0m function [22m[34mncalgebra[0m via [22m[34mSingularInterface[0m. In this case,
  extreme care is needed, because on the [1mGAP[0m side the polynomial will still be
  commutative.
  
  For  the  low-level communication with [1mSingular[0m, the interface relies on the
  [1mGAP[0m  function  [1m[34mInputOutputLocalProcess[0m ([1mReference: InputOutputLocalProcess[0m),
  and  this  function  is  available  only  in  [1mGAP[0m  4.2  (or newer) on a Unix
  environment  or in [1mGAP[0m 4.4 (or newer) on Windows; auto-detection is used. In
  this case, [1mGAP[0m interacts with a unique continuous session of [1mSingular[0m.
  
  In  the case that the [1mGAP[0m function [22m[34mInputOutputLocalProcess[0m is not available,
  then  the  singular  interface will use the [1mGAP[0m function [1m[34mProcess[0m ([1mReference:
  Process[0m).  In  this  case  only a limited subset of the functionality of the
  interface   are   available:   for   example   [1m[34mStartSingular[0m   ([1m1.3-1[0m)   and
  [1m[34mGeneratorsOfInvariantRing[0m  ([1m1.5-7[0m)  are  not  available,  but  [1m[34mGroebnerBasis[0m
  ([1m1.5-1[0m)  is;  [1m[34mSingularInterface[0m  ([1m1.3-8[0m)  supports  less data types. In this
  case,  for  each  function  call,  a  new session of [1mSingular[0m is started and
  quitted.
  
  
  [1m[4m[31m1.7-2 How different versions of [1mGAP[1m[4m[31m display polynomial rings and polynomials[0m
  
  The  way  in which [1mGAP[0m displays polynomials has changed passing from version
  4.3  to  4.4  and the way in which [1mGAP[0m displays polynomial rings has changed
  passing from version 4.4 to 4.5.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> # GAP 4.3 or older[0m
    [22m[35mgap> R := PolynomialRing( Rationals, [ "x" ] : new );[0m
    [22m[35mPolynomialRing(..., [ x ])[0m
    [22m[35mgap> x := IndeterminatesOfPolynomialRing( R )[1];;[0m
    [22m[35mgap> x^2 + x;[0m
    [22m[35mx+x^2[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> # GAP 4.4[0m
    [22m[35mgap> R := PolynomialRing( Rationals, [ "x" ] : new );[0m
    [22m[35mPolynomialRing(..., [ x ])[0m
    [22m[35mgap> x := IndeterminatesOfPolynomialRing( R )[1];;[0m
    [22m[35mgap> x^2 + x;[0m
    [22m[35mx^2+x[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> # GAP 4.5 or newer[0m
    [22m[35mgap> R := PolynomialRing( Rationals, [ "x" ] : new );[0m
    [22m[35mRationals[x][0m
    [22m[35mgap> x := IndeterminatesOfPolynomialRing( R )[1];;[0m
    [22m[35mgap> x^2 + x;[0m
    [22m[35mx^2+x[0m
  [22m[35m------------------------------------------------------------------[0m
  
  The examples in this manual use the way of displaying of the newest [1mGAP[0m.
  
  
  [1m[4m[31m1.7-3 Test file[0m
  
  The following performs a test of the package functionality using a test file
  [1m`Reference: Test Files'[0m.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> fn := Filename( DirectoriesPackageLibrary( "singular", "tst" ), "test" );;[0m
    [22m[35mgap> ReadTest( fn );[0m
    [22m[35mtrue[0m
  [22m[35m------------------------------------------------------------------[0m
  
  
  [1m[4m[31m1.7-4 Common problems[0m
  
  A common error is forgetting to use [1m[34mSingularSetBaseRing[0m ([1m1.3-6[0m). In the next
  example, [22m[34mSingularInterface[0m works only after having used [22m[34mSingularSetBaseRing[0m.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> a:=Indeterminate( Rationals );;[0m
    [22m[35mgap> F:=AlgebraicExtension( Rationals, a^5+4*a+1 );;[0m
    [22m[35mgap> R:=PolynomialRing( F, ["x","y"] : old );;[0m
    [22m[35mgap> x := R.1;; y := R.2;;[0m
    [22m[35mgap> SingularInterface( "lead", [x^3*y+x*y+y^2], "poly" );[0m
    [22m[35mError, sorry: Singular, or the interface to Singular, or the current[0m
    [22m[35mSingularBaseRing, do not support the object x^3*y+x*y+y^2.[0m
    [22m[35mDid you remember to use 'SingularSetBaseRing' ?[0m
    [22m[35m[...][0m
    [22m[35mbrk> quit;[0m
    [22m[35mgap> SingularSetBaseRing( R );[0m
    [22m[35mgap> SingularInterface( "lead", [x^3*y+x*y+y^2], "poly" );[0m
    [22m[35mx^3*y[0m
  [22m[35m------------------------------------------------------------------[0m
  
  A  corresponding  problem  would  happen  if  the  user  works directly with
  [1mSingular[0m and forgets to define the base-ring at first.
  
  As  explained  in the [1mGAP[0m documentation [1m`Reference: Polynomials and Rational
  Functions'[0m,  given  a  ring  [22m[34mR[0m,  [1mGAP[0m  does  not  consider [22m[34mR[0m as a subset of a
  polynomial  ring  over  [22m[34mR[0m: for example the zero of [22m[34mR[0m (0) and the zero of the
  polynomial  ring  (0x^0)  are  different objects. [1mGAP[0m prints these different
  objects  in the same way, and this fact may be misleading. This is a feature
  of [1mGAP[0m independent from the package [1msingular[0m, but it is important to keep it
  in  mind,  as most of the objects used by [1mSingular[0m are polynomials, or their
  coefficients.
  
  
  [1m[4m[31m1.7-5 Errors on the [1mSingular[1m[4m[31m side[0m
  
  Errors  may occur on the [1mSingular[0m side, for instance using [1m[34mSingularInterface[0m
  ([1m1.3-8[0m)  if  the  arguments  supplied  are  not  appropriate  for the called
  function. In general, it is still an open problem to find a satisfactory way
  to handle in [1mGAP[0m the errors of this kind.
  
  At  the  moment,  when  an  error on the [1mSingular[0m side happens, [1mSingular[0m may
  print an error message on the so-called ``standard error''; this message may
  appear  on  the  screen,  but  it  is  not  logged by the [1mGAP[0m function [1m[34mLogTo[0m
  ([1mReference:  LogTo[0m).  The interface prints [22m[34mNo output from Singular[0m, and then
  the  trivial  object  (of  the  type  specified  as  the  third  argument of
  [22m[34mSingularInterface[0m) may be returned.
  
  
  [1m[4m[31m1.7-6 Sending a report[0m
  
  As every software, also this package may contain bugs. If you find a bug, or
  a  missing  feature,  or  some  other  problem,  or if you have comments and
  suggestions,  or if you need some help, write an e-mail to both the authors.
  Please use an e-mail subject that begins with ``[22m[34msingular package: [0m''. Please
  include  in  the  report  the  code  that causes the problem, so that we can
  replicate the problem.
  
  If  appropriate,  you can set [1m[34mInfoSingular[0m ([1m1.7-8[0m) to [22m[34m3[0m, to see what happens
  between  [1mGAP[0m  and  [1mSingular[0m  (but  this may give a lot of output). Note that
  [1m[34mLogTo[0m  ([1mReference:  LogTo[0m)  does  not  log  messages written directly on the
  screen by [1mSingular[0m.
  
  Every  report  about  this  package is welcome, however the probability that
  your  problem  will be fixed quickly increases if you read the text ``How to
  Report                          Bugs                          Effectively'',
  [34mhttp://www.chiark.greenend.org.uk/~sgtatham/bugs.html[0m   ,  and  send  a  bug
  report  according  to  this  text. If the report is about the manual, please
  cite also its revision:
  
  [22m[32m@(#)$Id: singular.xml,v 1.30 2006/07/23 20:05:30 gap Exp $[0m.
  
  [1m[4m[31m1.7-7 SingularReportInformation[0m
  
  [1m[34m> SingularReportInformation( [0m[22m[34m[0m[1m[34m ) ____________________________________[0mfunction
  
  The function [22m[34mSingularReportInformation[0m collects a description of the system,
  which should be included in any bug report.
  
  [22m[35m-----------------------------  Log  ------------------------------[0m
    [22m[35mgap> SingularReportInformation();[0m
    [22m[35mPkg_Version := "4.04.15";[0m
    [22m[35mGap_Version := "4.dev";[0m
    [22m[35mGap_Architecture := "i686-pc-linux-gnu-gcc";[0m
    [22m[35mGap_BytesPerVariable := 4;[0m
    [22m[35muname := "Linux 2.4.20 i686";[0m
    [22m[35mSingular_Version: := 2004;[0m
    [22m[35mSingular_Name: := "/usr/local/Singular/2-0-4/ix86-Linux/Singular";[0m
    [22m[35m[0m
    [22m[35m"Pkg_Version := \"4.04.15\";\nGap_Version := \"4.dev\";\nGap_Architecture := \[0m
    [22m[35m\"i686-pc-linux-gnu-gcc\";\nGap_BytesPerVariable := 4;\nuname := \"Linux 2.4.2\[0m
    [22m[35m0 i686\";\nSingular_Version: := 2004;\nSingular_Name: := \"/usr/local/Singular\[0m
    [22m[35m/2-0-4/ix86-Linux/Singular\";\n"[0m
  [22m[35m------------------------------------------------------------------[0m
  
  [1m[4m[31m1.7-8 InfoSingular[0m
  
  [1m[34m> InfoSingular____________________________________________________[0minfo class
  
  This is the info class [1m`Reference: Info Functions'[0m used by the interface. It
  can be set to levels 0, 1, 2, and 3. At level 0 no information is printed on
  the  screen.  At  level 1 (default) the interface prints a message about the
  [22m[34mtype_output[0m,  when  "def"  is  used in [22m[34mSingularInterface[0m, see the example at
  [1m[34mSingularInterface[0m  ([1m1.3-8[0m). At level 2, information on the activities of the
  interface  is printed (e.g., messages when a [1mSingular[0m session, or a Groebner
  basis  calculation,  is  started or terminated). At level 3 all strings that
  [1mGAP[0m  sends  to  [1mSingular[0m  are  printed, as well as all strings that [1mSingular[0m
  sends back.
  
  [22m[35m---------------------------  Example  ----------------------------[0m
    [22m[35mgap> SetInfoLevel( InfoSingular, 2 );[0m
    [22m[35mgap> G:= SymmetricGroup( 3 );;[0m
    [22m[35mgap> R:= PolynomialRing( GF(2), 3 );;[0m
    [22m[35mgap> GeneratorsOfInvariantRing( R, G );[0m
    [22m[35m#I  running SingularInterface( "invariant_ring", [ "matrix", "matrix"[0m
    [22m[35m ], "list" )...[0m
    [22m[35m#I  done SingularInterface.[0m
    [22m[35m[ x_1+x_2+x_3, x_1*x_2+x_1*x_3+x_2*x_3, x_1*x_2*x_3 ][0m
    [22m[35mgap> I:= Ideal( R, last );;[0m
    [22m[35mgap> GroebnerBasis( I );[0m
    [22m[35m#I  running GroebnerBasis...[0m
    [22m[35m#I  done GroebnerBasis.[0m
    [22m[35m[ x_1+x_2+x_3, x_2^2+x_2*x_3+x_3^2, x_3^3 ][0m
    [22m[35mgap> SetInfoLevel( InfoSingular, 1 );[0m
  [22m[35m------------------------------------------------------------------[0m
  
