This is sing.htm, produced by makeinfo version 4.13 from singular.texi.
This is the texinfo file describing Singular (version 2-0-4)
File: sing.htm, Node: Top, Next: Preface, Prev: (dir), Up: (dir)

A Computer Algebra System for Polynomial Computations
HTML User Manual for Singular Version
2-0-4, October 2002
University of Kaiserslautern
Department of Mathematics
Centre for Computer Algebra
* Menu:
* Preface::
* Introduction::
* General concepts::
* Data types::
* Functions and system variables::
* Tricks and pitfalls::
* Examples::
* Polynomial data::
* Mathematical background::
* SINGULAR libraries::
* Release Notes::
* Index::
Table of Contents
About this document
File: sing.htm, Node: Preface, Next: Introduction, Prev: Top, Up: Top
1 Preface
*********
SINGULAR version 2-0-4
University of Kaiserslautern
Department of Mathematics and Centre for Computer Algebra
Authors: G.-M. Greuel, G. Pfister, H. Schoenemann
Copyright (C) 1986-2003
*NOTICE*
This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation ( version 2 of the License ); with the
following additional restrictions (which override any conflicting
restrictions in the GPL):
The following software used with SINGULAR have their own copyright: the
omalloc library, the readline library, the Gnu Multiple Precision
Library (GMP), NTL: A Library for doing Number Theory (NTL), the Multi
Protocol library (MP), the Singular-Factory library, the Singular-libfac
library, and, for the Windows distributions the Cygwin DLL and the
Cygwin tools (Cygwin), and the XEmacs editor (XEmacs).
Their copyrights and licenses can be found in the accompanying files
which are distributed along with these packages.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA (see GPL)
Please send any comments or bug reports to
.
Please register yourself as a SINGULAR user by using the registration
form on the SINGULAR homepage
`http://www.singular.uni-kl.de'. If for some reason you cannot access
the registration form, you can also register by sending an email to
with subject line `register' and body
containing the following data: your name, email address,
organisation, country and platform(s).
If you use Singular or parts thereof in a project and/or publish results
that were partly obtained using SINGULAR, we ask you to cite SINGULAR
and inform us thereof - see
`http://www.singular.uni-kl.de/how_to_cite.html', for information on how
to cite Singular.
Availability
============
The latest information about SINGULAR is always available from
`http://www.singular.uni-kl.de'. The program SINGULAR and the above
mentioned parts are available via anonymous ftp through the following
addresses:
GMP, libreadline
(C) Free Software Foundation
`ftp://ftp.gnu.ai.mit.edu' or its mirrors
MP
(C) Gray/Kajler/Wang, Kent State University
`http://www.symbolicnet.org/areas/protocols/mp.html'
NTL
(C) Victor Shoup
`ftp://www.shoup.net'
Singular-Factory
(C) Greuel/Stobbe, University of Kaiserslautern:
`ftp://www.mathematik.uni-kl.de/pub/Math/Singular/Factory'
Singular-libfac
(C) Messollen, University of Saarbru"cken:
`ftp://www.mathematik.uni-kl.de/pub/Math/Singular/Libfac'
SINGULAR binaries and sources
`ftp://www.mathematik.uni-kl.de/pub/Math/Singular/' or via a WWW
browser from
`http://www.mathematik.uni-kl.de/ftp/pub/Math/Singular/'
Cygwin
`http://www.cygwin.com/'
Xemacs
`http://www.xemacs.org'
Acknowledgements
================
The development of SINGULAR is directed and coordinated by Gert-Martin
Greuel, Gerhard Pfister, and Hans Scho"nemann.
Currently, the SINGULAR team has the following members: Olaf Bachmann,
Anne Fru"bis-Kru"ger, Thomas Keilen, Kai Kru"ger, Christoph Lossen,
Viktor Levandovskyy, Wilfred Pohl, Mathias Schulze, Eric Westenberger,
and Tim Wichmann.
Past members of the SINGULAR team are: Hubert Grassmann, Wolfgang
Neumann, Jens Schmidt, Ru"diger Stobbe.
Further contributions to SINGULAR were made by: Thomas Bayer, Isabelle
Bermejo, Stephan Endrass, Jose Ignacio Farran Martin, Wolfram Decker,
Philippe Gimenez, Christian Gorzel, Agnes Heydtmann, Dietmar Hillebrand,
Tobias Hirsch, Martin Lamm, Bernd Martin, Michael Messollen, Thomas
Nu"ssler, Moritz Wenk.
We should like to acknowledge the financial support given by the
Volkswagen-Stiftung, the Deutsche Forschungsgemeinschaft and the
Stiftung fu"r Innovation des Landes Rheinland-Pfalz to the SINGULAR
project.
File: sing.htm, Node: Introduction, Next: General concepts, Prev: Preface, Up: Top
2 Introduction
**************
* Menu:
* Background::
* How to use this manual::
* Getting started::
File: sing.htm, Node: Background, Next: How to use this manual, Prev: Introduction, Up: Introduction
2.1 Background
==============
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.
Based on an easy-to-use interactive shell and a C-like programming
language, SINGULAR's internal functionality is augmented and
user-extendible by libraries written in the SINGULAR programming
language. A general and efficient implementation of communication links
allows SINGULAR to make its functionality available to other programs.
SINGULAR'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. Schoenemann; Humboldt-Universitaet H.\ Sch\"onemann; Humboldt-Universit\"at
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 SINGULAR's "home-town" moved to Kaiserslautern, a
general standard basis algorithm was implemented in C and SINGULAR 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 SINGULAR 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.)
For the highlights of the new SINGULAR version 2-0-4 see *note News and
changes::.
File: sing.htm, Node: How to use this manual, Next: Getting started, Prev: Background, Up: Introduction
2.2 How to use this manual
==========================
For the impatient user
......................
In *note Getting started::, some simple examples explain how to use
SINGULAR in a step-by-step manner.
*note Examples:: should come next for real learning-by-doing or to
quickly solve some given mathematical problems without dwelling too
deeply into SINGULAR. This chapter contains a lot of real-life examples
and detailed instructions and explanations on how to solve mathematical
problems using SINGULAR.
For the systematic user
.......................
In *note General concepts::, all basic concepts which are important to
use and to understand SINGULAR are developed. But even for users
preferring the systematic approach it will be helpful to have a look at
the examples in *note Getting started::, every now and then. The topics
in the chapter are organized more or less in the order the novice user
has to deal with them.
* In *note Interactive use::, and its subsections there are some
words on entering and exiting SINGULAR, followed by a number of
other aspects concerning the interactive user-interface.
* To do anything more than trivial integer computations, one needs to
define a basering in SINGULAR. This is explained in detail in
*note Rings and orderings::.
* An overview of the algorithms implemented in the kernel of SINGULAR
is given in *note Implemented algorithms::.
* In *note The SINGULAR language::, language specific concepts are
introduced such as the notions of names and objects, data types and
conversion between them, etc.
* In *note Input and output::, SINGULAR's mechanisms to store and
retrieve data are discussed.
* The more complex concepts of procedures and libraries as well as
tools to debug them are considered in the following sections: *note
Procedures::, *note Libraries::, and *note Debugging tools::.
*note Data types::, is a complete treatment for SINGULAR's data types
where each section corresponds to one data type, alphabetically sorted.
For each data type, its purpose is explained, the syntax of its
declaration is given, and related operations and functions are listed.
Examples illustrate its usage.
*note Functions and system variables::, is an alphabetically ordered
reference list of all of SINGULAR's functions, control structures, and
system variables. Each entry includes a description of the syntax and
semantics of the item being explained as well as one or more examples on
how to use it.
Miscellaneous
.............
*note Tricks and pitfalls::, is a loose collection of limitations and
features which may be unexpected by those who expect the SINGULAR
language to be an exact copy of the C programming language or of some
Computer Algebra system's languages. But some mathematical hints are
collected there, as well.
*note Mathematical background::, introduces some of the mathematical
notions and definitions used throughout this manual. For example, if in
doubt what exactly SINGULAR means by a "negative degree reverse
lexicographical ordering" one should refer to this chapter.
*note SINGULAR libraries::, lists the libraries which come with SINGULAR
and the functions contained in them, respectively.
Typographical conventions
.........................
Throughout this manual, the following typographical conventions are
adopted:
* text in `typewriter' denotes SINGULAR input and output as well as
reserved names:
The basering can be set using the command `setring'.
* the arrow ==> denotes SINGULAR output:
`poly p=x+y+z;'
`p*p;'
`==> x2+2xy+y2+2xz+2yz+z2'
* square brackets are used to denote parts of syntax descriptions
which are optional:
[optional_text] required_text
* keys are denoted using typewriter, for example:
`N' (press the key `N' to get to the next node in help mode)
`RETURN' (press `RETURN' to finish an input line)
`CTRL-P' (press control key together with the key `P' to get the
previous input line)
File: sing.htm, Node: Getting started, Prev: How to use this manual, Up: Introduction
2.3 Getting started
===================
SINGULAR is a special purpose system for polynomial computations. Hence,
most of the powerful computations in SINGULAR require the prior
definition of a ring. Most important rings are polynomial rings over a
field, localizations hereof, or quotient rings of such rings modulo an
ideal. However, some simple computations with integers (machine integers
of limited size) and manipulations of strings are available without a
ring.
* Menu:
* First steps::
* Rings and standard bases::
* Procedures and libraries::
* Change of rings::
* Modules and their annihilator::
* Resolution::
File: sing.htm, Node: First steps, Next: Rings and standard bases, Prev: Getting started, Up: Getting started
2.3.1 First steps
-----------------
Once SINGULAR is started, it awaits an input after the prompt `>'.
Every statement has to be terminated by `;' .
37+5;
==> 42
All objects have a type, e.g., integer variables are defined by the word
`int'. An assignment is done by the symbol `=' .
int k = 2;
Test for equality resp. inequality is done using `==' resp. `!=' (or
`<>'), where `0' represents the boolean value FALSE, any other value
represents TRUE.
k == 2;
==> 1
k != 2;
==> 0
The value of an object is displayed by simply typing its name.
k;
==> 2
On the other hand the output is suppressed if an assignment is made.
int j;
j = k+1;
The last displayed (!) result is always available with the special
symbol `_' .
2*_; // the value from k displayed above
==> 4
Text starting with `//' denotes a comment and is ignored in
calculations, as seen in the previous example. Furthermore SINGULAR
maintains a history of the previous lines of input, which may be
accessed by `CTRL-P' (previous) and `CTRL-N' (next) or the arrows on the
keyboard. Note that the history is not available on Macintosh systems.
The whole manual is available online by typing the command `help;' .
Explanation on single topics, e.g., on `intmat', which defines a matrix
of integers, are obtained by
help intmat;
This shows the text of *note intmat::, in the printed manual.
Next, we define a $3 \times 3$
3 x 3 matrix of integers and initialize it with some values, row by row
from left to right:
intmat m[3][3] = 1,2,3,4,5,6,7,8,9;
A single matrix entry may be selected and changed using square brackets
`[' and `]'.
m[1,2]=0;
m;
==> 1,0,3,
==> 4,5,6,
==> 7,8,9
To calculate the trace of this matrix, we use a `for' loop. The curly
brackets `{' and `}' denote the beginning resp. end of a block. If you
define a variable without giving an initial value, as the variable `tr'
in the example below, SINGULAR assigns a default value for the specific
type. In this case, the default value for integers is `0'. Note that the
integer variable `j' has already been defined above.
int tr;
for ( j=1; j <= 3; j++ ) { tr=tr + m[j,j]; }
tr;
==> 15
Variables of type string can also be defined and used without a ring
being active. Strings are delimited by `"' (double quotes). They may be
used to comment the output of a computation or to give it a nice format.
If a string contains valid SINGULAR commands, it can be executed using
the function `execute'. The result is the same as if the commands would
have been written on the command line. This feature is especially useful
to define new rings inside procedures.
"example for strings:";
==> example for strings:
string s="The element of m ";
s = s + "at position [2,3] is:"; // concatenation of strings by +
s , m[2,3] , ".";
==> The element of m at position [2,3] is: 6 .
s="m[2,1]=0; m;";
execute(s);
==> 1,0,3,
==> 0,5,6,
==> 7,8,9
This example shows that expressions can be separated by `,' (comma)
giving a list of expressions. SINGULAR evaluates each expression in this
list and prints all results separated by spaces.
File: sing.htm, Node: Rings and standard bases, Next: Procedures and libraries, Prev: First steps, Up: Getting started
2.3.2 Rings and standard bases
------------------------------
To calculate with objects as ideals, matrices, modules, and polynomial
vectors, a ring has to be defined first.
ring r = 0,(x,y,z),dp;
The definition of a ring consists of three parts: the first part
determines the ground field, the second part determines the names of the
ring variables, and the third part determines the monomial ordering to
be used. So the example above declares a polynomial ring called `r' with
a ground field of characteristic 0 $0$
(i.e., the rational numbers) and ring variables called `x', `y', and
`z'. The `dp' at the end means that the degree reverse lexicographical
ordering should be used.
Other ring declarations:
`ring r1=32003,(x,y,z),dp;'
characteristic 32003, variables `x', `y', and `z' and ordering
`dp'.
`ring r2=32003,(a,b,c,d),lp;'
characteristic 32003, variable names `a', `b', `c', `d' and
lexicographical ordering.
`ring r3=7,(x(1..10)),ds;'
characteristic 7, variable names `x(1)',...,`x(10)', negative
degree reverse lexicographical ordering (`ds').
`ring r4=(0,a),(mu,nu),lp;'
transcendental extension of Q $Q$
by a $a$
, variable names `mu' and `nu'.
`ring r5=real,(a,b),lp;'
floating point numbers (single machine precision), variable names
`a' and `b'.
`ring r6=(real,50),(a,b),lp;'
floating point numbers with extended precision of 50 digits,
variable names `a' and `b'.
`ring r7=(complex,50,i),(a,b),lp;'
complex floating point numbers with extended precision of 50 digits
and imaginary unit `i', variable names `a' and `b'.
Typing the name of a ring prints its definition. The example below shows
that the default ring in SINGULAR is Z/32003[x,y,z] $Z/32003[x,y,z]$
with degree reverse lexicographical ordering:
ring r8;
r8;
==> // characteristic : 32003
==> // number of vars : 3
==> // block 1 : ordering dp
==> // : names x y z
==> // block 2 : ordering C
Defining a ring makes this ring the current active basering, so each
ring definition above switches to a new basering. The concept of rings
in SINGULAR is discussed in detail in *note Rings and orderings::.
The basering is now `r8'. Since we want to calculate in the ring `r',
which we defined first, we have to switch back to it. This can be done
using the function `setring':
setring r;
Once a ring is active, we can define polynomials. A monomial, say $x^3$
x^3 may be entered in two ways: either using the power operator `^',
saying `x^3', or in short-hand notation without operator, saying `x3'.
Note that the short-hand notation is forbidden if the name of the ring
variable consists of more than one character. Note, that SINGULAR always
expands brackets and automatically sorts the terms with respect to the
monomial ordering of the basering.
poly f = x3+y3+(x-y)*x2y2+z2;
f;
==> x3y2-x2y3+x3+y3+z2
The command `size' determines in general the number of "single entries"
in an object. In particular, for polynomials, `size' determines the
number of monomials.
size(f);
==> 5
A natural question is to ask if a point, e.g., `(x,y,z)=(1,2,0)', lies
on the variety defined by the polynomials `f' and `g'. For this we
define an ideal generated by both polynomials, substitute the
coordinates of the point for the ring variables, and check if the result
is zero:
poly g = f^2 *(2x-y);
ideal I = f,g;
ideal J = subst(I,var(1),1);
J = subst(J,var(2),2);
J = subst(J,var(3),0);
J;
==> J[1]=5
==> J[2]=0
Since the result is not zero, the point `(1,2,0)' does not lie on the
variety `V(f,g)'.
Another question is to decide whether some function vanishes on a
variety, or in algebraic terms if a polynomial is contained in a given
ideal. For this we calculate a standard basis using the command
`groebner' and afterwards reduce the polynomial with respect to this
standard basis.
ideal sI = groebner(f);
reduce(g,sI);
==> 0
As the result is `0' the polynomial `g' belongs to the ideal defined by
`f'.
The function `groebner', like many other functions in SINGULAR, prints a
protocol during calculations, if desired. The command `option(prot);'
enables protocolling whereas `option(noprot);' turns it off. *note
option::, explains the meaning of the different symbols printed during
calculations.
The command `kbase' calculates a basis of the polynomial ring modulo an
ideal, if the quotient ring is finite dimensional. As an example we
calculate the Milnor number of a hypersurface singularity in the global
and local case. This is the vector space dimension of the polynomial
ring modulo the Jacobian ideal in the global case resp. of the power
series ring modulo the Jacobian ideal in the local case. *Note Critical
points::, for a detailed explanation.
The Jacobian ideal is obtained with the command `jacob'.
ideal J = jacob(f);
==> // ** redefining J **
J;
==> J[1]=3x2y2-2xy3+3x2
==> J[2]=2x3y-3x2y2+3y2
==> J[3]=2z
SINGULAR prints the line `// ** redefining J **'. This indicates that we
have previously defined a variable with name `J' of type ideal (see
above).
To obtain a representing set of the quotient vector space we first
calculate a standard basis, then we apply the function `kbase' to this
standard basis.
J = groebner(J);
ideal K = kbase(J);
K;
==> K[1]=y4
==> K[2]=xy3
==> K[3]=y3
==> K[4]=xy2
==> K[5]=y2
==> K[6]=x2y
==> K[7]=xy
==> K[8]=y
==> K[9]=x3
==> K[10]=x2
==> K[11]=x
==> K[12]=1
Then
size(K);
==> 12
gives the desired vector space dimension $K[x,y,z]/\hbox{\rm jacob}(f)$.
K[x,y,z]/jacob(f). As in SINGULAR the functions may take the input
directly from earlier calculations, the whole sequence of commands may
be written in one single statement.
size(kbase(groebner(jacob(f))));
==> 12
When we are not interested in a basis of the quotient vector space, but
only in the resulting dimension we may even use the command `vdim' and
write:
vdim(groebner(jacob(f)));
==> 12
File: sing.htm, Node: Procedures and libraries, Next: Change of rings, Prev: Rings and standard bases, Up: Getting started
2.3.3 Procedures and libraries
------------------------------
SINGULAR offers a comfortable programming language, with a syntax close
to C. So it is possible to define procedures which collect several
commands to a new one. Procedures are defined with the keyword `proc'
followed by a name and an optional parameter list with specified types.
Finally, a procedure may return values using the command `return'.
Define the following procedure called `Milnor':
proc Milnor (poly h)
{
return(vdim(groebner(jacob(h))));
}
Note: if you have entered the first line of the procedure and pressed
`RETURN', SINGULAR prints the prompt `.' (dot) instead of the usual
prompt `>' . This shows that the input is incomplete and SINGULAR
expects more lines. After typing the closing curly bracket, SINGULAR
prints the usual prompt indicating that the input is now complete.
Then call the procedure:
Milnor(f);
==> 12
Note that the result may depend on the basering as we will see in the
next chapter.
The distribution of SINGULAR contains several libraries, each of which
is a collection of useful procedures based on the kernel commands, which
extend the functionality of SINGULAR. The command `help "all.lib";'
lists all libraries together with a one-line explanation.
One of these libraries is `sing.lib' which already contains a procedure
called `milnor' to calculate the Milnor number not only for
hypersurfaces but more generally for complete intersection
singularities.
Libraries are loaded with the command `LIB'. Some additional information
during the process of loading is displayed on the screen, which we omit
here.
LIB "sing.lib";
As all input in SINGULAR is case sensitive, there is no conflict with
the previously defined procedure `Milnor', but the result is the same.
milnor(f);
==> 12
The procedures in a library have a help part which is displayed by
typing
help milnor;
as well as some examples, which are executed by
example milnor;
Likewise, the library itself has a help part, to show a list of all the
functions available for the user which are contained in the library.
help sing.lib;
The output of the help commands is omitted here.
File: sing.htm, Node: Change of rings, Next: Modules and their annihilator, Prev: Procedures and libraries, Up: Getting started
2.3.4 Change of rings
---------------------
To calculate the local Milnor number we have to do the calculation with
the same commands in a ring with local ordering. Define the
localization of the polynomial ring at the origin (*note Polynomial
data::, and *note Mathematical background::).
ring rl = 0,(x,y,z),ds;
This ordering determines the standard basis which will be calculated.
Fetch the polynomial defined in the ring `r' into this new ring, thus
avoiding retyping the input.
poly f = fetch(r,f);
f;
==> z2+x3+y3+x3y2-x2y3
Instead of `fetch' we can use the function `imap' which is more general
but less efficient. The most general way to fetch data from one ring to
another is to use maps, this will be explained in *note map::.
In this ring the terms are ordered by increasing exponents. The local
Milnor number is now
Milnor(f);
==> 4
This shows that `f' has outside the origin in affine 3-space
singularities with local Milnor number adding up to $12-4=8$.
12-4=8. Using global and local orderings as above is a convenient way
to check whether a variety has singularities outside the origin.
The command `jacob' applied twice gives the Hessian of `f', a 3x3 -
matrix.
matrix H = jacob(jacob(f));
H;
==> H[1,1]=6x+6xy2-2y3
==> H[1,2]=6x2y-6xy2
==> H[1,3]=0
==> H[2,1]=6x2y-6xy2
==> H[2,2]=6y+2x3-6x2y
==> H[2,3]=0
==> H[3,1]=0
==> H[3,2]=0
==> H[3,3]=2
The `print' command displays the matrix in a nicer form.
print(H);
==> 6x+6xy2-2y3,6x2y-6xy2, 0,
==> 6x2y-6xy2, 6y+2x3-6x2y,0,
==> 0, 0, 2
We may calculate the determinant and (the ideal generated by all) minors
of a given size.
det(H);
==> 72xy+24x4-72x3y+72xy3-24y4-48x4y2+64x3y3-48x2y4
minor(H,1); // the 1x1 - minors
==> _[1]=2
==> _[2]=6y+2x3-6x2y
==> _[3]=6x2y-6xy2
==> _[4]=6x2y-6xy2
==> _[5]=6x+6xy2-2y3
The algorithm of the standard basis computations may be affected by the
command `option'. For example, a reduced standard basis of the ideal
generated by the $1 \times 1$-minors
1 x 1 - minors of H is obtained in the following way:
option(redSB);
groebner(minor(H,1));
==> _[1]=1
This shows that 1 is contained in the ideal of the $1 \times 1$-minors,
1 x 1 - minors, hence the corresponding variety is empty.
File: sing.htm, Node: Modules and their annihilator, Next: Resolution, Prev: Change of rings, Up: Getting started
2.3.5 Modules and their annihilator
-----------------------------------
Now we shall give three more advanced examples.
SINGULAR is able to handle modules over all the rings, which can be
defined as a basering. A free module of rank `n' is defined as follows:
ring rr;
int n = 4;
freemodule(4);
==> _[1]=gen(1)
==> _[2]=gen(2)
==> _[3]=gen(3)
==> _[4]=gen(4)
typeof(_);
==> module
print(freemodule(4));
==> 1,0,0,0,
==> 0,1,0,0,
==> 0,0,1,0,
==> 0,0,0,1
To define a module, we give a list of vectors generating a submodule of
a free module. Then this set of vectors may be identified with the
columns of a matrix. For that reason in SINGULAR matrices and modules
may be interchanged. However, the representation is different (modules
may be considered as sparse represented matrices).
ring r =0,(x,y,z),dp;
module MD = [x,0,x],[y,z,-y],[0,z,-2y];
matrix MM = MD;
print(MM);
==> x,y,0,
==> 0,z,z,
==> x,-y,-2y
However the submodule MD $MD$
may also be considered as the module of relations of the factor module $r^3/MD$.
r^3/MD. In this way, SINGULAR can treat arbitrary finitely generated
modules over the basering (*note Representation of mathematical
objects::).
In order to get the module of relations of MD $MD$
, we use the command `syz'.
syz(MD);
==> _[1]=x*gen(3)-x*gen(2)+y*gen(1)
We want to calculate, as an application, the annihilator of a given
module. Let $M = r^3/U$,
M = r^3/U, where U is our defining module of relations for the module $M$.
M.
module U = [z3,xy2,x3],[yz2,1,xy5z+z3],[y2z,0,x3],[xyz+x2,y2,0],[xyz,x2y,1];
Then, by definition, the annihilator of M is the ideal $\hbox{ann}(M) = \{a \mid aM = 0 \}$
ann(M) = {a | aM = 0 } which is by the description of M the same as $\{ a \mid ar^3 \in U \}$.
{ a | ar^3 contained in U}. Hence we have to calculate the quotient $U \colon r^3 $.
U:r^3. The rank of the free module is determined by the choice of U and
is the number of rows of the corresponding matrix. This may be
determined by the function `nrows'. All we have to do now is the
following:
quotient(U,freemodule(nrows(U)));
The result is too big to be shown here.
File: sing.htm, Node: Resolution, Prev: Modules and their annihilator, Up: Getting started
2.3.6 Resolution
----------------
There are several commands in SINGULAR for computing free resolutions.
The most general command is `res(... ,n)' which determines heuristically
what method to use for the given problem. It computes the free
resolution up to the length n $n$
, where n=0 $n=0$
corresponds to the full resolution.
Here we use the possibility to inspect the calculation process using the
option `prot'.
ring R; // the default ring in char 32003
R;
==> // characteristic : 32003
==> // number of vars : 3
==> // block 1 : ordering dp
==> // : names x y z
==> // block 2 : ordering C
ideal I = x4+x3y+x2yz,x2y2+xy2z+y2z2,x2z2+2xz3,2x2z2+xyz2;
option(prot);
resolution rs = res(I,0);
==> using lres
==> 4(m0)4(m1).5(m1)g.g6(m1)...6(m2)..
Disable this protocol with
option(noprot);
When we enter the name of the calculated resolution, we get a pictorial
description of the minimized resolution where the exponents denote the
rank of the free modules. Note that the calculated resolution itself may
not yet be minimal.
rs;
==> 1 4 5 2 0
==>R <-- R <-- R <-- R <-- R
==>
==>0 1 2 3 4
print(betti(rs),"betti");
==> 0 1 2 3
==> ------------------------------
==> 0: 1 - - -
==> 1: - - - -
==> 2: - - - -
==> 3: - 4 1 -
==> 4: - - 1 -
==> 5: - - 3 2
==> ------------------------------
==> total: 1 4 5 2
In order to minimize the resolution, that is to calculate the maps of
the minimal free resolution, we use the command `minres':
rs=minres(rs);
A single module in this resolution is obtained (as usual) with the
brackets `[' and `]'. The `print' command can be used to display a
module in a more readable format:
print(rs[3]);
==> z3, -xyz-y2z-4xz2+16z3,
==> 0, -y2,
==> -y+4z,48z,
==> x+2z, 48z,
==> 0, x+y-z
In this case, the output is to be interpreted as follows: the 3rd syzygy
module of R/I, `rs[3]', is the rank-2-submodule of $R^5$
R^5 generated by the vectors $(z^3,0,-y+4z,x+2z,0)$ and $(-xyz-y^2z-4xz^2+16z^3,-y^2,48z,48z,x+y-z)$.
(z^3,0,-y+4z,x+2z,0) and (-xyz-y^2z-4xz^2+16z^3,-y^2,48z,48z,x+y-z).
File: sing.htm, Node: General concepts, Next: Data types, Prev: Introduction, Up: Top
3 General concepts
******************
* Menu:
* Interactive use::
* Emacs user interface::
* Rings and orderings::
* Implemented algorithms::
* The SINGULAR language::
* Input and output::
* Procedures::
* Libraries::
* Guidelines for writing a library::
* Debugging tools::
File: sing.htm, Node: Interactive use, Next: Emacs user interface, Prev: General concepts, Up: General concepts
3.1 Interactive use
===================
In this section, aspects of interactive use are discussed. This
includes how to enter and exit SINGULAR, how to interpret its prompt,
how to get the online help, and so on.
There are a few important notes which one should not forget:
* every command has to be terminated by a `;' (semicolon) followed by
a
* the online help is accessible by means of the `help' function
* Menu:
* How to enter and exit::
* The SINGULAR prompt::
* The online help system::
* Interrupting SINGULAR::
* Editing input::
* Command line options::
* Startup sequence::
File: sing.htm, Node: How to enter and exit, Next: The SINGULAR prompt, Prev: Interactive use, Up: Interactive use
3.1.1 How to enter and exit
---------------------------
SINGULAR can either be run in ASCII-terminal or within Emacs.
To start SINGULAR in its ASCII-terminal user interface, enter
`Singular' at the system prompt. The SINGULAR banner appears which,
among others, reports the version and the compilation date.
To start SINGULAR in its Emacs user interface, either enter `ESingular'
at the system prompt, or type `M-x singular' within a running Emacs
(provided you have loaded the file `singular.el' in your running Emacs,
see *note Running SINGULAR under Emacs:: for details).
Generally, we recommend to use SINGULAR in its Emacs interface, since
this offers many more features and is more convenient to use than the
ASCII-terminal interface (*note Emacs user interface::).
To exit SINGULAR type `quit;', `exit;' or `$' (or, when running within
Emacs preferably type `C-c $').
SINGULAR and `ESingular' may also be started with command line options
and with filenames as arguments. More generally, the synopsis of
SINGULAR is
Singular [options] [file1 [file2 ...]]
ESingular [options] [file1 [file2 ...]]
*Note Command line options::, *note Startup sequence::, *note Running
SINGULAR under Emacs::.
File: sing.htm, Node: The SINGULAR prompt, Next: The online help system, Prev: How to enter and exit, Up: Interactive use
3.1.2 The SINGULAR prompt
-------------------------
The SINGULAR prompt `>' (larger than) asks the user for input of
commands. The "continuation" prompt `.' (period) asks the user for
input of missing parts of a command (remember the semicolon at the end
of every command).
SINGULAR does not interpret the semicolon as the end of a command if it
occurs inside a string. Also, SINGULAR waits for blocks (sequences of
commands enclosed in curly brackets) to be closed before prompting with
`>' for more commands. Thus, if SINGULAR does not respond with its
regular prompt after typing a semicolon it may wait for a `"' or a `}'
first.
Additional semicolons will not harm SINGULAR since they are interpreted
as empty statements.
File: sing.htm, Node: The online help system, Next: Interrupting SINGULAR, Prev: The SINGULAR prompt, Up: Interactive use
3.1.3 The online help system
----------------------------
The online help system is invoked with the `help' command. `?' may be
used as a synonym for `help'. Simply typing `help;' displays the "top"
of the help system (i.e., the title page of the SINGULAR manual) which
offers a short table of contents. Typing `help' topic`;' shows the
available documentation on topic. Here, topic may be either a function
name or, more generally, any index entry of the SINGULAR manual.
Furthermore, topic may contain wildcard characters. *Note help::, for
more information.
Online help information can be displayed in various help browsers. The
following table lists a summary of the supported browsers. See below for
more details about particular browsers.
*Browser* *Platform* *Description*
html Windows displays html version of manual in your
default html browser
winhlp Windows displays Windows help (.hlp) version of
manual
netscape Unix, uses `netscape' to display html version
Windows of manual
tkinfo Unix uses the `tkinfo' program to display
texinfo version of manual
xinfo Unix, uses the `info' program to display
Windows texinfo version of manual in an extra
`xterm'
info Unix, uses the `info' program to display
Windows texinfo version of manual
builtin all simply outputs the help information in
plain ASCII format
emacs Unix, when running SINGULAR within (X)emacs,
Windows display help in (X)emacs info buffer.
dummy all displays error message about no available
help browser
The browser which is used to display the help information, can be either
set at startup time with the command line option (*note Command line
options::)
--brower=
or with the SINGULAR command (*note system::)
system("--browser", );
The SINGULAR command
system("browsers");
lists all available browsers and the command
system("--browser");
returns the currently used browser.
If no browser is explicitly set by the user, then the first (w.r.t. the
order of the browsers in the table above) available browser is chosen.
In other words, the default browser is `netscape' for Unix platforms,
and `html' for Windows, unless your local set-up does not allow to run
it.
The `.singularrc' (*note Startup sequence::) file is a good place to set
your default browser. Recall that if a file `$HOME/.singularrc' exists
on your system, then the content of this file is executed before the
first user input. Hence, putting
if (system("version") >= 1306) // keep backwards-compatibility
{
if (! system("--emacs")
{
// only set help browser if not running within emacs
system("--browser", "info");
}
// if help browser is later on set to netscape,
// allow it to fetch HTML pages from the net
system("--allow-net", 1);
}; // the last semicolon is important: otherwise no ">", but "." prompt
in your file `$HOME/.singularrc' sets your default browser to `info',
unless SINGULAR is run within emacs (in which case the default browser
is set automatically to `emacs').
Obviously, certain external files and programs are required for the
SINGULAR help system to work correctly. If something is not available or
goes wrong, here are some tips for troubleshooting the help system:
* Under Unix, the environment variable `DISPLAY' has to be set for
the browsers `netscape', `tkinfo', and `xinfo' to work.
* The help browsers `netscape', `tkinfo', `xinfo', and `info' are
only available if the respective programs are installed on your
system (for `xinfo', the programs `xterm' and `info' are
necessary). You can explicitly specify which program to use, by
setting appropriate environment variables (whose names are the
names of the respective programs in all up-case letters).
For example, to use the program `navigator' with a private colormap
as `netscape' help browser, set the environment variable `NETSCAPE'
to the value `"navigator -install"'.
* If the help browser `netscape' can not find the local html pages of
the SINGULAR manual (which it looks for at `$RootDir/html' - see
*note Loading of a library:: for more info on `$RootDir') _and_ the
(command-line) option `--allow-net' has _explicitly_ been set (see
*note Command line options:: and *note system:: for more info on
setting values of command-line options), then it dispatches the
html pages from `http://www.singular.uni-kl.de/Manual' (note that
the non-local net-access of HTML pages is disabled, by default).
An alternative location of a local directory where the html pages
reside can be specified by setting the environment variable
`SINGULAR_HTML_DIR'.
* The help browsers `tkinfo', `xinfo', `info', and `builtin' need the
(info) file `singular.hlp' which it looks for at
`$RootDir/info/singular.hlp' (see *note Loading of a library:: for
more info on `$RootDir'). An alternative location of the info file
of the manual can be specified by setting the environment variable
`SINGULAR_INFO_FILE'.
* Menu:
See also:
* Command line options::
* Loading of a library::
* Startup sequence::
* system::
*See also:* *note Command line options::; *note Loading of a library::;
*note Startup sequence::; *note system::.
Info help browsers
..................
The help browsers `tkinfo', `xinfo' and `info' (so-called info help
browsers) are based on the `info' program from the Gnu `texinfo'
package. *Note An Introduction to Info: (info)Top, for more
information.
For info help browsers, the online manual is decomposed into "nodes" of
information, closely related to the division of the printed manual into
sections and subsections. A node contains text describing a specific
topic at a specific level of detail. The top line of a node is its
"header". The node's header tells the name of the current node
(`Node:'), the name of the next node (`Next:'), the name of the previous
node (`Prev:'), and the name of the upper node (`Up:').
To move within info, type commands consisting of single characters. Do
not type `RETURN'. Do not use cursor keys, either. Using some of the
cursor keys by accident might pop to some totally different node. Type
`l' to return to the original node. Some of the `info' commands read
input from the command line at the bottom line. The `TAB' key may be
used to complete partially entered input.
The most important commands are:
`q'
leaves the online help system
`n'
goes to the next node
`p'
goes to the previous node
`u'
goes to the upper node
`m'
picks a menu item specified by name
`f'
follows a cross reference
`l'
goes to the previously visited node
`b'
goes to the beginning of the current node
`e'
goes to the end of the current node
`SPACE'
scrolls forward a page
`DEL'
scrolls backward a page
`h'
invokes info tutorial (use `l' to return to the manual or `CTRL-X
0' to remove extra window)
`CTRL-H'
shows a short overview on the online help system (use `l' to return
to the manual or `CTRL-X 0' to remove extra window)
`s'
searches through the manual for a specified string, and selects the
node in which the next occurrence is found
`1', ..., `9'
picks i-th subtopic from a menu
File: sing.htm, Node: Interrupting SINGULAR, Next: Editing input, Prev: The online help system, Up: Interactive use
3.1.4 Interrupting SINGULAR
---------------------------
On Unix-like operating systems and on Windows NT, typing `CTRL-C' (or,
alternatively `C-c C-c', when running within Emacs), interrupts
SINGULAR. SINGULAR prints the current command and the current line and
prompts for further action. The following choices are available:
`a'
returns to the top level after finishing the current (kernel)
command. Notice that commands of the SINGULAR kernel (like `std')
can not be aborted, i.e. (`a')bort only happens whenever the
interpreter is active.
`c'
continues
`q'
quits SINGULAR
File: sing.htm, Node: Editing input, Next: Command line options, Prev: Interrupting SINGULAR, Up: Interactive use
3.1.5 Editing input
-------------------
The following keys can be used for editing the input and retrieving
previous input lines:
`TAB'
provides command line completion for function names and file names
`CTRL-B'
moves cursor left
`CTRL-F'
moves cursor right
`CTRL-A'
moves cursor to beginning of line
`CTRL-E'
moves cursor to end of line
`CTRL-D'
deletes character under cursor
Warning: on an empty line, `CTRL-D' is interpreted as the `EOF'
character which immediately terminates SINGULAR.
`BACKSPACE'
`DELETE'
`CTRL-H'
deletes character before cursor
`CTRL-K'
kills from cursor to end of line
`CTRL-U'
kills from cursor to beginning of line
`CTRL-N'
saves current line on history and gives next line
`CTRL-P'
saves current line on history and gives previous line
`RETURN'
saves the current line to the history and sends it to the SINGULAR
parser for interpretation
When run under a Unix-like operating system and in its ASCII-terminal
user interface, SINGULAR tries to dynamically link at runtime with the
GNU Readline library. *Note GNU Readline Library: (readline)Command Line
Editing, for more information. If a shared version of this library can
be found on your machine, then additional command-line editing features
like history completion are available. In particular, if SINGULAR is
able to load that library and if the environment variable `SINGULARHIST'
is set and has a name of a file as value, then the input history is
stored across sessions using this file. Otherwise, i.e., if the
environment variable `SINGULARHIST' is not set, then the history of the
last inputs is only available for the commands of the current session.
File: sing.htm, Node: Command line options, Next: Startup sequence, Prev: Editing input, Up: Interactive use
3.1.6 Command line options
--------------------------
The synopsis of SINGULAR is
Singular [options] [file1 [file2 ...]]
ESingular [options] [file1 [file2 ...]]
Options can be given in both, their long and short format. The following
options control the general behavior of SINGULAR:
`-d', `--sdb'
Enable the use of the source code debugger. *Note Source code
debugger::.
`-e', `--echo[=VAL]'
Set value of variable `echo' to `VAL' (integer in the range 0, ...,
9). Without an argument, `echo' is set to 1, which echoes all input
coming from a file. By default, the value of `echo' is 0. *Note
echo::.
`-h', `--help'
Print a one-line description of each command line option and exit.
`--allow-net'
Allow the `netscape' and `html' help browser to fetch HTML manual
pages over the net from the WWW home-site of SINGULAR. *Note The
online help system::, for more info.
`--browser=VAL'
Use `VAL' as browser for the SINGULAR online manual.
`VAL' may be one of `html' (Windows only), `netscape', `xinfo',
`tkinfo', `info', `builtin', or `emacs'. Depending on your platform
and local installation, only some browsers might be available. The
default browser is `html' for Windows and `netscape' for Unix
platforms. *Note The online help system::, for more info.
`--no-rc'
Do not execute the `.singularrc' file on start-up. By default,
this file is executed on start-up. *Note Startup sequence::.
`--no-stdlib'
Do not load the library `standard.lib' on start-up. By default,
this library is loaded on start-up. *Note Startup sequence::.
`--no-warn'
Do not display warning messages.
`--no-out'
Suppress display of all output.
`-t', `--no-tty'
Do not redefine the terminal characteristics. This option should
be used for batch processes.
`-q', `--quiet'
Do not print the start-up banner and messages when loading
libraries. Furthermore, redirect `stderr' (all error messages) to
`stdout' (normal output channel). This option should be used if
SINGULAR's output is redirected to a file.
`-v', `--verbose'
Print extended information about the version and configuration of
SINGULAR (used optional parts, compilation date, start of random
generator etc.). This information should be included if a user
reports an error to the authors.
The following command line options allow manipulations of the timer and
the pseudo random generator and enable the passing of commands and
strings to SINGULAR:
`-c', `--execute=STRING'
Execute `STRING' as (a sequence of) SINGULAR commands on start-up
after the `.singularrc' file is executed, but prior to executing
the files given on the command line. E.g., `Singular -c "help
all.lib; quit;"' shows the help for the library `all.lib' and
exits.
`-u', `--user-option=STRING'
Returns `STRING' on `system("--user-option")'. This is useful for
passing arbitrary arguments from the command line to the SINGULAR
interpreter. E.g.,
`Singular -u "xxx.dump" -c 'getdump(system("--user-option"))''
reads the file `xxx.dump' at start-up and allows the user to start
working with all the objects defined in a previous session.
`-r', `--random=SEED'
Seed (i.e., set the initial value of) the pseudo random generator
with integer `SEED'. If this option is not given, then the random
generator is seeded with a time-based `SEED' (the number of seconds
since January, 1, 1970, on Unix-like operating systems, to be
precise).
`--min-time=SECS'
If the `timer' (*note timer::), resp. `rtimer' (*note rtimer::) ,
variable is set, report only times larger than `SECS' seconds
(`SECS' needs to be a floating point number greater than 0). By
default, this value is set to 0.5 (i.e., half a second). E.g., the
option `--min-time=0.01' forces SINGULAR to report all times larger
than 1/100 of a second.
`--ticks-per-sec=TICKS'
Set unit of timer to `TICKS' ticks per second (i.e., the value
reported by the `timer' and `rtimer' variable divided by `TICKS'
gives the time in seconds). By default, this value is 1.
The next three options are of interest for the use with MP links:
`-b', `--batch'
Run in MP batch mode. Opens a TCP/IP connection with host specified
by `--MPhost' at the port specified by `--MPport'. Input is read
from and output is written to this connection in the MP format.
*Note MPtcp links::.
`--MPport=PORT'
Use `PORT' as default port number for MP connections (whenever not
further specified). This option is mandatory when the `--batch'
option is given. *Note MPtcp links::.
`--MPhost=HOST'
Use `HOST' as default host for MP connections (whenever not further
specified). This option is mandatory when the `--batch' option is
given. *Note MPtcp links::.
Finally, the following options are only available when running
`ESingular' (see *note Running SINGULAR under Emacs:: for details).
`--emacs=EMACS'
Use `EMACS' as Emacs program to run the SINGULAR Emacs interface,
where `EMACS' may e.g. be emacs ore xemacs.
`--emacs-dir=DIR'
Set the singular-emacs-home-directory, which is the directory where
singular.el can be found, to `DIR'.
`--emacs-load=FILE'
Load `FILE' on Emacs start-up, instead of the default load file.
`--singular=PROG'
Start `PROG' as SINGULAR program within Emacs
The value of options given to SINGULAR (resp. their default values, if
an option was not given), can be checked with the command
`system("--'long_option_name`")'. *Note system::.
system("--quiet"); // if ``quiet'' 1, otherwise 0
==> 1
system("--min-time"); // minimal reported time
==> 0.5
system("--random"); // seed of the random generator
==> 12345678
Furthermore, the value of options (e.g., `--browser') can be re-set
while SINGULAR is running with the command
`system("--'long_option_name_string `",'expression`)'. *Note system::.
system("--browser", "builtin"); // sets browser to 'builtin'
system("--ticks-per-sec", 100); // sets timer resolution to 100
File: sing.htm, Node: Startup sequence, Prev: Command line options, Up: Interactive use
3.1.7 Startup sequence
----------------------
On start-up, SINGULAR
1. loads the library `standard.lib' (provided the `--no-stdlib' option
was not given),
2. searches the current directory and then the home directory of the
user, and then all directories contained in the library
`SearchPath' (see *note Loading of a library:: for more info on
`SearchPath') for a file named `.singularrc' and executes it, if
found (provided the `--no-rc' option was not given),
3. executes the string specified with the `--execute' command line
option,
4. executes the files `file1', `file2' ... (given on the command
line) in that order.
*Note:* `.singularrc' file(s) are an appropriate place for setting some
default values of (command-line) options.
For example, a system administrator might remove the locally installed
HTML version of the manual and put a `.singularrc' file with the
following content
if (system("version") >= 1306) // assure backwards-compatibility
{
system("--allow-net", 1);
}; // the last semicolon is important: otherwise no ">", but "." prompt
in the directory containing the SINGULAR libraries, thereby allowing to
fetch the HTML on-line help from the WWW home-site of SINGULAR.
On the other hand, a single user might put a `.singularrc' with the
following content
if (system("version") >= 1306) // assure backwards-compatibility
{
if (! system("--emacs"))
{
// set default browser to info, unless we run within emacs
system("--browser", "info");
}
}; // the last semicolon is important: otherwise no ">", but "." prompt
in his home directory, which sets the default help browser to `info'
(unless SINGULAR is run within emacs) and thereby prevents the execution
of the"global" `.singularrc' file installed by the system administrator
(since the `.singularrc' file of the user is found before the "global"
`.singularrc' file installed by the system administrator).
File: sing.htm, Node: Emacs user interface, Next: Rings and orderings, Prev: Interactive use, Up: General concepts
3.2 Emacs user interface
========================
Besides running SINGULAR in an ASCII-terminal, SINGULAR might also be
run within Emacs. Emacs (or, XEmacs which is very similar) is a powerful
and freely available text editor, which, among others, provides a
framework for the implementation of interactive user interfaces.
Starting from version 1.3.6, SINGULAR provides such an implementation,
the so-called SINGULAR Emacs mode, or Emacs user interface.
Generally, we recommend to use the Emacs interface, instead of the
ASCII-terminal interface: The Emacs interface does not only provide
everything the ASCII-terminal interface provides, but offers much more.
Among others, it offers
* color-highlighting
* truncation of long lines
* folding of input and output
* TAB-completion for help topics
* highlighting of matching parentheses
* key-bindings and interactive menus for most user interface commands
and for basic SINGULAR commands (such as loading of libraries and
files)
* a mode for running interactive SINGULAR demonstrations
* convenient ways to edit SINGULAR input files
* interactive customization of nearly all aspects of the
user-interface.
To use the SINGULAR-Emacs interface you need to have Emacs version 20 or
higher, or XEmacs version 20.3 or higher installed on your system. These
editors can be downloaded for most hard- and software platforms
(including Windows 95/98/NT, but excluding the Macintosh), from either
`http://www.fsf.org/software/emacs/emacs.html' (Emacs), from
`http://www.xemacs.org' (XEmacs), or from our ftp site at
`ftp://www.mathematik.uni-kl.de/pub/Math/Singular/utils/'. The
differences between Emacs and XEmacs w.r.t. the SINGULAR-Emacs
interface are marginal - which editor to use is mainly a matter of
personal preferences.
The simplest way to start-up SINGULAR in its Emacs interface is by
running the program `ESingular' which is contained in the Singular
distribution. Alternatively, SINGULAR can be started within an already
running Emacs - see *note Running SINGULAR under Emacs:: for details.
The next section gives a tutorial-like introduction to Emacs. This
introductory section is followed by sections which explain the
functionality of various aspects of the Emacs user interface in more
detail: how to start/restart/kill SINGULAR within Emacs, how to run an
interactive demonstration, how to customize the Emacs user interface,
etc. Finally, the 20 most important commands of the Emacs interface
together with their key bindings are listed.
* Menu:
* A quick guide to Emacs::
* Running SINGULAR under Emacs::
* Demo mode::
* Customization of the Emacs interface::
* Editing SINGULAR input files with Emacs::
* Top 20 Emacs commands::
File: sing.htm, Node: A quick guide to Emacs, Next: Running SINGULAR under Emacs, Prev: Emacs user interface, Up: Emacs user interface
3.2.1 A quick guide to Emacs
----------------------------
This section gives a tutorial-like introduction to Emacs. Especially to
users who are not familiar with Emacs, we recommend that they go through
this section and try out the described features.
Emacs commands generally involve the `CONTROL' key (sometimes labeled
`CTRL' or `CTL') or the `META' key. On some keyboards, the `META' key
is labeled `ALT' or `EDIT' or something else (for example, on Sun
keyboards, the diamond key to the left of the space-bar is `META'). If
there is no `META' key, the `ESC' key can be used, instead. Rather than
writing out `META' or `CONTROL' each time we want to prefix a character,
we will use the following abbreviations:
`C-' means hold the `CONTROL' key while typing the character
`'. Thus, `C-f' would be: hold the `CONTROL' key
and type `f'.
`M-' means hold the `META' key down while typing `'. If
there is no `META' key, type , release it, then
type the character `'.
For user new to Emacs, we highly recommend that they go through the
interactive Emacs tutorial: type `C-h t' to start it.
For others, it is important to understand the following Emacs concepts:
window
In Emacs terminology, a window refers to separate panes within the
same window of the window system, and not to overlapping, separate
windows. When using SINGULAR within Emacs, extra windows may appear
which display help or output from certain commands. The most
important window commands are:
`C-x 1' `File->Un-Split' Un-Split window (i.e., kill other
windows)
`C-x o' Goto other window, i.e. move
cursor into other window.
cursor and point
The location of the cursor in the text is also called "point". To
paraphrase, the cursor shows on the screen where point is located
in the text. Here is a summary of simple cursor-moving operations:
`C-f' Move forward a character
`C-b' Move backward a character
`M-f' Move forward a word
`M-b' Move backward a word
`C-a' Move to the beginning of line
`C-e' Move to the end of line
buffer
Any text you see in an Emacs window is always part of some buffer.
For example, each file you are editing with Emacs is stored inside
a buffer, but also SINGULAR is running inside an Emacs buffer. Each
buffer has a name: for example, the buffer of a file you edit
usually has the same name as the file, SINGULAR is running in a
buffer which has the name `*singular*' (or, `*singular<2>*',
`*singular<3>*', etc., if you have multiple SINGULAR sessions
within the same Emacs).
When you are asked for input to an Emacs command, the cursor moves
to the bottom line of Emacs, i.e., to a special buffer, called the
"minibuffer". Typing within the minibuffer, ends the
input, typing within the minibuffer, lists all possible
input values to the interactive Emacs command.
The most important buffer commands are
`C-x b' Switch buffer
`C-x k' Kill current buffer
Alternatively, you can switch to or kill buffers using the `Buffer'
menu.
Executing commands
Emacs commands are executed by typing `M-x '
(remember that completes partial command names). Important
and frequently used commands have short-cuts for their execution:
Key bindings or even menu entries. For example, a file can be
loaded with `M-x load-file', or `C-x C-f', or with the `File->Open'
menu.
How to exit
To end the Emacs (and, SINGULAR) session, type `C-x C-c' (two
characters), or use the `File -> Exit' menu.
When Emacs is hung
If Emacs stops responding to your commands, you can stop it safely
by typing `C-g', or, if this fails, by typing `C-]'.
More help
Nearly all aspects of Emacs are very well documented: type `C-h'
and then a character saying what kind of help you want. For
example, typing `C-h i' enters the `Info' documentation browser.
Using the mouse
Emacs is fully integrated with the mouse. In particular, clicking
the right mouse button brings up a pop-up menu which usually
contains a few commonly used commands.
File: sing.htm, Node: Running SINGULAR under Emacs, Next: Demo mode, Prev: A quick guide to Emacs, Up: Emacs user interface
3.2.2 Running SINGULAR under Emacs
----------------------------------
There are two ways to start the SINGULAR Emacs interface: Typing
`ESingular' instead of `Singular' on the command shell launches a new
Emacs process, initializes the interface and runs SINGULAR within Emacs.
The other way is to start the interface in an already running Emacs, by
typing `M-x singular' inside Emacs. This initializes the interface and
runs SINGULAR within Emacs. Both ways are described in more detail
below.
Note: To properly run the Emacs interface, several files are needed
which usually reside in the `emacs' subdirectory of your SINGULAR
distribution. This directory is called singular-emacs-home-directory in
the following.
Starting the interface using ESingular
--------------------------------------
As mentioned above, `ESingular' is an "out-of-the-box" solution: You
don't have to add special things to your `.emacs' startup file to
initialize the interface; everything is done for you in a special file
called `.emacs-singular' (which comes along with the SINGULAR
distribution and resides in the singular-emacs-home-directory) which is
automatically loaded on Emacs startup (and the loading of the `.emacs'
file is automatically suppressed).
The customizable variables of the SINGULAR Emacs interface are set to
defaults which give the novice user a very shell like feeling of the
interface. Nevertheless, these default settings can be changed, see
*note Customization of the Emacs interface::. Besides other Emacs
initializations, such as fontification or blinking parentheses, a new
menu item called `Singular' is added to the main menu, providing menu
items for starting SINGULAR. On XEmacs, a button starting SINGULAR is
added to the main toolbar.
The SINGULAR interface is started automatically; once you see a buffer
called `*singular*' and the SINGULAR prompt you are ready to start your
SINGULAR session.
`ESingular' inherits all `Singular' options. For a description off all
these options, see *note Command line options::. Additionally there are
the following options which are special to `ESingular':
command-line option functionality
/
environment variable
`--emacs=EMACS' Use `EMACS' as Emacs program to run the SINGULAR
`ESINGULAR_EMACS' Emacs interface, where `EMACS' may e.g. be emacs
or xemacs.
`--emacs-dir=DIR' Set the singular-emacs-home-directory, which is
`ESINGULAR_EMACS_DIR' the directory where singular.el can be found,
to `DIR'.
`--emacs-load=FILE' Load `FILE' on Emacs start-up, instead of the
`ESINGULAR_EMACS_LOAD' default load file.
`--singular=PROG' Start `PROG' as SINGULAR program within Emacs
`ESINGULAR_SINGULAR'
Notice that values of these options can also be given by setting the
above mentioned environment variables (where values given as
command-line arguments take priority over values given by environment
variables).
Starting the interface within a running Emacs
---------------------------------------------
If you are a more experienced Emacs user and you already have your own
local `.emacs' startup file, you might want to start the interface out
of your running Emacs without using `ESingular'. For this, you should
add the following lisp code to your `.emacs' file:
(setq load-path (cons "" load-path))
(autoload 'singular "singular"
"Start Singular using default values." t)
(autoload 'singular-other "singular"
"Ask for arguments and start Singular." t)
Then typing `M-x singular' in a running Emacs session initializes the
interface in a new buffer and launches a SINGULAR process. The SINGULAR
prompt comes up and you are ready to start your SINGULAR session.
It is a good idea to take a look at the (well documented) file
`.emacs-singular' in the singular-emacs-home-directory, which comes
along with the distribution. In it you find some useful initializations
of the SINGULAR interface as well as some lisp code, which, for example,
adds a button to the XEmacs toolbar. Some of this code might be useful
for your `.emacs' file, too. And if you are a Emacs wizard, it is of
course a good idea to take a look at `singular.el' in the
singular-emacs-home-directory.
Starting, interrupting and stopping SINGULAR
--------------------------------------------
There are the following commands to start and stop SINGULAR:
* `singular-other' (or menu `Singular', item `Start...')
Starts a SINGULAR process and asks for the following four
parameters in the minibuffer area:
1. The Singular executable. This can either be a file name with
complete path, e.g., `/local/bin/Singular'. Then exactly this
executable is started. The path may contain the character `~'
denoting your home directory. Or it can be the name of a
command without path, e.g., `Singular'. Then the executable is
searched for in your `$PATH' environment variable.
2. The default working directory. This is the path to an existing
directory, e.g., `~/work'. The current directory is set to
this directory before SINGULAR is started.
3. Command line options. You can set any SINGULAR command line
option (see *note Command line options::).
4. The buffer name. You can specify the name of the buffer the
interface is running in.
* `singular' (or menu `Singular', item `Start default')
Starts SINGULAR with default settings for the executable, the
working directory, command line switches, and the buffer name. You
can customize this default settings, see *note Customization of the
Emacs interface::.
* `singular-exit-singular' (bound to `C-c $' or menu `Singular', item
`Exit')
Kills the running SINGULAR process of the current buffer (but does
not kill the buffer). Once you have killed a SINGULAR process you
can start a new one in the same buffer with the command `singular'
(or select the item `Start default' of the `Singular' menu).
* `singular-restart' (bound to `C-c C-r' or menu `Singular', item
`Restart')
Kills the running SINGULAR process of the current buffer and starts
a new process in the same buffer with exactly the same command line
arguments as before.
* `singular-control-c' (bound to `C-c C-c' or menu `Singular', item
`Interrupt')
Interrupt the Singular process running in the current buffer. Asks
whether to (`a')bort the current SINGULAR command, (`q')uit or
(`r')estart the current SINGULAR process, or (`c')ontinue without
doing anything (default).
Whenever a SINGULAR process is started within the Emacs interface, the
contents of a special startup file (by default `~/.emacs-singularrc') is
pasted as input to SINGULAR at the very end of the usual startup
sequence (see *note Startup sequence::). The name of the startup file
can be changed, see *note Customization of the Emacs interface::.
File: sing.htm, Node: Demo mode, Next: Customization of the Emacs interface, Prev: Running SINGULAR under Emacs, Up: Emacs user interface
3.2.3 Demo mode
---------------
The Emacs interface can be used to run interactive SINGULAR
demonstrations. A demonstration is started by loading a so-called
SINGULAR demo file with the Emacs command `singular-demo-load', bound to
`C-c C-d', or with the menu `Commands->Load Demo'.
A SINGULAR demo file should consist of SINGULAR commands separated by
blank lines. When running a demo, the input up to the next blank line is
echoed to the screen. Hitting executes the echoed commands and
shows their output. Hitting again, echos the next commands to
the screen, and so on, until all commands of the demo file are executed.
While running a demo, you can execute other commands on the SINGULAR
prompt: the next input of from the demo file is then echoed again, if
you hit on an empty input line.
A SINGULAR demo can prematurely be exited by either starting another
demo, or by executing the Emacs command `singular-demo-exit' (menu:
`Commands->Exit Demo').
Some aspects of running SINGULAR demos can be customized. *Note
Customization of the Emacs interface::, for more info.
File: sing.htm, Node: Customization of the Emacs interface, Next: Editing SINGULAR input files with Emacs, Prev: Demo mode, Up: Emacs user interface
3.2.4 Customization of the Emacs interface
------------------------------------------
Emacs provides a convenient interface to customize the behavior of Emacs
and the SINGULAR Emacs interface for your own needs. You enter the
customize environment by either calling `M-x customize' (on XEmacs you
afterwards have to enter `emacs' in the minibuffer area) or by selecting
the menu item `Options->Customize->Emacs...' for XEmacs, and the menu
item `Help->Customize->Toplevel Customization Group' for Emacs, resp. A
brief introduction to the customization mode comes up with the
customization buffer. All customizable parameters are hierarchically
grouped and you can browse through all these groups and change the
values of the parameters using the mouse. At the end you can safe the
settings to a special file making your changes permanent.
To change the settings of the SINGULAR Emacs interface you can either
select the item `Preferences' of the `Singular' menu, call `M-x
customize-group' and give the argument `singular-interactive' in the
minibuffer area, or browse from the top-level customization group
through the path `External->Singular->Singular interactive'.
The SINGULAR interface customization buffer is divided into four groups:
* Singular Faces
Here you can specify various faces used if font-lock-mode is
enabled (which it is, by default).
* Singular Sections And Foldings
Here you can specify special faces for SINGULAR input and output
and change the text used as replacement for folded sections.
For doing this, you also might find handy the function
`customize-face-at-point', which let's you customize the face at
the current position of point. This function is automatically
defined if you run `ESingular'). Otherwise, you should add its
definition (see below) to your personal `.emacs' file.
* Singular Interactive Miscellaneous
Here you can specify various different things such as the behavior
of the cursor keys, the name of the special SINGULAR startup file,
the appearance of the help window, or the default values for the
`singular' command.
* Singular Demo Mode
Here you can specify how chunks of the demo file are divided, or
specify a default directory for demo files.
When you run `ESingular', the settings of customized variables are saved
in the file `$HOME/.emacs-singular-cust'. Otherwise, the settings are
appended to your `.emacs' file. Among others, this means that the
customized settings of `ESingular' are not automatically taken over by
a "normal" Emacs, and vice versa.
File: sing.htm, Node: Editing SINGULAR input files with Emacs, Next: Top 20 Emacs commands, Prev: Customization of the Emacs interface, Up: Emacs user interface
3.2.5 Editing SINGULAR input files with Emacs
---------------------------------------------
Since SINGULAR's programming language is similar to C, you should use
the Emacs C/C++-mode to edit SINGULAR input files and SINGULAR
libraries. Among others, this Emacs mode provides automatic indentation,
line-breaking and keyword highlighting.
When running `ESingular', the C/C++-mode is automatically turned on
whenever a file with the suffix `.sing', or `.lib' is loaded.
For Emacs sessions which were not started by `ESingular', you should
add the following to your `.emacs' file:
;; turn on c++-mode for files ending in ".sing" and ".lib"
(setq auto-mode-alist (cons '("\\.sing\\'" . c++-mode) auto-mode-alist))
(setq auto-mode-alist (cons '("\\.lib\\'" . c++-mode) auto-mode-alist))
;; turn-on fontification for c++-mode
(add-hook 'c++-mode-hook
(function (lambda () (font-lock-mode 1))))
;; turn on aut-new line and hungry-delete
(add-hook 'c++-mode-hook
(function (lambda () (c-toggle-auto-hungry-state 1))))
;; a handy function for customization
(defun customize-face-at-point ()
"Customize face which point is at."
(interactive)
(let ((face (get-text-property (point) 'face)))
(if face
(customize-face face)
(message "No face defined at point"))))
Notice that you can change the default settings for source-code
highlighting (colors, fonts, etc.) by customizing the respective faces
using the `Customize' feature of Emacs. For doing this, you might find
handy the above given function `customize-face-at-point', which lets you
customize the face of the current position of point (this function is
automatically defined if you run `ESingular').
File: sing.htm, Node: Top 20 Emacs commands, Prev: Editing SINGULAR input files with Emacs, Up: Emacs user interface
3.2.6 Top 20 Emacs commands
---------------------------
Here is a list of the 20 probably most useful commands when using the
SINGULAR Emacs interface.
Starting and stopping of SINGULAR:
* `singular' (menu `Singular->Start Default...'): starts SINGULAR
using default arguments.
* `singular-other' (menu `Singular->Start'): starts SINGULAR asking
for several arguments in the minibuffer area.
* `singular-exit' (key `C-c $' or menu `Singular->Exit'): kills the
SINGULAR process running in the current buffer (but does not kill
the buffer).
* `singular-restart' (key `C-c C-r' or menu `Singular->Restart'):
kills the SINGULAR process running in the current buffer and starts
a new SINGULAR process with exactly the same arguments as before.
Editing input and output:
* `singular-beginning-of-line' (key `C-a'): moves point to beginning
of line, then skip past the SINGULAR prompt, if any.
* `singular-toggle-truncate-lines' (key `C-c C-t' or menu
`Commands->Truncate lines'): toggles whether long lines should be
truncated or not. If lines are not truncated, the commands
`singular-scroll-left' and `singular-scroll-right' are useful to
scroll left and right, resp.
* `singular-dynamic-complete' (key `TAB'): performs context specific
completion. If point is inside a string, file name completion is
done. If point is at the end of a help command (i.e., `help' or
`?'), completion on SINGULAR help topics is done. If point is at
the end of an example command (i.e., `example'), completion is done
on SINGULAR examples. In all other cases, completion on SINGULAR
commands is done.
* `singular-folding-toggle-fold-latest-output' (key `C-c C-o' or menu
`Commands->Fold/ Unfold Latest Output'): toggles folding of the
latest output section. If your last SINGULAR command produced a
huge output, simply type `C-c C-o' and it will be replaced by a
single line.
* `singular-folding-toggle-fold-at-point' (key `C-c C-f' or menu
`Commands->Fold/Unfold At Point'): toggles folding of the section
the point currently is in.
* `singular-folding-fold-all-output' (menu `Commands->Fold All
Output'): folds all SINGULAR output, replacing each output section
by a single line.
* `singular-folding-unfold-all-output' (menu `Commands->Unfold All
Output'): unfolds all SINGULAR output sections showing their true
contents.
Loading of files and SINGULAR demo mode:
* `singular-load-library' (key `C-c C-l' or menu
`Commands->Libraries->other...'): asks for a standard library name
or a library file in the minibuffer (hit `TAB' for completion) and
loads the library into SINGULAR. The submenu `Libraries' of the
`Commands' menu also provides a separate menu item for each
standard library.
* `singular-load-file' (key `C-c <' or menu `Commands->Load
File...'): asks for a file name in the minibuffer (which is
expanded using `expand-file-name' if given a prefix argument) and
loads the file into SINGULAR.
* `singular-demo-load' (key `C-c C-d' or menu `Commands->Load
Demo...'): asks for a file name of a SINGULAR demo file in the
minibuffer area (hit `SPACE' for completion) and enters the
SINGULAR demo mode showing the first chunk of the demo.
* `singular-demo-exit' (menu `Commands->Exit Demo'): exits from
SINGULAR demo mode and cleans up everything that is left from the
demo.
Help and Customization:
* `singular-help' (key `C-h C-s' or menu `Singular->Singular Help'):
asks for a SINGULAR help topic in the minibuffer (hit `TAB' for
completion) and shows the help text in a separate buffer.
* `singular-example' (key `C-c C-e' or menu `Singular->Singular
Example'): asks for a SINGULAR command in the minibuffer (hit `TAB'
for completion) and executes the example of this command in the
current SINGULAR buffer.
* `customize-group' (menu `Singular->Preferences'): enters the
customization group of the SINGULAR Emacs interface. (If called via
`M-x customize-group' give argument `singular-interactive' in the
minibuffer area.)
File: sing.htm, Node: Rings and orderings, Next: Implemented algorithms, Prev: Emacs user interface, Up: General concepts
3.3 Rings and orderings
=======================
All non-trivial algorithms in SINGULAR require the prior definition of a
ring. Such a ring can be
1. a polynomial ring over a field,
2. a localization of a polynomial ring,
3. a quotient ring by an ideal of one of 1. or 2.,
4. a tensor product of one of 1. or 2.
Except for quotient rings, all of these rings are realized by choosing a
coefficient field, ring variables, and an appropriate global or local
monomial ordering on the ring variables. *Note Term orderings::, *note
Mathematical background::.
The coefficient field of the rings may be
1. the field of rational numbers Q $Q$
,
2. finite fields $Z/p$, $p$ a prime $\le 2147483629$,
finite fields Z/p, p a prime <= 2147483629,
3. finite fields $\hbox{GF}(p^n)$ with $p^n$ elements, $p$ a prime, $p^n \le 2^{15}$,
finite fields GF(p^n) with p^n elements, p a prime, p^n <= 2^15,
4. transcendental extension of Q $Q$
or Z/p $Z/p$
,
5. simple algebraic extension of Q $Q$
or Z/p $Z/p$
,
6. the field of real numbers represented by floating point numbers of
a user defined precision.
7. the field of complex numbers represented by (pairs of) floating
point numbers of a user defined precision.
Throughout this manual, the current active ring in SINGULAR is called
basering. The reserved name `basering' in SINGULAR is an alias for the
current active ring. The basering can be set by declaring a new ring as
described in the following subsections or with the commands `setring'
and `keepring'. *Note keepring::, *note setring::.
Objects of ring dependent types are local to a ring. To access them
after a change of the basering they have to be mapped using `map' or by
the functions `imap' or `fetch'. *Note Objects::, *note fetch::, *note
imap::, *note map::.
All changes of the basering in a procedure are local to this procedure
unless a `keepring' command is used as the last statement of the
procedure. *Note Procedures::, *note keepring::.
* Menu:
* Examples of ring declarations::
* General syntax of a ring declaration::
* Term orderings::
File: sing.htm, Node: Examples of ring declarations, Next: General syntax of a ring declaration, Prev: Rings and orderings, Up: Rings and orderings
3.3.1 Examples of ring declarations
-----------------------------------
The exact syntax of a ring declaration is given in the next two
subsections; this subsection lists some examples first. Note that the
ordering has to be chosen such that the unit-elements of the ring are
precisely those elements with leading monomial 1. For more information,
see *note Monomial orderings::.
Every floating point number in a ring consists of two parts, which may
be chosen from the user. The leading part represents the number and the
rest is for the numerical stability. Two numbers with a difference only
in the rest are equal.
* the ring Z/32003[x,y,z] $Z/32003[x,y,z]$
with degree reverse lexicographical ordering. The exact ring
declaration may be omitted in the first example since this is the
default ring:
ring r;
ring r = 32003,(x,y,z),dp;
* the ring Q[a,b,c,d] $Q[a,b,c,d]$
with lexicographical ordering:
ring r = 0,(a,b,c,d),lp;
* the ring Z/7[x,y,z] $Z/7[x,y,z]$
with local degree reverse lexicographical ordering. The non-prime
10 is converted to the next lower prime in the second example:
ring r = 7,(x,y,z),ds;
ring r = 10,(x,y,z),ds;
* the ring $Z/7[x_1,\ldots,x_6]$
Z/7[x1,...,x6] with lexicographical ordering for $x_1,x_2,x_3$
x1,x2,x3 and degree reverse lexicographical ordering for $x_4,x_5,x_6$:
x4,x5,x6:
ring r = 7,(x(1..6)),(lp(3),dp);
* the localization of (Q[a,b,c])[x,y,z] $(Q[a,b,c])[x,y,z]$
at the maximal ideal
(x,y,z) $(x,y,z)$
:
ring r = 0,(x,y,z,a,b,c),(ds(3), dp(3));
* the ring Q[x,y,z] $Q[x,y,z]$
with weighted reverse lexicographical ordering. The variables x $x$
, y $y$
, and z $z$
have the weights 2, 1, and 3, respectively, and vectors are first
ordered by components (in descending order) and then by monomials:
ring r = 0,(x,y,z),(c,wp(2,1,3));
For ascending component order, the component ordering `C' has to be
used.
* the ring K[x,y,z] $K[x,y,z]$
, where K=Z/7(a,b,c) $K=Z/7(a,b,c)$
denotes the transcendental extension of Z/7 $Z/7$
by a $a$
, b $b$
and c $c$
with degree lexicographical ordering:
ring r = (7,a,b,c),(x,y,z),Dp;
* the ring K[x,y,z] $K[x,y,z]$
, where K=Z/7[a] $K=Z/7[a]$
denotes the algebraic extension of degree 2 of Z/7 $Z/7$
by a. $a.$
In other words, K $K$
is the finite field with 49 elements. In the first case, a $a$
denotes an algebraic element over Z/7 $Z/7$
with minimal polynomial $\mu_a=a^2+a+3$,
mu_a=a^2+a+3, in the second case, a $a$
refers to some generator of the cyclic group of units of K $K$
:
ring r = (7,a),(x,y,z),dp; minpoly = a^2+a+3;
ring r = (7^2,a),(x,y,z),dp;
* the ring R[x,y,z] $R[x,y,z]$
, where R $R$
denotes the field of real numbers represented by simple precision
floating point numbers. This is a special case:
ring r = real,(x,y,z),dp;
* the ring R[x,y,z] $R[x,y,z]$
, where R $R$
denotes the field of real numbers represented by floating point
numbers of 50 valid decimal digits and the same number of digits
for the rest:
ring r = (real,50),(x,y,z),dp;
* the ring R[x,y,z] $R[x,y,z]$
, where R $R$
denotes the field of real numbers represented by floating point
numbers of 10 valid decimal digits and with 50 digits for the rest:
ring r = (real,10,50),(x,y,z),dp;
* the ring R(j)[x,y,z] $R(j)[x,y,z]$
, where R $R$
denotes the field of real numbers represented by floating point
numbers of 30 valid decimal digits and the same number for the
rest. j $j$
denotes the imaginary unit.
ring r = (complex,30,j),(x,y,z),dp;
* the ring R(i)[x,y,z] $R(i)[x,y,z]$
, where R $R$
denotes the field of real numbers represented by floating point
numbers of 6 valid decimal digits and the same number for the rest.
i $i$
is the default for the imaginary unit.
ring r = complex,(x,y,z),dp;
* the quotient ring Z/7[x,y,z] $Z/7[x,y,z]$
modulo the square of the maximal ideal (x,y,z) $(x,y,z)$
:
ring R = 7,(x,y,z), dp;
qring r = std(maxideal(2));
File: sing.htm, Node: General syntax of a ring declaration, Next: Term orderings, Prev: Examples of ring declarations, Up: Rings and orderings
3.3.2 General syntax of a ring declaration
------------------------------------------
Rings
.....
*Syntax:*
`ring' name `=' `('coefficient_field`),' `('
names_of_ring_variables `),' `(' ordering `);'
*Default:*
`32003,(x,y,z),(dp,C);'
*Purpose:*
declares a ring and sets it as the current basering.
The coefficient_field is given by one of the following:
1. a non-negative int_expression less or equal 32003.
The int_expression should either be 0, specifying the field of
rational numbers Q, or a prime number p, specifying the finite
field with p elements. If it is not a prime number, int_expression
is converted to the next lower prime number.
2. an expression_list of an int_expression and one or more names.
The int_expression specifies the characteristic of the coefficient
field as described above. The names are used as parameters in
transcendental or algebraic extensions of the coefficient field.
Algebraic extensions are implemented for one parameter only. In
this case, a minimal polynomial has to be defined by assignment to
`minpoly'. *Note minpoly::.
3. an expression_list of an int_expression and a name.
The int_expression has to be a prime number p to the power of a
positive integer n. This defines the Galois field $\hbox{GF}(p^n)$ with $p^n$ elements, where $p^n$ has to be smaller or equal $2^{15}$.
GF(p^n) with p^n elements, where p^n has to be smaller or equal
2^15. The given name refers to a primitive element of $\hbox{GF}(p^n)$
GF(p^n) generating the multiplicative group. Due to a different
internal representation, the arithmetic operations in these
coefficient fields are faster than arithmetic operations in
algebraic extensions as described above.
4. an expression_list of the name `real' and two optional
int_expression giving the precision in decimal digits and the size
for the stabilizing rest. The default for the rest is the same size
as for the representation. An exception is the name `real' without
any integers. These numbers are implemented as machine floating
point numbers of single precision. Note that computations over all
these fields are not exact.
5. an expression_list of the name `complex', two optional
int_expression and a name. This specifies the field of complex
numbers represented with floating point numbers with a precision
similar to `real'. An expression_list without int_expression
defines a precision and rest with length 6. The name of the
imaginary unit is given by the last parameter. Note that
computations over these fields are not exact.
'names_of_ring_variables' is a list of names or indexed names.
'ordering' is a list of block orderings where each block ordering is
either
1. `lp', `dp', `Dp', `ls', `ds', or `Ds' optionally followed by a size
parameter in parentheses.
2. `wp', `Wp', `ws', `Ws', or `a' followed by a weight vector given as
an intvec_expression in parentheses.
3. `M' followed by an intmat_expression in parentheses.
4. `c' or `C'.
For the definition of the orderings, see *note Monomial orderings::.
If one of coefficient_field, names_of_ring_variables, and ordering
consists of only one entry, the parentheses around this entry may be
omitted.
Quotient rings
..............
*Syntax:*
`qring' name `=' ideal_expression `;'
*Default:*
none
*Purpose:*
declares a quotient ring as the basering modulo ideal_expression.
Sets it as current basering.
ideal_expression has to be represented by a standard basis.
The most convenient way to map objects from a ring to its quotient ring
and vice versa is to use the `fetch' function (*note fetch::).
SINGULAR computes in a quotient ring as long as possible with the given
representative of a polynomial, say, `f'. I.e., it usually does not
reduce `f' w.r.t. the quotient ideal. This is only done when necessary
during standard bases computations or by an explicit reduction using the
command `reduce(f, std(0))' (*note reduce::).
*Example:*
ring r=32003,(x,y),dp;
poly f=x3+yx2+3y+4;
qring q=std(maxideal(2));
basering;
==> // characteristic : 32003
==> // number of vars : 2
==> // block 1 : ordering dp
==> // : names x y
==> // block 2 : ordering C
==> // quotient ring from ideal
==> _[1]=y2
==> _[2]=xy
==> _[3]=x2
poly g=fetch(r, f);
g;
==> x3+x2y+3y+4
reduce(g,std(0));
==> 3y+4
File: sing.htm, Node: Term orderings, Prev: General syntax of a ring declaration, Up: Rings and orderings
3.3.3 Term orderings
--------------------
Any polynomial (resp. vector) in SINGULAR is ordered w.r.t. a term
ordering (or, monomial ordering), which has to be specified together
with the declaration of a ring. SINGULAR stores and displays a
polynomial (resp. vector) w.r.t. this ordering, i.e., the greatest
monomial (also called the leading monomial) is the first one appearing
in the output polynomial, and the smallest monomial is the last one.
*Remark:* The novice user should generally use the ordering `dp' for
computations in the polynomial ring $K[x_1,\ldots,x_n]$,
K[x1,...,xn], resp. `ds' for computations in the localization $\hbox{Loc}_{(x)}K[x_1,\ldots,x_n])$.
Loc_(x)K[x1,...,xn]). For more details, see *note Polynomial data::.
In a ring declaration, SINGULAR offers the following orderings:
1. Global orderings
`lp'
lexicographical ordering
`dp'
degree reverse lexicographical ordering
`Dp'
degree lexicographical ordering
`wp(' intvec_expression `)'
weighted reverse lexicographical ordering; the weight vector
may consist of positive integers only.
`Wp(' intvec_expression `)'
weighted lexicographical ordering; the weight vector may
consist of positive integers only.
Global orderings are well-orderings, i.e., 1 < x $1 < x$
for each ring variable x $x$
. They are denoted by a `p' as the second character in their name.
2. Local orderings
`ls'
negative lexicographical ordering
`ds'
negative degree reverse lexicographical ordering
`Ds'
negative degree lexicographical ordering
`ws(' intvec_expression `)'
(general) weighted reverse lexicographical ordering; the first
element of the weight vector has to be non-zero.
`Ws(' intvec_expression `)'
(general) weighted lexicographical ordering; the first element
of the weight vector has to be non-zero.
Local orderings are not well-orderings. They are denoted by an `s'
as the second character in their name.
3. Matrix orderings
`M(' intmat_expression `)'
intmat_expression has to be an invertible square matrix
Using matrix orderings, SINGULAR can compute standard bases w.r.t.
any monomial ordering that is compatible with the natural
semi-group structure on the monomials. In practice, the predefined
global and local orderings together with the block orderings should
be sufficient in most cases. These orderings are faster than their
corresponding matrix orderings since evaluation of a matrix
ordering is time consuming.
4. Extra weight vector
`a(' intvec_expression `)'
an extra weight vector `a(' intvec_expression `)' may precede
any monomial ordering
5. Product ordering
`(' ordering [ `(' int_expression `)' ]`,' ... `)'
any of the above orderings and the extra weight vector may be
combined to yield product or block orderings
The orderings `lp', `dp', `Dp', `ls', `ds', and `Ds' may be
followed by an int_expression in parentheses giving the size of the
block. For the last block the size is calculated automatically. For
the weighted orderings the size of the block is given by the size
of the weight vector. The same holds analogously for matrix
orderings.
6. Module orderings
`(' ordering`,' ...`, C )'
`(' ordering`,' ...`, c )'
sort polynomial vectors by the monomial ordering first, then
by components
`( C,' ordering`,' ... `)'
`( c,' ordering`,' ... `)'
sort polynomial vectors by components first, then by the
monomial ordering
Here a capital `C' sorts generators in ascending order, i.e.,
`gen(1)' < `gen(2)' < ... A small `c' sorts in descending order,
i.e., `gen(1)' > `gen(2)' > ... It is not necessary to specify the
module ordering explicitly since `(' ordering`,' ...`, C )' is the
default.
In fact, `c' or `C' may be specified anywhere in a product ordering
specification, not only at its beginning or end. All monomial
block orderings preceding the component ordering have higher
precedence, all monomial block orderings following after it have
lower precedence.
For a mathematical description of these orderings, see *note Polynomial
data::.
File: sing.htm, Node: Implemented algorithms, Next: The SINGULAR language, Prev: Rings and orderings, Up: General concepts
3.4 Implemented algorithms
==========================
The basic algorithm in SINGULAR is a general standard basis algorithm
for any monomial ordering which is compatible with the natural
semi-group structure of the exponents. This includes well-orderings
(Buchberger algorithm to compute a Groebner basis) and tangent cone
orderings (Mora algorithm) as special cases.
Nonetheless, there are a lot of other important algorithms:
* Algorithms to compute the standard operations on ideals and
modules: intersection, ideal quotient, elimination, etc.
* Different Syzygy algorithms and algorithms to compute free
resolutions of modules.
* Combinatorial algorithms to compute dimensions, Hilbert series,
multiplicities, etc.
* Algorithms for univariate and multivariate polynomial
factorization, resultant and gcd computations.
Commands to compute standard bases
----------------------------------
`facstd'
*note facstd::
computes a list of Groebner bases via the Factorizing Groebner
Basis Algorithm, i.e., their intersection has the same radical as
the original ideal. It need not be a Groebner basis of the given
ideal.
The intersection of the zero-sets is the zero-set of the given
ideal.
`fglm'
*note fglm::
computes a Groebner basis provided that a reduced Groebner basis
w.r.t. another ordering is given.
Implements the so-called FGLM (Faugere, Gianni, Lazard, Mora)
algorithm. The given ideal must be zero-dimensional.
`groebner'
*note groebner::
computes a standard resp. Groebner bases using a heuristically
chosen method.
This is the preferred method to compute a standard resp. Groebner
bases.
`mstd'
*note mstd::
computes a standard basis and a minimal set of generators.
`std'
*note std::
computes a standard resp. Groebner basis.
`stdfglm'
*note stdfglm::
computes a Groebner basis in a ring with a "difficult" ordering
(e.g., lexicographical) via `std' w.r.t. a "simple" ordering and
`fglm'.
The given ideal must be zero-dimensional.
`stdhilb'
*note stdhilb::
computes a Groebner basis in a ring with a "difficult" ordering
(e.g., lexicographical) via `std' w.r.t. a "simple" ordering and a
`std' computation guided by the Hilbert series.
Further processing of standard bases
------------------------------------
The next commands require the input to be a standard basis.
`degree'
*note degree::
computes the (Krull) dimension, codimension and the multiplicity.
The result is only displayed on the screen.
`dim'
*note dim::
computes the dimension of the ideal resp. module.
`highcorner'
*note highcorner::
computes the smallest monomial not contained in the ideal resp.
module. The ideal resp. module has to be finite dimensional as a
vector space over the ground field.
`hilb'
*note hilb::
computes the first, and resp. or, second Hilbert series of an ideal
resp. module.
`kbase'
*note kbase::
computes a vector space basis (consisting of monomials) of the
quotient of a ring by an ideal resp. of a free module by a
submodule.
The ideal resp. module has to be finite dimensional as a vector
space over the ground field and has to be represented by a standard
basis w.r.t. the ring ordering.
`mult'
*note mult::
computes the degree of the monomial ideal resp. module generated by
the leading monomials of the input.
`reduce'
*note reduce::
reduces a polynomial, vector, ideal or module to its normal form
with respect to an ideal or module represented by a standard basis.
`vdim'
*note vdim::
computes the vector space dimension of a ring (resp. free module)
modulo an ideal (resp. module).
Commands to compute resolutions
-------------------------------
`res'
*note res::
computes a free resolution of an ideal or module using a
heuristically chosen method. This is the preferred method to
compute free resolutions of ideals or modules.
`lres'
*note lres::
computes a free resolution of an ideal or module with La Scala's
method. The input needs to be homogeneous.
`mres'
*note mres::
computes a minimal free resolution of an ideal or module with the
Syzygy method.
`sres'
*note sres::
computes a free resolution of an ideal or module with Schreyer's
method. The input has to be a standard basis.
`nres'
*note nres::
computes a free resolution of an ideal or module with the standard
basis method.
`syz'
*note syz::
computes the first Syzygy (i.e., the module of relations of the
given generators).
Further processing of resolutions
---------------------------------
`betti'
*note betti::
computes the graded Betti numbers of a module from a free
resolution.
`minres'
*note minres::
minimizes a free resolution of an ideal or module.
`regularity'
*note regularity::
computes the regularity of a homogeneous ideal resp. module from a
given minimal free resolution.
Processing of polynomials
-------------------------
`char_series'
*note char_series::
computes characteristic sets of polynomial ideals.
`extgcd'
*note extgcd::
computes the extended gcd of two polynomials.
Implemented as extended Euclidean Algorithm. Applicable for
univariate polynomials only.
`factorize'
*note factorize::
computes factorization of univariate and multivariate polynomials
into irreducible factors.
The most basic algorithm is univariate factorization in prime
characteristic. The Cantor-Zassenhaus Algorithm is used in this
case. For characteristic 0, a univariate Hensel-lifting is done to
lift from prime characteristic to characteristic 0. For
multivariate factorization in any characteristic, the problem is
reduced to the univariate case first, then a multivariate
Hensel-lifting is used to lift the univariate factorization.
Note that there is no factorization of polynomials over algebraic
extensions of Q.
`gcd'
*note gcd::
computes greatest common divisors of univariate and multivariate
polynomials.
For prime characteristic, a subresultant gcd is used. In
characteristic 0, a modular algorithm is used for the univariate
case. For the multivariate case, the EZGCD is used.
Note that there is no gcd calculation for polynomials over
algebraic extensions of Q.
`resultant'
*note resultant::
computes the resultant of two univariate polynomials using the
subresultant algorithm.
Multivariate polynomials are considered as univariate polynomials
in the main variable (which has to be specified by the user).
`vandermonde'
*note vandermonde::
interpolates a polynomial from its values at several points
Matrix computations
-------------------
`bareiss'
*note bareiss::
implements sparse Gauss-Bareiss method for elimination (matrix
triangularization) in arbitrary integral domains.
`det'
*note det::
computes the determinant of a square matrix.
For matrices with integer entries a modular algorithm is used. For
other domains the Gauss-Bareiss method is used.
`minor'
*note minor::
computes all minors (=subdeterminants) of a given size for a
matrix.
Numeric computations
--------------------
`laguerre'
*note laguerre::
computes all (complex) roots of a univariate polynomial
`uressolve'
*note uressolve::
find all roots of 0-dimensional ideal i with multivariate
resultants
Controlling computations
------------------------
`option'
*note option::
allows setting of options for manipulating the behavior of
computations (such as reduction strategies) and for showing
protocol information indicating the progress of a computation.
File: sing.htm, Node: The SINGULAR language, Next: Input and output, Prev: Implemented algorithms, Up: General concepts
3.5 The SINGULAR language
=========================
SINGULAR interprets commands given interactively on the command line as
well as given in the context of user-defined procedures. In fact,
SINGULAR makes no distinction between these two cases. Thus, SINGULAR
offers a powerful programming language as well as an easy-to-use command
line interface without differences in syntax or semantics.
In the following, the basic language concepts such as commands,
expressions, names, objects, etc., are discussed. *Note Procedures::,
and *note Libraries::, for the concepts of procedures and libraries.
In many aspects, the SINGULAR language is similar to the C programming
language. For a description of some of the subtle differences, see
*note Major differences to the C programming language::.
Elements of the language
........................
The major building blocks of the SINGULAR language are expressions,
commands, and control structures. The notion of expressions in the
SINGULAR and the C programming language are identical, whereas the
notion of commands and control structures only roughly corresponds to
the C statements.
* An "expression" is a sequence of operators, functions, and operands
that specifies a computation. An expression always results in a
value of a specific type. *Note Data types::, and its subsections
(e.g., *note poly expressions::), for information on how to build
expressions.
* A "command" is either a declaration, an assignment, a call to a
function without return value, or a print command. For detailed
information, see *note General command syntax::.
* "Control structures" determine the execution sequence of commands.
SINGULAR provides control structures for conditional execution
(`if' ... `else') and iteration (`for' and `while'). Commands may
be grouped in pairs of `{' `}' (curly brackets) to form blocks.
*Note Control structures::, for more information.
Other notational conventions
............................
For user-defined functions, the notion of "procedure" and "function" are
synonymous.
As already mentioned above, functions without return values are called
commands. Furthermore, whenever convenient, the term "command" is used
for a function, even if it does return a value.
* Menu:
* General command syntax::
* Special characters::
* Names::
* Objects::
* Type conversion and casting::
* Flow control::
File: sing.htm, Node: General command syntax, Next: Special characters, Prev: The SINGULAR language, Up: The SINGULAR language
3.5.1 General command syntax
----------------------------
In SINGULAR a command is either a declaration, an assignment, a call to
a function without return value, or a print command. The general form of
a command is described in the following subsections.
Declaration
...........
1. type name `=' expression `;'
declares a variable with the given name of the given type and
assigns the expression as initial value to it. Expression is an
expression of the specified type or one that can be converted to
that type. *Note Type conversion and casting::.
2. type name_list `=' expression_list `;'
declares variables with the given names and assigns successively
each expression of expression_list to the corresponding name of
name_list. Both lists must be of the same length. Each expression
in expression_list is an expression of the specified type or one
that can be converted to that type. *Note Type conversion and
casting::.
3. type name `;'
declares a variable with the given name of the given type and
assigns the default value of the specific type to it.
*Note Names::, for more information on declarations. *Note Data
types::, for a description of all data types known to SINGULAR.
ring r; // the default ring
poly f,g = x^2+y^3,xy+z2; // the polynomials f=x^2+y^3 and g=x*y+z^2
ideal I = f,g; // the ideal generated by f and g
matrix m[3][3]; // a 3 x 3 zero matrix
int i=2; // the integer i=2
Assignment
..........
4. name `=' expression `;'
assigns expression to name.
5. name_list `=' expression_list `;'
assigns successively each expression of expression_list to the
corresponding name of name_list. Both lists must be of the same
length. This is not a simultaneous assignment. Thus, `f, g = g,
f;' does not swap the values of `f' and `g', but rather assigns `g'
to both `f' and `g'.
There must be a type conversion of the type of expression to the type of
name. *Note Type conversion and casting::.
An assignment itself does not yield a value. Hence, compound assignments
like `i = j = k;' are not allowed and result in an error.
f = x^2 + y^2 ; // overwrites the old value of f
I = jacob(f);
f,g = I[1],x^2+y^2 ; // overwrites the old values of f and g
Function without return value
.............................
6. function_name [ `(' argument_list `)' ] `;'
calls function function_name with arguments argument_list.
The function may have output (not to be confused with a return value of
type string). *Note Functions::. Functions without a return value are
specified there to have a return type 'none'.
Some of these functions have to be called without parentheses, e.g.,
`help', `LIB'.
ring r;
ideal i=x2+y2,x;
i=std(i);
degree(i); // degree has no return value but prints output
==> 2
Print command
.............
7. expression `;'
prints the value of an expression, for example, of a variable.
Use the function `print' (or the procedure show from inout.lib) to get a
pretty output of various data types, e.g., matrix or intmat. *Note
print::.
int i=2;
i;
==> 2
intmat m[2][2]=1,7,10,0;
print(m);
==> 1 7
==> 10 0
File: sing.htm, Node: Special characters, Next: Names, Prev: General command syntax, Up: The SINGULAR language
3.5.2 Special characters
------------------------
The following characters and operators have special meaning:
`='
assignment
`(', `)'
in expressions, for indexed names and for argument lists
`[', `]'
access operator for strings, integer vectors, ideals, matrices,
polynomials, resolutions, and lists. Used to build vectors of
polynomials. Example: `s[3]', `m[1,3]', `i[1..3]',
`[f,g+x,0,0,1]'.
`+'
addition operator
`-'
subtraction operator
`*'
multiplication operator
`/'
division operator. *Note Miscellaneous oddities::, for the
difference between the division operators `/' and `div'.
`%'
modulo operator
`^' or `**'
exponentiation operator
`=='
comparison operator equal
`!=' or `<>'
comparison operator not equal
`>='
comparison operator bigger or equal
`>'
comparison operator bigger
`<='
comparison operator smaller or equal
`<'
comparison operator smaller. Also used for file input. *Note
filecmd::.
`!'
boolean operator not
`&&'
boolean operator and
`||'
boolean operator or
`"'
delimiter for string constants
``'
delimiter for name substitution
`?'
synonym for `help'
`//'
comment delimiter. Comment extends to end of line.
`/*'
comment delimiter. Starts a comment which ends with `*/'.
`*/'
comment delimiter. Ends a comment which starts with `/*'.
`;'
statement separator
`,'
separator for expression lists and function arguments
`\'
escape character for `"' and `\' within strings
`..'
interval specifier returning intvec. E.g., `1..3' which is
equivalent to the intvec `1, 2, 3'.
`_'
value of expression last displayed
`~'
breakpoint in procedures
`#'
list of parameters in procedures without explicit parameter list
`$'
terminates SINGULAR
File: sing.htm, Node: Names, Next: Objects, Prev: Special characters, Up: The SINGULAR language
3.5.3 Names
-----------
SINGULAR is a strongly typed language. This means that all names (=
identifiers) have to be declared prior to their use. For the general
syntax of a declaration, see the description of declaration commands
(*note General command syntax::).
*Note Data types::, for a description of SINGULAR's data types. *Note
typeof::, for a short overview of possible types. To get information on
a name and the object named by it, the `type' command may be used (*note
type::).
It is possible to redefine an already existing name if doing so does not
change its type. A redefinition first sets the variable to the default
value and then computes the expression. The difference between
redefining and overwriting a variable is shown in the following example:
int i=3;
i=i+1; // overwriting
i;
==> 4
int i=i+1; // redefinition
==> // ** redefining i **
i;
==> 1
User defined names should start with a letter and consist of letters and
digits only. As an exception to this rule, the characters `@', and `_'
may be used as part of a name, too. Capital and small letters are
distinguished. Indexed names are built as a name followed by an
int_expression in parentheses. A list of indexed names can be built as
a name followed by an intvec_expression in parentheses.
ring R;
int n=3;
ideal j(3);
ideal j(n); // is equivalent to the above
==> // ** redefining j(3) **
ideal j(2)=x;
j(2..3);
==> j(2)[1]=x j(3)[1]=0
Names may not coincide with reserved names (keywords). Type
`reservedName();' to get a list of the reserved names. *Note
reservedName::. Names should not interfere with names of ring variables
or, more generally, with monomials. *Note Identifier resolution::.
The command `listvar' provides a list of the names in use (*note
listvar::).
The most recently printed expression is available under the special name
`_', e.g.,
ring r;
ideal i=x2+y3,y3+z4;
std(i);
==> _[1]=y3+x2
==> _[2]=z4-x2
ideal k=_;
k*k+x;
==> _[1]=y6+2x2y3+x4
==> _[2]=y3z4+x2z4-x2y3-x4
==> _[3]=z8-2x2z4+x4
==> _[4]=x
size(_[3]);
==> 3
A string_expression enclosed in ``'...``' (back ticks) evaluates to the
value of the variable named by the string_expression. This feature is
referred to as name substitution.
int foo(1)=42;
string bar="foo";
`bar+"(1)"`;
==> 42
File: sing.htm, Node: Objects, Next: Type conversion and casting, Prev: Names, Up: The SINGULAR language
3.5.4 Objects
-------------
Every object in SINGULAR has a type and a value. In most cases it has
also a name and in some cases an attribute list. The value of an object
may be examined simply by printing it with a print command: object`;'.
The type of an object may be determined by means of the `typeof'
function, the attributes by means of the `attrib' function (*note
typeof::, *note attrib::):
ring r=0,x,dp;
typeof(10);
==> int
typeof(10000000000000000);
==> number
typeof(r);
==> ring
attrib(x);
==> no attributes
attrib(std(ideal(x)));
==> attr:isSB, type int
Each object of type `poly', `ideal', `vector', `module', `map',
`matrix', `number', or `resolution' belongs to a specific ring. Also
`list', if at least one of the objects contained in the list belongs to
a ring. These objects are local to the ring. Their names can be used
for other objects in other rings. Objects from one ring can be mapped
to another ring using maps or with the commands `fetch' or `imap'.
*Note map::, *note fetch::, *note imap::.
All other types do not belong to a ring and can be accessed within every
ring and across rings. They can be declared even if there is no active
basering.
File: sing.htm, Node: Type conversion and casting, Next: Flow control, Prev: Objects, Up: The SINGULAR language
3.5.5 Type conversion and casting
---------------------------------
Type conversion
...............
Assignments convert the type of the right-hand side to the type of the
left-hand side of the assignment, if possible. Operators and functions
which require certain types of operands can also implicitly convert the
type of an expression. It is, for example, possible to multiply a
polynomial by an integer because the integer is automatically converted
to a polynomial. Type conversions do not act transitively. Possible
conversions are:
1. `int' ==> `ideal'
2. `poly' ==> `ideal'
3. `intvec' ==> `intmat'
4. `int' ==> `intvec'
5. `int' ==> `intmat'
6. `string' ==> `link'
7. `resolution' ==> `list'
8. `ideal' ==> `matrix'
9. `int' ==> `matrix'
10. `intmat' ==> `matrix'
11. `intvec' ==> `matrix'
12. `module' ==> `matrix'
13. `number' ==> `matrix'
14. `poly' ==> `matrix'
15. `vector' ==> `matrix'
16. `ideal' ==> `module'
17. `matrix' ==> `module'
18. `vector' ==> `module'
19. `int' ==> `number'
20. `int' ==> `poly'
21. `number' ==> `poly'
22. `string' ==> `proc'
23. `list' ==> `resolution'
24. `int' ==> `vector' (i ==> i*`gen(1)')
25. `poly' ==> `vector' (p ==> p*`gen(1)')
Type casting
............
An expression can be casted to another type by using a type cast
expression:
type `(' expression `)'.
Possible type casts are:
to from
`ideal' expression lists of `int', `number', `poly'
`ideal' `int', `matrix', `module', `number', `poly', `vector'
`int' `number', `poly'
`intvec' expression lists of `int', `intmat'
`intmat' `intvec' (*note intmat type cast::)
`list' expression lists of any type
`matrix' `module', `ideal', `vector', `matrix'.
There are two forms to convert something to a matrix: if
`matrix(' expression `)' is used then the size of the
matrix is determined by the size of expression.
But `matrix(' expression `,' m `,' n `)' may also be used
- the result is a $ m \times n $
m x n matrix (*note matrix type cast::)
`module' expression lists of `int', `number', `poly', `vector'
`module' `ideal', `matrix', `vector'
`number' `poly'
`poly' `int', `number'
`string' any type (*note string type cast::)
*Example:*
ring r=0,x,(c,dp);
number(3x);
==> 0
number(poly(3));
==> 3
ideal i=1,2,3,4,5,6;
print(matrix(i));
==> 1,2,3,4,5,6
print(matrix(i,3,2));
==> 1,2,
==> 3,4,
==> 5,6
vector v=[1,2];
print(matrix(v));
==> 1,
==> 2
module(matrix(i,3,2));
==> _[1]=[1,3,5]
==> _[2]=[2,4,6]
File: sing.htm, Node: Flow control, Prev: Type conversion and casting, Up: The SINGULAR language
3.5.6 Flow control
------------------
A block is a sequence of commands surrounded by { and }.
{
command;
...
}
Blocks are used whenever SINGULAR is used as a structured programming
language. The `if' and `else' structures allow conditional execution of
blocks (see *note if::, *note else::). `for' and `while' loops are
available for repeated execution of blocks (see *note for::, *note
while::). In procedure definitions the main part and the example
section are blocks as well(see *note proc::).
* Menu:
* break::
* quit::
* keepring::
* export::
* if::
* else::
* for::
* while::
* proc::
* return::
* continue::
File: sing.htm, Node: Input and output, Next: Procedures, Prev: The SINGULAR language, Up: General concepts
3.6 Input and output
====================
SINGULAR's input and output (short, I/O) is realized using links. Links
are the communication channels of SINGULAR, i.e., something SINGULAR can
write to and read from. In this section, a short overview of the usage
of links and of the different link types is given.
For loading of libraries, see *note LIB::. For executing program
scripts, see *note filecmd::.
Monitoring
----------
A special form of I/O is monitoring. When monitoring is enabled,
SINGULAR makes a typescript of everything printed on your terminal to a
file. This is useful to create a protocol of a SINGULAR session. The
`monitor' command enables and disables this feature (*note monitor::).
How to use links
----------------
Recall that links are the communication channels of SINGULAR, i.e.,
something SINGULAR can write to and read from using the functions
`write' and `read'. There are furthermore the functions `dump' and
`getdump' which store resp. retrieve the content of an entire SINGULAR
session to, resp. from, a link. The `dump' and `getdump' commands are
not available for DBM links.
For more information, see *note write::, *note read::, *note dump::,
*note getdump::.
*Example:*
ring r; poly p = x+y;
dump("MPfile:w test.mp"); // dump the session to the file test.mp
kill r; // kill the basering
listvar();
==> // LIB [0] string standard.lib
getdump("MPfile:r test.mp");// read the dump from the file
listvar();
==> // r [0] *ring
==> // p [0] poly
==> // LIB [0] string standard.lib
Specifying a link can be as easy as specifying a filename as a string.
Except for MPtcp links, links even do not need to be explicitly opened
or closed before, resp. after, they are used. To explicitly open or
close a link, the `open', resp. `close', commands may be used (see *note
open::, *note close::).
Links have various properties which can be queried using the `status'
function (*note status::).
*Example:*
link l = "MPtcp:fork";
l;
==> // type : MPtcp
==> // mode : fork
==> // name :
==> // open : no
==> // read : not ready
==> // write: not ready
open(l);
status(l, "open");
==> yes
close(l);
status(l, "open");
==> no
ASCII links
-----------
Data that can be converted to a string that can be written into files
for storage or communication with other programs. The data are written
in plain ASCII format. Reading from an ASCII link returns a string --
conversion into other data is up to the user. This can be done, for
example, using the command `execute' (*note execute::).
ASCII links should primarily be used for storing small amounts of data,
especially if it might become necessary to manually inspect or
manipulate the data.
*Note ASCII links::, for more information.
*Example:*
// (over)write file test.ascii, link is specified as string
write(":w test.ascii", "int i =", 3, ";");
// reading simply returns the string
read("test.ascii");
==> int i =
==> 3
==> ;
==>
// but now test.ascii is "executed"
execute(read("test.ascii"));
i;
==> 3
MPfile links
------------
Data is stored in the binary MP format. Read and write access is very
fast compared to ASCII links. All data (including such data that cannot
be converted to a string) can be written to an MPfile link. Reading
from an MPfile link returns the written expressions (i.e., not a string,
in general).
MPfile links should primarily be used for storing large amounts of data
(like dumps of the content of an entire SINGULAR session), and if the
data to be stored cannot be easily converted from or to a string (like
rings, or maps).
MPfile links are implemented on Unix-like operating systems only.
*Note MPfile links::, for more information.
*Example:*
ring r;
// (over)write MPfile test.mp, link is specified as string
write("MPfile:w test.mp", x+y);
kill r;
def p = read("MPfile:r test.mp");
typeof(p); p;
==> poly
==> x+y
MPtcp links
-----------
Data is communicated with other processes (e.g., SINGULAR processes)
which may run on the same computer or on different ones. Data exchange
is accomplished using TCP/IP links in the binary MP format. Reading
from an MPtcp link returns the written expressions (i.e., not a string,
in general).
MPtcp links should primarily be used for communications with other
programs or for parallel computations (see, for example, *note
Parallelization with MPtcp links::).
MPtcp links are implemented on Unix-like operating systems only.
*Note MPtcp links::, for more information.
*Example:*
ring r;
link l = "MPtcp:launch"; // declare a link explicitly
open(l); // needs an open, launches another SINGULAR as a server
write(l, x+y);
kill r;
def p = read(l);
typeof(p); p;
==> poly
==> x+y
close(l); // shuts down SINGULAR server
DBM links
---------
Data is stored in and accessed from a data base. Writing is
accomplished by a key and a value and associates the value with the key
in the specified data base. Reading is accomplished w.r.t. a key, the
value associated to it is returned. Both the key and the value have to
be specified as strings. Hence, DBM links may be used only for data
which may be converted to or from strings.
DBM links should primarily be used when data needs to be accessed not in
a sequential way (like with files) but in an associative way (like with
data bases).
*Note DBM links::, for more information.
*Example:*
ring r;
// associate "x+y" with "mykey"
write("DBM:w test.dbm", "mykey", string(x+y));
// get from data base what is stored under "mykey"
execute(read("DBM: test.dbm", "mykey"));
==> x+y
File: sing.htm, Node: Procedures, Next: Libraries, Prev: Input and output, Up: General concepts
3.7 Procedures
==============
Procedures contain sequences of commands of the SINGULAR language. They
are used to extend the set of commands with user defined commands.
Procedures are defined by either typing them on the command line or by
loading them from a so-called library file with the LIB command, see
*note LIB::. Procedures are invoked like normal built-in commands,
i.e., by typing their name followed by the list of arguments in
parentheses. The invocation then executes the sequence of commands
stored in the specified procedure. All defined procedures can be
displayed by the command `listvar(proc);'.
* Menu:
* Procedure definition::
* Names in procedures::
* Parameter list::
* Procedure commands::
File: sing.htm, Node: Procedure definition, Next: Names in procedures, Prev: Procedures, Up: Procedures
3.7.1 Procedure definition
--------------------------
*Syntax:*
[`static'] `proc' proc_name [parameter_list]
["help_text"]
`{'
\quad
procedure_body
`}'
[`example'
`{'
\quad
sequence_of_commands;
`}']
*Purpose:*
defines a new function, the `proc' proc_name, with the additional
information help_text, which is copied to the screen by `help
proc_name;' and the `example' section which is executed by `example
proc_name;'.
The help_text, the parameter_list, and the example section are
optional. The default for a parameter_list is `(list #)', see
*note Parameter list::. The help and example sections are ignored
if the procedure is defined interactively, i.e., if it was not
loaded from a file by a LIB command (*note LIB::).
Specifying `static' in front of the proc-definition (in a library
file) makes this procedure local to the library, i.e., accessible
only for the other procedures in the same library, but not for the
users. So there is no reason anymore to define a procedure within
another one (it just makes debugging harder).
Example of an interactive procedure definition
..............................................
proc milnor_number (poly p)
{
ideal i= std(jacob(p));
int m_nr=vdim(i);
if (m_nr<0)
{
"// not an isolated singularity";
}
return(m_nr); // the value of m_nr is returned
}
ring r1=0,(x,y,z),ds;
poly p=x^2+y^2+z^5;
milnor_number(p);
==> 4
Example of a procedure definition in a library
..............................................
First, the library definition:
// Example of a user accessible procedure
proc tab (int n)
"USAGE: tab(n); (n integer)
RETURNS: string of n space tabs
EXAMPLE: example tab; shows an example"
{ return(internal_tab(n)); }
example
{
"EXAMPLE:"; echo=2;
for(int n=0; n<=4; n=n+1)
{ tab(4-n)+"*"+tab(n)+"+"+tab(n)+"*"; }
}
// Example of a static procedure
static proc internal_tab (int n)
{ return(" "[1,n]); }
Now, we load the library and execute the procedures defined there:
LIB "sample.lib"; // load the library sample.lib
example tab; // show an example
==> // proc tab from lib sample.lib
==> EXAMPLE:
==> for(int n=0; n<=4; n=n+1)
==> { tab(4-n)+"*"+tab(n)+"+"+tab(n)+"*"; }
==> *+*
==> * + *
==> * + *
==> * + *
==> * + *
==>
"*"+tab(3)+"*"; // use the procedure tab
==> * *
// the static procedure internal_tab is not accessible
"*"+internal_tab(3)+"*";
==> ? 'sample.lib::internal_tab()' is a local procedure and cannot be acce\
ssed by an user.
==> ? error occurred in line 5: ` "*"+internal_tab(3)+"*";`
// show the help section for tab
help tab;
==> // ** Could not get IdxFile.
==> // ** Either set environment variable SINGULAR_IDX_FILE to IdxFile,
==> // ** or make sure that IdxFile is at /home/hannes/singular/2-0/doc/singu\
lar.idx
==> // proc tab from lib sample.lib
==> proc tab (int n)
==> USAGE: tab(n); (n integer)
==> RETURNS: string of n space tabs
==> EXAMPLE: example tab; shows an example
Guidelines for the help text of a procedure
...........................................
There are no enforced rules on the format of the help section of a
procedure.
Nevertheless, we recommend that the help text of a procedure should
contain information about the usage, purpose, return values and
generated objects. Particular assumptions or limitations should be
listed. It should also be mentioned if global objects are generated or
manipulated.
The help text of procedures contained in libraries of the SINGULAR
distribution should furthermore comply with certain rules as explained
in *note The help string of procedures::.
File: sing.htm, Node: Names in procedures, Next: Parameter list, Prev: Procedure definition, Up: Procedures
3.7.2 Names in procedures
-------------------------
All variables are local to the procedure they are defined in. Locally
defined variables cannot interfere with names in other procedures and
are automatically deleted after leaving the procedure.
Internally, local variables are stored using the nesting level. A
variable is said to have nesting level 1, if it is local to a procedure
that was called interactively, nesting level 2, if it is local to a
procedure that was called by a procedure of nesting level 1 etc.
`listvar()' also displays the nesting level, nesting level 0 is used for
global objects (see *note listvar::). A ring may be 'moved up' by one
nesting level with `keepring' (see *note keepring::). All variables
living in that ring are moved together with that ring.
To keep local variables after leaving the procedure, they have to be
exported (i.e. made known) to some higher level by the `export' command
(*note export::).
*Example:*
proc xxx
{
int k=4; //defines a local variable k
int result=k+2;
export(result); //defines the global variable "result".
}
xxx();
listvar(all);
==> // result [0] int 6
==> // LIB [0] string standard.lib
Note that the variable `result' became a global variable after the
execution of `xxx'.
File: sing.htm, Node: Parameter list, Next: Procedure commands, Prev: Names in procedures, Up: Procedures
3.7.3 Parameter list
--------------------
`*Syntax:*'
`( )'
`(' parameter_definition `)'
`*Purpose:*'
defines the number, type and names of the arguments to a `proc'.
The parameter_list is optional. The default for a parameter_list
is `(list #)' which means the arguments are referenced by `#[1],
#[2]', etc.
`*Example:*'
proc x0
{
// can be called with
... // any number of arguments of any type: #[1], #[2],...
// number of arguments: size(#)
}
proc x1 ()
{
... // can only be called without arguments
}
proc x2 (ideal i, int j)
{
... // can only be called with 2 arguments,
// which can be converted to ideal resp. int
}
proc x3 (i,j)
{
... // can only be called with 2 arguments
// of any type
// (i,j) is the same as (def i,def j)
}
proc x5 (i,list #)
{
... // can only be called with at least 1 argument
// number of arguments: size(#)+1
}
`*Note:*'
The parameter_list may stretch across multiple lines.
A parameter may have any type (including the types `proc' and
`ring'). If a parameter is of type ring, then it can only be
specified by name, but not with a type, e.g.
proc x6 (r)
{
... // this is correct even if the parameter is a ring
}
proc x7 (ring r)
{
... // this is NOT CORRECT
}
File: sing.htm, Node: Procedure commands, Prev: Parameter list, Up: Procedures
3.7.4 Procedure commands
------------------------
Some commands only make sense inside a procedure, since they make
objects known to the nesting level from which the procedure was called
or to all nesting levels.
* Menu:
See
* export::
* keepring::
* return::
See *note export::; *note keepring::; *note return::.
File: sing.htm, Node: Libraries, Next: Guidelines for writing a library, Prev: Procedures, Up: General concepts
3.8 Libraries
=============
A library is a collection of SINGULAR procedures in a file.
SINGULAR reads a library with the command `LIB'. General information
about the library is displayed by the command `help libname_lib'. After
loading the library, its procedures can be used like the built-in
SINGULAR functions.
To have the full functionality of a built-in function libraries have to
comply with the few syntax rules described below.
Furthermore, libraries which are to be included in the SINGULAR
distribution, have to comply with certain rules as explained in *note
Guidelines for writing a library::.
* Menu:
* Loading of a library::
* Format of a library::
File: sing.htm, Node: Loading of a library, Next: Format of a library, Up: Libraries
3.8.1 Loading of a library
--------------------------
Libraries can be loaded with the `LIB' command:
`*Syntax:*'
`LIB' string_expression `;'
`*Type:*'
none
`*Purpose:*'
reads a library of procedures from a file. If the given filename
does not start with `.' or `/' and can not be located in the
current directory, each directory contained in the library
`SearchPath' is searched for file of this name.
`*Note on SearchPath:*'
The the library `SearchPath' is constructed at SINGULAR start-up
time as follows:
1. the directories contained in the environment variable
`SINGULARPATH' are appended
2. the directories `$BinDir/LIB', `$RootDir/LIB',
`$RootDir/../LIB', `$DefaultDir/LIB', `$DefaultDir/../LIB' are
appended, where
* `$BinDir' is the value of the environment variable
`SINGULAR_BIN_DIR', if set, or, if not set, the directory
in which the SINGULAR program resides
* `$RootDir' is the value of the environment variable
`SINGULAR_ROOT_DIR', if set, or, if not set,
`$BinDir/../'.
* `$DefaultDir' is the value of the environment variable
`SINGULAR_DEFAULT_DIR', if set, or `/usr/local/Singular/'
on a Unix platform, `\Singular\' on a Windows 95/98/NT
platform, and `::Singular:' on a Macintosh.
3. all directories which do not exist are removed from the
`SearchPath'.
For setting environment variables see *note system::, or consult
the manual of your shell.
The library `SearchPath' can be examined by starting up SINGULAR
with the option `-v', or by issuing the command
`system("--version");'.
`*Note on standard.lib:*'
Unless SINGULAR is started with the `--no-stdlib' option, the
library `standard.lib' is automatically loaded at start-up time.
Only the names of the procedures in the library are loaded, the body of
the procedures is read during the first call of this procedure. This
minimizes memory consumption by unused procedures. When SINGULAR is
started with the `-q' or `--quiet' option, no message about the loading
of a library is displayed. More precisely, option `-q' (and likewise
`--quiet') unsets option `loadLib' to inhibit monitoring of library
loading (*note option::).
All loaded libraries are displayed by the `LIB;' command:
option(loadLib); // show loading of libraries;
// standard.lib is loaded
LIB;
==> standard.lib
// the names of the procedures of inout.lib
LIB "inout.lib"; // are now known to Singular
==> // ** loaded inout.lib (1.21.2.5,2002/06/12)
LIB;
==> standard.lib,inout.lib
* Menu:
See
* Command line options::
* LIB::
* Procedures and libraries::
* SINGULAR libraries::
* proc::
* standard_lib::
* string::
* system::
See *note Command line options::; *note LIB::; *note Procedures and
libraries::; *note SINGULAR libraries::; *note proc::; *note
standard_lib::; *note string::; *note system::.
File: sing.htm, Node: Format of a library, Prev: Loading of a library, Up: Libraries
3.8.2 Format of a library
-------------------------
A library file can contain comments, a category-, info- and
version-string definition, `LIB' commands, `proc' commands and `proc'
commands with `example' and `help' sections, i.e., the following
keywords are allowed: `category', `info', `version', `LIB', `/* ... */',
`//', `[static] proc'. Anything else is not recognized by the parser of
SINGULAR and leads to an error message while loading the library. If an
error occurs, loading is aborted and an error message is displayed,
specifying the type of error and the line where it was detected.
The category-, info- and version-string are defined as follows:
`*Syntax:*'
`info' = string_constant `;'
`*Purpose:*'
defines the general help for the library. This text is displayed on
`help libname_lib;'.
`*Example:*'
info="
This could be the general help of a library.
Quotes must be escaped with a \ such as \"
";
`*Note:*'
In the info-string the characters \ and " must be preceded by a \
(escaped). It is recommended that the info string is placed on the
top of a library file and contains general information about the
library as well as a listing of all procedures available to the
users (with a one line description of each procedure).
Although there is no enforced format of the info string of a
library, we recommend that you follow certain rules as explained in
*note The help string of a library::.
`*Syntax:*'
`version' = string_constant `;'
`*Purpose:*'
defines the version number for the library. It is displayed when
the library is loaded.
`*Example:*'
version="$ Id: sample.lib,v 1.2 1998/05/07 singular Exp $";
version="some version string";
`*Note:*'
It is common practice to simply define the version string to be `"$
I'`d:$"' and let a version control system expand it.
`*Syntax:*'
`category' = string_constant `;'
`*Purpose:*'
defines the category for the library.
`*Example:*'
category="Utilities";
`*Note:*'
reserved for sorting the libraries into categories.
File: sing.htm, Node: Guidelines for writing a library, Next: Debugging tools, Prev: Libraries, Up: General concepts
3.9 Guidelines for writing a library
====================================
Although there are very few enforced rules on how libraries are written
(see *note Libraries::), it is recommended that the libraries comply
with the guidelines explained in this section, so that debugging and
understanding are made easier.
*Note:* For libraries which are to be included in the SINGULAR
distribution, the following guidelines are mandatory.
* Menu:
* Procedures in a library::
* Documentation of a library::
* Typesetting of help strings::
* The help string of a library::
* The help string of procedures::
* template_lib::
File: sing.htm, Node: Procedures in a library, Next: Documentation of a library, Up: Guidelines for writing a library
3.9.1 Procedures in a library
-----------------------------
In this section we list miscellaneous recommendations on how procedures
contained in a library should be implemented.
1. The info- and version-string should appear at the beginning of the
library, before procedure definitions.
2. The info-string should have the format as explained in *note The
help string of a library::.
3. Each procedure which should not be accessible by users should be
declared `static'.
4. Each procedure which is not declared `static' should have a help
and example section as explained in *note Procedure definition::.
Such procedures should furthermore carefully check any assumptions
made about their input (like the type of list elements), and, if
necessary, omit an error using the function *note ERROR::.
5. No procedures should be defined within the body of another
procedure.
6. If the value of the reserved variable `printlevel' (*note
printlevel::) is greater than 0 then interactive user-input, i.e.,
the usage of functions like `pause("..")' or `read("");' (*note
read::), may be requested.
7. If the value of the reserved variable `printlevel' (*note
printlevel::) is 0 then interactive user-input, i.e., the usage of
functions like `pause("..")' or `read("");' (*note read::), may
*not* be requested. Instead, an error (using the function *note
ERROR::) should be reported together with the recommendation on
increasing the value of the reserved variable `printlevel'.
8. It is often useful for a procedure to print out comments, either to
explain results or to display intermediate computations. However,
if this procedure is called by another procedure, such comments are
confusing and disturbing in most cases.
SINGULAR offers an elegant solution, which requires the usage of
the SINGULAR function *note dbprint:: and the reserved variables
*note printlevel::, and *note voice:: (`voice' counts the nesting
of procedures; It has the value 1 on the top level, 2 inside the
first procedure etc.; `printlevel' has the value 0 by default, but
can be set to any integer value by the user).
For example, if the following procedure `Test' is called directly
from the top level then `comment1' is displayed (i.e., printed out)
but not `comment2'; and nothing is displayed if `Test' is called
from within any other procedure. However, if `printlevel' is set
to a value k with k>0, then `comment1' (resp. `comment2') is
displayed provided that `Test' is called from other procedures,
with a nesting level up to k (resp. k-1).
Note furthermore, that the example part of a procedure behaves in
this respect like a procedure (i.e., the value of `voice' is 1).
Therefore, the command `printlevel=1;' is necessary for `comment1'
to be displayed on ` example Test;'. However, since printlevel is a
global variable, it should be reset to the old value at the end of
the example part.
proc Test
"USAGE: ...
...
EXAMPLE: example Test; shows an example
"
{ ...
int p = printlevel - voice + 3;
...
dbprint(p,"comment1");
dbprint(p-1,"comment2");
// dbprint prints only if p > 0
...
}
example
{ "EXAMPLE:"; echo = 2;
int p = printlevel; //store old value of printlevel
printlevel = 1; //assign new value to printlevel
...
Test();
printlevel = p; //reset printlevel to old value
}
File: sing.htm, Node: Documentation of a library, Next: Typesetting of help strings, Prev: Procedures in a library, Up: Guidelines for writing a library
3.9.2 Documentation of a library
--------------------------------
The typesetting language in which the SINGULAR documentation is written
is `texinfo'. Based on various tools, `info, dvi, ps,' and `html'
versions of the `texinfo' documentation are generated.
Starting with SINGULAR version 1-3, the `texinfo' documentation of all
libraries of the SINGULAR distribution is generated automatically from
their source code.
More precisely, for each library,
- the info string of the library is parsed and typeset as explained
in *note Typesetting of help strings::.
- the help string of each procedure listed in the `PROCEDURE:'
section of the library info string is parsed and typeset as
explained in *note Typesetting of help strings::.
- the example of each procedure listed in the `PROCEDURE:' section of
the library info string is computed and its output is included into
the documentation.
For a uniform look-and-feel of the library documentation, library
developers should
- follow the recommendation of *note The help string of a library::
and *note The help string of procedures::.
- consult the source code of libraries like `template.lib' (*note
template_lib::) for examples on how library documentations are
written.
- make sure that each procedure listed in the `PROCEDURE:' section of
the library info string has a help string and an example section.
- not use interactive functions like `pause("..")' or `read("");'
(*note read::) and should limit the length of input lines to 60
characters in the example section of procedures.
- carefully check the generated documentation of their libraries in
its various formats using the `lib2doc' (*note lib2doc::) utility.
* Menu:
* lib2doc::
File: sing.htm, Node: lib2doc, Up: Documentation of a library
3.9.2.1 lib2doc
...............
`lib2doc' is a utility to generate the stand-alone documentation for a
SINGULAR library in various formats.
The `lib2doc' utility should be used by developers of SINGULAR libraries
to check the generation of the documentation of their libraries.
`lib2doc' can be downloaded from
`ftp://www.mathematik.uni-kl.de/pub/Math/Singular/misc/lib2doc.tar.gz'
*Important:*
To use `lib2doc', you need to have `perl' (version 5 or higher),
`texinfo' (version 3.12 or higher) and `Singular' and `libparse'
(version 1-3-4 or higher) installed on your system.
To generate the documentation for a library, follow these steps:
1. Unpack lib2doc.tar.gz
gzip -dc lib2doc.tar.gz | tar -pxf -
and
cd lib2doc
2. Edit the beginning of the file `Makefile', filling in the values
for `SINGULAR' and `LIBPARSE'. Check also the values of `PERL' and
`LATEX2HTML'.
3. Copy your library to the current directory:
cp /mylib.lib .
4. Now you can run the following commands:
`make mylib.hlp'
Generates the file `mylib.hlp' - the info file for the
documentation of `mylib.lib'. This file can be viewed with
info -f mylib.hlp
`make mylib.dvi'
Generates the file `mylib.dvi' - the dvi file for the
documentation of `mylib.lib'. This file can be viewed with
xdvi mylib.dvi
`make mylib.ps'
Generates the file `mylib.ps' - the PostScript file for the
documentation of `mylib.lib'. This file can be viewed with
(for example)
ghostview mylib.dvi
`make mylib.html'
Generates the file `mylib.html' - the HTML file for the
documentation of `mylib.lib'. This file can be viewed with
(for example)
netscape mylib.html
`make clean'
Deletes all generated files.
Note that you can safely ignore messages complaining about
undefined references.
File: sing.htm, Node: Typesetting of help strings, Next: The help string of a library, Prev: Documentation of a library, Up: Guidelines for writing a library
3.9.3 Typesetting of help strings
---------------------------------
The help strings of procedures and info strings of libraries which are
included in the distribution of SINGULAR are parsed and automatically
converted into the texinfo format (the typesetting language in which the
documentation of SINGULAR is written).
For optimal typesetting results, the guidelines for writing libraries
and procedures should be followed, and the following points should be
kept in mind:
* If a help string starts with an `@' sign, then no parsing is done,
and the help string is assumed to be already in the texinfo format.
* help strings are typeset within a `@table @asis' environment (which
is similar to a latex `description' environment).
* If a line starts with only uppercase words and contains a colon,
then the text up to the colon is taken to be the description-string
of an item and the text following the colon is taken to be the
content of the item.
* If the description-string of an item matches
`EXAMPLE'
then this item and its content is ignored.
`SEE ALSO'
then the content of the item is assumed to be comma-separated
words which are valid references to other texinfo nodes of the
manual. (e.g., all procedure and command names are also
texinfo nodes).
`KEYWORDS' (or, `KEYPHRASES')
then the content of the item is assumed to be a
semicolon-separated list of phrases which are taken as keys
for the index of the manual (N.B. the name of a
procedure/library is automatically added to the index keys).
`PROCEDURES'
then the content of the item is assumed to be a summary
description of the procedures contained in the library.
Separate texinfo nodes (subsections in printed documents) are
*only* created out of the help strings of such procedures
which appear in the summary description of a library.
`LIBRARY'
then the content of the item is assumed to be a one-line
description of a library. If this one-line description consist
of only uppercase characters, then it is typeset in all
lowercase characters in the manual (otherwise it is left as
is).
* For the content of an item, the following texinfo markup elements
are recognized (and, their content not further manipulated):
`@*'
to enforce a line-break.
Example:
`old line @* new line'
==>
old line
new line
`@ref{...}'
References to other parts of the SINGULAR manual can be set
using one of the following `@ref{node}' constructs. Notice
that `node' must be the name of a section of the SINGULAR
manual. In particular, it may be a name of a function, library
or library procedure.
`@xref{node}'
for a reference to the node `node' at the beginning of a
sentence.
`@ref{node}'
for a reference to the node `node' at the end of a
sentence.
`@pxref{node}'
for a reference to the node `node' within parenthesis.
Example:
`@xref{Tropical Storms}, for more info.'
==>*Note Hurricanes::, for more info.
==>See Section 3.1 [Hurricanes], page 24, for more info.
`For more information, see @ref{Hurricanes}.'
==>For more information, see *Note Hurricanes::.
==>For more information, see Section 3.1 [Hurricanes],
page 24.
`... storms cause flooding (@pxref{Hurricanes}) ...'
==>... storms cause flooding (*Note Hurricanes::) ...
==>... storms cause flooding (see Section 3.1
[Hurricanes], page 24)
`@math{..}'
for typesetting of small (i.e., which do not go over multiple
lines) mathematical expressions in LaTeX math-mode syntax.
Example:
`@math{\alpha}'
==>
\alpha $\alpha$
Note:
Mathematical expressions inside `@math{..}' may not
contain curly parenthesis and the "at" sign, i.e., may
not contain `{,},@'.
`@code{..}'
for typesetting of small (i.e., which do not go over multiple
lines) strings in typewriter font.
Example:
`@code{typewriter font}'
==>
`typewriter font'
Note:
The string inside `@code{..}' may not contain curly
parenthesis and the "at" sign, i.e., may not contain
`{,},@'.
`@example'
`...'
`@end example'
for pre-formatted text which is indented and typeset in
typewriter font.
Example:
before example
@example
in example
notice extra identation and
escape of special characters like @{,@},@@
@end example
after example
==>
before example
in example
notice extra identation and
escape of special characters like {,},@
after example
Note:
The characters {,},@ have to be escaped by an @ sign
inside an @example environment.
`@format'
`...'
`@end format'
for pre-formatted text which is not indented and typeset in
normal font.
Example:
before format
@format
in format
no extra identation but still
escape of special characters like @{,@},@@
@end format
after format
==>
before format
in format
no extra identation but still
escape of special characters like {,},@
after format
Note:
The characters {,},@ have to be escaped by an @ sign
inside an @example environment.
`@texinfo'
`...'
`@end texinfo'
for text which is written in pure texinfo.
Example:
@texinfo
Among others, within a texinfo environment
one can use the tex environment to typeset
more complex mathematical like
@tex
$i_{1,1} $
@tex
@end texinfo
==>
Among others, within a texinfo environment one can use
the tex environment to typeset more complex mathematical
like $ i_{1,1} $
Furthermore, a line-break is inserted in front of each line whose
previous line is shorter than 60 characters and does not contain
any of the above described recognized texinfo markup elements.
See also *note template_lib:: for an examples of the typesetting rules
explained here.
File: sing.htm, Node: The help string of a library, Next: The help string of procedures, Prev: Typesetting of help strings, Up: Guidelines for writing a library
3.9.4 The help string of a library
----------------------------------
The help (or, info) string of a library should have the following
format:
info="
LIBRARY:
AUTHOR:
[SEE ALSO: ]
[KEYWORDS: ]
PROCEDURES:
;
.
.
;
";
Only such procedures should be listed in the `PROCEDURE' section which
are not `static' and which have a help and example section.
The purpose of the one line procedure descriptions is not to give a
short help for the procedure, but to help the user decide what procedure
might be the right one for the job. Details can then be found in the
help section of each procedure. Therefore parameters may be omitted or
abbreviated if necessary. If this description consists of only
upper-case characters, then it will be typeset in all lowercase
characters in the manual.
For more information, see *note Typesetting of help strings::. For an
example, see *note template_lib::.
File: sing.htm, Node: The help string of procedures, Next: template_lib, Prev: The help string of a library, Up: Guidelines for writing a library
3.9.5 The help string of procedures
-----------------------------------
The help string of a procedure should have the following format:
USAGE: ();
[CREATE: ]
RETURN:
[NOTE: ]
[SEE ALSO: ]
[KEYWORDS: ]
EXAMPLE: example ; shows an example
Further arbitrary items (like `THEORY:', or `BACKGROUND:') are
recognized, as well, but should be used diligently.
Remember that help strings are formatted as explained in *note
Typesetting of help strings::. In particular, descriptions may contain
the texinfo markup elements `@*, @math{..}, @code{..}, @example,
@format, @texinfo' to better control their typesetting. See *note
msum::, *note mdouble::, *note mtripple:: for examples.
File: sing.htm, Node: template_lib, Prev: The help string of procedures, Up: Guidelines for writing a library
3.9.6 template_lib
------------------
First, we show the source-code of a template library:
////////////////////////////////////////////////////////////////////
// version string automatically expanded by CVS
version="Id: general.tex,v 1.1 2003/08/08 14:27:06 pertusus Exp $";
category="Miscellaneous";
// summary description of the library
info="
LIBRARY: template.lib A Template for a Singular Library
AUTHOR: Olaf Bachmann, email: obachman@mathematik.uni-kl.de
SEE ALSO: standard_lib, Guidelines for writing a library,
Typesetting of help strings
KEYWORDS: library, template.lib; template.lib; library, info string
PROCEDURES:
mdouble(int) return double of int argument
mtripple(int) return three times int argument
msum([int,..,int]) sum of int arguments
";
////////////////////////////////////////////////////////////////////
proc mdouble(int i)
"USAGE: mdouble(i); i int
RETURN: int: i+i
NOTE: Help string is in pure ASCII
this line starts on a new line since previous line is short
mdouble(i): no new line
SEE ALSO: msum, mtripple, Typesetting of help strings
KEYWORDS: procedure, ASCII help
EXAMPLE: example mdouble; shows an example"
{
return (i + i);
}
example
{ "EXAMPLE:"; echo = 2;
mdouble(0);
mdouble(-1);
}
////////////////////////////////////////////////////////////////////
proc mtripple(int i)
"@c we do texinfo here
@table @asis
@item @strong{Usage:}
@code{mtripple(i)}; @code{i} int
@item @strong{Return:}
int: @math{i+i+i}
@item @strong{Note:}
Help is in pure Texinfo
@*This help string is written in texinfo, which enables you to use,
among others, the @@math command for mathematical typesetting (like
@math{\alpha, \beta}).
@*It also gives more control over the layout, but is, admittingly,
more cumbersome to write.
@end table
@c use @c ref contstuct for references
@cindex procedure, texinfo help
@c ref
@strong{See also:}
@ref{mdouble}, @ref{msum}, @ref{Typesetting of help strings}
@c ref
"
{
return (i + i + i);
}
example
{ "EXAMPLE:"; echo = 2;
mtripple(0);
mtripple(-1);
}
////////////////////////////////////////////////////////////////////
proc msum(list #)
"USAGE: msum([i_1,..,i_n]); @code{i_1,..,i_n} def
RETURN: Sum of int arguments
NOTE: This help string is written in a mixture of ASCII and texinfo
@* Use a @ref constructs for references (like @pxref{mtripple})
@* Use @code for typewriter font (like @code{i_1})
@* Use @math for simple math mode typesetting (like @math{i_1}).
@* Note: No parenthesis like } are allowed inside @math and @code
@* Use @example for indented preformatted text typeset in typewriter
font like
@example
this --> that
@end example
Use @format for preformatted text typeset in normal font
@format
this --> that
@end format
Use @texinfo for text in pure texinfo
@texinfo
@expansion{}
@tex
$i_{1,1}$
@end tex
@end texinfo
Notice that
automatic linebreaking is still in affect (like on this line).
SEE ALSO: mdouble, mtripple, Typesetting of help strings
KEYWORDS: procedure, ASCII/Texinfo help
EXAMPLE: example msum; shows an example"
{
if (size(#) == 0) { return (0);}
if (size(#) == 1) { return (#[1]);}
int i;
def s = #[1];
for (i=2; i<=size(#); i++)
{
s = s + #[i];
}
return (s);
}
example
{ "EXAMPLE:"; echo = 2;
msum();
msum(4);
msum(1,2,3,4);
}
After typesetting, the library appears in the document as follows (with
one subsection for each procedure):
*Library:*
template.lib
*Purpose:*
A Template for a Singular Library
*Author:*
Olaf Bachmann, email: obachman@mathematik.uni-kl.de
*Procedures:*
* Menu:
* mdouble:: return double of int argument
* mtripple:: return three times int argument
* msum:: sum of int arguments
* Menu:
See also:
* Guidelines for writing a library::
* Typesetting of help strings::
* standard_lib::
*See also:* *note Guidelines for writing a library::; *note Typesetting
of help strings::; *note standard_lib::.
File: sing.htm, Node: mdouble, Next: mtripple, Up: template_lib
3.9.6.1 mdouble
...............
Procedure from library `template.lib' (*note template_lib::).
*Usage:*
mdouble(i); i int
*Return:*
int: i+i
*Note:*
Help string is in pure ASCII
this line starts on a new line since previous line is short
mdouble(i): no new line
*Example:*
LIB "template.lib";
mdouble(0);
==> 0
mdouble(-1);
==> -2
* Menu:
See also:
* Typesetting of help strings::
* msum::
* mtripple::
*See also:* *note Typesetting of help strings::; *note msum::; *note
mtripple::.
File: sing.htm, Node: mtripple, Next: msum, Prev: mdouble, Up: template_lib
3.9.6.2 mtripple
................
Procedure from library `template.lib' (*note template_lib::).
*Usage:*
`mtripple(i)'; `i' int
*Return:*
int: i+i+i $i+i+i$
*Note:*
Help is in pure Texinfo
This help string is written in texinfo, which enables you to use,
among others, the @math command for mathematical typesetting (like
\alpha, \beta $\alpha, \beta$
).
It also gives more control over the layout, but is, admittingly,
more cumbersome to write.
* Menu:
*See also:*
* Typesetting of help strings::
* mdouble::
* msum::
*See also:* *note Typesetting of help strings::; *note mdouble::; *note
msum::.
*Example:*
LIB "template.lib";
mtripple(0);
==> 0
mtripple(-1);
==> -3
File: sing.htm, Node: msum, Prev: mtripple, Up: template_lib
3.9.6.3 msum
............
Procedure from library `template.lib' (*note template_lib::).
*Usage:*
msum([i_1,..,i_n]); `i_1,..,i_n' def
*Return:*
Sum of int arguments
*Note:*
This help string is written in a mixture of ASCII and texinfo
Use a @ref constructs for references (like *note mtripple::)
Use @code for typewriter font (like `i_1')
Use @math for simple math mode typesetting (like i_1 $i_1$
).
Note: No parenthesis like } are allowed inside @math and @code
Use @example for indented preformatted text typeset in typewriter
font like
this --> that
Use @format for preformatted text typeset in normal font
this -> that
Use @texinfo for text in pure texinfo
==> $i_{1,1}$
Notice that
automatic linebreaking is still in affect (like on this line).
*Example:*
LIB "template.lib";
msum();
==> 0
msum(4);
==> 4
msum(1,2,3,4);
==> 10
* Menu:
See also:
* Typesetting of help strings::
* mdouble::
* mtripple::
*See also:* *note Typesetting of help strings::; *note mdouble::; *note
mtripple::.
File: sing.htm, Node: Debugging tools, Prev: Guidelines for writing a library, Up: General concepts
3.10 Debugging tools
====================
If SINGULAR does not come back to the prompt while calling a user
defined procedure, probably a bracket or a `"' is missing. The easiest
way to leave the procedure is to type some brackets or `"' and then
.
* Menu:
* Tracing of procedures::
* Source code debugger::
* Break points::
* Printing of data::
* libparse::
File: sing.htm, Node: Tracing of procedures, Next: Source code debugger, Prev: Debugging tools, Up: Debugging tools
3.10.1 Tracing of procedures
----------------------------
Setting the `TRACE' variable to 1 (resp. 3) results in a listing of the
called procedures (resp. together with line numbers). If `TRACE' is set
to 4, `Singular' displays each line before its interpretation and waits
for the key being pressed.
* Menu:
* TRACE var::
See *note TRACE var::.
*Example:*
proc t1
{
int i=2;
while (i>0)
{ i=i-1; }
}
TRACE=3;
t1();
==>
==> entering t1 (level 0)
==> {1}{2}{3}{4}{5}{4}{5}{6}{7}{4}{5}{6}{7}{4}{6}{7}{8}
==> leaving t1 (level 0)
File: sing.htm, Node: Source code debugger, Next: Break points, Prev: Tracing of procedures, Up: Debugging tools
3.10.2 Source code debugger
---------------------------
The source code debugger (sdb) is an experimental feature, it's
interface may change in future versions of Singular.
To enable the use of the source code debugger SINGULAR has to be started
with the option `-d' or `--sdb' (see *note Command line options::).
sdb commands
............
Each sdb command consist of one character which may be followed by a
parameter.
`b'
print backtrace of calling stack
`c'
continue
`e'
edit the current procedure and reload it (current call will be
aborted)
only available on UNIX systems
`h',`?'
display help screen
`n'
execute current line, sdb break at next line
`p'
display type and value of the variable given by
`Q'
quit this Singular session
`q'
quit debugger, set debugger flags(0,1,2)
0: continue, disable the debugger
1: continue
2: throw an error, return to toplevel
Syntactical errors in procedures
................................
If SINGULAR was started with the command line option `-d' or `--sdb' a
syntactical error in a procedure will start the source code debugger
instead of returning to the top level with an error message. The
commands `q 1' and `q 2' are equivalent in this case.
SDB breakpoints in procedures
.............................
Up to seven SDB breakpoints can be set. To set a breakpoint at a
procedure use `breakpoint'. (See *note breakpoint::).
These breakpoints can be cleared with the command `d breakpoint_no' from
within the debugger or with `breakpoint(' proc_name `,-1);'.
File: sing.htm, Node: Break points, Next: Printing of data, Prev: Source code debugger, Up: Debugging tools
3.10.3 Break points
-------------------
A break point can be put into a proc by inserting the command `~'. If
`Singular' reaches a break point it asks for lines of commands
(line-length must be less than 80 characters) from the user. It returns
to normal execution if given an empty line. See *note ~::.
*Example:*
proc t
{
int i=2;
~;
return(i+1);
}
t();
==> -- break point in t --
==> -- 0: called from STDIN --
i; // here local variables of the procedure can be accessed
==> 2
==> -- break point in t --
==> 3
File: sing.htm, Node: Printing of data, Next: libparse, Prev: Break points, Up: Debugging tools
3.10.4 Printing of data
-----------------------
The procedure `dbprint' is useful for optional output of data: it takes
2 arguments and prints the second argument, if the first argument is
positive; it does nothing otherwise.
* Menu:
* dbprint::
* voice::
File: sing.htm, Node: libparse, Prev: Printing of data, Up: Debugging tools
3.10.5 libparse
---------------
`libparse' is a stand-alone program contained in the SINGULAR
distribution (at the place where the SINGULAR executable program
resides), which cannot be called inside of SINGULAR. It is a debugging
tool for libraries which performs exactly the same checks as the `LIB'
command in SINGULAR, but generates more output during parsing.
`libparse' is useful if an error occurs while loading the library, but
the whole block around the line specified seems to be correct. In these
situations the real error might be hundreds of lines earlier in the
library.
*Usage:*
`libparse [options] singular-library'
*Options:*
`-d' Debuglevel
increases the amount of output during parsing, where Debuglevel is
an integer between 0 and 4. Default is 0.
`-s'
turns on reporting about violations of unenforced syntax rules
The following syntax checks are performed in any case:
* counting of pairs of brackets {,} , [,] and (,) (number of {
has to match number of }, same for [,] and (,) ).
* counting of " ( number of " must be even ).
* general library syntax ( only LIB, static, proc (with
parameters, help, body and example) and comments, i.e // and `/*
... */', are allowed).
Its output lists all procedures that have been parsed successfully:
$ libparse sample.lib
Checking library 'sample.lib'
Library function line,start-eod line,body-eob line,example-eoe
Version:0.0.0;
g Sample tab line 9, 149-165 13, 271-298 14, 300-402
l Sample internal_tab line 24, 450-475 25, 476-496 0, 0-496
where the following abbreviations are used:
* g: global procedure (default)
* l: static procedure, i.e., local to the library.
each of the following is the position of the byte in the library.
* start: begin of 'proc'
* eod: end of parameters
* body: start of procedure body '{'
* eob: end of procedure body '}'
* example: position of 'example'
* eoe: end of example '}'
Hence in the above example, the first procedure of the library
sample.lib is user-accessible and its name is tab. The procedure starts
in line 9, at character 149. The head of the procedure ends at character
165, the body starts in line 13 at character 271 and ends at character
298. The example section extends from line 14 character 300 to character
402.
The following example shows the result of a missing close-bracket } in
line 26 of the library `sample.lib'.
LIB "sample.lib";
==> ? Library sample.lib: ERROR occurred: in line 26, 497.
==> ? missing close bracket '}' at end of library in line 26.
==> ? Cannot load library,... aborting.
==> ? error occurred in STDIN line 1: `LIB "sample.lib";`
File: sing.htm, Node: Data types, Next: Functions and system variables, Prev: General concepts, Up: Top
4 Data types
************
This chapter explains all data types of SINGULAR in alphabetical order.
For every type, there is a description of the declaration syntax as well
as information about how to build expressions of certain types.
The term expression list in SINGULAR refers to any comma separated list
of expressions.
For the general syntax of a declaration see *note General command
syntax::.
* Menu:
* def::
* ideal::
* int::
* intmat::
* intvec::
* link::
* list::
* map::
* matrix::
* module::
* number::
* poly::
* proc::
* qring::
* resolution::
* ring::
* string::
* vector::
File: sing.htm, Node: def, Next: ideal, Prev: Data types, Up: Data types
4.1 def
=======
Objects may be defined without a specific type: they get their type from
the first assignment to them. E.g., `ideal i=x,y,z; def j=i^2;' defines
the ideal `i^2' with the name `j'.
*Note:* Unlike other assignments a ring as an untyped object is not a
copy but another reference to the same (possibly unnamed) ring. This
means that entries in one of these rings appear also in the other ones.
The following defines a ring `s' which is just another reference (or
name) for the basering `r'.
ring r=32003,(x,y,z),dp;
poly f = x;
def s=basering;
setring s;
nameof(basering);
==> s
listvar();
==> // s [0] *ring
==> // f [0] poly
==> // r [0] ring
==> // LIB [0] string standard.lib
poly g = y;
kill f;
listvar(r);
==> // r [0] ring
==> // g [0] poly
ring t=32003,(u,w),dp;
def rt=r+t;
rt;
==> // characteristic : 32003
==> // number of vars : 5
==> // block 1 : ordering dp
==> // : names x y z
==> // block 2 : ordering dp
==> // : names u w
==> // block 3 : ordering C
This reference to a ring with def is useful if the basering is not local
to the procedure (so it cannot be accessed by its name) but one needs a
name for it (e.g., for a use with `setring' or `map'). `setring r;'
does not work in this case, because `r' may not be local to the
procedure.
* Menu:
* def declarations::
File: sing.htm, Node: def declarations, Prev: def, Up: def
4.1.1 def declarations
----------------------
*Syntax:*
`def' name `=' expression `;'
*Purpose:*
defines an object of the same type as the right-hand side.
*Default:*
none
*Note:*
This is useful if the right-hand side may be of variable type as a
consequence of a computation (e.g., ideal or module or matrix). It
may also be used in procedures to give the basering a name which is
local to the procedure.
*Example:*
def i=2;
typeof(i);
==> int
* Menu:
See
* typeof::
See *note typeof::.
File: sing.htm, Node: ideal, Next: int, Prev: def, Up: Data types
4.2 ideal
=========
Ideals are represented as lists of polynomials which generate the ideal.
Like polynomials they can only be defined or accessed with respect to a
basering.
*Note:* `size' counts only the non-zero generators of an ideal whereas
`ncols' counts all generators.
* Menu:
* ideal declarations::
* ideal expressions::
* ideal operations::
* ideal related functions::
File: sing.htm, Node: ideal declarations, Next: ideal expressions, Prev: ideal, Up: ideal
4.2.1 ideal declarations
------------------------
*Syntax:*
`ideal' name `=' list_of_poly_and_ideal_expressions `;'
`ideal' name `=' ideal_expression `;'
*Purpose:*
defines an ideal.
*Default:*
0
*Example:*
ring r=0,(x,y,z),dp;
poly s1 = x2;
poly s2 = y3;
poly s3 = z;
ideal i = s1, s2-s1, 0,s2*s3, s3^4;
i;
==> i[1]=x2
==> i[2]=y3-x2
==> i[3]=0
==> i[4]=y3z
==> i[5]=z4
size(i);
==> 4
ncols(i);
==> 5
File: sing.htm, Node: ideal expressions, Next: ideal operations, Prev: ideal declarations, Up: ideal
4.2.2 ideal expressions
-----------------------
An ideal expression is:
1. an identifier of type ideal
2. a function returning ideal
3. ideal expressions combined by the arithmetic operations `+' or `*'
4. a power of an ideal expression (operator `^' or `**')
Note that the computation of the product `i*i' involves all
products of generators of `i' while `i^2' involves only the
different ones, and is therefore faster.
5. a type cast to ideal
*Example:*
ring r=0,(x,y,z),dp;
ideal m = maxideal(1);
m;
==> m[1]=x
==> m[2]=y
==> m[3]=z
poly f = x2;
poly g = y3;
ideal i = x*y*z , f-g, g*(x-y) + f^4 ,0, 2x-z2y;
ideal M = i + maxideal(10);
timer =0;
i = M*M;
timer;
==> 0
ncols(i);
==> 505
timer =0;
i = M^2;
ncols(i);
==> 505
timer;
==> 0
i[ncols(i)];
==> x20
vector v = [x,y-z,x2,y-x,x2yz2-y];
ideal j = ideal(v);
File: sing.htm, Node: ideal operations, Next: ideal related functions, Prev: ideal expressions, Up: ideal
4.2.3 ideal operations
----------------------
`+'
addition (concatenation of the generators and simplification)
`*'
multiplication (with ideal, poly, vector, module; simplification in
case of multiplication with ideal)
`^'
exponentiation (by a non-negative integer)
ideal_expression `[' intvec_expression `]'
are polynomial generators of the ideal, index 1 gives the first
generator.
*Note:* For simplification of an ideal, see also *note simplify::.
*Example:*
ring r=0,(x,y,z),dp;
ideal I = 0,x,0,1;
I;
==> I[1]=0
==> I[2]=x
==> I[3]=0
==> I[4]=1
I + 0; // simplification
==> _[1]=1
ideal J = I,0,x,x-z;;
J;
==> J[1]=0
==> J[2]=x
==> J[3]=0
==> J[4]=1
==> J[5]=0
==> J[6]=x
==> J[7]=x-z
I * J; // multiplication with simplification
==> _[1]=1
I*x;
==> _[1]=0
==> _[2]=x2
==> _[3]=0
==> _[4]=x
vector V = [x,y,z];
print(V*I);
==> 0,x2,0,x,
==> 0,xy,0,y,
==> 0,xz,0,z
ideal m = maxideal(1);
m^2;
==> _[1]=x2
==> _[2]=xy
==> _[3]=xz
==> _[4]=y2
==> _[5]=yz
==> _[6]=z2
ideal II = I[2..4];
II;
==> II[1]=x
==> II[2]=0
==> II[3]=1
File: sing.htm, Node: ideal related functions, Prev: ideal operations, Up: ideal
4.2.4 ideal related functions
-----------------------------
`char_series'
irreducible characteristic series (see *note char_series::)
`coeffs'
matrix of coefficients (see *note coeffs::)
`contract'
contraction by an ideal (see *note contract::)
`diff'
partial derivative (see *note diff::)
`degree'
multiplicity, dimension and codimension of the ideal of leading
terms (see *note degree::)
`dim'
Krull dimension of basering modulo the ideal of leading terms (see
*note dim::)
`eliminate'
elimination of variables (see *note eliminate::)
`facstd'
factorizing Groebner basis algorithm (see *note facstd::)
`factorize'
ideal of factors of a polynomial (see *note factorize::)
`fglm'
Groebner basis computation from a Groebner basis w.r.t. a different
ordering (see *note fglm::)
`finduni'
computation of univariate polynomials lying in a zero dimensional
ideal (see *note finduni::)
`groebner'
Groebner basis computation (a wrapper around
`std,stdhilb,stdfglm',...) (see *note groebner::)
`highcorner'
computes the smallest monomial not contained in the ideal. The
ideal has to be zero-dimensional. (see *note highcorner::)
`homog'
homogenization with respect to a variable (see *note homog::)
`hilb'
Hilbert series of a standard basis (see *note hilb::)
`indepSet'
sets of independent variables of an ideal (see *note indepSet::)
`interred'
interreduction of an ideal (see *note interred::)
`intersect'
ideal intersection (see *note intersect::)
`jacob'
ideal of all partial derivatives resp. jacobian matrix (see *note
jacob::)
`jet'
Taylor series up to a given order (see *note jet::)
`kbase'
vector space basis of basering modulo ideal of leading terms (see
*note kbase::)
`koszul'
Koszul matrix (see *note koszul::)
`lead'
leading terms of a set of generators (see *note lead::)
`lift'
lift-matrix (see *note lift::)
`liftstd'
standard basis and transformation matrix computation (see *note
liftstd::)
`lres'
free resolution for homogeneous ideals (see *note lres::)
`maxideal'
power of the maximal ideal at 0 (see *note maxideal::)
`minbase'
minimal generating set of a homogeneous ideal, resp. module, or an
ideal, resp. module, in a local ring (see *note minbase::)
`minor'
set of minors of a matrix (see *note minor::)
`modulo'
represents $(h1+h2)/h1 \cong h2/(h1 \cap h2)$
(h1+h2)/h1=h2/(h1 intersect h2) (see *note modulo::)
`mres'
minimal free resolution of an ideal resp. module w.r.t. a minimal
set of generators of the given ideal resp. module (see *note
mres::)
`mstd'
standard basis and minimal generating set of an ideal (see *note
mstd::)
`mult'
multiplicity, resp. degree, of the ideal of leading terms (see
*note mult::)
`ncols'
number of columns (see *note ncols::)
`preimage'
preimage under a ring map (see *note preimage::)
`qhweight'
quasihomogeneous weights of an ideal (see *note qhweight::)
`quotient'
ideal quotient (see *note quotient::)
`reduce'
normalform with respect to a standard basis (see *note reduce::)
`res'
free resolution of an ideal resp. module but not changing the given
ideal resp. module (see *note res::)
`simplify'
simplify a set of polynomials (see *note simplify::)
`size'
number of non-zero generators (see *note size::)
`sortvec'
permutation for sorting ideals resp. modules (see *note sortvec::)
`sres'
free resolution of a standard basis (see *note sres::)
`std'
standard basis computation (see *note std::)
`stdfglm'
standard basis computation with fglm technique (see *note
stdfglm::)
`stdhilb'
Hilbert driven standard basis computation (see *note stdhilb::
`subst'
substitute a ring variable (see *note subst::)
`syz'
computation of the first syzygy module (see *note syz::)
`vdim'
vector space dimension of basering modulo ideal of leading terms
(see *note vdim::)
`weight'
optimal weights (see *note weight::)
File: sing.htm, Node: int, Next: intmat, Prev: ideal, Up: Data types
4.3 int
=======
Variables of type int represent the machine integers and are, therefore,
limited in their range (e.g., the range is between -2147483647 and
2147483647 on 32-bit machines). They are mainly used to count things
(dimension, rank, etc.), in loops (see *note for::), and to represent
boolean values (FALSE is represented by 0, every other value means TRUE,
see *note boolean expressions::).
Integers consist of a sequence of digits, possibly preceded by a sign.
A space is considered as a separator, so it is not allowed between
digits. A sequence of digits outside the allowed range is converted to
the type `number' if possible.
* Menu:
* int declarations::
* int expressions::
* int operations::
* boolean expressions::
* boolean operations::
* int related functions::
File: sing.htm, Node: int declarations, Next: int expressions, Prev: int, Up: int
4.3.1 int declarations
----------------------
*Syntax:*
`int' name `=' int_expression `;'
*Purpose:*
defines an integer variable.
*Default:*
0
*Example:*
int i = 42;
int j = i + 3; j;
==> 45
i = i * 3 - j; i;
==> 81
int k; // assigning the default value 0 to k
k;
==> 0
File: sing.htm, Node: int expressions, Next: int operations, Prev: int declarations, Up: int
4.3.2 int expressions
---------------------
An int expression is:
1. a sequence of digits (if the number represented by this sequence is
too large to fit into the range of integers it is automatically
converted to the type number, if a basering is defined)
2. an identifier of type int
3. a function returning int
4. int expressions combined by the arithmetic operations `+', `-',
`*', `div', `/', `%' (`mod'), or `^'
5. a boolean expression
6. a type cast to int
*Note:* Variables of type int represent the compiler integers and are,
therefore, limited in their range (see *note Limitations::). If this
range is too small the expression must be converted to the type number
over a ring with characteristic 0.
*Example:*
12345678901; // too large
==> ? `12345678901` greater than 2147483647(max. integer representation)
==> ? error occurred in line 1: `12345678901; // too large`
typeof(_);
==> none
ring r=0,x,dp;
12345678901;
==> 12345678901
typeof(_);
==> number
// Note: 11*13*17*100*200*2000*503*1111*222222
// returns a machine integer:
11*13*17*100*200*2000*503*1111*222222;
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> // ** int overflow(*), result may be wrong
==> -1875651584
// using the type cast number for a greater allowed range
number(11)*13*17*100*200*2000*503*1111*222222;
==> 12075748128684240000000
ring rp=32003,x,dp;
12345678901;
==> 9603
typeof(_);
==> number
intmat m[2][2] = 1,2,3,4;
m;
==> 1,2,
==> 3,4
m[2,2];
==> 4
typeof(_);
==> int
det(m);
==> -2
m[1,1] + m[2,1] == trace(m);
==> 0
! 0;
==> 1
1 and 2;
==> 1
intvec v = 1,2,3;
def d =transpose(v)*v; // scalarproduct gives an 1x1 intvec
typeof(d);
==> intvec
int i = d[1]; // access the first (the only) entry in the intvec
ring rr=31,(x,y,z),dp;
poly f = 1;
i = int(f); // cast to int
// Integers may be converted to constant polynomials by an assignment,
poly g=37;
// define the constant polynomial g equal to the image of
// the integer 37 in the actual coefficient field, here it equals 6
g;
==> 6
* Menu:
See
* Type conversion and casting::
* number::
See *note Type conversion and casting::; *note number::.
File: sing.htm, Node: int operations, Next: int related functions, Prev: int expressions, Up: int
4.3.3 int operations
--------------------
`++'
changes its operand to its successor, is itself no int expression
`--'
changes its operand to its predecessor, is itself no int expression
`+'
addition
`-'
negation or subtraction
`*'
multiplication
`/'
integer division (omitting the remainder), rounding toward 0
`div'
integer division (omitting the remainder >= 0)
`%'
integer modulo (the remainder of the division `/')
`mod'
integer modulo (the remainder of the division `div'), always
non-negative
`^', `**'
exponentiation (exponent must be non-negative)
`<', `>', `<=', `>=', `==', `<>'
comparison
*Note:* An assignment `j=i++;' or `j=i--;' is not allowed, in particular
it does not change the value of `j', see *note Limitations::.
*Example:*
int i=1;
int j;
i++; i; i--; i;
==> 2
==> 1
// ++ and -- do not return a value as in C, can not assign
j = i++;
==> // ** right side is not a datum, assignment ignored
// the value of j is unchanged
j; i;
==> 0
==> 2
i+2, 2-i, 5^2;
==> 4 0 25
5 div 2, 8%3;
==> 2 2
-5 div 2, -5 / 2, -5 mod 2, -5 % 2;
==> -3 -2 1 -1
1<2, 2<=2;
==> 1 1
File: sing.htm, Node: int related functions, Next: boolean expressions, Prev: int operations, Up: int
4.3.4 int related functions
---------------------------
`char'
characteristic of the coefficient field of a ring (see *note
char::)
`deg'
degree of a poly resp. vector (see *note deg::)
`det'
determinant (see *note det::)
`dim'
Krull dimension of basering modulo ideal of leading terms, resp.
dimension of module of leading terms (see *note dim::)
`extgcd'
Bezout representation of gcd (see *note extgcd::)
`find'
position of a substring in a string (see *note find::)
`gcd'
greatest common divisor (see *note gcd::)
`koszul'
Koszul matrix (see *note koszul::)
`memory'
memory usage (see *note memory::)
`mult'
multiplicity of an ideal, resp. module, of leading terms (see *note
mult::)
`ncols'
number of columns (see *note ncols::)
`npars'
number of ring parameters (see *note npars::)
`nrows'
number of rows of a matrix, resp. the rank of the free module where
the vector or module lives (see *note nrows::)
`nvars'
number of ring variables (see *note nvars::)
`ord'
degree of the leading term of a poly resp. vector (see *note ord::)
`par'
n-th parameter of the basering (see *note par::)
`pardeg'
degree of a number considered as a polynomial in the ring
parameters (see *note pardeg::)
`prime'
the next lower prime (see *note prime::)
`random'
a pseudo random integer between the given limits (see *note
random::)
`regularity'
regularity of a resolution (see *note regularity::)
`rvar'
test, if the given expression or string is a ring variable (see
*note rvar::)
`size'
number of elements in an object (see *note size::)
`trace'
trace of an integer matrix (see *note trace::)
`var'
n-th ring variable of the basering (see *note var::)
`vdim'
vector space dimension of basering modulo ideal of leading terms,
resp. of freemodule modulo module of leading terms (see *note
vdim::)
File: sing.htm, Node: boolean expressions, Next: boolean operations, Prev: int related functions, Up: int
4.3.5 boolean expressions
-------------------------
A boolean expression is really an int expression used in a logical
context:
An int expression (<> 0 evaluates to _TRUE_ (represented by 1), 0
represents _FALSE_).
The following is the list of available comparisons of objects of the
same type.
*Note:* There are no comparisons for ideals and modules, resolution and
maps.
1. an integer comparison:
i == j
i != j // or i <> j
i <= j
i >= j
i > j
i < j
2. a number comparison:
m == n
m != n // or m <> n
m < n
m > n
m <= n
m >= n
For numbers from Z/p or from field extensions not all operations
are useful:
- 0 is always the smallest element,
- in Z/p the representatives in the range -(p-1)/2..(p-1)/2 when
p>2 resp. 0 and 1 for p=2 are used for comparisons,
- in field extensions the last two operations (`>=,<=') yield
always TRUE (1) and the `<' and `>' are equivalent to `!='.
3. a polynomial or vector comparison:
f == g
f != g // or f <> g
f <= g // comparing the leading term w.r.t. the monomial order
f < g
f >= g
f > g
4. an intmat or matrix comparison:
v == w
v != w // or v <> w
5. an intvec or string comparison:
f == g
f != g // or f <> g
f <= g // comparing lexicographically
f >= g // w.r.t. the order specified by ASCII
f > g
f < g
6. boolean expressions combined by boolean operations (`and', `or',
`not')
*Note:* All arguments of a logical expression are first evaluated and
then the value of the logical expression is determined. For example, the
logical expression `(a || b)' is evaluated by first evaluating `a' _and_
`b', even though the value of `b' has no influence on the value of `(a
|| b)', if `a' evaluates to true.
Note that this evaluation is different from the left-to-right,
conditional evaluation of logical expressions (as found in most
programming languages). For example, in these other languages, the value
of `(1 || b)' is determined without ever evaluating `b'.
See *note Major differences to the C programming language::.
File: sing.htm, Node: boolean operations, Prev: boolean expressions, Up: int
4.3.6 boolean operations
------------------------
`and'
logical `and', may also be written as `&&'
`or'
logical `or', may also be written as `||'
`not'
logical `not', may also be written as `!'
The precedence of the boolean operations is:
1. parentheses
2. comparisons
3. not
4. and
5. or
*Example:*
(1>2) and 3;
==> 0
1 > 2 and 3;
==> 0
! 0 or 1;
==> 1
!(0 or 1);
==> 0
File: sing.htm, Node: intmat, Next: intvec, Prev: int, Up: Data types
4.4 intmat
==========
Integer matrices are matrices with integer entries. For the range of
integers see *note Limitations::. Integer matrices do not belong to a
ring, they may be defined without a basering being defined. An intmat
can be multiplied by and added to an int; in this case the int is
converted into an intmat of the right size with the integer on the
diagonal. The integer `1', for example, is converted into the unit
matrix.
* Menu:
* intmat declarations::
* intmat expressions::
* intmat type cast::
* intmat operations::
* intmat related functions::
File: sing.htm, Node: intmat declarations, Next: intmat expressions, Prev: intmat, Up: intmat
4.4.1 intmat declarations
-------------------------
*Syntax:*
`intmat' name `=' intmat_expression `;'
`intmat' name `[' rows `] [' cols `] =' intmat_expression `;'
`intmat' name `[' rows `] [' cols `] ='
list_of_int_and_intvec_and_intmat_expressions `;'
rows and cols must be positive int expressions.
*Purpose:*
defines an intmat variable.
Given a list of integers, the matrix is filled up with the first
row from the left to the right, then the second row and so on. If
the int_list contains less than rows*cols elements, the matrix is
filled up with zeros; if it contains more elements, only the first
rows*cols elements are used.
*Default:*
0 (1 x 1 matrix)
*Example:*
intmat im[3][5]=1,3,5,7,8,9,10,11,12,13;
im;
==> 1,3,5,7,8,
==> 9,10,11,12,13,
==> 0,0,0,0,0
im[3,2];
==> 0
intmat m[2][3] = im[1..2,3..5]; // defines a submatrix
m;
==> 5,7,8,
==> 11,12,13
File: sing.htm, Node: intmat expressions, Next: intmat type cast, Prev: intmat declarations, Up: intmat
4.4.2 intmat expressions
------------------------
An intmat expression is:
1. an identifier of type intmat
2. a function returning intmat
3. intmat operations with int (`+', `-', `*', `div', `%')
4. intmat operations (`+', `-', `*')
5. a type cast to intmat (*note intmat type cast::)
*Example:*
intmat Idm[2][2];
Idm +1; // add the unit intmat
==> 1,0,
==> 0,1
intmat m1[3][2] = _,1,-2; // take entries from the last result
m1;
==> 1,0,
==> 0,1,
==> 1,-2
intmat m2[2][3]=1,0,2,4,5,1;
transpose(m2);
==> 1,4,
==> 0,5,
==> 2,1
intvec v1=1,2,4;
intvec v2=5,7,8;
m1=v1,v2; // fill m1 with v1 and v2
m1;
==> 1,2,
==> 4,5,
==> 7,8
trace(m1*m2);
==> 56
* Menu:
See
* Type conversion and casting::
* number::
See *note Type conversion and casting::; *note number::.
File: sing.htm, Node: intmat type cast, Next: intmat operations, Prev: intmat expressions, Up: intmat
4.4.3 intmat type cast
----------------------
`*Syntax:*'
`intmat (' expression `)'
`intmat (' expression, int_n, int_m `)'
`*Type:*'
intmat
`*Purpose:*'
Converts expression to an intmat, where expression must be of type
intvec, or intmat. If int_n and int_m are supplied, then they
specify the dimension of the intmat. Otherwise, the size (resp.
dimensions) of the intmat are determined by the size (resp.
dimensions) of the expression.
`*Example:*'
intmat(intvec(1));
==> 1
intmat(intvec(1), 1, 2);
==> 1,0
intmat(intvec(1,2,3,4), 2, 2);
==> 1,2,
==> 3,4
intmat(_, 2, 3);
==> 1,2,3,
==> 4,0,0
intmat(_, 2, 1);
==> 1,
==> 2
* Menu:
See
* Type conversion and casting::
* intmat::
* matrix type cast::
See *note Type conversion and casting::; *note intmat::; *note matrix
type cast::.
File: sing.htm, Node: intmat operations, Next: intmat related functions, Prev: intmat type cast, Up: intmat
4.4.4 intmat operations
-----------------------
`+'
addition with intmat or int; the int is converted into a diagonal
intmat
`-'
negation or subtraction with intmat or int; the int is converted
into a diagonal intmat
`*'
multiplication with intmat, intvec, or int; the int is converted
into a diagonal intmat
`div,/'
division of entries in the integers (omitting the remainder)
`%, mod'
entries modulo int (remainder of the division)
`<>', `=='
comparison
intmat_expression `[' intvec_expression`,' intvec_expression `]'
is an intmat entry, where the first index indicates the row and the
second the column
*Example:*
intmat m[2][4] = 1,0,2,4,0,1,-1,0,3,2,1,-2;
m;
==> 1,0,2,4,
==> 0,1,-1,0
m[2,3]; // entry at row 2, col 3
==> -1
size(m); // number of entries
==> 8
intvec v = 1,0,-1,2;
m * v;
==> 7,1
typeof(_);
==> intvec
intmat m1[4][3] = 0,1,2,3,v,1;
intmat m2 = m * m1;
m2; // 2 x 3 intmat
==> -2,5,4,
==> 4,-1,-1
m2*10; // multiply each entry of m with 10;
==> -20,50,40,
==> 40,-10,-10
-m2;
==> 2,-5,-4,
==> -4,1,1
m2 % 2;
==> 0,1,0,
==> 0,1,1
m2 div 2;
==> -1,2,2,
==> 2,-1,-1
m2[2,1]; // entry at row 2, col 1
==> 4
m1[2..3,2..3]; // submatrix
==> 1 0 2 1
m2[nrows(m2),ncols(m2)]; // the last entry of intmat m2
==> -1
File: sing.htm, Node: intmat related functions, Prev: intmat operations, Up: intmat
4.4.5 intmat related functions
------------------------------
`betti'
Betti numbers of a free resolution (see *note betti::)
`det'
determinant (see *note det::)
`ncols'
number of cols (see *note ncols::)
`nrows'
number of rows (see *note nrows::)
`random'
create a pseudo random intmat (see *note random::)
`size'
total number of entries (see *note size::)
`transpose'
transpose of an intmat (see *note transpose::)
`trace'
trace of an intmat (see *note trace::)
File: sing.htm, Node: intvec, Next: link, Prev: intmat, Up: Data types
4.5 intvec
==========
Variables of type intvec are lists of integers. For the range of
integers see *note Limitations::. They may be used for simulating sets
of integers (and other sets if the intvec is used as an index set for
other objects). Addition and subtraction of an intvec with an int or an
intvec is done element-wise.
* Menu:
* intvec declarations::
* intvec expressions::
* intvec operations::
* intvec related functions::
File: sing.htm, Node: intvec declarations, Next: intvec expressions, Prev: intvec, Up: intvec
4.5.1 intvec declarations
-------------------------
*Syntax:*
`intvec' name `=' intvec_expression `;'
`intvec' name `=' list_of_int_and_intvec_expressions `;'
*Purpose:*
defines an intvec variable.
An intvec consists of an ordered list of integers.
*Default:*
0
*Example:*
intvec iv=1,3,5,7,8;
iv;
==> 1,3,5,7,8
iv[4];
==> 7
iv[3..size (iv)];
==> 5 7 8
File: sing.htm, Node: intvec expressions, Next: intvec operations, Prev: intvec declarations, Up: intvec
4.5.2 intvec expressions
------------------------
An intvec expression is:
1. a range: int expression `..' int expression
2. a function returning intvec
3. intvec operations with int (`+', `-', `*', `/', `%')
4. intvec operations (`+', `-')
5. intvec operation with intmat (`*')
6. a type cast to intvec
*Example:*
intvec v=-1,2;
intvec w=v,v; // concatenation
w;
==> -1,2,-1,2
w = -2..2,v,1;
w;
==> -2,-1,0,1,2,-1,2,1
intmat m[3][2] = 0,1,2,-2,3,1;
m*v;
==> 2,-6,-1
typeof(_);
==> intvec
v = intvec(m);
v;
==> 0,1,2,-2,3,1
ring r;
poly f = x2z + 2xy-z;
f;
==> x2z+2xy-z
v = leadexp(f);
v;
==> 2,0,1
File: sing.htm, Node: intvec operations, Next: intvec related functions, Prev: intvec expressions, Up: intvec
4.5.3 intvec operations
-----------------------
`+'
addition with intvec or int (component-wise)
`-'
negation or subtraction with intvec or int (component-wise)
`*'
multiplication with int (component-wise)
`/', `div'
division by int (component-wise)
`%, mod'
modulo (component-wise)
`<>', `==', `<=', `>=', `>', `<'
comparison (done lexicographically)
intvec_expression `[' int_expression `]'
is an element of the intvec; the first element has index one.
*Example:*
intvec iv = 1,3,5,7,8;
iv+1; // add 1 to each entry
==> 2,4,6,8,9
iv*2;
==> 2,6,10,14,16
iv;
==> 1,3,5,7,8
iv-10;
==> -9,-7,-5,-3,-2
iv=iv,0;
iv;
==> 1,3,5,7,8,0
iv div 2;
==> 0,1,2,3,4,0
iv+iv; // component-wise addition
==> 2,6,10,14,16,0
iv[size(iv)-1]; // last-1 entry
==> 8
intvec iw=2,3,4,0;
iv==iw; // lexicographic comparison
==> 0
iv < iw;
==> 1
iv != iw;
==> 1
iv[2];
==> 3
iw = 4,1,2;
iv[iw];
==> 7 1 3
File: sing.htm, Node: intvec related functions, Prev: intvec operations, Up: intvec
4.5.4 intvec related functions
------------------------------
`hilb'
returns Hilbert series as intvec (see *note hilb::)
`indepSet'
sets of independent variables of an ideal (see *note indepSet::)
`leadexp'
the exponent vector of the leading monomial (see *note leadexp::)
`nrows'
number of rows (see *note nrows::)
`qhweight'
returns quasihomogeneous weights (see *note qhweight::)
`size'
length of the intvec (see *note size::)
`sortvec'
permutation for sorting ideals/modules (see *note sortvec::)
`transpose'
transpose of an intvec, returns an intmat (see *note transpose::)
`weight'
returns weights for the weighted ecart method (see *note weight::)
File: sing.htm, Node: link, Next: list, Prev: intvec, Up: Data types
4.6 link
========
Links are the communication channels of SINGULAR, i.e., something
SINGULAR can write to and/or read from. Currently, SINGULAR supports
four different link types:
* ASCII links (see *note ASCII links::)
* MPfile links (see *note MPfile links::)
* MPtcp links (see *note MPtcp links::)
* DBM links (see *note DBM links::)
* Menu:
* link declarations::
* link expressions::
* link related functions::
* ASCII links::
* MP links::
* DBM links::
File: sing.htm, Node: link declarations, Next: link expressions, Prev: link, Up: link
4.6.1 link declarations
-----------------------
*Syntax:*
`link' name `=' string_expression `;'
*Purpose:*
defines a new communication link.
*Default:*
none
*Example:*
link l=":w example.txt";
int i=22; // cf. ASCII links for explanation
string s="An int follows:";
write(l,s,i);
l;
==> // type : ASCII
==> // mode : w
==> // name : example.txt
==> // open : yes
==> // read : not ready
==> // write: ready
close(l); //
read(l);
==> An int follows:
==> 22
==>
close(l);
File: sing.htm, Node: link expressions, Next: link related functions, Prev: link declarations, Up: link
4.6.2 link expressions
----------------------
A link expression is:
1. an identifier of type link
2. a string describing the link
A link is described by a string which consists of two parts: a property
string followed by a name string. The property string describes the type
of the link (`ASCII', `MPfile', `MPtcp' or `DBM') and the mode of the
link (e.g., open for read, write or append). The name string describes
the filename of the link, resp. a network connection for MPtcp links.
For a detailed format description of the link describing string see:
* for ASCII links: *note ASCII links::
* for MPfile links: *note MPfile links::
* for MPtcp links: *note MPtcp links::
* for DBM links: *note DBM links::
* Menu:
* ASCII links::
* MPfile links::
* MPtcp links::
* DBM links::
File: sing.htm, Node: link related functions, Next: ASCII links, Prev: link expressions, Up: link
4.6.3 link related functions
----------------------------
`close'
closes a link (see *note close::)
`dump'
generates a dump of all variables and their values (see *note
dump::)
`getdump'
reads a dump (see *note getdump::)
`open'
opens a link (see *note open::)
`read'
reads from a link (see *note read::)
`status'
gets the status of a link (see *note status::)
`write'
writes to a link (see *note write::)
`kill'
closes and kills a link (see *note kill::)
File: sing.htm, Node: ASCII links, Next: MP links, Prev: link related functions, Up: link
4.6.4 ASCII links
-----------------
Via ASCII links data that can be converted to a string can be written
into files for storage or communication with other programs. The data is
written in plain ASCII format. The output format of polynomials is done
w.r.t. the value of the global variable `short' (see *note short::).
Reading from an ASCII link returns a string -- conversion into other
data is up to the user. This can be done, for example, using the command
`execute' (see *note execute::).
The ASCII link describing string has to be one of the following:
1. `"ASCII: "' + filename
the mode (read or append) is set by the first `read' or `write'
command.
2. `"ASCII:r "' + filename
opens the file for reading.
3. `"ASCII:w "' + filename
opens the file for overwriting.
4. `"ASCII:a "' + filename
opens the file for appending.
There are the following default values:
* the type `ASCII' may be omitted since ASCII links are the default
links.
* if non of `r', `w', or `a' is specified, the mode of the link is
set by the first `read' or `write' command on the link. If the
first command is `write', the mode is set to `a' (append mode).
* if the filename is omitted, `read' reads from stdin and `write'
writes to stdout.
Using these default rules, the string `":r temp"' describes a link which
is equivalent to the link `"ASCII:r temp"': an ASCII link to the file
`temp' which is opened for reading. The string `"temp"' describes an
ASCII link to the file `temp', where the mode is set by the first `read'
or `write' command. See also the example below.
Note that the filename may contain a path. On Microsoft Windows (resp.
MS-DOS) platforms, names of a drive can precede the filename, but must
be started with a `//' (as in `//c/temp/ex'. An ASCII link can be used
either for reading or for writing, but not for both at the same time. A
`close' command must be used before a change of I/O direction. Types
without a conversion to `string' cannot be written.
*Example:*
ring r=32003,(x,y,z),dp;
link l=":w example.txt"; // type is ASCII, mode is overwrite
l;
==> // type : ASCII
==> // mode : w
==> // name : example.txt
==> // open : no
==> // read : not ready
==> // write: not ready
status(l, "open", "yes"); // link is not yet opened
==> 0
ideal i=x2,y2,z2;
write (l,1,";",2,";","ideal i=",i,";");
status(l, "open", "yes"); // now link is open
==> 1
status(l, "mode"); // for writing
==> w
close(l); // link is closed
write("example.txt","int j=5;");// data is appended to file
read("example.txt"); // data is returned as string
==> 1
==> ;
==> 2
==> ;
==> ideal i=
==> x2,y2,z2
==> ;
==> int j=5;
==>
execute(read(l)); // read string is executed
==> 1
==> 2
==> // ** redefining i **
close(l); // link is closed
File: sing.htm, Node: MP links, Next: DBM links, Prev: ASCII links, Up: link
4.6.5 MP links
--------------
MP (Multi Protocol) links give the possibility to store and communicate
data in the binary MP format: Read and write access is very fast
compared to ASCII links. MP links can be established using files (link
type is `MPfile') or using TCP sockets (link type is `MPtcp'). All data
(including such data that cannot be converted to a string) can be
written to an MP link. For ring-dependent data, a ring description is
written together with the data. Reading from an MP link returns an
expression (not a string) which was evaluated after the read operation.
If the expression read from an MP link is not from the same ring as the
current ring, then a `read' changes the current ring.
Currently, MP links are only available on Unix platforms and data is
written without attributes (which is likely to change in future
versions). For a general description of MP, see
`http://symbolicnet.mcs.kent.edu/areas/mp.html'.
* Menu:
* MPfile links::
* MPtcp links::
File: sing.htm, Node: MPfile links, Next: MPtcp links, Prev: MP links, Up: MP links
4.6.5.1 MPfile links
....................
MPfile links provide the possibility to store data in a file using the
binary MP format. Read and write operations are very fast compared to
ASCII links. Therefore, for storing large amounts of data, MPfile links
should be used instead of ASCII links. Unlike ASCII links, data read
from MPfile links is returned as expressions one at a time, and not as a
string containing the entire content of the file. Furthermore,
ring-dependent data is stored together with a ring description.
Therefore, reading ring-dependent data might change the current ring.
The MPfile link describing string has to be one of the following:
1. `"MPfile: "' + filename
the mode (read or append) is set by the first `read' or `write'
command.
2. `"MPfile:r "' + filename
opens the file for reading.
3. `"MPfile:w "' + filename
opens the file for overwriting.
4. `"MPfile:a "' + filename
opens the file for appending.
There are the following default values:
* if none of `r', `w', or `a' is specified, the mode of the link is
set by the first `read' or `write' command on the link. If the
first command is `write', the mode is set to `a' (append mode).
Note that the filename may contain a path. An MPfile link can be used
either for reading or for writing, but not for both at the same time. A
`close' command must be used before a change of I/O direction.
*Example:*
ring r;
link l="MPfile:w example.mp"; // type=MPfile, mode=overwrite
l;
==> // type : MPfile
==> // mode : w
==> // name : example.mp
==> // open : no
==> // read : not ready
==> // write: not ready
ideal i=x2,y2,z2;
write (l,1, i, "hello world");// write three expressions
write(l,4); // append one more expression
close(l); // link is closed
// open the file for reading now
read(l); // only first expression is read
==> 1
kill r; // no basering active now
def i = read(l); // second expression
// notice that current ring was set, the name was assigned
// automatically
listvar(ring);
==> // mpsr_r0 [0] *ring
def s = read(l); // third expression
listvar();
==> // s [0] string hello world
==> // mpsr_r0 [0] *ring
==> // i [0] ideal, 3 generator(s)
==> // l [0] link
==> // LIB [0] string standard.lib
close(l); // link is closed
dump("MPfile:w example.mp"); // dump everything to example.mp
kill i, s; // kill i and s
getdump("MPfile: example.mp");// get previous dump
listvar(); // got all variables and values back
==> // mpsr_r0 [0] *ring
==> // i [0] ideal, 3 generator(s)
==> // s [0] string hello world
==> // l [0] link
==> // LIB [0] string standard.lib
File: sing.htm, Node: MPtcp links, Prev: MPfile links, Up: MP links
4.6.5.2 MPtcp links
...................
MPtcp links give the possibility to exchange data in the binary MP
format between two processes which may run on the same or on different
computers. MPtcp links can be opened in four different modes:
`listen'
SINGULAR acts as a server.
`connect'
SINGULAR acts as a client.
`launch'
SINGULAR acts as a client, launching an application as server.
`fork'
SINGULAR acts as a client, forking another SINGULAR as server.
The MPtcp link describing string has to be
* listen mode:
1. `"MPtcp:listen --MPport "' + portnumber
SINGULAR becomes a server and waits at the port for a connect call.
* connect mode:
2. `"MPtcp:connect --MPport "' + portnumber
3. `"MPtcp:connect --MPhost "' + hostname + `" --MPport "' +
portnumber
SINGULAR becomes a client and connects to a server waiting at the
host and port.
* launch mode:
4. `"MPtcp:launch"'
5. `"MPtcp:launch --MPrsh "' + rsh
6. `"MPtcp:launch --MPrsh "' + rsh + `" --MPhost "' + hostname
7. `"MPtcp:launch --MPrsh "' + rsh + `" --MPhost "' + hostname +
`" --MPapplication "' + application
SINGULAR becomes a client and starts (launches) the application
using the specified remote shell command (default is `ssh') on a
(possibly) different host (default is `localhost' which then acts
as a server.
* fork mode:
8. `"MPtcp:fork"'
SINGULAR becomes a client and forks another SINGULAR on the same
host which acts as a server.
There are the following default values:
* if none of `listen', `connect', `launch' or `fork' is specified,
the default mode is set to `fork'.
* if no remote shell (rsh) command is specified, then the command
`ssh' is used.
* if no application is specified (in mode `launch') the default
application is the value of `system("Singular") + "-bq"'. (This
evaluates to the absolute path of the SINGULAR currently running
with the option `"-bq"' appended.)
* if no hostname is specified the local host is used as default host.
To open an MPtcp link in launch mode, the application to launch must
either be given with an absolute pathname, or must be in a directory
contained in the search path. The launched application acts as a server,
whereas the SINGULAR that actually opened the link acts as a client.
SINGULAR automatically appends the command line arguments "`--MPmode
connect --MPhost' hostname `--MPport' portnumber" to the command line of
the server application. Both hostname and portnumber are substituted by
the values from the link specification. The client "listens" at the
given port until the server application does a connect call. If SINGULAR
is used as server application it has to be started with the command line
option `-b'. Since launching is done using a remote shell command, the
host on which the application should run must have an entry in the
`.rhosts' file. Even the local machine must have an entry if
applications are to be launched locally.
If the MPtcp link is opened in fork mode a child of the current SINGULAR
is forked. All variables and their values are inherited by the child.
The child acts as a server whereas the SINGULAR that actually opened the
link acts as a client.
To arrange the evaluation of an expression by a server, the expression
must be quoted using the command `quote' (see *note quote::), so that a
local evaluation is prevented. Otherwise, the expression is evaluated
first, and the result of the evaluation is written, instead of the
expression which is to be evaluated.
If SINGULAR is in server mode, the value of the variable `mp_ll' is the
MPtcp link connecting to the client and SINGULAR is in an infinite
read-eval-write loop until the connection is closed from the client side
(by closing its connecting link). Reading and writing is done to the
link `mp_ll': After an expression is read, it is evaluated and the
result of the evaluation is written back. That is, for each expression
which was written to the server, there is exactly one expression written
back. This might be an "empty" expression, if the evaluation on the
server side does not return a value.
MPtcp links should explicitly be opened before being used. MPtcp links
are bidirectional, i.e., can be be used for both, writing and reading.
Reading from an MPtcp link blocks until data was written to that link.
The `status' command can be used to check whether there is data to read.
*Example:*
LIB "general.lib"; // needed for "killall" command
link l="MPtcp:launch";
open(l); l; // l is ready for writing but not for reading
==> // type : MPtcp
==> // mode : launch
==> // name :
==> // open : yes
==> // read : not ready
==> // write: ready
ring r; ideal i=x2+y,xyz+z,x2+y2;
write (l,quote(std(eval(i)))); // std(i) is computed on server
def j = read(l);j; // result of computation on server is read
==> j[1]=z
==> j[2]=y2-y
==> j[3]=x2+y2
write(l, quote(getdump(mp_ll))); // server reads dump
dump(l); // dump is written to server (includes proc's)
read(l); // result of previous write-command is read
killall("not", "link"); killall("proc"); // kills everything, but links
==> // ** killing the basering for level 0
write(l, quote(dump(mp_ll))); // server writes dump
getdump(l); // dump is read from server
read(l); // result of previous write-command is read
close(l); // server is shut down
listvar(all); // same state as we had before "killall()"
==> // mpsr_r0 [0] ring
==> // r [0] *ring
==> // j [0] ideal, 3 generator(s)
==> // i [0] ideal, 3 generator(s)
==> // l [0] link
l = "MPtcp:"; // fork link declaration
open(l); l; // Notice that name is "parent"
==> // type : MPtcp
==> // mode : fork
==> // name : parent
==> // open : yes
==> // read : not ready
==> // write: ready
write(l, quote(status(mp_ll, "name")));
read(l); // and name of forked link is "child"
==> child
write(l,quote(i)); // Child inherited vars and their values
read(l);
==> _[1]=x2+y
==> _[2]=xyz+z
==> _[3]=x2+y2
close(l); // shut down forked child
File: sing.htm, Node: DBM links, Prev: MP links, Up: link
4.6.6 DBM links
---------------
DBM links provide access to data stored in a data base. Each entry in
the data base consists of a (key_string, value_string) pair. Such a pair
can be inserted with the command `write('link`,' key_string`,'
value_string`)'. By calling `write('link`,' key_string`)', the entry
with key key_string is deleted from the data base. The value of an entry
is returned by the command `read('link`,' key_string`)'. With only one
argument, `read('link`)' returns the next key in the data base. Using
this feature a data base can be scanned in order to access all entries
of the data base.
If a data base with name `name' is opened for writing for the first
time, two files (`name.pag' and `name.dir'), which contain the data
base, are automatically created.
The DBM link describing string has to be one of the following:
1. `"DBM: "' + name
opens the data base for reading (default mode).
2. `"DBM:r "' + name
opens the data base for reading.
3. `"DBM:rw "' + name
opens the data base for reading and writing.
Note that `name' must be given without the suffix `.pag' or `.dir'. The
name may contain an (absolute) path.
*Example:*
link l="DBM:rw example";
write(l,"1","abc");
write(l,"3","XYZ");
write(l,"2","ABC");
l;
==> // type : DBM
==> // mode : rw
==> // name : example
==> // open : yes
==> // read : ready
==> // write: ready
close(l);
// read all keys (till empty string):
read(l);
==> 1
read(l);
==> 3
read(l);
==> 2
read(l);
==>
// read data corresponding to key "1"
read(l,"1");
==> abc
// read all data:
read(l,read(l));
==> abc
read(l,read(l));
==> XYZ
read(l,read(l));
==> ABC
// close
close(l);
File: sing.htm, Node: list, Next: map, Prev: link, Up: Data types
4.7 list
========
Lists are arrays whose elements can be of any type (including ring and
qring). If one element belongs to a ring the whole list belongs to that
ring. This applies also to the special list `#'. The expression `list()'
is the empty list.
Note that a list stores the objects itself and not the names. Hence, if
`L' is a list, `L[1]' for example has no name. A name, say `R', can be
created for `L[1]' by `def R=L[1];'. To store also the name of an
object, say `r', it can be added to the list with `nameof(r);'. Rings
and qrings may be objects of a list.
*Note*: Unlike other assignments a ring as an element of a list is not a
copy but another reference to the same ring.
* Menu:
* list declarations::
* list expressions::
* list operations::
* list related functions::
File: sing.htm, Node: list declarations, Next: list expressions, Prev: list, Up: list
4.7.1 list declarations
-----------------------
*Syntax:*
`list' name `=' expression_list`;'
`list' name `=' list_expression`;'
*Purpose:*
defines a list (of objects of possibly different types).
*Default:*
empty list
*Example:*
list l=1,"str";
l[1];
==> 1
l[2];
==> str
ring r;
listvar(r);
==> // r [0] *ring
ideal i = x^2, y^2 + z^3;
l[3] = i;
l;
==> [1]:
==> 1
==> [2]:
==> str
==> [3]:
==> _[1]=x2
==> _[2]=z3+y2
listvar(r); // the list l belongs now to the ring r
==> // r [0] *ring
==> // l [0] list, size: 3
==> // i [0] ideal, 2 generator(s)
File: sing.htm, Node: list expressions, Next: list operations, Prev: list declarations, Up: list
4.7.2 list expressions
----------------------
A list expression is:
1. the empty list `list()'
2. an identifier of type list
3. a function returning list
4. list expressions combined by the arithmetic operation `+'
5. a type cast to list
* Menu:
See
* Type conversion and casting::
See *note Type conversion and casting::.
*Example:*
list l = "hello",1;
l;
==> [1]:
==> hello
==> [2]:
==> 1
l = list();
l;
==> empty list
ring r =0,x,dp;
factorize((x+1)^2);
==> [1]:
==> _[1]=1
==> _[2]=x+1
==> [2]:
==> 1,2
list(1,2,3);
==> [1]:
==> 1
==> [2]:
==> 2
==> [3]:
==> 3
File: sing.htm, Node: list operations, Next: list related functions, Prev: list expressions, Up: list
4.7.3 list operations
---------------------
`+'
concatenation
`delete'
deletes one element from list, returns new list
`insert'
inserts or appends a new element to list, returns a new list
list_expression `[' int_expression `]'
is a list entry; the index 1 gives the first element.
*Example:*
list l1 = 1,"hello",list(-1,1);
list l2 = list(1,2,3);
l1 + l2; // one new list
==> [1]:
==> 1
==> [2]:
==> hello
==> [3]:
==> [1]:
==> -1
==> [2]:
==> 1
==> [4]:
==> 1
==> [5]:
==> 2
==> [6]:
==> 3
list l3 =_;
l1,l2; // two lists
==> [1]:
==> 1
==> [2]:
==> hello
==> [3]:
==> [1]:
==> -1
==> [2]:
==> 1
==> [1]:
==> 1
==> [2]:
==> 2
==> [3]:
==> 3
l2[2];
==> 2
File: sing.htm, Node: list related functions, Prev: list operations, Up: list
4.7.4 list related functions
----------------------------
`bareiss'
returns a list of a matrix (lower triangular) and of an intvec
(permutations of columns, see *note bareiss::)
`betti'
Betti numbers of a resolution (see *note betti::)
`delete'
deletes an element from a list (see *note delete::)
`facstd'
factorizing Groebner basis algorithm (see *note facstd::)
`factorize'
list of factors of a polynomial (see *note factorize::)
`insert'
inserts or appends a new element to a list (see *note insert::)
`lres'
free resolution (see *note lres::)
`minres'
minimize a free resolution (see *note minres::)
`mres'
minimal free resolution of an ideal, resp. module w.r.t. a minimal
set of generators of the first module (see *note mres::)
`names'
list of all user-defined variable names (see *note names::)
`res'
free resolution of an ideal, resp. module (see *note res::)
`size'
number of entries (see *note size::)
`sres'
free resolution of an ideal, resp. module, given by a standard base
(see *note sres::)
File: sing.htm, Node: map, Next: matrix, Prev: list, Up: Data types
4.8 map
=======
Maps are ring maps from a preimage ring into the basering.
*Note:*
* the target of a map is *ALWAYS* the actual basering
* the preimage ring is stored "by name", that means, maps can only be
used in such contexts, where the name of the preimage ring can be
resolved (i.e., there might be problems for rings/maps defined in
subprocedures). See also *note Identifier resolution::, *note Names
in procedures::.
Maps between rings with different coefficient fields are possible and
listed below.
Canonically realized are
* $Q \rightarrow Q(a, \ldots)$
Q -> Q(a,..)
* $Q \rightarrow R$
Q -> R
* $Q \rightarrow C$
Q -> C
* $Z/p \rightarrow (Z/p)(a, \ldots)$
Z/p ->(Z/p)(a,...)
* $Z/p \rightarrow GF(p^n)$
Z/p -> GF(p^n)
* $Z/p \rightarrow R$
Z/p -> R
* $R \rightarrow C$
R -> C
Possible are furthermore
* % This is quite a hack, but for now it works.
$Z/p \rightarrow Q,
\quad
[i]_p \mapsto i \in [-p/2, \, p/2]
\subseteq Z$
Z/p -> Q : [i]_p -> i in [-p/2, p/2] in Z
* $Z/p \rightarrow Z/p^\prime,
\quad
[i]_p \mapsto i \in [-p/2, \, p/2] \subseteq Z, \;
i \mapsto [i]_{p^\prime} \in Z/p^\prime$
Z/p -> Z/p' : [i]_p in Z/p -> i in [-p/2,p/2] in Z, i -> [i]_p' in
Z/p'
* $C \rightarrow R, \quad$ the real part
C -> R : the real part
Finally, in Singular we allow the mapping from rings with coefficient
field Q to rings whose ground fields have finite characteristic:
* $Q \rightarrow Z/p$
Q -> Z/p
* $Q \rightarrow (Z/p)(a, \ldots)$
Q -> (Z/p)(a,..)
In these cases the denominator and the numerator of a number are mapped
separately by the usual map from Z to Z/p, and the image of the number
is built again afterwards by division. It is thus not allowed to map
numbers whose denominator is divisible by the characteristic of the
target ground field, or objects containing such numbers. We, therefore,
strongly recommend using such maps only to map objects with integer
coefficients.
* Menu:
* map declarations::
* map expressions::
* map operations::
* fetch::
* imap::
* subst::
See *note imap::; *note fetch::; *note subst::.
File: sing.htm, Node: map declarations, Next: map expressions, Prev: map, Up: map
4.8.1 map declarations
----------------------
*Syntax:*
`map' name `=' preimage_ring_name `,' ideal_expression `;'
`map' name `=' preimage_ring_name `,'
list_of_poly_and_ideal_expressions `;'
`map' name `=' map_expression `;'
*Purpose:*
defines a ring map from preimage_ring to basering.
Maps the variables of the preimage ring to the generators of the
ideal. If the ideal contains less elements than variables in the
preimage_ring the remaining variables are mapped to 0, if the ideal
contains more elements these are ignored. The image ring is always
the actual basering. For the mapping of coefficients from
different fields see *note map::.
*Default:*
none
*Note:*
There are standard mappings for maps which are close to the
identity map: `fetch' and `imap'.
The name of a map serves as the function which maps objects from
the preimage_ring into the basering. These objects must be defined
by names (no evaluation in the preimage ring is possible).
*Example:*
ring r1=32003,(x,y,z),dp;
ideal i=x,y,z;
ring r2=32003,(a,b),dp;
map f=r1,a,b,a+b;
// maps from r1 to r2,
// x -> a
// y -> b
// z -> a+b
f(i);
==> _[1]=a
==> _[2]=b
==> _[3]=a+b
// operations like f(i[1]) or f(i*i) are not allowed
ideal i=f(i);
// objects in different rings may have the same name
map g = r2,a2,b2;
map phi = g(f);
// composition of map f and g
// maps from r1 to r2,
// x -> a2
// y -> b2
// z -> a2+b2
phi(i);
==> _[1]=a2
==> _[2]=b2
==> _[3]=a2+b2
* Menu:
See
* fetch::
* ideal expressions::
* imap::
* map::
* ring::
See *note fetch::; *note ideal expressions::; *note imap::; *note map::;
*note ring::.
File: sing.htm, Node: map expressions, Next: map operations, Prev: map declarations, Up: map
4.8.2 map expressions
---------------------
A map expression is:
1. an identifier of type map
2. a function returning map
3. map expressions combined by composition using parentheses (`(',
`)')
File: sing.htm, Node: map operations, Prev: map expressions, Up: map
4.8.3 map operations
--------------------
`( )'
composition of maps. If, for example, `f' and `g' are maps, then
`f(g)' is a map expression giving the composition of `f' and `g'.
map_expression `[' int_expressions `]'
is a map entry (the image of the corresponding variable)
*Example:*
ring r=0,(x,y),dp;
map f=r,y,x; // the map f permutes the variables
f;
==> f[1]=y
==> f[2]=x
poly p=x+2y3;
f(p);
==> 2x3+y
map g=f(f); // the map g defined as f^2 is the identity
g;
==> g[1]=x
==> g[2]=y
g(p) == p;
==> 1
File: sing.htm, Node: matrix, Next: module, Prev: map, Up: Data types
4.9 matrix
==========
Objects of type matrix are matrices with polynomial entries. Like
polynomials they can only be defined or accessed with respect to a
basering. In order to compute with matrices having integer or rational
entries define a ring with characteristic 0 and at least one variable.
A matrix can be multiplied by and added to a poly; in this case the poly
is converted into a matrix of the right size with the poly on the
diagonal.
If A is a matrix then the assignment `module M=A;' or `module
M=module(A);' creates a module generated by the columns of A. Note that
the trailing zero columns of A may be deleted by module operations with
M.
* Menu:
* matrix declarations::
* matrix expressions::
* matrix type cast::
* matrix operations::
* matrix related functions::
File: sing.htm, Node: matrix declarations, Next: matrix expressions, Prev: matrix, Up: matrix
4.9.1 matrix declarations
-------------------------
*Syntax:*
`matrix' name`['rows`]['cols`] =' list_of_poly_expressions `;'
`matrix' name = matrix_expression `;'
*Purpose:*
defines a matrix (of polynomials).
The given poly_list fills up the matrix beginning with the first
row from the left to the right, then the second row and so on. If
the poly_list contains less than rows*cols elements, the matrix is
filled up with zeros; if it contains more elements, then only the
first rows*cols elements are used. If the right-hand side is a
matrix expression the matrix on the left-hand side gets the same
size as the right-hand side, otherwise the size is determined by
the left-hand side. If the size is omitted a 1x1 matrix is
created.
*Default:*
0 (1 x 1 matrix)
*Example:*
int ro = 3;
ring r = 32003,(x,y,z),dp;
poly f=xyz;
poly g=z*f;
ideal i=f,g,g^2;
matrix m[ro][3] = x3y4, 0, i, f ; // a 3 x 3 matrix
m;
==> m[1,1]=x3y4
==> m[1,2]=0
==> m[1,3]=xyz
==> m[2,1]=xyz2
==> m[2,2]=x2y2z4
==> m[2,3]=xyz
==> m[3,1]=0
==> m[3,2]=0
==> m[3,3]=0
print(m);
==> x3y4,0, xyz,
==> xyz2,x2y2z4,xyz,
==> 0, 0, 0
matrix A; // the 1 x 1 zero matrix
matrix B[2][2] = m[1..2, 2..3]; //defines a submatrix
print(B);
==> 0, xyz,
==> x2y2z4,xyz
matrix C=m; // defines C as a 3 x 3 matrix equal to m
print(C);
==> x3y4,0, xyz,
==> xyz2,x2y2z4,xyz,
==> 0, 0, 0
File: sing.htm, Node: matrix expressions, Next: matrix type cast, Prev: matrix declarations, Up: matrix
4.9.2 matrix expressions
------------------------
A matrix expression is:
1. an identifier of type matrix
2. a function returning matrix
3. matrix expressions combined by the arithmetic operations `+', `-'
or `*'
4. a type cast to matrix (*note matrix type cast::)
*Example:*
ring r=0,(x,y),dp;
poly f= x3y2 + 2x2y2 +2;
matrix H = jacob(jacob(f)); // the Hessian of f
matrix mc = coef(f,y);
print(mc);
==> y2, 1,
==> x3+2x2,2
module MD = [x+y,1,x],[x+y,0,y];
matrix M = MD;
print(M);
==> x+y,x+y,
==> 1, 0,
==> x, y
File: sing.htm, Node: matrix type cast, Next: matrix operations, Prev: matrix expressions, Up: matrix
4.9.3 matrix type cast
----------------------
`*Syntax:*'
`matrix (' expression `)'
`matrix (' expression, int_n, int_m `)'
`*Type:*'
matrix
`*Purpose:*'
Converts expression to a matrix, where expression must be of type
int, intmat, intvec, number, poly, ideal, vector, module, or
matrix. If int_n and int_m are supplied, then they specify the
dimension of the matrix. Otherwise, the size (resp. dimensions) of
the matrix are determined by the size (resp. dimensions) of the
expression.
`*Example:*'
ring r=32003,(x,y,z),dp;
matrix(x);
==> _[1,1]=x
matrix(x, 1, 2);
==> _[1,1]=x
==> _[1,2]=0
matrix(intmat(intvec(1,2,3,4), 2, 2));
==> _[1,1]=1
==> _[1,2]=2
==> _[2,1]=3
==> _[2,2]=4
matrix(_, 2, 3);
==> _[1,1]=1
==> _[1,2]=2
==> _[1,3]=0
==> _[2,1]=3
==> _[2,2]=4
==> _[2,3]=0
matrix(_, 2, 1);
==> _[1,1]=1
==> _[2,1]=3
* Menu:
See
* Type conversion and casting::
* intmat type cast::
* matrix::
See *note Type conversion and casting::; *note intmat type cast::; *note
matrix::.
File: sing.htm, Node: matrix operations, Next: matrix related functions, Prev: matrix type cast, Up: matrix
4.9.4 matrix operations
-----------------------
`+'
addition with matrix or poly; the poly is converted into a diagonal
matrix
`-'
negation or subtraction with matrix or poly; the poly is converted
into a diagonal matrix
`*'
multiplication with matrix or poly; the poly is converted into a
diagonal matrix
`/'
division by poly
`==', `<>', `!='
comparison
matrix_expression `[' int_expression`,' int_expression `]'
is a matrix entry, where the first index indicates the row and the
second the column
*Example:*
ring r=32003,x,dp;
matrix A[3][3] = 1,3,2,5,0,3,2,4,5; // define a matrix
print(A); // nice printing of small matrices
==> 1,3,2,
==> 5,0,3,
==> 2,4,5
A[2,3]; // matrix entry
==> 3
A[2,3] = A[2,3] + 1; // change entry
A[2,1..3] = 1,2,3; // change 2nd row
print(A);
==> 1,3,2,
==> 1,2,3,
==> 2,4,5
matrix E[3][3]; E = E + 1; // the unit matrix
matrix B =x*E - A;
print(B);
==> x-1,-3, -2,
==> -1, x-2,-3,
==> -2, -4, x-5
det(B); // the characteristic polynomial of A
==> x3-8x2-2x-1
A*A*A - 8 * A*A - 2*A == E; // Cayley-Hamilton
==> 1
vector v =[x,-1,x2];
A*v; // multiplication of matrix and vector
==> _[1,1]=2x2+x-3
==> _[2,1]=3x2+x-2
==> _[3,1]=5x2+2x-4
matrix m[2][2]=1,2,3;
print(m-transpose(m));
==> 0,-1,
==> 1,0
File: sing.htm, Node: matrix related functions, Prev: matrix operations, Up: matrix
4.9.5 matrix related functions
------------------------------
`bareiss'
Gauss-Bareiss algorithm (see *note bareiss::)
`coef'
matrix of coefficients and monomials (see *note coef::)
`coeffs'
matrix of coefficients (see *note coeffs::)
`det'
determinant (see *note det::)
`diff'
partial derivative (see *note diff::)
`jacob'
Jacobi matrix (see *note jacob::)
`koszul'
Koszul matrix (see *note koszul::)
`lift'
lift-matrix (see *note lift::)
`liftstd'
standard basis and transformation matrix computation (see *note
liftstd::)
`minor'
set of minors of a matrix (see *note minor::)
`ncols'
number of columns (see *note ncols::)
`nrows'
number of rows (see *note nrows::)
`print'
nice print format (see *note print::)
`size'
number of matrix entries (see *note size::)
`subst'
substitute a ring variable (see *note subst::)
`trace'
trace of a matrix (see *note trace::)
`transpose'
transpose a matrix (see *note transpose::)
`wedge'
wedge product (see *note wedge::)
See also the library *note matrix_lib::, which contains more
matrix-related functions.
File: sing.htm, Node: module, Next: number, Prev: matrix, Up: Data types
4.10 module
===========
Modules are submodules of a free module over the basering with basis
`gen(1)', `gen(2)', ... . They are represented by lists of vectors
which generate the submodule. Like vectors they can only be defined or
accessed with respect to a basering. If M $M$
is a submodule of R^n, $R^n$,
R $R$
the basering, generated by vectors v_1, ..., v_k, then v_1, ..., v_k $v_1, \ldots, v_k$, then $v_1, \ldots, v_k$
may be considered as the generators of relations of R^n/M $R^n/M$
between the canonical generators `gen(1)',...,`gen(n)'. Hence any
finitely generated R $R$
-module can be represented in SINGULAR by its module of relations. The
assignments `module M=v1,...,vk; matrix A=M;' create the presentation
matrix of size n x k n$\times$k
for R^n/M, R$^n$/M,
i.e., the columns of A are the vectors v_1, ..., v_k $v_1, \ldots, v_k$
which generate M (cf. *note Representation of mathematical objects::).
* Menu:
* module declarations::
* module expressions::
* module operations::
* module related functions::
File: sing.htm, Node: module declarations, Next: module expressions, Prev: module, Up: module
4.10.1 module declarations
--------------------------
*Syntax:*
`module' name `=' list_of_vector_expressions `;'
`module' name `=' module_expression `;'
*Purpose:*
defines a module.
*Default:*
[0]
*Example:*
ring r=0,(x,y,z),(c,dp);
vector s1 = [x2,y3,z];
vector s2 = [xy,1,0];
vector s3 = [0,x2-y2,z];
poly f = xyz;
module m = s1, s2-s1,f*(s3-s1);
m;
==> m[1]=[x2,y3,z]
==> m[2]=[-x2+xy,-y3+1,-z]
==> m[3]=[-x3yz,-xy4z+x3yz-xy3z]
// show m in matrix format (columns generate m)
print(m);
==> x2,-x2+xy,-x3yz,
==> y3,-y3+1, -xy4z+x3yz-xy3z,
==> z, -z, 0
File: sing.htm, Node: module expressions, Next: module operations, Prev: module declarations, Up: module
4.10.2 module expressions
-------------------------
A module expression is:
1. an identifier of type module
2. a function returning module
3. module expressions combined by the arithmetic operation `+'
4. multiplication of a module expression with an ideal or a poly
expression: `*'
5. a type cast to module
* Menu:
See
* Type conversion and casting::
* ideal::
* poly::
* vector::
See *note Type conversion and casting::; *note ideal::; *note poly::;
*note vector::.
File: sing.htm, Node: module operations, Next: module related functions, Prev: module expressions, Up: module
4.10.3 module operations
------------------------
`+'
addition (concatenation of the generators and simplification)
`*'
multiplication with ideal or poly, but not `module` * `module`
module_expression `[' int_expression `,' int_expression `]'
is a module entry, where the first index indicates the row and the
second the column
module_expressions `[' int_expression `]'
is a vector, where the index indicates the column
*Example:*
ring r=0,(x,y,z),dp;
module m=[x,y],[0,0,z];
print(m*(x+y));
==> x2+xy,0,
==> xy+y2,0,
==> 0, xz+yz
File: sing.htm, Node: module related functions, Prev: module operations, Up: module
4.10.4 module related functions
-------------------------------
`coeffs'
matrix of coefficients (see *note coeffs::)
`degree'
multiplicity, dimension and codimension of the module of leading
terms (see *note degree::)
`diff'
partial derivative (see *note diff::)
`dim'
Krull dimension of free module over the basering modulo the module
of leading terms (see *note dim::)
`eliminate'
elimination of variables (see *note eliminate::)
`freemodule'
the free module of given rank (see *note freemodule::)
`groebner'
Groebner basis computation (a wrapper around
`std,stdhilb,stdfglm',...) (see *note groebner::)
`hilb'
Hilbert function of a standard basis (see *note hilb::)
`homog'
homogenization with respect to a variable (see *note homog::)
`interred'
interreduction of a module (see *note interred::)
`intersect'
module intersection (see *note intersect::)
`jet'
Taylor series up to a given order (see *note jet::)
`kbase'
vector space basis of free module over the basering modulo the
module of leading terms (see *note kbase::)
`lead'
initial module (see *note lead::)
`lift'
lift-matrix (see *note lift::)
`liftstd'
standard basis and transformation matrix computation (see *note
liftstd::)
`lres'
free resolution (see *note lres::)
`minbase'
minimal generating set of a homogeneous ideal, resp. module, or an
ideal, resp. module, over a local ring
`modulo'
represents $(h1+h2)/h1=h2/(h1 \cap h2)$
(h1+h2)/h1=h2/(h1 intersect h2) (see *note modulo::)
`mres'
minimal free resolution of an ideal resp. module w.r.t. a minimal
set of generators of the given module (see *note mres::)
`mult'
multiplicity, resp. degree, of the module of leading terms (see
*note mult::)
`ncols'
number of columns (see *note ncols::)
`nrows'
number of rows (see *note nrows::)
`print'
nice print format (see *note print::)
`prune'
minimize the embedding into a free module (see *note prune::)
`qhweight'
quasihomogeneous weights of an ideal, resp. module (see *note
qhweight::)
`quotient'
module quotient (see *note quotient::)
`reduce'
normalform with respect to a standard basis (see *note reduce::)
`res'
free resolution of an ideal, resp. module, but not changing the
given ideal, resp. module (see *note res::)
`simplify'
simplify a set of vectors (see *note simplify::)
`size'
number of non-zero generators (see *note size::)
`sortvec'
permutation for sorting ideals/modules (see *note sortvec::)
`sres'
free resolution of a standard basis (see *note sres::)
`std'
standard basis computation (see *note std::, *note liftstd::)
`subst'
substitute a ring variable (see *note subst::)
`syz'
computation of the first syzygy module (see *note syz::)
`vdim'
vector space dimension of free module over the basering modulo
module of leading terms (see *note vdim::)
`weight'
"optimal" weights (see *note weight::)
File: sing.htm, Node: number, Next: poly, Prev: module, Up: Data types
4.11 number
===========
Numbers are elements from the coefficient field (or ground field). They
can only be defined or accessed with respect to a basering which
determines the coefficient field. See *note ring declarations:: for
declarations of coefficient fields.
*Warning:* Beware of the special meaning of the letter `e' (immediately
following a sequence of digits) if the field is real (or complex). See
*note number operations::, *note Miscellaneous oddities::.
* Menu:
* number declarations::
* number expressions::
* number operations::
* number related functions::
File: sing.htm, Node: number declarations, Next: number expressions, Prev: number, Up: number
4.11.1 number declarations
--------------------------
*Syntax:*
`number' name `=' number_expression `;'
*Purpose:*
defines a number.
*Default:*
0
*Note:*
Numbers may only be declared w.r.t. the coefficient field of the
current basering, i.e., a ring has to be defined prior to any
number declaration. See *note Rings and orderings:: for a list of
the available coefficient fields.
*Example:*
// finite field Z/p, p<= 32003
ring r = 32003,(x,y,z),dp;
number n = 4/6;
n;
==> -10667
// finite field GF(p^n), p^n <= 32767
// z is a primitive root of the minimal polynomial
ring rg= (7^2,z),x,dp;
number n = 4/9+z;
n;
==> z11
// the rational numbers
ring r0 = 0,x,dp;
number n = 4/6;
n;
==> 2/3
// algebraic extensions of Z/p or Q
ring ra=(0,a),x,dp;
minpoly=a^2+1;
number n=a3+a2+2a-1;
n;
==> (a-2)
a^2;
==> -1
// transcedental extensions of Z/p or Q
ring rt=(0,a),x,dp;
number n=a3+a2+2a-1;
n;
==> (a3+a2+2a-1)
a^2;
==> (a2)
// machine floating point numbers, single precision
ring R_0=real,x,dp;
number n=4/6;
n;
==> 6.667e-01
n=0.25e+2;
n;
==> 2.500e+01
// floating point numbers, arbitrary prescribed precision
ring R_1=(real,50),x,dp;
number n=4.0/6;
n;
==> 0.66666666666666666666666666666666666666666666666667
n=0.25e+2;
n;
==> 25
// floating point complex numbers, arbitrary prescribed precision
// the third parameter gives the name of the imaginary unit
ring R_2=(complex,50,i),x,dp;
number n=4.0/6;
n;
==> 0.66666666666666666666666666666666666666666666666667
n=0.25e+2*i+n;
n;
==> (0.66666666666666666666666666666666666666666666666667+i*25)
File: sing.htm, Node: number expressions, Next: number operations, Prev: number declarations, Up: number
4.11.2 number expressions
-------------------------
A number expression is:
1. a rational number (there are NO spaces allowed inside a rational
number, see *note int expressions::)
2. a floating point number (if the coefficient field is `real'):
`.'`e'
3. an identifier of type number
4. a function returning number
5. an int expression (see *note Type conversion and casting::)
6. number expressions combined by the arithmetic operations `+', `-',
`*', `/', `^', or `**'.
7. a type cast to number
*Example:*
// the following expressions are in any ring int expressions
2 / 3;
==> 0
4/ 8;
==> 0
2 /2; // the notation of / for div might change in the future
==> 1
ring r0=0,x,dp;
2/3, 4/8, 2/2 ; // are numbers
==> 2/3 1/2 1
poly f = 2x2 +1;
leadcoef(f);
==> 2
typeof(_);
==> number
ring rr =real,x,dp;
1.7e-2; 1.7e+2; // are valid (but 1.7e2 not), if the field is `real`
==> 1.700e-02
==> 1.700e+02
ring rp = (31,t),x,dp;
2/3, 4/8, 2/2 ; // are numbers
==> 11 -15 1
poly g = (3t2 +1)*x2 +1;
leadcoef(g);
==> (3t2+1)
typeof(_);
==> number
par(1);
==> (t)
typeof(_);
==> number
* Menu:
See
* Type conversion and casting::
* ring::
See *note Type conversion and casting::; *note ring::.
File: sing.htm, Node: number operations, Next: number related functions, Prev: number expressions, Up: number
4.11.3 number operations
------------------------
`+'
addition
`-'
negation or subtraction
`*'
multiplication
`/'
division
`^', `**'
power, exponentiation (by an integer)
`<=, >=, ==, <>'
comparison
`mod'
integer modulo (the remainder of the division `div'), always
non-negative
*Note:* quotient and exponentiation is only recognized as a number
expression if it is already a number, see *note Miscellaneous
oddities::.
For the behavior of comparison operators in rings with ground field
different from real or the rational numbers, see *note boolean
expressions::.
*Example:*
ring r=0,x,dp;
number n = 1/2 +1/3;
n;
==> 5/6
n/2;
==> 5/12
1/2/3;
==> 1/6
1/2 * 1/3;
==> 1/6
n = 2;
n^-2;
==> 1/4
// the following oddities appear here
2/(2+3);
==> 0
number(2)/(2+3);
==> 2/5
2^-2; // for int's exponent must be non-negative
==> ? exponent must be non-negative
==> ? error occurred in line 12: ` 2^-2; // for int's exponent must be no\
n-negative`
number(2)^-2;
==> 1/4
3/4>=2/5;
==> 1
2/6==1/3;
==> 1
File: sing.htm, Node: number related functions, Prev: number operations, Up: number
4.11.4 number related functions
-------------------------------
`cleardenom'
cancel denominators of numbers in poly and divide it by its content
(see *note cleardenom::)
`impart'
imaginary part of a complex number, 0 otherwise (see *note
impart::, *note repart::)
`numerator, denominator'
return the numerator/denominator of a rational number (see *note
numerator::, *note denominator::)
`leadcoef'
coefficient of the leading term (see *note leadcoef::)
`par'
n-th parameter of the basering (see *note par::)
`pardeg'
degree of a number in ring parameters (see *note pardeg::)
`parstr'
string form of ring parameters (see *note parstr::)
`repart'
real part of a complex number (see *note impart::, *note repart::)
File: sing.htm, Node: poly, Next: proc, Prev: number, Up: Data types
4.12 poly
=========
Polynomials are the basic data for all main algorithms in `SINGULAR'.
They consist of finitely many terms (coefficient*power product) which
are combined by the usual polynomial operations (see *note poly
expressions::). Polynomials can only be defined or accessed with respect
to a basering which determines the coefficient type, the names of the
indeterminates and the monomial ordering.
ring r=32003,(x,y,z),dp;
poly f=x3+y5+z2;
* Menu:
* poly declarations::
* poly expressions::
* poly operations::
* poly related functions::
File: sing.htm, Node: poly declarations, Next: poly expressions, Prev: poly, Up: poly
4.12.1 poly declarations
------------------------
*Syntax:*
`poly' name `=' poly_expression `;'
*Purpose:*
defines a polynomial.
*Default:*
0
*Example:*
ring r = 32003,(x,y,z),dp;
poly s1 = x3y2+151x5y+186xy6+169y9;
poly s2 = 1*x^2*y^2*z^2+3z8;
poly s3 = 5/4x4y2+4/5*x*y^5+2x2y2z3+y7+11x10;
int a,b,c,t=37,5,4,1;
poly f=3*x^a+x*y^(b+c)+t*x^a*y^b*z^c;
f;
==> x37y5z4+3x37+xy9
short = 0;
f;
==> x^37*y^5*z^4+3*x^37+x*y^9
* Menu:
See also:
* short::
*See also:* *note short::.
File: sing.htm, Node: poly expressions, Next: poly operations, Prev: poly declarations, Up: poly
4.12.2 poly expressions
-----------------------
A poly expression is (optional parts in square brackets):
1. a monomial (there are NO spaces allowed inside a monomial)
[coefficient] ring_variable [ exponent] [ring_variable [exponent] ...]
monomials which contain an indexed ring variable must be built from
`ring_variable' and `coefficient' with the operations `*' and `^'
2. an identifier of type poly
3. a function returning poly
4. poly expressions combined by the arithmetic operations `+', `-',
`*', `/', or `^'
5. an int expression (see *note Type conversion and casting::)
6. a type cast to poly
*Example:*
2x, x3, 2x2y3, xyz, 2xy2; // are monomials
2*x, x^3, 2*x^2*y^3, x*y*z, 2*x*y^2; // are poly expressions
2*x(1); // is a valid poly expression, but not 2x(1) (a syntax error)
2*x^3; // is a valid poly expression equal to 2x3 (a valid monomial)
// but not equal to 2x^3 which will be interpreted as (2x)^3
// since 2x is a monomial
ring r=0,(x,y),dp;
poly f = 10x2y3 +2x2y2-2xy+y -x+2;
lead(f);
==> 10x2y3
leadmonom(f);
==> x2y3
simplify(f,1); // normalize leading coefficient
==> x2y3+1/5x2y2-1/5xy-1/10x+1/10y+1/5
poly g = 1/2x2 + 1/3y;
cleardenom(g);
==> 3x2+2y
int i = 102;
poly(i);
==> 102
typeof(_);
==> poly
* Menu:
See
* Type conversion and casting::
* ring::
See *note Type conversion and casting::; *note ring::.
File: sing.htm, Node: poly operations, Next: poly related functions, Prev: poly expressions, Up: poly
4.12.3 poly operations
----------------------
`+'
addition
`-'
negation or subtraction
`*'
multiplication
`/'
division by a polynomial, ignoring the rest
`^', `**'
power by an integer
`<', `<=', `>', `>=', `==', `<>'
comparison (w.r.t. monomial ordering)
poly_expression `[' intvec_expression `]'
the monomial at the indicated place w.r.t. the monomial ordering
*Example:*
ring R=0,(x,y),dp;
poly f = x3y2 + 2x2y2 + xy - x + y + 1;
f;
==> x3y2+2x2y2+xy-x+y+1
f + x5 + 2;
==> x5+x3y2+2x2y2+xy-x+y+3
f * x2;
==> x5y2+2x4y2+x3y-x3+x2y+x2
(x+y)/x;
==> 1
f/3x2;
==> 1/3xy2+2/3y2
x5 > f;
==> 1
x<=y;
==> 0
x>y;
==> 1
ring r=0,(x,y),ds;
poly f = fetch(R,f);
f;
==> 1-x+y+xy+2x2y2+x3y2
x5 > f;
==> 0
f[2..4];
==> -x+y+xy
size(f);
==> 6
f[size(f)+1]; f[-1]; // monomials out of range are 0
==> 0
==> 0
intvec v = 6,1,3;
f[v]; // the polynom built from the 1st, 3rd and 6th monomial of f
==> 1+y+x3y2
File: sing.htm, Node: poly related functions, Prev: poly operations, Up: poly
4.12.4 poly related functions
-----------------------------
`cleardenom'
cancel denominators of numbers in poly and divide it by its content
(see *note cleardenom::)
`coef'
matrix of coefficients and monomials (see *note coef::)
`coeffs'
matrix of coefficients (see *note coeffs::)
`deg'
degree (see *note deg::)
`det'
determinant (see *note det::)
`diff'
partial derivative (see *note diff::)
`extgcd'
Bezout representation of gcd (see *note extgcd::)
`factorize'
factorize polynomial (see *note factorize::)
`finduni'
find univariate polynomials in a zero-dimensional ideal (see *note
finduni::)
`gcd'
greatest common divisor (see *note gcd::)
`homog'
homogenization (see *note homog::)
`jacob'
ideal, resp. matrix, of all partial derivatives (see *note jacob::)
`lead'
leading term (see *note lead::)
`leadcoef'
coefficient of the leading term (see *note leadcoef::)
`leadexp'
the exponent vector of the leading monomial (see *note leadexp::)
`leadmonom'
leading monomial (see *note leadmonom::)
`jet'
monomials with degree smaller k+1 (see *note jet::)
`ord'
degree of the leading monomial (see *note ord::)
`qhweight'
quasihomogeneous weights (see *note qhweight::)
`reduce'
normal form with respect to a standard base (see *note reduce::)
`rvar'
test for ring variable (see *note rvar::)
`simplify'
normalize a polynomial (see *note simplify::)
`size'
number of monomials (see *note size::)
`subst'
substitute a ring variable (see *note subst::)
`trace'
trace of a matrix (see *note trace::)
`var'
the indicated variable of the ring (see *note var::)
`varstr'
variable in string form (see *note varstr::)
File: sing.htm, Node: proc, Next: qring, Prev: poly, Up: Data types
4.13 proc
=========
Procedures are sequences of SINGULAR commands in a special format. They
are used to extend the set of SINGULAR commands with user defined
commands. Once a procedure is defined it can be used as any other
SINGULAR command. Procedures may be defined by either typing them on the
command line or by loading them from a file. For a detailed description
on the concept of procedures in SINGULAR see *note Procedures::. A file
containing procedure definitions which comply with certain syntax rules
is called a library. Such a file is loaded using the command `LIB'. For
more information on libraries see *note Libraries::.
* Menu:
* proc declaration::
File: sing.htm, Node: proc declaration, Prev: proc, Up: proc
4.13.1 proc declaration
-----------------------
*Syntax:*
[`static'] `proc' proc_name [parameter_list]
["help_text"]
`{'
\quad
procedure_body
`}'
[`example'
`{'
\quad
sequence_of_commands;
`}']
`proc' proc_name `=' proc_name `;'
`proc' proc_name `=' string_expression `;'
*Purpose:*
defines a new function, the `proc' proc_name, with the additional
information help_text, which is copied to the screen by `help
proc_name;' and the `example' section which is executed by `example
proc_name;'.
The help_text, the parameter_list, and the example section are
optional. The default for a parameter_list is `(list #)', see
*note Parameter list::. The help and example sections are ignored
if the procedure is defined interactively, i.e., if it was not
loaded from a file by a *note LIB:: command.
Specifying `static' in front of the proc-definition is only
possible in a library file and makes this procedure local to the
library, i.e., accessible only for the other procedures in the same
library, but not for the users.
*Example:*
proc milnor_number (poly p)
{
ideal i= std(jacob(p));
int m_nr=vdim(i);
if (m_nr<0)
{
"// not an isolated singularity";
}
return(m_nr); // the value of m_nr is returned
}
ring r1=0,(x,y,z),ds;
poly p=x^2+y^2+z^5;
milnor_number(p);
==> 4
* Menu:
See
* LIB::
* Libraries::
* Procedures::
See *note LIB::; *note Libraries::; *note Procedures::.
File: sing.htm, Node: qring, Next: resolution, Prev: proc, Up: Data types
4.14 qring
==========
SINGULAR offers the opportunity to calculate in quotient rings (factor
rings), i.e., rings modulo an ideal. The ideal has to be given as a
standard basis. For a detailed description of the concept of rings and
quotient rings see *note Rings and orderings::.
* Menu:
* qring declaration::
File: sing.htm, Node: qring declaration, Prev: qring, Up: qring
4.14.1 qring declaration
------------------------
*Syntax:*
`qring' name `=' ideal_expression `;'
*Default:*
none
*Purpose:*
declares a quotient ring as the basering modulo ideal_expression.
Sets it as current basering.
*Example:*
ring r=0,(x,y,z),dp;
ideal i=xy;
qring q=std(i);
basering;
==> // characteristic : 0
==> // number of vars : 3
==> // block 1 : ordering dp
==> // : names x y z
==> // block 2 : ordering C
==> // quotient ring from ideal
==> _[1]=xy
File: sing.htm, Node: resolution, Next: ring, Prev: qring, Up: Data types
4.15 resolution
===============
The resolution type is intended as an intermediate representation which
internally retains additional information obtained during computation of
resolutions. It furthermore enables the use of partial results to
compute, for example, Betti numbers or minimal resolutions. Like ideals
and modules, a resolution can only be defined w.r.t. a basering.
*Note:* to access the elements of a resolution, it has to be assigned to
a list, which also completes computations and may therefore take time,
(resp. an access directly with the brackets `[ , ]' causes implicitly a
cast to a list).
* Menu:
* resolution declarations::
* resolution expressions::
* resolution related functions::
File: sing.htm, Node: resolution declarations, Next: resolution expressions, Prev: resolution, Up: resolution
4.15.1 resolution declarations
------------------------------
*Syntax:*
`resolution' name `=' resolution_expression `;'
*Purpose:*
defines a resolution.
*Default:*
none
*Example:*
ring R;
ideal i=z2,x;
resolution re=res(i,0);
re;
==> 1 2 1
==> R <-- R <-- R
==>
==> 0 1 2
==> resolution not minimized yet
==>
betti(re);
==> 1,1,0,
==> 0,1,1
list l = re;
l;
==> [1]:
==> _[1]=x
==> _[2]=z2
==> [2]:
==> _[1]=-z2*gen(1)+x*gen(2)
==> [3]:
==> _[1]=0
File: sing.htm, Node: resolution expressions, Next: resolution related functions, Prev: resolution declarations, Up: resolution
4.15.2 resolution expressions
-----------------------------
A resolution expression is:
1. an identifier of type resolution
2. a function returning a resolution
3. a type cast to resolution from a list of ideals, resp. modules..
* Menu:
See
* Type conversion and casting::
See *note Type conversion and casting::.
File: sing.htm, Node: resolution related functions, Prev: resolution expressions, Up: resolution
4.15.3 resolution related functions
-----------------------------------
`betti'
Betti numbers of a resolution (see *note betti::)
`lres'
free resolution (see *note lres::)
`minres'
minimize a free resolution (see *note minres::)
`mres'
minimal free resolution of an ideal, resp. module w.r.t. a minimal
set of generators of the given ideal, resp. module (see *note
mres::)
`res'
free resolution of an ideal, resp. module, but not changing the
given ideal, resp. module (see *note res::)
`sres'
free resolution of a standard basis (see *note sres::)
File: sing.htm, Node: ring, Next: string, Prev: resolution, Up: Data types
4.16 ring
=========
Rings are used to describe properties of polynomials, ideals etc.
Almost all computations in SINGULAR require a basering. For a detailed
description of the concept of rings see *note Rings and orderings::.
* Menu:
* ring declarations::
* ring related functions::
* ring operations::
File: sing.htm, Node: ring declarations, Next: ring related functions, Prev: ring, Up: ring
4.16.1 ring declarations
------------------------
*Syntax:*
`ring' name `= (' coefficient_field `),' `('
names_of_ring_variables `),' `(' ordering `);'
*Default:*
`32003,(x,y,z),(dp,C);'
*Purpose:*
declares a ring and sets it as the actual basering.
The coefficient_field is given by one of the following:
1. a non-negative int_expression less or equal 2147483629.
2. an expression_list of an int_expression and one or more names.
3. the name `real'
4. an expression_list of the name `real' and an int_expression.
5. an expression_list of the name `complex', an optional
int_expression and a name.
For the definition of the 'coefficient_field', see *note Rings and
orderings::.
'names_of_ring_variables' must be a list of names or indexed names.
'ordering' is a list of block orderings where each block ordering is
either
1. `lp', `dp', `Dp', `ls', `ds', or `Ds' optionally followed by a size
parameter in parentheses.
2. `wp', `Wp', `ws', `Ws', or `a' followed by a weight vector given as
an intvec_expression in parentheses.
3. `M' followed by an intmat_expression in parentheses.
4. `c' or `C'.
For the definition of the orderings, see *note Term orderings::, *note
Monomial orderings::.
If one of coefficient_field, names_of_ring_variables, and ordering
consists of only one entry, the parentheses around this entry may be
omitted.
File: sing.htm, Node: ring related functions, Next: ring operations, Prev: ring declarations, Up: ring
4.16.2 ring related functions
-----------------------------
`charstr'
description of the coefficient field of a ring (see *note
charstr::)
`keepring'
move ring to next upper level (see *note keepring::)
`npars'
number of ring parameters (see *note npars::)
`nvars'
number of ring variables (see *note nvars::)
`ordstr'
monomial ordering of a ring (see *note ordstr::)
`parstr'
names of all ring parameters or the name of the n-th ring parameter
(see *note parstr::)
`qring'
quotient ring (see *note qring::)
`setring'
set a new basering (see *note setring::)
`varstr'
names of all ring variables or the name of the n-th ring variable
(see *note varstr::)
File: sing.htm, Node: ring operations, Prev: ring related functions, Up: ring
4.16.3 ring operations
----------------------
`+'
construct a new ring k[X,Y] $k[X,Y]$
from k_1[X] $k_1[X]$
and k_2[Y] $k_2[Y]$
.
Concerning the ground fields k_1 $k_1$
and k_2 $k_2$
take the following guide lines into consideration:
* Neither k_1 $k_1$
nor k_2 $k_2$
may be R $R$
or C $C$
.
* If the characteristic of k_1 $k_1$
and k_2 $k_2$
differs, then one of them must be Q $Q$
.
* At most one of k_1 $k_1$
and k_2 $k_2$
may be have parameters.
* If one of k_1 $k_1$
and k_2 $k_2$
is an algebraic extension of Z/p $Z/p$
it may not be defined by a `charstr' of type `(p^n,a)'.
*Example:*
ring R1=0,(x,y),dp;
ring R2=32003,(a,b),dp;
def R=R1+R2;
R;
==> // characteristic : 32003
==> // number of vars : 4
==> // block 1 : ordering dp
==> // : names x y
==> // block 2 : ordering dp
==> // : names a b
==> // block 3 : ordering C
* Menu:
See also:
* ring_lib::
*See also:* *note ring_lib::.
File: sing.htm, Node: string, Next: vector, Prev: ring, Up: Data types
4.17 string
===========
Variables of type `string' are used for output (almost every type can be
"converted" to `string') and for creating new commands at runtime see
*note execute::. They are also return values of certain interpreter
related functions (see *note Functions::). String constants consist of
a sequence of ANY characters (including newline!) between a starting
`"' and a closing `"'. There is also a string constant `newline', which
is the newline character. The `+' sign "adds" strings, `""' is the
empty string (hence strings form a semigroup). Strings may be used to
comment the output of a computation or to give it a nice format. Strings
may also be used for intermediate conversion of one type into another.
string s="Hi";
string s1="a string with new line at the end"+newline;
string s2="another string with new line at the end
";
s;s1;s2;
==> Hi
==> a string with new line at the end
==>
==> another string with new line at the end
==>
ring r; ideal i=std(ideal(x,y^3));
"dimension of i =",dim(i),", multiplicity of i =",mult(i);
==> dimension of i = 1 , multiplicity of i = 3
"dimension of i = "+string(dim(i))+", multiplicity of i = "+string(mult(i));
==> dimension of i = 1, multiplicity of i = 3
"a"+"b","c";
==> ab c
A comma between two strings makes an expression list out of them (such a
list is printed with a separating blank in between), while a `+'
concatenates strings.
* Menu:
* string declarations::
* string expressions::
* string type cast::
* string operations::
* string related functions::
File: sing.htm, Node: string declarations, Next: string expressions, Prev: string, Up: string
4.17.1 string declarations
--------------------------
*Syntax:*
`string' name `=' string_expression `;'
`string' name `=' list_of_string_expressions `;'
*Purpose:*
defines a string variable.
*Default:*
"" (the empty string)
*Example:*
string s1="Now I know";
string s2="how to encode a \" in a string...";
string s=s1+" "+s2; // concatenation of 3 strings
s;
==> Now I know how to encode a " in a string...
s1,s2; // 2 strings, separated by a blank in the output:
==> Now I know how to encode a " in a string...
File: sing.htm, Node: string expressions, Next: string type cast, Prev: string declarations, Up: string
4.17.2 string expressions
-------------------------
A string expression is:
1. a sequence of characters between two unescaped quotes (`"')
2. an identifier of type string
3. a function returning string
4. a substring (using the bracket operator)
5. a type cast to string (*note string type cast::)
6. string expressions combined by the operation `+'.
*Example:*
// string_expression[start, length] : a substring
// (possibly filled up with blanks)
// the substring of s starting at position 2
// with a length of 4
string s="123456";
s[2,4];
==> 2345
"abcd"[2,2];
==> bc
// string_expression[position] : a character from a string
s[3];
==> 3
// string_expression[position..position] :
// a substring starting at the first position up to the second
// given position
s[2..4];
==> 2 3 4
// a function returning a string
typeof(s);
==> string
* Menu:
See
* Type conversion and casting::
* string type cast::
See *note Type conversion and casting::; *note string type cast::.
File: sing.htm, Node: string type cast, Next: string operations, Prev: string expressions, Up: string
4.17.3 string type cast
-----------------------
`*Syntax:*'
`string (' expression [, expression_2, ... expression_n]`)'
`*Type:*'
string
`*Purpose:*'
Converts each expression to a string, where expression can be of
any type. The concatenated string of all concersions is returned.
The elements of intvec, intmat, ideal, module, matrix, and list,
are separated by a comma. No newlines are inserted.
Not defined elements of a list are omitted.
For link, the name of the link is used.
For map, the ideal defining the mapping is converted.
`*Note:*'
When applied to a list, elements of type intvec, intmat, ideal,
module, matrix, and list become indistinguishable.
`*Example:*'
string("1+1=", 2);
==> 1+1=2
string(intvec(1,2,3,4));
==> 1,2,3,4
string(intmat(intvec(1,2,3,4), 2, 2));
==> 1,2,3,4
ring r;
string(r);
==> (32003),(x,y,z),(dp(3),C)
string(ideal(x,y));
==> x,y
qring R = std(ideal(x,y));
string(R);
==> (32003),(x,y,z),(dp(3),C)
map phi = r, ideal(x,z);
string(phi);
==> x,z
list l;
string(l);
==>
l[3] = 1;
string(l); // notice that l[1],l[2] are omitted
==> 1
l[2] = l;
l;
==> [2]:
==> [3]:
==> 1
==> [3]:
==> 1
string(l); // notice that lists of list is flattened
==> 1,1
l[1] = intvec(1,2,3);
l;
==> [1]:
==> 1,2,3
==> [2]:
==> [3]:
==> 1
==> [3]:
==> 1
string(l); // notice that intvec elements are not distinguishable
==> 1,2,3,1,1
* Menu:
See
* Type conversion and casting::
* print::
* string::
See *note Type conversion and casting::; *note print::; *note string::.
File: sing.htm, Node: string operations, Next: string related functions, Prev: string type cast, Up: string
4.17.4 string operations
------------------------
`+'
concatenation
`<=', `>=', `==', `<>'
comparison (lexicographical with respect to the ASCII encoding)
string_expression `[' int_expression `]'
is a character of the string; the index 1 gives the first
character.
string_expression `[' int_expression`,' int_expression `]'
is a substring, where the first argument is the start index and the
second is the length of the substring, filled up with blanks if the
length exceeds the total size of the string
string_expression `[' intvec_expression `]'
is a expression list of characters from the string
*Example:*
string s="abcde";
s[2];
==> b
s[3,2];
==> cd
">>"+s[1,10]+"<<";
==> >>abcde <<
s[2]="BC"; s;
==> aBcde
intvec v=1,3,5;
s=s[v]; s;
==> ace
s="123456"; s=s[3..5]; s;
==> 345
File: sing.htm, Node: string related functions, Prev: string operations, Up: string
4.17.5 string related functions
-------------------------------
`charstr'
description of the coefficient field of a ring (see *note
charstr::)
`execute'
executing string as command (see *note execute::)
`find'
position of a substring in a string (see *note find::)
`names'
list of strings of all user-defined variable names (see *note
names::)
`nameof'
name of an object (see *note nameof::)
`option'
lists all defined options (see *note option::)
`ordstr'
monomial ordering of a ring (see *note ordstr::)
`parstr'
names of all ring parameters or the name of the n-th ring parameter
(see *note parstr::)
`read'
read a file (see *note read::)
`size'
length of a string (see *note size::)
`sprintf'
string formatting (see *note sprintf::)
`typeof'
type of an object (see *note typeof::)
`varstr'
names of all ring variables or the name of the n-th ring variable
(see *note varstr::)
File: sing.htm, Node: vector, Prev: string, Up: Data types
4.18 vector
===========
Vectors are elements of a free module over the basering with basis
`gen(1)', `gen(2)', ... . Each vector belongs to a free module of rank
equal to the biggest index of a generator with non-zero coefficient.
Since generators with zero coefficients need not be written any vector
may be considered also as an element of a free module of higher rank.
Like polynomials they can only be defined or accessed with respect to
the basering. (E.g., if `f' and `g' are polynomials then
`f*gen(1)+g*gen(3)+gen(4)' may also be written as `[f,0,g,1]' or as
`[f,0,g,1,0]'.) Note that the elements of a vector have to be surrounded
by square brackets (`[' , `]') (cf. *note Representation of
mathematical objects::).
* Menu:
* vector declarations::
* vector expressions::
* vector operations::
* vector related functions::
File: sing.htm, Node: vector declarations, Next: vector expressions, Prev: vector, Up: vector
4.18.1 vector declarations
--------------------------
*Syntax:*
`vector' name `=' vector_expression `;'
*Purpose:*
defines a vector of polynomials (an element of a free module).
*Default:*
[0]
*Example:*
ring r=0,(x,y,z),(c,dp);
poly s1 = x2;
poly s2 = y3;
poly s3 = z;
vector v = [s1, s2-s1, s3-s1]+ s1*gen(5);
// v is a vector in the free module of rank 5
v;
==> [x2,y3-x2,-x2+z,0,x2]
File: sing.htm, Node: vector expressions, Next: vector operations, Prev: vector declarations, Up: vector
4.18.2 vector expressions
-------------------------
A vector expression is:
1. an identifier of type vector
2. a function returning vector
3. a poly expression (via the canonical embedding `p' ==> `p*gen(1)')
4. vector expressions combined by the arithmetic operations `+' or `-'
5. a poly expression and a vector expression combined by the
arithmetic operation `*'
6. a type cast to vector using the brackets `[' , `]'
*Example:*
// ordering gives priority to components:
ring rr=0,(x,y,z),(c,dp);
vector v=[x2+y3,2,0,x*y]+gen(6)*x6;
v;
==> [y3+x2,2,0,xy,0,x6]
vector w=[z3-x,3y];
v-w;
==> [y3-z3+x2+x,-3y+2,0,xy,0,x6]
v*(z+x);
==> [xy3+y3z+x3+x2z,2x+2z,0,x2y+xyz,0,x7+x6z]
* Menu:
See
* Type conversion and casting::
* ring::
See *note Type conversion and casting::; *note ring::.
File: sing.htm, Node: vector operations, Next: vector related functions, Prev: vector expressions, Up: vector
4.18.3 vector operations
------------------------
`+'
addition
`-'
negation or subtraction
`/'
division by a monomial, not divisible terms yield 0
`<', `<=', `>', `>=', `==', `<>'
comparison of leading terms w.r.t. monomial ordering
vector_expression `[' int_expressions `]'
is a vector entry; the index 1 gives the first entry.
*Example:*
ring R=0,(x,y),(c,dp);
[x,y]-[1,x];
==> [x-1,-x+y]
[1,2,x,4][3];
==> x
File: sing.htm, Node: vector related functions, Prev: vector operations, Up: vector
4.18.4 vector related functions
-------------------------------
`cleardenom'
quotient of a vector by its content (see *note cleardenom::)
`coeffs'
matrix of coefficients (see *note coeffs::)
`deg'
degree (see *note deg::)
`diff'
partial derivative (see *note diff::)
`gen'
i-th generator (see *note gen::)
`homog'
homogenization (see *note homog::)
`jet'
k-jet: monomials with degree smaller k+1 (see *note jet::)
`lead'
leading term (see *note lead::)
`leadcoef'
leading coefficient (see *note leadcoef::)
`leadexp'
the exponent vector of the leading monomial (see *note leadexp::)
`leadmonom'
leading monomial (see *note leadmonom::)
`nrows'
number of rows (see *note nrows::)
`ord'
degree of the leading monomial (see *note ord::)
`reduce'
normal form with respect to a standard base (see *note reduce::)
`simplify'
normalize a vector (see *note simplify::)
`size'
number of monomials (see *note size::)
`subst'
substitute a ring variable (see *note subst::)
File: sing.htm, Node: Functions and system variables, Next: Tricks and pitfalls, Prev: Data types, Up: Top
5 Functions and system variables
********************************
* Menu:
* Functions::
* Control structures::
* System variables::
File: sing.htm, Node: Functions, Next: Control structures, Prev: Functions and system variables, Up: Functions and system variables
5.1 Functions
=============
This section gives a complete reference of all functions, commands and
special variables of the SINGULAR kernel (i.e., all built-in commands).
*Note standard_lib::, for those functions from the `standard.lib' (this
library is automatically loaded at start-up time) which extend the
functionality of the kernel and are written in the SINGULAR programming
language.
The general syntax of a function is
[target =] function_name ();
If no target is specified, the result is printed. In some cases (e.g.,
`export', `keepring', `kill', `setring', `type') the brackets are
optional. For the commands `help', `break', `quit', `exit' and `LIB' no
brackets are allowed.
List of all supported kernel functions.
* Menu:
* attrib::
* bareiss::
* betti::
* char::
* char_series::
* charstr::
* cleardenom::
* close::
* coef::
* coeffs::
* contract::
* dbprint::
* defined::
* deg::
* degree::
* delete::
* det::
* diff::
* dim::
* division::
* dump::
* eliminate::
* eval::
* ERROR::
* example::
* execute::
* exit::
* extgcd::
* facstd::
* factorize::
* fetch::
* fglm::
* fglmquot::
* filecmd::
* find::
* finduni::
* fprintf::
* freemodule::
* gcd::
* gen::
* getdump::
* groebner::
* help::
* highcorner::
* hilb::
* homog::
* hres::
* imap::
* impart::
* indepSet::
* insert::
* interred::
* intersect::
* jacob::
* jet::
* kbase::
* kill::
* killattrib::
* koszul::
* laguerre::
* lead::
* leadcoef::
* leadexp::
* leadmonom::
* LIB::
* lift::
* liftstd::
* listvar::
* lres::
* maxideal::
* memory::
* minbase::
* minor::
* minres::
* modulo::
* monitor::
* mpresmat::
* mres::
* mstd::
* mult::
* nameof::
* names::
* ncols::
* npars::
* nres::
* nrows::
* nvars::
* open::
* option::
* ord::
* ordstr::
* par::
* pardeg::
* parstr::
* preimage::
* prime::
* print::
* printf::
* prune::
* qhweight::
* quot::
* quote::
* quotient::
* random::
* read::
* reduce::
* regularity::
* repart::
* res::
* reservedName::
* resultant::
* rvar::
* setring::
* simplex::
* simplify::
* size::
* sortvec::
* sprintf::
* sres::
* status::
* std::
* stdfglm::
* stdhilb::
* subst::
* system::
* syz::
* trace::
* transpose::
* type::
* typeof::
* uressolve::
* vandermonde::
* var::
* varstr::
* vdim::
* wedge::
* weight::
* write::
File: sing.htm, Node: attrib, Next: bareiss, Prev: Functions, Up: Functions
5.1.1 attrib
------------
`*Syntax:*'
`attrib (' name `)'
`*Type:*'
none
`*Purpose:*'
displays the attribute list of the object called name.
`*Example:*'
ring r=0,(x,y,z),dp;
ideal I=std(maxideal(2));
attrib(I);
==> attr:isSB, type int
`*Syntax:*'
`attrib (' name `,' string_expression `)'
`*Type:*'
any
`*Purpose:*'
returns the value of the attribute string_expression of the
variable name. If the attribute is not defined for this variable,
`attrib' returns the empty string.
`*Example:*'
ring r=0,(x,y,z),dp;
ideal I=std(maxideal(2));
attrib(I,"isSB");
==> 1
// although maxideal(2) is a standard basis,
// SINGULAR does not know it:
attrib(maxideal(2), "isSB");
==> 0
`*Syntax:*'
`attrib (' name`,' string_expression`,' expression `)'
`*Type:*'
none
`*Purpose:*'
sets the attribute string_expression of the variable name to the
value expression.
`*Example:*'
ring r=0,(x,y,z),dp;
ideal I=maxideal(2); // the attribute "isSB" is not set
vdim(I);
==> // ** I is no standardbasis
==> 4
attrib(I,"isSB",1); // the standard basis attribute is set here
vdim(I);
==> 4
`*Remark:*'
An attribute may be described by any string_expression. Some of
these are used by the kernel of SINGULAR and referred to as
reserved attributes. Non-reserved attributes may be used, however,
in procedures and can considerably speed up computations.
`*Reserved attributes:*'
(not all are in use at the moment)
`isSB'
the standard basis property is set by all commands computing a
standard basis like `groebner', `std', `stdhilb' etc.; used by
`lift', `dim', `degree', `mult', `hilb', `vdim', `kbase'
`isHomog'
the weight vector for homogeneous or quasihomogeneous
ideals/modules
`isCI'
complete intersection property
`isCM'
Cohen-Macaulay property
`rank'
set the rank of a module (see *note nrows::)
`withSB'
value of type ideal, resp. module, is std
`withHilb'
value of type intvec is hilb(_,1) (see *note hilb::)
`withRes'
value of type list is a free resolution
`withDim'
value of type int is the dimension (see *note dim::)
`withMult'
value of type int is the multiplicity (see *note mult::)
File: sing.htm, Node: bareiss, Next: betti, Prev: attrib, Up: Functions
5.1.2 bareiss
-------------
`*Syntax:*'
`bareiss (' module_expression `)'
`bareiss (' matrix_expression `)'
`bareiss (' module_expression`,' int_expression`,' int_expression
`)'
`bareiss (' matrix_expression`,' int_expression`,' int_expression
`)'
`*Type:*'
list of module and intvec
`*Purpose:*'
applies the sparse Gauss-Bareiss algorithm (see *note References::,
Lee and Saunders) to a module (or with type conversion to a matrix)
with an 'optimal' pivot strategy. The vectors of the module are the
columns of the matrix, hence elimination takes place w.r.t. rows.
With only one parameter a complete elimination is done. Result is
a list: the first entry is a module with a minimal independent set
of vectors (as a matrix lower triangular), the second entry an
intvec with the permutation of the rows w.r.t. the original matrix,
that is, a k at position l indicates that row l became row k.
The further parameters control the algorithm. `bareiss(M,i,j)' does
not consider the last i rows in the elimination procedure and stops
computing when the remaining number of vectors (columns) to reduce
is at most j.
`*Example:*'
ring r=0,(x,y,z),(c,dp);
module mm;
// ** generation of the module mm **
int d=7;
int b=2;
int db=d-b;
int i;
for(i=d;i>0;i--){ mm[i]=3*x*gen(i); }
for(i=db;i;i--){ mm[i]=mm[i]+7*y*gen(i+b); }
for(i=d;i>db;i--){ mm[i]=mm[i]+7*y*gen(i-db); }
for(i=d;i>b;i--){ mm[i]=mm[i]+11*z*gen(i-b); }
for(i=b;i;i--){ mm[i]=mm[i]+11*z*gen(i+db); }
// ** the generating matrix of mm **
print(mm);
==> 3x, 0, 11z,0, 0, 7y, 0,
==> 0, 3x, 0, 11z,0, 0, 7y,
==> 7y, 0, 3x, 0, 11z,0, 0,
==> 0, 7y, 0, 3x, 0, 11z,0,
==> 0, 0, 7y, 0, 3x, 0, 11z,
==> 11z,0, 0, 7y, 0, 3x, 0,
==> 0, 11z,0, 0, 7y, 0, 3x
// complete elimination
list ss=bareiss(mm);
print(ss[1]);
==> 7y, 0, 0, 0, 0, 0, 0,
==> 3x, -33xz, 0, 0, 0, 0, 0,
==> 11z,-121z2,1331z3,0, 0, 0, 0,
==> 0, 0, 0, 9317yz3,0, 0, 0,
==> 0, 21xy, _[5,3],14641z4,-43923xz4,0, 0,
==> 0, 0, 0, 0, 65219y2z3,_[6,6],0,
==> 0, 49y2, _[7,3],3993xz3,_[7,5], _[7,6],_[7,7]
ss[2];
==> 2,7,5,1,4,3,6
// elimination up to 3 vectors
ss=bareiss(mm,0,3);
print(ss[1]);
==> 7y, 0, 0, 0, 0, 0, 0,
==> 3x, -33xz, 0, 0, 0, 0, 0,
==> 11z,-121z2,1331z3,0, 0, 0, 0,
==> 0, 0, 0, 9317yz3,0, 0, 0,
==> 0, 0, 0, 0, 27951xyz3,102487yz4,65219y2z3,
==> 0, 21xy, _[6,3],14641z4,_[6,5], _[6,6], -43923xz4,
==> 0, 49y2, _[7,3],3993xz3,_[7,5], _[7,6], _[7,7]
ss[2];
==> 2,7,5,1,3,4,6
// elimination without the last 3 rows
ss=bareiss(mm,3,0);
print(ss[1]);
==> 7y, 0, 0, 0, 0, 0, 0,
==> 0, 77yz,0, 0, 0, 0, 0,
==> 0, 0, 231xyz, 0, 0, 0, 0,
==> 0, 0, 0, 1617xy2z,0, 0, 0,
==> 11z,21xy,-1331z3,14641z4, _[5,5],_[5,6],_[5,7],
==> 0, 0, 539y2z, _[6,4], _[6,5],_[6,6],-3773y3z,
==> 3x, 49y2,-363xz2,3993xz3, _[7,5],_[7,6],_[7,7]
ss[2];
==> 2,3,4,1
* Menu:
See
* det::
* matrix::
See *note det::; *note matrix::.
File: sing.htm, Node: betti, Next: char, Prev: bareiss, Up: Functions
5.1.3 betti
-----------
`*Syntax:*'
`betti (' list_expression `)'
`betti (' resolution_expression `)'
`betti (' list_expression `,' int_expression `)'
`betti (' resolution_expression `,' int_expression `)'
`*Type:*'
intmat
`*Purpose:*'
with 1 argument: computes the graded Betti numbers of a minimal
resolution of $R^n/M$, if $R$ denotes the basering and
$M$ a homogeneous submodule of $R^n$ and the argument represents a
resolution of
$R^n/M$.
The entry d of the intmat at place (i,j) is the minimal number of
generators in degree i+j of the j-th syzygy module (= module of
relations) of $R^n/M$ (the 0th (resp.\ 1st) syzygy module of $R^n/M$ is
$R^n$ (resp.\ $M$)).
R^n/M, if R denotes the basering and M a homogeneous submodule of
R^n and the argument represents a resolution of R^n/M:
The entry d of the intmat at place (i,j) is the minimal number of
generators in degree i+j of the j-th syzygy module (= module of
relations) of R^n/M (the 0th (resp. 1st) syzygy module of R^n/M is
R^n (resp. M)). The argument is considered to be the result of a
res/sres/mres/nres/lres command. This implies that a zero is only
allowed (and counted) as a generator in the first module.
For the computation betti uses only the initial monomials. This
could lead to confusing results for a non-homogeneous input.
The optional second argument is a switch for the minimization of
the Betti numbers. If it is 0 then the Betti numbers correspond
exactly to the input - otherwise the command is identical to the
one-argument form.
`*Example:*'
ring r=32003,(a,b,c,d),dp;
ideal j=bc-ad,b3-a2c,c3-bd2,ac2-b2d;
list T=mres(j,0); // 0 forces a full resolution
// a minimal set of generators for j:
print(T[1]);
==> bc-ad,
==> c3-bd2,
==> ac2-b2d,
==> b3-a2c
// second syzygy module of r/j which is the first
// syzygy module of j (minimal generating set):
print(T[2]);
==> bd,c2,ac,b2,
==> -a,-b,0, 0,
==> c, d, -b,-a,
==> 0, 0, -d,-c
// the second syzygy module (minimal generating set):
print(T[3]);
==> -b,
==> a,
==> -c,
==> d
print(T[4]);
==> 0
betti(T);
==> 1,0,0,0,
==> 0,1,0,0,
==> 0,3,4,1
// most useful for reading off the graded Betti numbers:
print(betti(T),"betti");
==> 0 1 2 3
==> ------------------------------
==> 0: 1 - - -
==> 1: - 1 - -
==> 2: - 3 4 1
==> ------------------------------
==> total: 1 4 4 1
Hence
* the 0th syzygy module of r/j (which is r) has 1 generator in degree
0 (which is 1),
* the 1st syzygy module `T[1]' (which is j) has 4 generators (one in
degree 2 and three in degree 3),
* the 2nd syzygy module `T[2]' has 4 generators (all in degree 4),
* the 3rd syzygy module `T[3]' has 1 generator in degree 5,
where the generators are the columns of the displayed matrix and degrees
are assigned such that the corresponding maps have degree 0: $$
0 \longleftarrow r/j \longleftarrow r(1)
\buildrel{T[1]}\over{\longleftarrow} r(2) \oplus r^3(3)
\buildrel{T[2]}\over{\longleftarrow} r^4(4)
\buildrel{T[3]}\over{\longleftarrow} r(5)
\longleftarrow 0 \quad .
$$
T[1] T[2] T[3]
0 <- r/j <- r(1) <---- r(2)+r^3(3) <---- r^4(4) <---- r(5) <- 0 .
* Menu:
See
* Syzygies and resolutions::
* hres::
* lres::
* mres::
* print::
* res::
* resolution::
* sres::
See *note Syzygies and resolutions::; *note hres::; *note lres::; *note
mres::; *note print::; *note res::; *note resolution::; *note sres::.
File: sing.htm, Node: char, Next: char_series, Prev: betti, Up: Functions
5.1.4 char
----------
`*Syntax:*'
`char (' ring_name `)'
`*Type:*'
int
`*Purpose:*'
returns the characteristic of the coefficient field of a ring.
`*Example:*'
ring r=32003,(x,y),dp;
char(r);
==> 32003
ring s=0,(x,y),dp;
char(s);
==> 0
ring ra=(7,a),(x,y),dp;
minpoly=a^3+a+1;
char(ra);
==> 7
ring rp=(49,a),(x,y),dp;
char(rp);
==> 7
ring rr=real,x,dp;
char(rr);
==> 0
* Menu:
See
* charstr::
* ring::
See *note charstr::; *note ring::.