
            singular: the GAP interface to Singular
===========================================================================

This is the README file for the package `singular'; a GAP interface
to the computer algebra system Singular (see
http://www.singular.uni-kl.de/).

===========================================================================

Installing `singular':

1) unpack `singular.tar.gz' in the `pkg' subdirectory of the GAP root
   directory.

2) If the Singular executable is in your search path, then it is ok: GAP
   will find it. If not, edit the file `pkg/singular/gap/singular.g': at
   the beginning of this file, the full path to the Singular executable
   on your system must be added. For instance:
   sing_exec:="/usr/local/bin/Singular";
   Alteratively, one can give this path inside a GAP session, with the
   same command.

3) It should work. From within GAP things are started with

gap> LoadPackage("singular");
true

   Use RequirePackage instead in GAP 4.x, 1 <= x <= 3.

4) The documentation is in the `doc' subdirectory.



===========================================================================


Preliminary announcement of August 2003 (and preliminary documentation):

Dear Gap developers,
this is the announcement that the experimental version of the package
"singular" has been released.

This package, written by Willem de Graaf and myself, provides an interface
to the system Singular ("SINGULAR is a Computer Algebra system for
polynomial computations with emphasis on the special needs of commutative
algebra, algebraic geometry, and singularity theory.
SINGULAR'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.
SINGULAR 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."
See http://www.singular.uni-kl.de/ . Singular is not included in the
package, but can be downloaded for free from that site.)

The package is available in the Gap cvs repository in the directory
4.0/pkg/singular.

All the warnings about the stuff in the cvs repository apply. Further,
this package can hang the Gap session (you will have to type <ctrl>-C
twice, and you will lose the content of the session, if it was not saved
with SaveWorkspace). This should not happen during normal use (please
report if it happens to you), but only with code designed to hang Gap,
such as
SingularInterface("execute", ["quit"], "def" );

This package is designed for using the Gap function
"InputOutputLocalProcess" available on Unix machines, and was tested with
Linux, Sun and Alpha, but should work partially also with "Process" on
non-Unix machines (not yet tested, reports are welcome). Auto-detection
is used.

This packages requires Gap 4.2 or newer: with Gap 4.1 "Process" is used
instead of "InputOutputLocalProcess", as the latter was not yet there;
so the same limitations of above apply. When this package is loaded with a
Gap version older than 4.4, some harmles errors "Syntax error: warning: 
unbound global variable in ..." are displayed.


At this moment the package can handle only finite fields and the
Rationals.

The documentation that comes with the package is obsolete, and may be
useless. However an "implicit documentation" is provided with the code
(the code tells what the functions do), and some examples of usage are
below.

Hints, bug reports, patches, requests of other functionalities, and so on
are welcomed. Add the output of SingularReportInformations(); to your
report.

Now the package contains some stuff about Lie algebras, but an other
package with it is planned.



# load

LoadPackage("singular");


# specify the Singular executable (not needed if Singular is in the path)

sing_exec:= "/home/wdg/Singular/2-0-3/ix86-Linux/Singular";


# let's define some Gap objects

R:=PolynomialRing( Rationals, ["x", "y", "z"]);;
gen:=GeneratorsOfLeftOperatorRingWithOne(R);;
x:=gen[1];;y:=gen[2];;z:=gen[3];;
pol1:=-3*x*z^3+x^3+x*y*z;;
pol2:=-3*x^2*z^3+x^4+x^2*y*z-3*x*z^3+x^3+x*y*z;;
pol3:=x*y+x*z+x+y+z;;
I:=Ideal( R, [ pol1, pol2, pol3] );;


# set the basering in singular (this is done automatically by the other
# functions when the arguments are rings or ideals).

SingularSetBaseRing( R );


# Let be "Singfunc" the name of a function of Singular, and GapList a list
# of Gap objects. Then the function
#
# SingularInterface( "Singfunc", GapList, type_output );
#
# will convert the objects in the list GapList info Singular objects, will
# apply Singfunc to them from within Singular, and will convert to output
# back into a Gap objects.
# The argument type_output must be one of "def",
# "ideal", "int", "intmat", "intvec", "link", "list", "map", "matrix",
# "module", "number", "poly", "proc", "qring", "resolution", "ring",
# "string", "vector", and tells to the interface the type in Singular of
# the output of Singfunc. In doubt you can use "def".
# See in the documentation of Singular the chapter "4. Data types".

SingularInterface( "jacob", [ pol1 ], "ideal" );
SingularInterface( "dim", [ I ], "int" );
SingularInterface( "std", [ I ], "ideal" );

# when the output is an ideal, use GeneratorsOfTwoSidedIdeal to get the
# generators.


# this calculates the Groebner Basis

GroebnerBasis( I );


# sometimes we need only to know whether the Groebner Basis is trivial
# (i.e. equal to the unit) or not.

HasTrivialGroebnerBasis( I );


# This loads (in Singular) the library general.lib

SingularLibrary( "general.lib");


# the gcd of polynomials (also multivariate ones)

GcdUsingSingular( pol1, pol2, pol3 );


# factorizations of polynomials (also multivariate ones)

FactorsUsingSingularNC( pol1 );


# this checks also the output of Singular

FactorsUsingSingular( pol2 );


# As i/o streams do consume system resources, and only a limited number
# can be open at any time, it is wise to close Singular when it will be
# not needed anymore.

CloseSingular();

# Singular will start again when one of the functions above is called, or
# by StartSingular();

# Not that the time used by Singular is not reported by the function 
# Runtimes(); until the Singular session is terminated. The cpu time resp. 
# the wall clock time used by a singular session can by get with:

Int( SingularCommand( "", "timer" ) );
Int( SingularCommand( "", "rtimer" ) );



Greetings,
Marco Costantini

===========================================================================

Addendum

** Reserved chars or strings:

Don't use the following chars or strings with the interface:

@	marks the end of the Singular output

'	delimits the useful Singular output 

$	the interface discards all the '$' sent to Singular

GAP_...	all the names of the Singular variables defined by the interface 
	begin with "GAP_": don't use these names for your variables




** Type conversions:

type    Gap -> Singular                 Singular -> Gap
        * := sets basering              U := only on Unix

def     (no sense)                      U (ask Singular for the type)
ideal   *ParseGapIdealToSingIdeal       done
int     ParseToSingInt                  Int
intmat  done                            U done
intvec  done                            done
link                                    U (done)
list    done                            U done
map
matrix  done                            U done
module
number  ParseGapNumberToSingNumber      [ ParseSingNumberToGapNumber, Rat ]
poly    ParseGapPolyToSingPoly          ParseSingPolyToGapPoly
proc                                    U ParseSingProcToGapFunction
qring
resolution
ring    *ParseGapRingToSingRing         (planned)
string  done                            x->x;
vector  done                            (planned)

