source: git/doc/usercard.tex @ 660fdd

% $Id: usercard.tex,v 1.1 1998-05-12 07:24:29 schmidt Exp $

%
% usercard.tex - Singular user quick reference card.
%

\input singcard.tex

\centerline{\hbf SINGULAR Quick Reference}

\centerline{\srm {\ssc Singular} Version 1.2.0}

\bigskip

Do not forget to terminate all commands with a {\tt ;} (semicolon)!

Especially if \Singular\ prints the continuation prompt {\tt .}
(dot) instead of the regular command prompt {\tt >}, then it
waits for a command to be terminated by a {\tt ;}.  If that does
not help, try one or more {\tt "} or {\tt \char`}} to close an
opened string or procedure.

Comments start with {\tt //} and extend to the end of the line.

\sec Starting SINGULAR(2.5cm)
Singular&                       start \Singular\cr
Singular {\it files} $\ldots$&  read {\it files\/} and prompt for further commands\cr
Singular --help&                print short help on command line options and
                                exit\cr
\endsec

\sec Stopping SINGULAR()
quit;&                          exit \Singular; also {\tt exit;} or {\tt \$}\cr
\ctl c&                         interrupt \Singular\ (on $*$ix systems only)\cr
\endsec

\sec Getting help()
help;&                          enter online help system\cr
help {\it topic\/};&            describe {\it topic\/}; also {\tt? {\it topic\/};}\cr
\subsec{Inside the online help system:}
&                               (on $*$ix systems only)\cr
\ctl h&                         get help on help system\cr
q&                              exit from help system\cr
n\rmslash p\rmslash u&          go to next/previous/upper node\cr
m&                              pick menu item by name\cr
l&                              go to last visited node/exit from help on help\cr
SPC\rmslash DEL&                scroll forward/backward one page\cr
\endsec

\sec Commandline editing()
\sectext
You may edit the commandline and retrieve previous commands in a
way common to most modern shells (on $*$ix systems only):\cr
BS\rmslash\ctl d&               remove character on the left/right of the
                                cursor\cr
\ctl p\rmslash\ctl n&           get previous/next line from history\cr
\ctl b\rmslash\ctl f&           move cursor left/right\cr
\ctl a\rmslash\ctl e&           go to beginning/end of line\cr
\ctl u\rmslash\ctl k&           delete to beginning/end of line\cr
\endsec

\sec Names and objects()
\sectext
\parskip=\verysmallskipamount
All names(=identifiers) have to be declared.  A declaration has the syntax

{\tt\quad {\it type\/} {\it name\/} \opt{= {\it expression\/}};}

Names of type {\tt number}, {\tt poly}, {\tt ideal}, {\tt vector}, {\tt
module}, {\tt matrix}, {\tt map}, and {\tt resolution} may be declared
only inside a ring.  They are local to that ring.  The same holds for a {\tt
list} if it contains an object of the above types.  All other types may be
declared at any moment.  They are visible globally.

Names may consist of alphanumeric characters including {\tt \_} (underscore) and
have to start with a letter.  Names may be followed by an integer expression in
parentheses, resulting in so-called {\it indexed names}.

The expression {\tt {\it name\/}({\it n}..{\it m\/})} is a shortcut for {\tt
{\it name\/}({\it n\/}), $\ldots$, {\it name\/}({\it m\/})} which is especially
useful for declaring ring variables (\eg {\tt ring r = 0, x(1..3), dp;}).\cr
\endsec

\vfill
\centerline{\srm \copyright 1998 \qquad Permissions on back}

\eject

\sec Ring declaration()
\longentry ring {\it name\/} = {\it basefield}, ({\it ringvars}), {\it ordering\/};&
                                \hyphenpenalty=50 \tolerance=200 declare the
                                ring {\it name\/} and make it the current
                                base\-ring.  {\it ringvars\/} has to be a list
                                of names or indexed names, the other items are
                                described below.  An example:\par {\tt ring r =
                                32003, (x, y, z), dp;}\cr
\longentry qring {\it name\/} = {\it ideal\/};&
                                declare the quotient ring {\it name\/} of the
                                current basering with respect to ideal {\it
                                ideal\/}.  Make {\it name\/} the new
                                basering.\cr
\subsec{Available {\bit basefields\/}:}
0&                              the field of rational numbers\cr
\it p&                          the finite field $Z_p$ with {\it p\/}
                                elements,\par
                                $2 \le p \le 32003$ a prime\cr
({\it p\/}\^{}{\it n}, {\it gen\/})&
                                the finite field with $p^n$ elements, {\it p\/}
                                a prime and\par
                                $4 \le p^n \le 32671$. The name {\it gen\/}
                                refers to some generator of the group of
                                unities.\cr
({\it p}, {\it alpha\/})&       algebraic extension of $Q$ or $Z_p$ ($p =
                                0$ or as above) by {\it alpha}.  You have to
                                specify the minpoly $\mu_{\hbox{\tit alpha}}$
                                for {\it alpha\/} immediately after the ring
                                declaration with an assignment to {\tt minpoly}
                                (\eg {\tt minpoly=a\^{}2+1;}).  {\it alpha\/}
                                has to be a valid name.\cr
({\it p}, $t_1$, $\ldots$)&     transcendental extension of $Q$ or $Z_p$
                                ($p = 0$ or as above) by~$t_i$.  As $t_i$ you
                                may use either names or indexed names.\cr
real&                           the real numbers represented by floating point
                                numbers\cr
\endsec

\sec Term orderings()
\sectext
An {\it ordering\/} as referred to in the ring declaration may be either 
a global, local, or matrix ordering or a list of these resulting in a
pro\-duct ordering.  The list may include extra weight vectors and may be
preceded or followed by a module order specification.\cr
\subsec{Global orderings}
lp&                             lexicographical ordering\cr
dp&                             degree reverse lexicographical ordering\cr
Dp&                             degree lexicographical ordering\cr
wp($w_1$, $\ldots$)&            weighted reverse lexicographical ordering\cr
Wp($w_1$, $\ldots$)&            weighted lexicographical ordering\cr
&                               The $w_i$ have to be positive integers.\cr
\subsec{Local orderings}
ls&                             negative lexicographical ordering\cr
ds&                             negative degree reverse lexicographical ordering\cr
Ds&                             negative degree lexicographical ordering\cr
ws($w_1$, $\ldots$)&            general weighted reverse lexicographical ordering\cr
Ws($w_1$, $\ldots$)&            general weighted lexicographical ordering\cr
&                               $w_1$ has to be a nonzero integer, every other
                                $w_i$ may be any integer\cr
\subsec{Matrix orderings}
\longentry M($M_{11}$, $M_{12}$, $\ldots$, $M_{nn}$)&
                                {\it M\/} has to be an invertible matrix with
                                integer coeffi\-cients.  Coefficients have to be
                                specified row-wise.\cr
\subsec{Product orderings}
\longentry($o_1$\opt{($k_1$)}, $o_2$\opt{($k_2$)}, $\ldots$, $o_n$\opt{($k_n$)})&
                                the orderings {\tt lp}, {\tt dp}, {\tt Dp}, {\tt
                                ls}, {\tt ds}, {\tt Ds} may be followed by an
                                integer expression $k_i$ in parentheses which
                                specifies the number of variables $o_i$ refers
                                to (\eg {\tt (lp(3), dp(2))}).\cr
\subsec{Module orderings}
({\it c}, $o_1$, $\ldots$)&     sort by components first\cr
($o_1$, $\ldots$, {\it c\/})&   sort by variables first\cr
&                               $o_i$ may be any of the above orderings or an
                                extra weight vector, {\it c\/} may be one of
                                {\tt C} or {\tt c}:\cr
C&                              sort generators in ascending order (\ie {\tt
                                gen({\it i\/})} $<$ {\tt gen({\it j\/})} iff $i <
                                j$)\cr
c&                              sort generators in descending order\cr
\subsec{Extra weight vector}
a($w_1$, $\ldots$)&             any of the above degree orderings may be
                                preceded by an extra weight vector\cr
\endsec

\begingroup
\def\interentryskip{\noalign{\verysmallskip}}%
\sec Data types(1.5cm)
\sectext
First, examples of ring-independent types:\cr
\interentryskip
\longitem
int i1 = 101; int i2 = 13 div 3;\cr
\interentryskip
\longitem
intvec iv = 13 div 3, -4, i1;\cr
\interentryskip
\longentry
intmat im[2][2] = 13 div 3, -4, i1;&
                                a $2\times 2$ matrix.  Entries are filled
                                row-wise, missing entries are set to zero, extra
                                entries are ignored.  vector/matrix elements are
                                accessed using the {\tt[$\ldots$]} operator,
                                where the first index is one (\eg {\tt iv[3];
                                im[1, 2];}).\cr
\interentryskip
\longitem
string s1 = "a quote \char"5C " and a backslash \char"5C \char"5C";\par
string s2 = "con" + "catenation";\cr
\interentryskip
\sectext
The basering in the following is {\tt ring r = 0, (x, y, z, mu, nu), dp;}\cr
\interentryskip
\longitem
number n = 5/3;\cr
\interentryskip
\longentry
poly p(1) = 2xy2+3/4x3yz4;\par
poly p(2) = (5/3)*mu\^{}2*nu\^{}3+n*yz2;&
                                {\tt p(1)} equals $3/4x^3yz^4+2xy^2$.  The
                                short format of monomials is valid for
                                one-character ring variables only.\cr
\interentryskip
\longentry
ideal i = p(1..2), x+y;&        note the use of indexed names\cr
\interentryskip
\longentry
vector v = [p(1), p(2), x+y];\par
vector w = 2*p(1)*gen(6)+n*nu*gen(1);&
                                vectors may be written in brackets ({\tt
                                [$\ldots$]}) or expressed as linear
                                combinations of the canonical generators {\tt
                                gen({\it i\/})}\cr
\interentryskip
\longitem
module mo = v, w, x+y*gen(1);\cr
\interentryskip
\longitem
resolution r = sres(std(mo), 0);\cr
\interentryskip
\longentry
matrix ma[2][2] = 5/3, p(1), 101;&
                                the rules for declaring, filling, and accessing
                                of integer matricies apply to the types {\tt
                                matrix} and {\tt vector}, too\cr
\interentryskip
\longentry
list l = iv, v, p(1..2), mo;&
                                lists may collect objects of any type.  They are
                                ring-dependent iff one of the entries is.\cr
\endsec
\endgroup

\sec Monitoring and debugging tools()
timer = 1;&                     print time used for commands to execute\cr
\longentry int t = timer; {\it commandsequence}; timer-t;&
                                print time in seconds used for {\it commandsequence}
                                to execute\cr
memory(1);&                     print number of bytes allocated from system\cr
option(prot);&                  show algorithm protocol\cr
option(mem);&                   show algorithm memory usage\cr
\noalign{\medskip}
TRACE = 1;&                     print protocol on execution of procedures\cr
listvar(all);&                  list all (user-)defined names\cr
\longentry listvar({\it ringname});&
                                list all names belonging to {\it ringname}\cr
\endsec

\eject

\sec Options()
option();&                      show current option settings\cr
\longentry option($option_1$, no$option_2$, $\ldots$);&
                                switch $option_1$ on and $option_2$ off, resp.\cr
option(none);&                  reset all options to default values\cr
\sectext
The most important options:\cr
\subsec{Monitoring}
debugLib&                       show loading of procedures from libraries\cr
mem&                            show algorithm memory usage\cr
prot&                           show algorithm protocol\cr
\subsec{Standard bases}
fastHC&                         try to find highest corner as fast as possible\cr
intStrategy&                    avoid divisions\cr
morePairs&                      create additional pairs\cr
notSugar&                       disable sugar strategy\cr
redSB&                          compute reduced standard bases\cr
redTail&                        reduce tails\cr
sugarCrit&                      use sugar criteria\cr
weightM&                        automatically compute weights\cr
\subsec{Resolutions}
minRes&                         do additional minimizing\cr
notRegularity&                  disable regularity bound\cr
\subsec{Miscellany}
returnSB&                       let some functions return standard bases\cr
\endsec

\sec System variables()
\sectext
The most important system variables:\cr
\subsec{Standard bases}
degBound&                       stop if (weighted) total degree exceeds {\tt
                                degBound}\cr
multBound&                      stop if multiplicity gets smaller than {\tt
                                multBound}\cr
noether&                        cut off all monomials above the monomial {\tt
                                noether}\cr
\subsec{Miscellany}
minPoly&                        use {\tt minPoly} as minimal polynomial for
                                algebraic extensions\cr
short&                          print monomials in a long format if non-zero\cr
timer&                          on assignment of a non-zero value show time
                                used for execution of executed commands.  On
                                evaluation, return system time in seconds used
                                by \Singular\ since start\cr
TRACE&                          print information on procedures being executed
                                if {\tt TRACE} is larger than one\cr
\endsec

\sec Mapping(1.5cm)
\longentry map {\it name\/} = {\it ringname}, {\it idealexpression};&
                                declare a map {\it name\/} from {\it ringname}
                                to current basering.  The $i$'th ring variable
                                from {\it ringname} is mapped to the $i$'th
                                generator from {\it idealexpression}.\cr
\longentry {\it mapname\/}({\it expression\/})&
                                apply map {\it mapname\/} to {\it expression}\cr
\noalign{\smallskip}
\sectext
Coefficients between rings with different basefields are mapped in the following
way (non-canonical maps only):\par
$Z_p \rightarrow Q: [i]_p \mapsto i \in [-p/2,p/2] \subset Z$\par
$Z_p \rightarrow Z_q: [i]_p \mapsto i \in [-p/2,p/2] \subset Z \mapsto [i]_q \in
Z_q$\cr
\noalign{\smallskip}
\longentry subst({\it expression}, {\it ringvar}, {\it monomial\/})&
                                substitute {\it ringvar\/} by {\it monomial\/}
                                in {\it expression}\cr
\longentry imap({\it ringname}, {\it name\/})&
                                map object {\it name\/} from subring {\it
                                ringname\/} to current basering\cr
\longentry fetch({\it ringname}, {\it name\/})&
                                map object {\it name\/} from ring {\it
                                ringname\/} to current basering.  The rings
                                have to be ``allmost'' identical.\cr
\endsec

\sec Liebe SINGULAR-Entwickler und Benutzer!()
\sectext
\font\ninerm=cmr9
\ninerm\baselineskip=11pt
\parindent=1em
Das ist der Entwurf einer Quick-Reference-Card f\"ur SINGULAR.  Nachdem der
`kanonische' Teil gesetzt ist, gebe ich die Arbeit weiter an Euch.  Genauer:

\medskip
\item{$\bullet$} K\"onntet Ihr bitte den bereits vorhandenen Text korrektur\-lesen,
  insbesondere auch auf typografische Fehler achtend.

\item{$\bullet$} Eure \"Anderungsw\"unsche und Kritik dazu h\"atte ich gerne.
  Allerdings ist die erste Seite bereits voll.  Wenn Ihr also irgendwo eine
  Zeile mehr haben wollt, m\"u\ss t Ihr auch dazusagen, wo eine andere
  rausgenommen werden soll.

\hang Die Karte ist keine Kurzeinf\"uhrung in SINGULAR, sondern soll als
  Ged\"achtnisst\"utze dienen.  Dies bitte bei Kritik der Art ``zu ungenau!''
  oder ``besser!'' beachten.  Davon abgesehen bitte ich um konstruktive Kritik.

\item{$\bullet$} Es fehlen noch Abschnitte zu Input/Output und zu den
  meistgebrauchten mathematischen Funktionen.  F\"ur den Input/Output-Teil bitte
  das aufschreiben, was ihr f\"ur erw\"ahnenswert haltet bzw. h\"aufig braucht.
  Und f\"ur die mathematischen Funktionen bitte ich regelrecht um eine
  ``Top-Twenty'' der von Euch am h\"aufigsten gebrauchten SINGULAR-Kernel
  Funktionen.  Oder auch Library-Funktionen?

\hang Irgendwann soll es noch eine ``Programmer's Quick Reference Card''
  geben (hoffentlich nicht von mir).  Dementsprechend also eher Funktionen
  ber\"ucksichtigen, die f\"ur den interaktiven Gebrauch wichtig sind.
\cr
\endsec

\bye